The jMaki Widget Model

A jMaki widget is a reusable component that is made up of an HTML template and a corresponding JavaScript file. An optional CSS file may be provided by the widget. This document details the jMaki widget model and what initialization parameters that are passed to each widget. For more information on where to put widgets in your application see jMaki Applications.

Template - component.htm

jMaki ensures that the HTML templates get rendered with unique and instance specific parameters. The following is a template of a simple <div> element with unique id.

<div id="${uuid}"></div>

component.htm Example

The ${uuid} token is replaced when jMaki processes the template as it renders the page. For a full list of tokens and the properties they map to see Widget Properties.

Behavior - component.js

jmaki.namespace(""); = function(wargs) {
    // widget code here    

component.js example

Notice that the entire widget is placed in a namespace and that it is called "Widget". This is because all jMaki widgets are in essence packages and the Widget is the constructor which is passed an the widget arguments. Widget JavaScript code not conforming to this convention will not be loaded.

Widget Properties

The server-side runtime passes instance parameters for an individual widget to the jMaki JavaScript runtime as a function call with the instance parameters as an object literal. The JavaScript runtime then passes instance parameters to the widget as it is created. Following are the arguments that are passed and the token names that are replaced in the widget component.htm template.

Property NameTemplate TokenWidget ArgumentsValue
scriptN/AN/AThe URI to JavaScript for the widget.This is basically an override for the component.js.
templateN/AN/AThe URI to the template.This is an override for the component.htm.
styleN/AN/AThe URI to the styles used for this widget.This is an override for the component.css.
name${name}wargs.nameThe name of the component. This is the only required argument.
id${uuid}wargs.uuidThe unique value associated to each component instance. This value is autogenerated by the server runtime and may be overriden using an 'id' argument.
args${args}wargs.argsA JavaScript object literal that may contain any number of JavaScript key value pairs.
service${service}wargs.serviceThis is the service value associated with each component instance. When a service is used, the data used by the widget is loaded asynchronously using an Ajax call after the widget has loaded.
value${value}wargs.valueThe service value is an inline value given to the widget that needs to be in JavaScript object literal format.

The most powerful attribute is the args attribute as it can be used to map any set of generic properties to a widget as an object literal. These properties may then be accessed from the widget instance (via the widget.args property). Care must be taken to properly document the various properties as they can differ on a widget to widget basis.

With JSP and JSF, the properties are passed in using tag attributes on the tag matching the name of the property. In all cases the properties must be included 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.

Widget Initialization

jMaki will do the following after the page onload event fires.

  1. Lookup up the constructor function for each widget in the order they are defined in the page. Constructors must be named jmaki.[widget name].Widget. For example, in the case of a widget with the name "" the constructor that is searched for is Note that all constructors are required to be under the jmaki namespace to keep all jMaki JavaScript objects from cluttering the JavaScript global scope.
  2. Call new on the constructor passing the widget instance parameters as an object literal.
  3. Place the widget instance contained in the jmaki.attributes Map with the unqiue ID (uuid) as the key. You can later get a handle of this widget instance using the call jmaki.getWidget(uuid)

Post Load Event

If your widget requires post initialization you can provide a postLoad function which will be called following the widget initialization.

// define the namespaces for foo and bar
jmaki.namespace(""); = function(wargs) {
    this.postLoad = function() {
        var this = jmaki.attributes.get(wargs.uuid);
        // do something with this

component.js example with a postLoad function

Providing a public postLoad is a good place to register glue listeners and load data asynchronously.

Widget Destruction

You can provide a code that will unwire events and nodes that may lead to memory leaks by providing a destroy function on your widget. This function will be called when the clearWidgets function is called.

// define the namespaces for foo and bar
jmaki.namespace(""); = function(wargs) {
    var container = document.getElementById(wargs.uuid);
    this.destroy = function() {
        var this = jmaki.attributes.get(widget.uuid);
        // do something with this

component.js example with a destroy function

While not required, it is recommended you provide a public destroy method in your widgets to clean up widget resources.


JavaScript Recommendations for AJAX Component Writers - Essential if you are going to write widgets.