Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new window

For information on migrating to InterSystems IRISOpens in a new window, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions pageOpens in a new window (login required).

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 in a new window.

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 in a new window and GridX at in a new window.

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:

Copy code to clipboard

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”).


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

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

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

Deprecated Dojo Plugin Classes

The %ZEN.Mojo.Plugin.dojoPageManagerOpens in a new window, %ZEN.Mojo.Plugin.dojo2DChartHelperOpens in a new window, %ZEN.Mojo.Plugin.dojoDijitHelperOpens in a new window, and %ZEN.Mojo.Plugin.dojoGridXHelperOpens in a new window 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:

Copy code to clipboard

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 ]
        var topContainer = zen('leftView').getItemByKey('layoutContainer-1');
        if (topContainer) {
    Copy code to clipboard

    (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%;}
    Copy code to clipboard

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
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:

Copy code to clipboard

(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”):

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


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

FeedbackOpens in a new window