Creating Plugins

This chapter describes the basic requirements to follow if you create your own plugin classes. It discusses the following topics:

Creating a Page Manager Plugin

To create a page manager plugin, your page class must meet the following requirements:

It must extend %ZEN.Mojo.Plugin.basePageManagerOpens in a new tab.
It must specify a logical name. To do this, include the pluginName property and specify its InitialExpression. By convention, specify the same name as used in the XData block (see the next item).
It can specify the XMLNAME parameter. This is useful if you want to include the version number (with dashes and period characters) in the name of the plugin, as used in the XData block. If XMLNAME is not specified, the name of the plugin defaults to the short class name.
It can specify a version. To do this, include the version property and specify its InitialExpression.
It must implement the onCheckLibraries(), afterRenderDocument(), and afterPopDocument() methods (see the following section for details).

Required Page Manager Methods

The following methods of the page class are required by any page manager plugin.

onCheckLibraries()

  ClientMethod onCheckLibraries() [ Language = javascript ]

Alerts the user if the needed libraries are not available. Zen Mojo invokes this method when it displays a Zen Mojo page that uses this page manager class. This method should perform a suitable check on whether the libraries needed by this plugin class are available to the page class. If the libraries are not available, the method should use alert() to display a warning to the user.

For example:

  ClientMethod onCheckLibraries() [ Language = javascript ]
  {
    if (typeof $ === 'undefined') {
      alert('jQuery library is not loaded correctly. Check your includes.');
      return false;
    } else if (typeof $.UIGoToArticle === 'undefined') {
      alert('Chocolate Chip UI library is not loaded correctly. Check your includes.');
      return false;
    }
    return true;
  }

If no libraries are needed, the method can simply return true.

afterRenderDocument()

ClientMethod afterRenderDocument(docView, displayMode, html) [ Language = javascript ]

where docView is the id of the documentView instance, displayMode is the current display mode of the instance, and html is the HTML generated for this instance. displayMode can be 'layout', 'data', 'html', or 'iframe'

This method controls how Zen Mojo defines the DOM (Document Object Model) used by the browser. The sequence of events is as follows:

The page is requested.
Zen Mojo generates the HTML needed for each documentView.
If the property suppressRender is false, Zen Mojo inserts the HTML into the DOM.
Otherwise, Zen Mojo skips this step.
Zen Mojo calls afterRenderDocument().

If this method does not need to do anything, it can simply return null.

afterPopDocument()

ClientMethod afterPopDocument(docView, render) [ Language = javascript ]

Controls how the page manager handles transitions when popDocument() is called. The sequence of events is as follows:

A client method calls popDocument().
Zen Mojo renders the new document as described in the afterRenderDocument() entry.
Zen Mojo calls afterPopDocument().

If this method does not need to do anything, it can simply return null.

Creating a Helper Plugin

To create a helper plugin, your helper class must meet the following requirements:

It must extend %ZEN.Mojo.Plugin.baseHelperPluginOpens in a new tab.
It must specify a logical name. To do this, include the pluginName property and specify its InitialExpression. By convention, specify the same name as used in the XData block (see the next item).
It can specify the XMLNAME parameter. This is useful if you want to include the version number (with dashes and period characters) in the name of the plugin, as used in the XData block. If XMLNAME is not specified, the name of the plugin defaults to the short class name.
(Recommended) It can specify a version. To do this, include the version property and specify its InitialExpression.
It must implement the onCheckLibraries(), getFeatures(), and createLayoutObjects() methods (see the following section for details).

Required Helper Plugin Methods

The following methods of the helper class are required by any helper plugin.

onCheckLibraries()

ClientMethod onCheckLibraries() [ Language = javascript ]

Alerts the user if the needed libraries are not available. Zen Mojo invokes this method when it displays a Zen Mojo page that uses this helper plugin class. This method should perform a suitable check on whether the libraries needed by this plugin class have been loaded (see the example for the page class version of onCheckLibraries(), shown previously in “Required Page Manager Methods”). If the libraries are not available, the method should use alert() to display a warning to the user..

If no libraries are needed, the method can simply return true.

getFeatures()

ClientMethod getFeatures() [ Language = javascript ]

Returns an array of objects, with one object for each layout element supported by this helper plugin. Each object in this array must include the identifier property, whose value must be the logical name of the layout element. Zen Mojo uses this information internally to determine how to dispatch rendering requests.

createLayoutObjects()

ClientMethod createLayoutObjects(type, instance) [ Language = javascript ]

Generates the HTML for each layout object supported by this helper plugin. Zen Mojo calls this method once for each layout object in the layout graph. The arguments are type (the type of layout object) and instance (the layout object itself).

This method should define instance.$render for each possible type, and instance.$render should return the HTML that is appropriate for that type.

If you want to expose a way to retrieve specific generated HTML elements, create a unique id for those element. To generate a unique id, use the Zen Mojo $makeId() function, which generates an unique id in all scenarios, even if you are using the document stack. The following shows an example:

html.push('<h1 id="'+this.$makeId('caption')+'" class="'+captionClass+'" style="'+zenGet(this.captionStyle)+'">');

Within the logic that defines the HTML for a given layout object, be sure to pass a different string value to this function for each HTML element that must have an id.

Creating Plugin Documentation

To create plugin documentation for a page manager, specify comments for that class (with three slashes at the start of each line). The Plugin Documentation app automatically displays these comments (see “Using the Plugin Documentation and Widget Reference Apps”).

To create plugin documentation for a helper plugin, define an associated class as follows:

It must extend %ZEN.Mojo.Plugin.baseHelperDocumentationOpens in a new tab
Its name must be fullPluginClassNameDocumentation
It must implement the getDocumentation() method as follows:
```
ClientMethod getDocumentation(identifier) [ Language = javascript ]
```
Where identifier is the type of a layout object provided by the helper plugin. For each possible identifier, this method should return an object with the following properties:
- description — Short description of the layout object.
- attributes — Array of objects that describe the attributes supported for this layout object. Each object in this array should specify the following properties:
  - name — Name of the attribute
  - type — Type of the attribute ( valid types are string, number, boolean, date, object, array, or function)
  - description — Description of the attribute
For example:
```
{ description: 'Description of the identifier e.g. $loop', 
  attributes: [ {
    name:'value',
    type:'string',
    description:'Holds the value of the html element'
  } ]
}
```