Getting Started With Project jMaki for the GlassFish v3 Application Server

Adding a jMaki Widget to a Page

Once you have set up your application and created a page using one of the templates, you can add a jMaki widget to the page. Developing the plotCity Application Using Project jMaki and the NetBeans IDE 6.1 details how to build a jMaki application using the NetBeans IDE 6.1 plug-in, using plotCity as an example. When you drag and drop a widget on a page using the plug-in, it does three things:

Adds the widget resources to the application.
Adds the jMaki tag library definition to the page.
Adds to the page a custom jMaki widget tag that references the widget and sets the widgets attributes to default values.

For example, if you added the jMaki Dojo combobox widget to a page, the IDE does the following:

Adds the component.js and component.htm files to the resources/dojo directory of your application
Adds the third-party Dojo widget code to the resources/libs directory of your application.

Adds the following tag library declaration and widget tag to your page:

<%@ taglib prefix="a" uri="http://jmaki/v1.0/jsp" %>
...
<a:widget name="dojo.combobox"
   value="[
       {label : 'Alabama', value : 'AL'},
       {label : 'California', value : 'CA'},
       {label : 'New York', value : 'NY', selected : true},
       {label : 'Texas', value : 'TX'}	           
    ]" />

As the preceding code shows, the widget tag is a custom tag from the jMaki tag library. This tag represents a JSP tag handler.

When you drag and drop the combobox widget onto a page, the IDE initializes the tag with the name of the widget using the name attribute. The name is in dot notation similar to Java^TM package names. It refers to the directory that contains the widget's resource files. In this case, the combobox widget's resources are in the dojo/combobox directory.

The IDE also initializes the widget with a default value using the value attribute. As most jMaki widgets do, the combobox widget accepts data in JSON format. You can use the value attribute to reference this data. For example, the default value that NetBeans gives the combobox widget is:

[
{label : 'Alabama', value : 'AL'},
{label : 'California', value : 'CA'},
{label : 'New York', value : 'NY', selected : true},
{label : 'Texas', value : 'TX'}
]

The next section details how to populate a widget with your own data.

The widget tag requires you to set a different set of attributes depending on which widget the tag represents. The best way to determine what attributes a widget expects is to look at the widget's widget.json file by right-clicking on the widget tag in the IDE and selecting jMaki from the pop-up menu. You can use the customizer that pops up to edit the values of the attributes.

The following table lists the most common attributes.

Table 1 Common jMaki Attributes


Attribute	Required	Value
id	No	Identifies the widget instance so that you can reference the widget.
name	Yes	The name of the widget
style	No	The CSS style for this widget. Defaults to `component.css`
service	No	Refers to a component that provides extra services for the widget. You can use this attribute to reference a component that serves data to the widget.
value	No	References the widget's data
args	No	object literal that defines additional tag attributes

For the plotCity example, you also need to add id attributes to the combobox widget tags so that you can refer to the widgets from your event handlers, as explained in Handling Widget Events. You'll name the combobox that holds the states thisState, and you'll name the combobox that holds the cities thisCity:

<a:widget  id="thisState"
	name="dojo.combobox"
	... />
<a:widget id="thisCity"
	name="dojo.combobox"
	... />