Using Zen Mojo
Creating the Classes
|
|
When you create a Zen Mojo application, most of the work is the task of defining the template class or classes. So that you can start that work as quickly as possible, this chapter describes the prerequisite work of defining a set of interrelated classes as a starting point. It discusses the following topics:
Studio provides a convenient wizard that you can use as a starting point for this set of classes. The wizard generates a page class, a template class, and (optionally) an application class. To use this wizard:
-
-
-
Specify values for some or all of the following options:
-
Package Name (Required) Specify the name of the package to contain the classes.
-
Page Class Name (Required) Specify the short class name for the page class.
-
Page Name Specify the logical name of this page within its application.
-
-
-
-
-
-
Domain Specify a short string. This option specifies the localization domain of any localizable strings generated by this class.
Other than the class names, you can change all the details creating the classes.
-
Studio then generates a Zen Mojo page class, template class, and (if you specified
Application Class Name) application class, all in the package that you specified for
Package Name.
The page class contains preliminary parameter definitions, a preliminary pageContents XData block, and an empty XData Style block. It also specifies the
JSINCLUDES and
CSSINCLUDES class parameters, based on the helper plugins you selected.
The application class (if generated) contains preliminary parameter definitions and an empty XData Style block.
A Zen Mojo application class is optional.
-
Optionally define the
APPLICATION parameter. For the value, specify the name of the matching application class, from the
previous section. For example:
Parameter APPLICATION = "ZMdemo.dojo.Application";
-
Parameter TEMPLATECLASS = "ZMdemo.dojo.baseTemplate";
-
Parameter PROVIDERLIST = "data,layout";
-
In this definition, you typically use one or more plugins. Make a note of the plugins you use.
-
In most cases, these parameters specify external JavaScript libraries and CSS style sheets, respectively, to be loaded into the page instance. For the Google maps helper plugin, however,
JSINCLUDES indicates the URL of the Google Maps API. The libraries are loaded in the order in which they are listed, from left to right; this is important if one library depends upon another.
Note that not all plugins require these parameters.
-
Define the
DOMAIN parameter. This parameter specifies the localization domain of any localizable strings generated by this class. For example:
Parameter DOMAIN = "MyZenMojoApp";
This parameter is not required, but InterSystems recommends that you always specify it.
-
Define the
NAMESPACE parameter. This parameter specifies the XML namespace to which this template belongs. Each Zen Mojo template should have a unique combination of
NAMESPACE and short class name.
Parameter NAMESPACE = "http://www.intersystems.com/zen/mojo/demo/dojo";
-
Define the
DOMAIN parameter. This parameter specifies the localization domain of any localizable strings generated by this class. For example:
Parameter DOMAIN = "MyZenMojoApp";
This parameter is not required, but InterSystems recommends that you always specify it.
-
-
-
Ensure that in the corresponding
page class, the
PROVIDERLIST parameter lists the name of each possible data object. The server-side page object cannot return data objects unless the
PROVIDERLIST parameter lists those objects.
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">
your contents here
</pane>
}
return zenPage.getContent('contentObject',key,criteria);
Note that
getContent() is a built-in page method and
contentObject is the name of a content object provided, ultimately, by the template.
The following shows an example:
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" developerMode="true"
ongetlayout ="return zenPage.getContent('mainViewLayout',key,criteria);">
<mojo:mojoDefaultPageManager>
<mojo:HTML5Helper/>
</mojo:mojoDefaultPageManager>
</mojo:documentView>
</pane>
}
In this example, child elements are indented for readability. It is not necessary for you to do the same.
You should register one or more plugins for use in each documentView. To do so:
-
Include one page manager plugin as a child element of <mojo:documentView>.
-
Include one or more helper plugins as child elements of the page manager plugin.
The following shows the general structure (with extra indentation for clarity; you do not need to include this indentation):
<mojo:documentView id="mainView" other attributes...>
<mojo:somePageManager>
<mojo:someHelper/>
<mojo:anotherHelper/>
<mojo:yetAnotherHelper/>
</mojo:somePageManager>
</mojo:documentView>
If you use custom plugins, it is important to consider the order in which you list the helper plugins, because of the possibility of plugin conflict. A
plugin conflict occurs if a single documentView uses multiple helper plugins and those plugins have layout objects with the same name. For all plugins provided by InterSystems, each layout object has a unique name, but custom plugins could potentially have layout objects with the same names as InterSystems layout objects. This is not an error condition, but rather a scenario that requires special handling. For more information, see
Detecting and Resolving Plugin Conflicts in
Using Zen Mojo Plugins.
Depending on the plugins you use, a page can contain multiple documentViews that can affect each other. For example, you could have two documentViews, side by side. The left documentView could display options that control what is shown in the right documentView.
For some plugins, only one documentView is supported. For details, see
Using Zen Mojo Plugins. In general, if a page manager plugin is intended for use on mobile devices, that plugin uses the entire page and does not support multiple documentViews.
Now that you have created a set of Zen Mojo classes to use as a starting point, do the following to create your Zen Mojo application:
-
Important:
Depending on the page manager plugin you are using, you may need to implement additional methods in the page class to make your page contents visible.
-
-
-
Later chapters in this book discuss additional topics.