Page Manager and Helper Plugins for jQuery Mobile
The jQuery Mobile page manager plugin and jQuery Mobile helper plugin enable you to use the jQuery Mobile framework. The jQuery Mobile framework is designed for mobile devices, but can also be used on desktop computers. For detailed information about jQuery Mobile, see http://jquerymobile.com/Opens in a new tab.
Adding jQuery Mobile to the Page Class
The files listed in this section are contained in jQuery Mobile version 1.4.5 and jQuery (core) version 1.10.2. If they are not already installed on your system, you can get jQuery Mobile at https://jquerymobile.com/download/all/Opens in a new tab and jQuery at https://code.jquery.com/jquery/Opens in a new tab.
These instructions assume that the jQuery and jQuery Mobile files are in <install-dir>/csp/broker (see “Adding Plugins to the Page Class” for details). The following files must be available:
-
jquery.mobile-1.4.5.min.js
-
jquery.mobile-1.4.5.min.css
-
jquery-1.10.2.min.js
Plugins are also available for versions 1.4.3 and 1.3.2 of jQuery Mobile. See “Older jQuery Mobile Classes” for details.
Add the following filename strings to the JSINCLUDES and CSSINCLUDES (or CSS3INCLUDES) parameters of your page class. Caché assumes that /csp/broker is the root directory for all relative paths:
-
CSSINCLUDES filenames:
"jquery.mobile-1.4.5.min.css"
-
JSINCLUDES filenames:
"jquery-1.10.2.min.js, jquery.mobile-1.4.5.min.js"
Bear in mind that files are loaded in the order that they are listed in the parameters. In this case, the jQuery library must be listed first because the jQuery Mobile library depends on it.
The following example demonstrates how the jQuery Mobile page manager and helper can be registered in your pageContents XData block (as described in “Adding Plugins to the Page Class”):
<mojo:jQM-1.4.5-PageManager>
<mojo:jQM-1.4.5-Helper/>
<mojo:mojoDefaultHelper/>
</mojo:jQM-1.4.5-PageManager>
Page manager and helper elements can both take optional attributes (see “Support for jQuery Mobile Animation and Themes”).
A page class that uses the jQuery Mobile page manager can include only one documentView in its pageContents XData block.
The jQuery Mobile page manager is required when you use jQuery Mobile helper plugin, and can also be used with most other helper plugins. The Default helper plugin is required by several jQuery Mobile layout objects.
The jQuery Mobile helper provides extended versions of HTML5 elements. If it is used together with the HTML5 helper, the jQuery Mobile helper should be listed first. Plugin conflicts are also likely when the jQuery Mobile helper is used with other helpers that extend HTML5 elements (see “Detecting and Resolving Plugin Conflicts”).
-
jQuery Mobile helper layout objects $collapsible, $collapsibleset, $navbar, and $listview require the $loop layout object provided by the Default helper plugin. These layout objects will display the string "($loop)" in place of the expected output if the Default helper is not included.
-
In the pageContents XData block, both <mojo:jQM-1.4.5-PageManager> and <mojo:jQM-1.4.5-Helper/> elements can take optional attributes. For details, see “Support for jQuery Mobile Animation and Themes” later in this chapter.
For more information on these plugins, see %ZEN.Mojo.Plugin.jQM145PageManagerOpens in a new tab and %ZEN.Mojo.Plugin.jQM145HelperOpens in a new tab in the class reference.
Older jQuery Mobile Classes
Support for jQuery Mobile version 1.4.3 is provided by the %ZEN.Mojo.Plugin.jQM143PageManagerOpens in a new tab and %ZEN.Mojo.Plugin.jQM143HelperOpens in a new tab plugin classes . Usage is identical to version 1.4.5 except that jquery.mobile-1.4.3.min.js and jquery.mobile-1.4.3.min.css are used, and the elements shown in the following example are used in the pageContents XData block:
<mojo:jQM-1.4.3-PageManager>
<mojo:jQM-1.4.3-Helper/>
<mojo:mojoDefaultHelper/>
</mojo:jQM-1.4.3-PageManager>
Support for jQuery Mobile version 1.3.2 is provided by the %ZEN.Mojo.Plugin.jQM132PageManagerOpens in a new tab and %ZEN.Mojo.Plugin.jQM132HelperOpens in a new tab plugin classes. Usage is identical to version 1.4.5 except that jquery.mobile-1.3.2.min.js and jquery.mobile-1.3.2.min.css are used, and the elements shown in the following example are used in the pageContents XData block:
<mojo:jQM-1.3.2-PageManager>
<mojo:jQM-1.3.2-Helper/>
<mojo:mojoDefaultHelper/>
</mojo:jQM-1.3.2-PageManager>
The jQuery Mobile %ZEN.Mojo.Plugin.jQMPageManagerOpens in a new tab and %ZEN.Mojo.Plugin.jQMHelperOpens in a new tab plugin classes are currently available for backward compatibility with earlier versions of Zen Mojo. These classes also use jQuery Mobile version 1.3.2, and usage is identical to the current 1.3.2 plugins except that the older classes are registered using the following elements:
<mojo:jQMPageManager>
<mojo:jQMHelper/>
<mojo:mojoDefaultHelper/>
</mojo:jQMPageManager>
These older classes are not being updated and will be removed in a later release.
Support for jQuery Mobile Animation and Themes
In the pageContents XData block, both page manager and helper elements support optional attributes related to themes and animation. The following example uses all five attributes:
<mojo:jQM-1.4.5-PageManager jQueryTheme="a" jQueryAnimation="flip">
<mojo:jQM-1.4.5-Helper jQueryHeaderTheme="a" jQueryBarTheme="d" jQueryCollapsibleTheme="c"/>
</mojo:jQM-1.4.5-PageManager>
You can specify the following attributes for the page manager element:
-
jQueryTheme
Specifies the jQuery theme for the documentView. For example:
<mojo:jQM-1.4.5-PageManager jQueryTheme="a">
-
jQueryAnimation
Specifies the jQuery Mobile animation to use when modifying the document stack (pushing new documents onto the stack or popping documents off the stack). For example:
<mojo:jQM-1.4.5-PageManager jQueryAnimation="flip">
You can specify the following attributes of for the helper element:
-
jQueryHeaderTheme
Specifies the jQuery theme for the header and footer.
-
jQueryBarTheme
Specifies the jQuery theme for grids and bars.
-
jQueryCollapsibleTheme
Specifies the jQuery theme for collapsible sets.
Any or all of the helper attributes can be used in the same element. For example:
<mojo:jQM-1.4.5-Helper jQueryHeaderTheme="a" jQueryBarTheme="d" jQueryCollapsibleTheme="c"/>
If you need to change these attributes after initial setup, use the changeTheme() helper plugin method (described later in “Custom jQuery Mobile Helper Plugin Methods”).
Using jQuery Mobile in a Template Class
See “jQuery Mobile Helper Layout Objects” later in this chapter for a complete list of available layout objects.
The following methods are available within all appropriate layout objects:
-
$hide() — Hides the layout object.
-
$refresh() — Re-renders the HTML for the layout object.
-
$show() — Shows the layout object.
See “Custom jQuery Mobile Helper Plugin Methods” later in this chapter for a list of jQuery Mobile utility methods.
The jQuery Mobile plugins provide direct access to the jQuery Mobile framework via the $.mobile object, which your client methods can use to refer to jQuery Mobile methods. For example:
$.mobile.loading('show') ;
jQuery Mobile plugins have no special event handling requirements.
jQuery Mobile Helper Layout Objects
The following list is intended as a quick reference to the layout options offered by the jQuery Mobile helper plugin. For complete reference information, use the Plugin Documentation app (see “Using the Plugin Documentation and Widget Reference Apps”):
$button | $controlgroup | $input | $navbaritem | $radio-button |
$checkbox | $fieldset | $link | $pagecontent | $select |
$collapsible | $footer | $listview | $panel | $string |
$collapsibleset | $grid | $listviewitem | $password | $text |
$control | $header | $navbar | $popup | $textarea |
Since the jQuery Mobile helper provides extended versions of HTML5 elements, plugin conflicts are likely when it is used with other helpers that extend HTML5 elements (see “Detecting and Resolving Plugin Conflicts” earlier in this book).
Custom jQuery Mobile Helper Plugin Methods
In addition to methods inherited from %ZEN.Mojo.Plugin.baseHelperPluginOpens in a new tab, the jQuery Mobile helper plugin provides the following methods:
-
changeTheme()
ClientMethod changeTheme(newTheme = "c", headerTheme = "a", barTheme = "a") [ Language = javascript ]
Given a theme, a header theme, and a bar theme, this method updates the themes used in this page. For example:
var mainView = zen('mainView'); mainView.getPluginByName('jQM-1.4.5-Helper').changeTheme('d','b','b');
The themes are originally set as attributes of the helper element in the pageContents XData block (see “Support for jQuery Mobile Animation and Themes” earlier in this chapter).
-
openPanel()
ClientMethod openPanel(id) [ Language = javascript ]
Given the id of a $panel object, this method displays that panel. For example:
var mainView = zen('mainView'); getPluginByLayoutObjectType($panel).openPanel('leftPanel');
-
closePanel()
ClientMethod closePanel(id) [ Language = javascript ]
Given the id of a $panel object, this method closes that panel.
-
togglePanel()
ClientMethod togglePanel(id) [ Language = javascript ]
Given the id of a $panel object, this method toggles the panel open or closed.
-
showPopup()
ClientMethod showPopup(key, options) [ Language = javascript ]
Given the key of a $popup object, this method displays that object. The options argument is an object that contains any options for the popup. For example:
var view = zen('mainView'); view.getPluginByLayoutObjectType($popup').showPopup('form-popup',{x:150,y:200});
-
closePopup()
ClientMethod closePopup(key) [ Language = javascript ]
Given the key of a $popup object, this method closes that object.
Using jQuery Mobile Plugin Sample Code
The Widget Reference offers interactive widget samples for the jQuery Mobile helper plugin. The reference includes working examples, detailed descriptions, and source code that you can cut and paste into your own applications.
A complete sample application is also available for each version the jQuery Mobile page manager and helper plugins. For the jQuery Mobile 1.4.5 version, open Studio and go to ZMdemo.JQM145 in the SAMPLES namespace. Compile the classes in that package if necessary. To run the application, open ZMdemo.JQM145.HomePage and select View > Web Page. When running in debug mode, remember to set the debug target URL to csp/samples/ZMdemo.JQM145.HomePage.cls.
For the other jQuery Mobile versions, follow the same directions but specify ZMdemo.JQM143 or ZMdemo.JQM (for version 1.3.2).
In addition to the jQuery Mobile page manager and helper plugins, these sample applications also use the Google Maps, HTML5, and Default helper plugins.