Page Manager and Helper Plugins for Dojo

The Dojo page manager plugin and related helper plugins provide support for the Dojo Toolkit. Helper plugins include Dojo Dijit helper for the Dijit user interface framework, Dojo 2D Chart helper for dojox/charting/Chart2D, and Dojo GridX helper for the separately packaged GridX library. These plugins are best suited for use on desktop computers. For detailed information about the Dojo Toolkit, see https://dojotoolkit.org/Opens in a new tab.

Adding Dojo to the Page Class

Adding Required Dojo Files

The files listed in this section are in either Dojo Toolkit 1.9.1 or GridX 1.3.0. If they are not already installed on your system, you can download Dojo at http://download.dojotoolkit.org/release-1.9.1/Opens in a new tab and GridX at https://github.com/oria/gridx/releasesOpens in a new tab.

These instructions assume that the files are in a subdirectory of <install-dir>/csp/broker named dojo-release-1-9-1 (see “Adding Plugins to the Page Class” for details). The following files must be available:

/dojo/dojo.js
/app/dojo_2DChart.js
/app/dojo_191Dijit.js
/dijit/themes/claro/claro.css (or another theming style sheet)

/gridx/resources/claro/Gridx.css (required only if you are using the GridX plugin)

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:
"dojo-release-1-9-1/dijit/themes/claro/claro.css, dojo-release-1-9-1/gridx/resources/claro/Gridx.css"
JSINCLUDES filenames:
"dojo-release-1-9-1/dojo/dojo.js, dojo-release-1-9-1/app/dojo_2DChart.js, dojo-release-1-9-1/app/dojo_191Dijit.js"

Registering the Dojo Plugins

The following example demonstrates how the Dojo page manager and one or more Dojo helpers can be registered in your pageContents XData block (as described in “Adding Plugins to the Page Class”). Each Dojo helper plugin is independent of the others, so register only the Dojo helpers you intend to use:

  <mojo:dojo-1.9.1-PageManager>
    <mojo:dojo-1.9.1-DijitHelper/>
    <mojo:dojo-1.9.1-2DChartHelper/>
    <mojo:dojoGridX-1.3.0-Helper/>
    <mojo:mojoDefaultHelper/>
  </mojo:dojo-1.9.1-PageManager>

The Dojo page manager is required if you use Dojo helper plugins, and can also be used with most other helper plugins. The Default helper plugin is required only by some layout objects in the Dojo Dijit helper.

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

Note:

A page class that uses the Dojo page manager can include more than one documentView in its pageContents XData block. For a working example, see the HTML5 sample program (“Using HTML5 Helper Sample Code”).

Other Options and Requirements

Your page class must implement page method adjustContentSize(), event handler onlayoutHandler(), and an XData Style block, as described in “Additional Dojo Page Manager Requirements” later in this chapter.
Dojo Dijit helper layout objects $AccordionContainer, $BorderContainer, $ContentPane, $DojoxContentPane, and $LayoutContainer 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.

The page manager plugin has several methods and properties not discussed here. See %ZEN.Mojo.Plugin.dojo191PageManagerOpens in a new tab in the Caché class reference for details.

For more information on the helper plugins, see %ZEN.Mojo.Plugin.dojo1912DChartHelperOpens in a new tab, %ZEN.Mojo.Plugin.dojo191DijitHelperOpens in a new tab, and %ZEN.Mojo.Plugin.dojoGridX130HelperOpens in a new tab in the class reference.

Note:

Deprecated Dojo Plugin Classes

The %ZEN.Mojo.Plugin.dojoPageManagerOpens in a new tab, %ZEN.Mojo.Plugin.dojo2DChartHelperOpens in a new tab, %ZEN.Mojo.Plugin.dojoDijitHelperOpens in a new tab, and %ZEN.Mojo.Plugin.dojoGridXHelperOpens in a new tab plugin classes are currently available for backward compatibility with earlier versions of Zen Mojo. These classes also use Dojo version 1.9.1, and usage is identical to the current plugins except that the older classes are registered using the following elements:

  <mojo:dojoPageManager>
    <mojo:dojoDijitHelper/>
    <mojo:dojo2DChartHelper/>
    <mojo:dojoGridXHelper/>
  </mojo:dojoPageManager>

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

Additional Dojo Page Manager Requirements

In order to use the Dojo page manager plugin, your page class must implement overrides for page method adjustContentSize() and event handler onlayoutHandler(), and add an XData Style block. If you omit any of these items, the web page will not display your contents.

Override for basePage.adjustContentSize()
This method must specify the width, height, and position of each documentView. For a details and examples, see “Overriding the adjustContentSize() Method” in the “Working with Plugins” chapter.
Override for basePage.onlayoutHandler()
This method must first invoke the inherited onlayoutHandler(), and then resize the top-level layout object. In the following example, 'layoutContainer-1 is the top-level layout object within the layout graph used by the page:
```
  ClientMethod onlayoutHandler() [ Language = javascript ]
  {
    this.invokeSuper('onlayoutHandler',arguments);
    var topContainer = zen('leftView').getItemByKey('layoutContainer-1');
    if (topContainer) {
      topContainer.$dojoItem.resize();
    }
  }
```
(For details on $dojoItem, see the section on “Direct Access to the Dojo Libraries” in “Using Dojo in a Template Class”).
Add an XData Style block
This style block must define the dvDocument class with height as 100%. For example:
```
  XData Style {
  <style type="text/css">
    .dvDocument { height: 100%;}
  </style>
  }
```

Using Dojo in a Template Class

The following statements apply to all three Dojo helper plugins.

Dojo Layout Objects

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

Custom Dojo Layout Object Methods

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.

Dojo Helper Plugin Methods

Each of these plugins has several utility methods. See %ZEN.Mojo.Plugin.dojo1912DChartHelperOpens in a new tab, %ZEN.Mojo.Plugin.dojo191DijitHelperOpens in a new tab, and %ZEN.Mojo.Plugin.dojoGridX130HelperOpens in a new tab in the class reference for details.

Direct Access to the Dojo Libraries

The Dojo helper plugins provide direct access to the Dojo Toolkit libraries via the $dojoItem property of each layout object. You can use the documentView.getItemByKey() method to return a layout object, and then use the $dojoItem property of that layout object to call a library function. For example:

  myDocView.getItemByKey('myKey').$dojoItem.show();

(For an example using getItemByKey(), see “Tutorial 3: Event Handling” in Using Zen Mojo).

Event Handling

Dojo plugins have no special event handling requirements.

Dojo Helper Layout Objects

The following lists are intended as a quick reference to the layout options offered by the Dojo helper plugins. For complete reference information, use the Plugin Documentation app (see “Using the Plugin Documentation and Widget Reference Apps”):

dojo2DChart

$Chart — represents a 2D chart.
$ChartLegend — represents a chart legend.

dojoGridX

$Gridx — represents a Dojo GridX. A $refresh call will update the body of the table with the current data of the associated store.

dojoDijit

Since the Dojo Dijit helper provides extended versions of HTML5 elements, plugin conflicts are likely when the it is used with other helpers that extend HTML5 elements (see “Detecting and Resolving Plugin Conflicts” earlier in this book).

$AccordionContainer	$DropDownMenu	$MenuSeparator	$TextBox
$BorderContainer	$Editor	$MultiSelect	$Textarea
$Button	$Fieldset	$NumberSpinner	$TimeTextBox
$CheckBox	$FilteringSelect	$NumberTextBox	$TitlePane
$CheckedMenuItem	$Form	$PopupMenuBarItem	$ToggleButton
$ColorPalette	$HorizontalRule	$PopupMenuItem	$Toolbar
$ComboBox	$HorizontalRuleLabels	$ProgressBar	$ToolbarSeparator
$ComboButton	$HorizontalSlider	$RadioButton	$Tooltip
$ContentPane	$InlineEditBox	$RadioMenuItem	$TooltipDialog
$CurrencyTextBox	$LayoutContainer	$Select	$Tree
$DataList	$LinkPane	$SimpleTextarea	$TreeObjectStoreModel
$DateTextBox	$Menu	$SplitContainer	$ValidationTextBox
$Dialog	$MenuBar	$StackContainer	$VerticalRule
$DojoxContentPane	$MenuBarItem	$StoreMemory	$VerticalRuleLabels
$DropDownButton	$MenuItem	$TabContainer	$VerticalSlider

Using Dojo Plugin Sample Code

A sample application is available for the Dojo page manager and helper plugins. In Studio, go to ZMdemo.dojo in the SAMPLES namespace, and compile the classes in that package if necessary. To run the application, open ZMdemo.dojo.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.dojo.HomePage.cls.

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

The Dojo page manager and helper plugins are also used in the HTML5 sample program (see “Using HTML5 Helper Sample Code”), which demonstrates how to implement two different instances of documentView.