Skip to main content

Upgrade Steps for Beta Program Customers

This appendix describes changes that affect code you created if you were in the Zen Mojo beta program.

Class Renaming

The Zen Mojo classes have been renamed. Rather than being contained in the %ZEN.Mobile package, the classes are now contained in the %ZEN.Mojo package.

Upgrade Steps

Namespace Changes

The documentView component and all plugins are now in the XML namespace "http://www.intersystems.com/zen/mojo" rather than "http://www.intersystems.com/zen/mobile". This means that it is necessary to update the use of XML namespaces in the pageContents of your page classes.

Also, the convention is now to use the namespace prefix mojo rather than zmf, for the Zen Mojo namespace.

Upgrade Steps

  • In the <pane> element, change this:

    xmlns:zmf="http://www.intersystems.com/zen/mobile"
    

    To this:

    xmlns:mojo="http://www.intersystems.com/zen/mojo"
    
  • In the rest of the pageContents XData block, change the zmf prefix to mojo

Example

Consider the following fragment, from a class that worked with Zen Mojo beta code:

XData pageContents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{<pane xmlns="http://www.intersystems.com/zen"
xmlns:zmf="http://www.intersystems.com/zen/mobile" layout="none">

<zmf:documentView id="mainView" 
...

To work with the released Zen Mojo, this fragment would have to look like the following instead:

XData pageContents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{<pane xmlns="http://www.intersystems.com/zen"
xmlns:mojo="http://www.intersystems.com/zen/mojo" layout="none">

<mojo:documentView id="mainView" 
...

Plugin Refactoring

The name of all the plugins have also changed, and there are now two kinds of plugins: page manager plugins and helper plugins.

Each documentView must contain exactly one page manager plugin and can contain multiple helper plugins. The page manager plugin defines the logic that controls the page, and the helper plugins contain the logic that defines the layout objects.

In the pageContents XData block, the documentView element must contain the page manager plugin as a child element. The page manager plugin must contain the helper plugins as its child elements, as follows:

<mojo:documentView id="mainView" additional attributes here...> 
   <mojo:somePageManagerPlugin>
      <mojo:someHelperPlugin/>
      <mojo:anotherHelperPlugin/>
   </mojo:somePageManagerPlugin>
</mojo:documentView>

This example shows indentations for added clarity; you do not need to include any indentation.

For information on the plugins, see Using Zen Mojo Plugins.

The core plugin has been removed. There is a new default helper plugin, which provides the $loop and $content elements that had formerly been in the core plugin. This helper plugin, however, does not provide the other layout objects of the old core plugin. It is expected that no customers are actually using those layout objects.

Upgrade Steps and Examples

The following list provides examples of specific replacements:

CHUI plugin

If you had used the Chocolate-Chip UI plugin, your documentView might have looked like this:

<zmf:documentView id="mainView" additional attributes here...> 
<zmf:chuiPlugin/>
<zmf:googleMapsPlugin/>
</zmf:documentView>

Replace this with the following:

<mojo:documentView id="mainView" additional attributes here...> 
<mojo:chuiPageManager>
<mojo:chuiHelper/>
<mojo:googleMapsHelper/>
</mojo:chuiPageManager>
</mojo:documentView>

If you had not included <mojo:googleMapsPlugin/> in the original, omit <mojo:googleMapsHelper/> in your new version.

Dojo plugin

If you had used the Dojo plugin, your documentView might have looked like this:

<zmf:documentView id="mainView" additional attributes here...> 
<zmf:dojoPlugin/>
<zmf:googleMapsPlugin/>
</zmf:documentView>

Replace this with the following:

<mojo:documentView id="mainView" additional attributes here...> 
<mojo:dojoPageManager>
<mojo:dojoDijitHelper/>
<mojo:dojo2DChartHelper/>
<mojo:dojoGridXHelper/>
<mojo:googleMapsHelper/>
</mojo:dojoPageManager>
</mojo:documentView>

If you had not included <mojo:googleMapsPlugin/> in the original, omit <mojo:googleMapsHelper/> in your new version. Also note that there are multiple Dojo helper plugins, and that you might not need all of these.

JQuery Mobile plugin

If you had used the JQuery Mobile plugin, your documentView might have looked like this:

<zmf:documentView id="mainView" additional attributes here...> 
<zmf:jqmPlugin/>
<zmf:googleMapsPlugin/>
</zmf:documentView>

Replace this with the following:

<mojo:documentView id="mainView" additional attributes here...> 
<mojo:jQMPageManager>
<mojo:jQMHelper/>
<mojo:googleMapsHelper/>
</mojo:jQMPageManager>
</mojo:documentView>

If you had not included <mojo:googleMapsPlugin/> in the original, omit <mojo:googleMapsHelper/> in your new version.

Core plugin

If you had used the core plugin, your documentView might have looked like this:

<zmf:documentView id="mainView" additional attributes here...> 
<zmf:corePlugin/>
<zmf:googleMapsPlugin/>
</zmf:documentView>

Replace this with the following:

<mojo:documentView id="mainView" additional attributes here...> 
<mojo:mojoDefaultPageManager>
<mojo:mojoDefaultHelper/>
<mojo:googleMapsHelper/>
</mojo:mojoDefaultPageManager>
</mojo:documentView>

If you had not included <mojo:googleMapsPlugin/> in the original, omit <mojo:googleMapsHelper/> in your new version.

Note that the Mojo default helper does not define all the objects that had been contained in the core plugin; it defines only $loop, $if, and $content. If you had used other layout objects, also add another helper plugin such as <mojo:HTML5Helper/> and update your layout graphs to use layout objects supported by that plugin.

Event Handling Changes

The documentView component no longer supports the onselect, onchange, and onevent callback attributes. Instead, this component automatically invokes the onselect(), onchange(), and onevent() methods of the associated template, if any. These methods have the following signatures:

ClientMethod onselect(key, value, docViewId) [ Language = javascript ]

ClientMethod onchange(key, value, final, docViewId) [ Language = javascript ]

ClientMethod onevent(eventType, key, value, docViewId) [ Language = javascript ]

Where:

  • key — key of the relevant layout object

  • value — value of that layout object, if any

  • docViewId — id of the documentView in which the select action, change action, or other event occurred

  • final — indicates whether the value passed is the final value

  • evtType — type of the event

These methods do nothing by default. Zen Mojo provides them so that you can customize the behavior of your page. For details, see “Event Handlers,” earlier in this book.

Upgrade Steps

To handle this part of the upgrade, use the following approach:

  1. Examine the onselect, onchange, and onevent callback attributes that are currently defined in your documentView components. For example:

    onselect="zenPage.myMainViewSelect(key,value);"
    

    Remove this attribute from the documentView.

    Also make a note of the id of the documentView.

  2. Examine the method referred to by the callback. Following recommended practices, this method would typically find the associated template and invoke a method in it, as in the following example:

    ClientMethod myMainViewSelect(key, value, final) [ Language = javascript ]
    {
        // check whether template has a handler for selection; if so, use it
        var template = this.getTemplate();
        if (template && template.myMainViewSelect) {
            return template.myMainViewSelect(key,value,final);
        }
    }
    

    This method is no longer needed. Remove it.

  3. In the template class, override the onselect() method (via Class > Refactor > Override). For simplicity, you can create this method as a simple dispatcher. Check the value of the docView argument and use that to determine which existing template method to invoke. For example:

    ClientMethod onselect(key, value, docViewId) [ Language = javascript ]
    {
        if (docViewId='mainView') {
               myMainViewSelect(key, value);
        }
    }
    

    If the page has other documentView elements that define onselect, repeat steps 1 and 2, and add additional branches to the new onselect() method.

Use a similar procedure for the now-removed onchange and onevent callback attributes.

FeedbackOpens in a new tab