Using jMaki Widgets

Before starting you learn more about the jMaki Widget which will describe the seperate components that make up a widget. It would also be good to review thejMaki Application Structure to learn more about what resources need to be put in what places.

This document explains how to define widgets and describes how to configure individual instances of widgets. This document will also review the life cycle of a jMaki widgets.

Identifying jMaki Widgets

The "name" attribute is the key used to put all the components together. The name of a widget maps to a directory that contains the resources needed for a widget. A widget is generally made up of a html template (component.htm), behavior (component.js), and styles (component.css). The name of a widget is similar to specifying a Java package or directory where the jMaki widget resources live. The directories are separated using a "." and the last directory contains the resource files that make up the widget. The rest of the directory structure is used to organize the resources so that they do not conflict with other widget resources such as images and possibly other JavaScript code. This structure is needed to uniquely specify the widget code and make the widget resources accessible to a web client.Following is an example of a jMaki widget.

In JSP / JSF

<widget name="my.widget"/>

In PHP:

<?php addWidget("my.widget"); ?>

In the example, the jMaki server-side component will look in the same directory as the widget for a directory called "my" which contains a directory "widget". If this directory is found, jMaki will then look for a file called my/widget/component.js and my/widget/component.htm. If not found and you are using JavaServer Faces, the jMaki server-side component will look under the /resources/my/widget directory for the widget and it's resources (e.g. /resources/my/widget). Placing widgets resources relative to the page in which the widgets works if you want to have customized widgets, however, it is recommended that you place your widgets under the /resources/my/widget as they can be used from any directory in the web application.

The life-cycle of a jMaki Widget

Now that we know what widgets are and have seen how widgets names and types are used let's dig a little deeper and see how widgets are created and initialized. jMaki widgets are rendered in a two step process which spans both the client and the server. The following diagram details the lifecycle in more detail.

1. jMaki Widget Defined Encountered
2. Resource References for the Widget are Rendered to the Page - The JSP tag or JSF component renders the necessary HTML content with the proper linkages to the corresponding files that make up a jMaki widget. For example, the CSS styles defined in the component.css of a widget. If the widget is of a specific type, such as Dojo, the script tags for those dependent libraries will also be rendered to the page.
3. Template Content is rendered to the Page - The template content from the component.htm file is rendered to the page. The template content contains tokens such as ${uuid} which represent a unique identifier of the widget. These identifiers are replaced on a per widget basis as the HTML is initially rendered. Content will be further rendered on the client after the page loads.
4. jMaki Bootstrapper is Initialized - A script element containing the jMaki boostrapper (jmaki.js) is rendered to the page before any other script references are rendered by the JSP tag or JSF component. This script creates a globally scoped JavaScript object named "jmaki" which contains properties and functions to register, load and support jMaki widgets.
5. Widget instance is created and registered with the Bootstrapper - After a widget's template text has been rendered, the widget along with its instance parameters is registered with the jmaki bootstrapper. Registration is done using the jmaki.addWidget function where the instance parameters used to initialize the widget are passed as object literals.
6. Widgets are Initialized and Rendered to the Page - Following the JavaScript "onload" event the jmaki boostrapper will iterate through the widgets that were registered and initialize each instance. Each widget is evaluated using the JavaScript code from the corresponding component.js. A locally scoped object literal named widget containing the initialization parameters (properties) for the widget such as the the unique identifier of the widget, service name, and arguments that were defined for the widget is used to initialize the widget instance. These parameters correspond with those that were rendered to page for that widget instance.
7. The Page is made available - Once rendered, the page is made available for further event processing.

The key steps for the the parameters getting passed by the server rendered code to the JavaScript instance are found in steps 3, 5 and 6 above. Parameters such as the widget identifier from template content in component.htm are rendered in step 5 and are passed to the JavaScript runtime (the jmaki.addWidget bootstrapper). The same parameters are then passed as properties in step 6 to the component.js script that initializes the widget instance. jMaki is all about parameterized JavaScript. Now that we have seen how the parameters are passed between the Java and JavaScript worlds lets look in more detail at what parameters may be passed.

jMaki Widget Attributes

jMaki widget instances can be configured with a variety of properties which are described in the Widget Model documentation

In JSP and JSF the attribute names matching the property names are used to configure a widget.

In PHP the order of the function parameters is the following:

addWidget(name, service, args, value, uuid);

The only required parameter is the name and if you need to skip any arguments you can do so by passing null as the value. In all cases the properties must be encluded in double quotes. All JavaScript properties used with the args and value are JavaScript object literals and should use single quotes or escaped double quotes.

Example of a jMaki Widget

Following is an actual JSP file declaring two jMaki components.

<%@ taglib prefix="a" uri="http://jmaki/v1.0/jsp" %>
<a:widget name="dojo.clock"  />

The same widget may be defined in PHP as:

<?php require_once 'Jmaki.php'; ?>
<?php addWidget('dojo.clock'); ?> 

The JSP and PHP are rendered to HTML as:

<script type="text/javascript" src="http://localhost:8084/WebApplication2/resources/jmaki.js"></script>
<script type="text/javascript">jmaki.webRoot='http://localhost:8084/WebApplication2';jmaki.resourcesRoot ='/resources';jmaki.xhp ='http://localhost:8084/WebApplication2/xhp';</script>
<script type="text/javascript" src="http://localhost:8084/WebApplication2/glue.js"></script>
<script type="text/javascript" src="http://localhost:8084/WebApplication2/resources/system-glue.js"></script>
<script type="text/javascript">if (typeof djConfig =='undefined') djConfig = { parseWidgets: false, searchIds: [] };</script>
<script type="text/javascript" src="http://localhost:8084/WebApplication2/resources/dojo/resources/libs/dojo/v0.4.3/dojo.js"></script>
<script type="text/javascript" src="http://localhost:8084/WebApplication2/resources/dojo/clock/component.js"></script>

<span id="dojo_clock1"></span>
<script type="text/javascript">jmaki.addWidget({widgetDir:'http://localhost:8084/WebApplication2/resources/dojo/clock',uuid:'dojo_clock1',name:'dojo.clock',sourceURL:'http://localhost:8084/WebApplication2/'});</script>

In the case of both platforms the script and style references are the same. This is what allows one set of widgets to be supported on multiple server runtimes because the JavaScript, CSS, and template code which make up the widgets and client-side infrastructure are the same.

The bootstrapper ("jmaki.js") is loaded first as it manages the loading and initialization of all the widgets. The parameters that make an individual widget unique are passed to the bootstrapper for each component instance as can be seend in the following snippet:

<script type="text/javascript">jmaki.addWidget({widgetDir:'http://localhost:8084/WebApplication2/resources/dojo/clock',uuid:'dojo_clock1',name:'dojo.clock',sourceURL:'http://localhost:8084/WebApplication2/'});</script>

These parameters are passed to the constructor for each widget (defined in widget's "component.js" file). The processing of the parameters is up to the widget.