Page Manager and Helper Plugins for ChocolateChip-UI

The ChocolateChip-UI page manager and helper plugins provide support for the ChocolateChip-UI framework. Because the ChocolateChip-UI framework was designed for mobile devices, these plugins are especially suitable for use on mobile devices, but could also be used on desktop computers. For detailed information about ChocolateChip-UI, see http://chocolatechip-ui.com/Opens in a new tab.

Adding ChocolateChip-UI to the Page Class

Adding Required ChocolateChip-UI Files

The files listed in this section are contained in the ChocolateChip-UI 3.5.2 release and the jQuery 2.0.3 release. If ChocolateChip-UI is not already installed on your system, you can generate the required files by building the version 3.5.2 source available at https://github.com/chocolatechipui/chocolatechip-ui/releasesOpens in a new tab. The jQuery library is available at https://code.jquery.com/jquery/Opens in a new tab.

These instructions assume that the ChocolateChip-UI files are in <install-dir>/csp/broker (see “Adding Plugins to the Page Class” for details). The following files must be available:

chui-3.5.2.js
chui-ios-3.5.2.css

ChocolateChip-UI also requires the jQuery 2.0.3 library. The following file must be in /csp/broker:

jquery-2.0.3.min.js

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:
"chui-ios-3.5.2.css"
JSINCLUDES filenames:
"jquery-2.0.3.min.js, chui-3.5.2.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 ChocolateChip-UI library depends on it.

Registering the ChocolateChip-UI Plugins

The following example demonstrates how the ChocolateChip-UI page manager and helper can be registered in your pageContents XData block (as described in “Adding Plugins to the Page Class”):

  <mojo:chui-3.5.2-PageManager>
    <mojo:chui-3.5.2-Helper/>
    <mojo:mojoDefaultHelper/>
  </mojo:chui-3.5.2-PageManager>

Note:

A page class that uses the ChocolateChip-UI page manager can include only one documentView in its pageContents XData block.

The ChocolateChip-UI page manager is required when you use ChocolateChip-UI helper plugin, and can also be used with most other helper plugins. The Default helper plugin is required only by the ChocolateChip-UI $list layout object.

The ChocolateChip-UI helper provides extended versions of HTML5 elements. If it is used together with the HTML5 helper, the ChocolateChip-UI helper should be listed first. Plugin conflicts are also likely when the ChocolateChip-UI helper is used with other helpers that extend HTML5 elements (see “Detecting and Resolving Plugin Conflicts”).

Other Options and Requirements

The $list layout object requires the $loop layout object provided by the Default helper plugin. This layout object will display the string "($loop)" in place of the expected output if the Default helper is not included.

For more information on these plugins, see %ZEN.Mojo.Plugin.chui352PageManagerOpens in a new tab and %ZEN.Mojo.Plugin.chui352HelperOpens in a new tab in the class reference.

Note:

Deprecated ChocolateChip-UI Plugin Classes

The %ZEN.Mojo.Plugin.chuiPageManagerOpens in a new tab and %ZEN.Mojo.Plugin.chuiHelperOpens in a new tab plugin classes are currently available for backward compatibility with earlier versions of Zen Mojo. These classes also use ChocolateChip-UI version 3.5.2, and usage is identical to the current plugins except that the older classes are registered using the following elements:

  <mojo:chuiPageManager>
    <mojo:chuiHelper/>
  </mojo:chuiPageManager>

These older classes are not being updated and will be removed in a later release.

Using ChocolateChip-UI in a Template Class

Important:

Required Layout Objects

A ChocolateChip-UI layout graph must always contain at least one $article layout object with at least one $section layout object in it. This requirement is imposed by the ChocolateChip-UI framework.

ChocolateChip-UI Layout Objects

See “ChocolateChip-UI Helper Layout Objects” later in this chapter for a complete list of available layout objects.

Custom ChocolateChip-UI Layout Object Methods

The following method is available within all appropriate layout objects:

$refresh() — Re-renders the HTML for the layout object.

ChocolateChip-UI Helper Plugin Methods

The ChocolateChip-UI helper plugin does not include any utility methods other than those inherited from %ZEN.Mojo.Plugin.baseHelperPluginOpens in a new tab.

Direct Access to ChocolateChip-UI Libraries

When you use the ChocolateChip-UI plugins, your client methods can access variables defined in the ChocolateChip-UI JavaScript files. These variables abstract the user input interaction from the device input. For details, see http://chocolatechip-ui.com/documentation#/chuijsOpens in a new tab.

Event Handling

ChocolateChip-UI plugins have no special event handling requirements.

ChocolateChip-UI Helper Layout Objects

The following list is intended as a quick reference to the layout options offered by the ChocolateChip-UI helper plugin. For complete reference information, use the Plugin Documentation app (see “Using the Plugin Documentation and Widget Reference Apps”):

$article	$div	$h3	$link	$navbar
$aside	$h1	$h4	$list	$p
$button	$h2	$h5	$listitem	$section

Since the ChocolateChip-UI 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).

Using ChocolateChip-UI Plugin Sample Code

A complete sample application is available for the ChocolateChip-UI page manager and helper plugins. In Studio, go to ZMdemo.chui in the SAMPLES namespace. Compile the classes in that package if necessary. To run the application, open ZMdemo.chui.HomePageOpens in a new tab and select View > Web Page. When running in debug mode, remember to set the debug target URL to csp/samples/ZMdemo.chui.HomePage.cls.

In addition to the ChocolateChip-UI page manager and helper plugins, the sample application also uses the HTML5 and Default helper plugins.