Creating the Classes - Using Zen Mojo - Caché & Ensemble 2018.1

docs.intersystems.com

Using Zen Mojo

Creating the Classes

InterSystems: The power behind what matters

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

Choosing Plugins and Downloading Files

Early in development, you should decide which plugins you will use. In some cases, you will need to download files for use by a plugin. For a list of plugins and files that they need, see Using Zen Mojo Plugins.

Using the Zen Mojo Wizard

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:

Click File > New, click Zen, and click Zen Mojo Site.
Click OK.
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.
- Page Manager — (Required) Select a page manager.
- Chosen Helper Plugins — Select the helper plugins to use in this page class. To select a helper plugin, click an item in the Available Helper Plugins list. (To remove a helper plugin from the Chosen Helper Plugins, click it in that list.)
- Template Class Name — (Required) Specify the short class name for the template class. The class is created in the package given by Package Name.
- Application Class Name — Specify the short class name for the application class (if any). The class, if specified, is created in the package given by Package Name.
- Application Name — Specify the logical name of this 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.
Click Finish.

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 template class contains preliminary definitions of %OnGetJSONContent(), onGetContent(), and other methods.

The application class (if generated) contains preliminary parameter definitions and an empty XData Style block.

The next step is to examine the page class and modify its pageContents XData block as needed. See “Creating a Basic pageContents Definition,” later in this chapter.

Creating Zen Mojo Classes Manually

As an alternative to using the Zen Mojo wizard, you can create the initial application class, page class, and template class manually. This section describes the requirements.

Defining the Zen Mojo Application Class

A Zen Mojo application class is optional.

To define a Zen Mojo application class, define a class that extends %ZEN.Mojo.baseApplication and optionally include a Style XData block in this class. For details, see the chapter “Using Style Sheets.”

For additional options for the application class, see the class references for %ZEN.Mojo.baseApplication.

Defining a Zen Mojo Page Class

To create a basic Zen Mojo page class, create a class that extends %ZEN.Mojo.basePage. In your class:

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";

Define the TEMPLATECLASS parameter. For the value, specify the name of a Zen Mojo template class, which is discussed later in this chapter. For example:

Parameter TEMPLATECLASS = "ZMdemo.dojo.baseTemplate";

Define the PROVIDERLIST parameter. For the value, specify a comma-separated list of the names of the content objects needed for this page. This list includes the major branches of %OnGetJSONContent() in your template class (see the following subsection “Defining a Template Class”). For example:
```
Parameter PROVIDERLIST = "data,layout";
```
Override the inherited pageContents XData block and create a basic definition of the page (see the following section, “Creating a Basic pageContents Definition”).

In this definition, you typically use one or more plugins. Make a note of the plugins you use.
Update the JSINCLUDES parameter and CSSINCLUDES (or CSS3INCLUDES) parameters as needed by the plugins. For details, see Using Zen Mojo Plugins.

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.

Defining a Template Class

To create a template class, create a class that extends %ZEN.Mojo.Component.contentTemplate. In your class, do the following as a starting point:

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.

For example:
```
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.
Create a preliminary version of the onGetContent() method, which acts as the dispatcher for all requests for content objects. See “Defining onGetContent(),” in the previous chapter.
Create a preliminary version of the %OnGetJSONContent(), which returns data objects from the server. See “Defining %OnGetJSONContent(),” in the previous chapter.
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.

Creating a Basic pageContents Definition

In the page class, the pageContents XData block defines the contents of the primary area of the page, as described in “Parts of a Zen Mojo Page,” earlier in this book. The following shows the skeletal structure of this XData block:

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

In place of your contents here, include one or more <mojo:documentView> elements. For each of these, include a page manager plugin and all needed helper plugins (see the next section, “Registering Plugins”). Also specify the id attribute of each documentView, as well as either or both of the ongetlayout and ongetdata XML attributes, depending on your needs. For ongetlayout and ongetdata, use values like the following:

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.

Registering Plugins

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>

For details, see Using Zen Mojo Plugins.

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.

Using Multiple documentViews

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.

Next Steps

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:

Read the relevant chapters of Using Zen Mojo Plugins to learn about additional implementation steps that are required or recommended for the plugins you are using.

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.
Create layout methods. See “Defining Layout Methods.”
Define event handlers and other options to specify the behavior of the page. The chapter “Summary of Callbacks and Event Handlers” summarizes the options. For information on options you can use within the event handlers and callbacks, see the following chapters:
Define and apply style information as needed. See the chapter “Using Style Sheets.”

Later chapters in this book discuss additional topics.