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 a Web Application Using Project jMaki details how to build a jMaki application using the NetBeans IDE 5.5.1 module. When you drag and drop a widget on a page using the module, the module 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://java.sun.com/jmaki" %>
...
<a:widget name="dojo.combobox"
    value="[['Item 1','I1'],['Item 2','I2'],['Item 3', 'I3']]"/>

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. It also initializes the widget with a default value using the value attribute.

All widget tags must specify the name of the widget with the name attribute. The name is in dot notation similar to Java 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.

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:

[['Item 1', 'I1'],['Item 2','I2'],['Item 3', 'I3']]

This value is a JSON array that contains a set of other JSON arrays. Each of those arrays contains the label and value for each item in the combobox. You can put your data directly in the value attribute as shown by this example. You can also reference the data in a bean using an expression language (EL) expression from the value attribute. Another way to reference the data is from a servlet or JSP page using a service attribute. 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. Although you must always identify the name of the widget with the name attribute, you might not use the value attribute if the widget does not accept any data.

The best way to determine what attributes a widget expects is to look at the widget's widget.json file. An easy way to view this file is by right-clicking on the widget tag in NetBeans and selecting jMaki→jMaki from the pop-up menu. You can use this customizer to edit the values of the attributes.

Table 3-1 lists the most common attributes.

Table 3-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

Obtaining Application Keys for Google and Yahoo Widgets

Another task you need to perform before you can use the wrapped Google widgets in your application is to obtain an application-wide API key. This key is tied to the URL where you are hosting the application that uses the widgets. If you want to use the wrapped Yahoo widgets in your application, you should also obtain an application key, but you are not required to do so.

Project jMaki allows you to configure one or more application-wide keys. For example, if you use Google Search, Google Maps, and the Google Geocoder, you can share the same API keys across your application.

If you are using Yahoo widgets, you do not need to obtain an application key because jMaki provides an application key that applies to all URLs of applications that use Yahoo widgets. The simplejMaki application uses the Yahoo map widget, but the application does not include its own API key. However, in a production environment, you should register your own application key for Yahoo widgets, especially if you are deploying to a different context root or are changing the port.

Obtaining a Google API Key

To use the Google map service APIs, you must first create a Google account if you do not already have one, log in, and obtain a map key. The Google map key is specific to your application and allows up to 50,000 page views each day. Both the Google account and map key are free.

In your web browser, go to http://www.google.com/apis/maps/ to access the Google map key sign-up page from your web browser.
Click Sign up for a Google Maps API key. The Google map key license agreement page opens in your web browser.
Review and accept the agreement and enter the URL for your web site, such as http://localhost:8080/simplejMaki/. The URL that you specify must exactly match the one that you use to execute the application. If you reconfigure your server to use a port or you deploy to a different server, then you must obtain another key from Google.
Click Generate API Key. Google generates your map key.
Copy the map key and save it somewhere.
Open config.json from the Web Pages/resources directory of your web application project that uses jMaki.
Find the apikeys property in the file.
Go to the google key definitions inside the apikeys property.

Add the URL of your application and the key you obtained in step 5, as shown by these example default entries in the config.json file:

{"id": "google", 
    "keys": [ 
        {"url": "http://localhost:8080/jmaki", "key": "ABC..." }, 
        {"url" : "http://localhost:8080/google-test", "key" : "XYZ..." } 
    ] 
}

Obtaining a Yahoo URL Key

The simplejMaki example does not include a new Yahoo API key. For the purpose of this example and for your own testing and development, the key that jMaki already provides works fine because it applies across all URLs. The following JSON code from config.json configures this all-purpose Yahoo API key:

{"id": "yahoo", 
    "keys": [{"url" : "*", "key" : "jmaki-key"}]
}

The wildcard character given for the url attribute in the preceding Yahoo API key configuration means that you can share the API key, jmaki-key across URLs. Nevertheless, you should register your own key in a production environment, especially if you are deploying to a different context root or are changing the port.

To obtain a Yahoo API key, do the following:

Visit the Yahoo site to obtain an API key by launching this URL:
```
https://developer.yahoo.com/wsregapp/index.php
```
Save the API Key somewhere.
Open config.json from the Web Pages/resources directory of your web application project that uses jMaki.
Find the apikeys property in the file.
Go to the yahoo key definitions inside the apikeys property.
Add the URL of your application and the key you obtained in step 5, as shown by the default entry in the config.json file:
```
{"id": "yahoo", 
    "keys": [{"url" : "*", "key" : "jmaki-key"}]
} 
```