Using Zen Mojo Plugins
Creating Plugins
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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:
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:
  1. The page is requested.
  2. Zen Mojo generates the HTML needed for each documentView.
  3. If the property suppressRender is false, Zen Mojo inserts the HTML into the DOM.
    Otherwise, Zen Mojo skips this step.
  4. 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:
  1. A client method calls popDocument().
  2. Zen Mojo renders the new document as described in the afterRenderDocument() entry.
  3. 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:
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: