Working with Plugins
This chapter discusses the following topics:
Overview — provides a simple description of helper plugins, which define layout objects, and page manager plugins, which contain specified sets of helper plugins.
Choosing Plugins for Your Application — lists the available helper and page manager plugins, and discusses how each one might be used.
Adding Plugins to the Page Class — describes the basic procedures for specifying plugins and related resources in your page class.
Detecting and Resolving Plugin Conflicts — describes how to resolve conflicts when two plugins use the same name for a layout object.
Implementing Required Methods in the Page Class — explains when and how to implement the adjustContentSize() and onPageShow() methods.
Using Plugin Resources in a Template Class — demonstrates how to use special methods provided by helper plugins and layout objects.
A Zen Mojo application consists of the following primary components:
one or more template classes, which determine what is displayed on your web page
a set of plugin classes, which define the layout objects used by the templates
the page class, which specifies the plugin classes and other resources available to your template classes
A set of plugins must by specified for each documentView defined in the pageContents XData block of your page class (for details, see “Adding Plugins to the Page Class” later in this chapter).
Each documentView element must specify a single page manager plugin, which will contain one or more helper plugins. Each helper plugin defines a set of layout objects. These elements perform the following functions:
A page manager plugin provides the interface between the templates and a set of helper plugins.
Helper plugins define layout objects and other library-specific resources used by template classes.
When you specify a helper plugin in your page class, the layout objects defined in that helper become available to your template classes. A helper plugin may also provide additional resources, such as utility methods for common tasks.
Layout objects use library functions to produce HTML strings.
Choosing Plugins for Your Application
The following helper plugins can be used in any application:
Zen Mojo Default helper — provides utility layout objects used by most helper plugins. It can be used by any page manager (not just the Default page manager).
HTML5 helper — provides layout objects for most standard HTML5 elements.
Bootstrap helper — provides layout objects for many of Twitter Bootstrap’s enhanced versions of HTML5 elements.
Chart.js helper — provides layout objects for the lightweight Chart.js library.
Highcharts helper — similar to Chart.js, but Highcharts provides a much greater variety of charts.
Google Maps helper — provides layout objects that support an online connection to the Google Maps API.
These helper plugins can be used with any page manager.
The Default page manager supports only the previously listed helpers.
The ChocolateChip-UI page manager supports a helper containing layout objects for the enhanced ChocolateChip-UI versions of HTML5 elements. This page manager is best for relatively simple mobile applications.
The jQuery Mobile page manager supports a helper containing layout objects for the long list jQuery Mobile enhanced HTML5 elements. This page manager may be preferable for complex mobile applications.
The Dojo page manager supports three helpers for three different APIs in the Dojo Toolkit. This page manager is best for complex desktop applications.
Adding Plugins to the Page Class
Plugins are added to your application by specifying some or all of the following items in the page class:
Parameter JSINCLUDES As STRING = "jquery-1.11.3.min.js,bootstrap-3.3.5/js/bootstrap.min.js" Parameter CSSINCLUDES As STRING = "bootstrap-3.3.5/css/bootstrap.min.css"
Caché assumes that /csp/broker is the root directory for each of these paths and filenames.
Plugin page manager and helper classes
In the pageContents XData block of your page class, you must register one or more plugins for use in each documentView (see “Basic Definition of a Zen Mojo Page” in the book Using Zen Mojo). To do so:
Include only 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 example shows the general structure (with optional indentation for clarity):
<mojo:documentView id="mainView" ongetlayout = "return zenPage.getContent('layout',key);"> <mojo:mojoDefaultPageManager> <mojo:bootstrap-3.3.x-Helper/> <mojo:mojoDefaultHelper/> </mojo:mojoDefaultPageManager> </mojo:documentView>
The order in which you list helper plugins is important. When two plugins use the same name for a layout object, your application will use the layout object from the plugin listed first. Later instances of layout objects with the same name will be ignored. See “Detecting and Resolving Plugin Conflicts” for details.
Required page methods
Depending on the plugins you choose, your page class may have to implement certain required methods. See “Implementing Required Methods in the Page Class” for details.
For each plugin or set of plugins, this book describes all page class requirements at the beginning of the relevant chapter. See the Bootstrap chapter for the information used in the previous examples.
Detecting and Resolving Plugin Conflicts
It is important to consider the order in which you list the helper plugins, in the case of plugin conflict. A plugin conflict occurs when a single documentView uses multiple helper plugins and those plugins have layout objects with the same name. A plugin conflict is not an error condition, but rather a situation that requires special handling. There is a default behavior and a way to override it.
In the case of a plugin conflict, by default, Zen Mojo uses the layout object rendering logic as given in the helper plugin that is listed first. If you do not want the default behavior, you can modify it.
To override the default handling, do the following:
Specify the onresolvepluginconflicts callback attribute of the documentView. Use a value like the following:
In this callback, you can use the variable conflicts, which Zen Mojo provides. This variable is an array that contains the names of layout objects defined by more than one plugin.
Implement the method to which your callback attribute refers. In this method, use the setPluginMapping() method of the documentView instance. The following shows a simple example:
For any given layout object type, your implementation can specify which helper plugin should perform the rendering for that layout object type.
Implementing Required Methods in the Page Class
Depending on the plugins you choose, your application may have to implement the adjustContentSize() method or the onPageShow() callback, as described in the following sections:
Overriding the adjustContentSize() Method — this method specifies the size and position of each documentView. This is an existing page method that requires an override when using the Default or Dojo page managers.
Implementing the onPageShow() Callback — this callback method performs extra processing before the page is displayed. It is required when the Google Maps helper is used, and optional in all other cases.
Overriding the adjustContentSize() Page Method
The purpose of the adjustContentSize() method is to specify the size and position of each documentView, based on the current width and height of the pageContents pane, which varies depending on the screen size and current rotation. This method is called when the basePage.onlayoutHandler() event is triggered. It has the following signature:
Where load indicates if the page is being loaded. This argument is 1 when the page is loaded and is 0 at other times. width and height are the current width and height, respectively, of the pageContents pane, in pixels.
In this method, it is typically necessary to do the following for each documentView on this page:
Get a reference to the documentView and call its setSize() method. The following example gets an instance of documentView with id mainView, and uses the width and height arguments received when adjustContentSize() is called from onlayoutHandler():
var mainView = zen('mainView'); mainView.setSize(width, height);
where width and height are the desired width and height in pixels.
If there is more than one documentView on the page, specify the position of the top, left corner of each documentView. Use the documentView.getEnclosingDiv() instance method to get the <div> that contains the instance, then specify the style.top and style.left properties of the <div>. Specify the values as 'nnnpx' where nnn is an integer. For example:
var mainDiv = mainView.getEnclosingDiv(); mainDiv.style.top = '0px'; mainDiv.style.left = '0px';
In the following example, there are two documentView instances. The left one is one-fourth of the width of the pageContents area, and the right one uses the rest of the space.
Implementing the onPageShow() Callback
You can specify the optional onPageShow callback attribute in the page manager element of your pageContents XData block, as demonstrated in the following example:
This attribute defines the callback method to be invoked after rendering the layout objects for the plugin. For example, you could implement a method that adjusts the display for a layout object provided by a different plugin. Each page manager plugin contains appropriate code to invoke the callback if it has been defined.
Currently, the callback is only required when using the Google Maps plugin, which needs a way to resize the map after rendering the other page items. The following example implements a callback method that triggers a Google Maps resize event:
Specify the onPageShow callback attribute of the page manager element. This example uses the jQuery Mobile page manager:
In your page class, implement a method similar to the following:
This example assumes that the application defines the 'maps-demo' layout key, and that the documentView id attribute is 'mainView'. See “Custom Google Maps Helper Plugin Methods” for information on the resizeMap() method.
Using Plugin Resources in a Template Class
Both helper plugins and layout objects sometimes contain methods that provide object-specific utilities, as described in the following sections:
Layout Object Methods — provide extra functionality to individual layout objects.
Helper Plugin Methods
For each plugin, information on available plugin methods is listed in the relevant chapter under the heading “<Plugin-name> Helper Plugin Methods”. Some chapters also include a more detailed “Custom <Plugin-name> Helper Plugin Methods” section (for example, the resizemap() function used in this example is described under “Custom Google Maps Helper Plugin Methods” in the Google Maps chapter).
Layout Object Methods
Individual layout objects may also contain special methods. For example, many layout objects have a $refresh method. The following call would refresh the display of the layout object identified by key 'person1':
For each plugin, details on available layout object methods are listed in the relevant chapter under the heading “Custom <Plugin-name> Layout Object Methods”.