Using Zen Mojo Plugins
Page Manager and Helper Plugins for jQuery Mobile
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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/.

Adding jQuery Mobile to the Page Class
Adding Required jQuery Mobile Files
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/ and jQuery at https://code.jquery.com/jquery/.
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:
Note:
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:
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.
Registering the jQuery Mobile Plugins
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).
Note:
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).
Other Options and Requirements
For more information on these plugins, see %ZEN.Mojo.Plugin.jQM145PageManager and %ZEN.Mojo.Plugin.jQM145Helper in the class reference.
Older jQuery Mobile Classes
Support for jQuery Mobile version 1.4.3 is provided by the %ZEN.Mojo.Plugin.jQM143PageManager and %ZEN.Mojo.Plugin.jQM143Helper 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.jQM132PageManager and %ZEN.Mojo.Plugin.jQM132Helper 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>
Note:
Deprecated jQuery Mobile Plugins
The jQuery Mobile %ZEN.Mojo.Plugin.jQMPageManager and %ZEN.Mojo.Plugin.jQMHelper 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>
Optional jQuery Mobile Page Manager Attributes
You can specify the following attributes for the page manager element:
Optional jQuery Mobile Helper Attributes
You can specify the following attributes of for the helper element:
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
jQuery Mobile Layout Objects
See jQuery Mobile Helper Layout Objects later in this chapter for a complete list of available layout objects.
Custom jQuery Mobile Layout Object Methods
The following methods are available within all appropriate layout objects:
jQuery Mobile Helper Plugin Methods
See Custom jQuery Mobile Helper Plugin Methods later in this chapter for a list of jQuery Mobile utility methods.
Direct Access to the jQuery Mobile Framework
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') ;
Event Handling
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.baseHelperPlugin, the jQuery Mobile helper plugin provides the following methods:
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.