Getting Started Using the jMaki Framework to Create Ajax-Enabled JSP-based Web Applications


The jMaki framework allows you to quickly and easily create JavaScript-centric Ajax-enabled web applications.

The goal of this tutorial is to get you up and running using the jMaki framework as quickly as possible.  See the section, Next Steps, for links to documentation that gives more detail on using jMaki features.

Contents

Obtaining Required Software
Setting Up Your Environment
Running a jMaki Application
Creating a Blank Web Application
Adding a jMaki Widget
Accessing Data from a Widget
Adding Behavior to the Widget
Next Steps


Obtaining Required Software

To get started using the jMaki framework, you need to do the following:
  1. Download and install Java SE SDK, version 1.4 or or later.
  2. Download and install GlassFish or the Java EE SDK, version 1.4 or later.
  3. Download and install the Ant build tool.  If you are using GlassFish or Java EE SDK, then you don't need to obtain Ant separately because GlassFish and the Java EE SDK already include it.
  4. Download and unzip jMaki 1.0.1.
  5. Download and install a browser that supports JavaScript.  This includes IE 6, Mozilla 1.4, and Firefox.
This guide uses the  jMaki_INSTALL path variable to represent the path to your jMaki installation.

Setting Up Your Environment


To use the build system included with the jMaki release to run your jMaki web applications, you need to provide paths to the web server you installed:

  1. Go to jmaki_INSTALL/.
  2. Make a copy of the build.properties.sample file and call it build.properties.
  3. Copy the build.properties file you created into your home directory.
  4. Make sure that the path to your Ant installation is in your system path.
  5. Uncomment the java.autodeploy.dir property and set it to the autodeploy directory of your web server, such as:
    java.autodeploy.dir=<JavaEE_HOME>/domains/domain1/autodeploy
Now you are ready to run jMaki applications using the built-in build system.

Running a jMaki Application

This section describes how you can run the samples included in the jMaki  release you installed while performing the tasks in the previous section.

Run the mapit jMaki Sample:

  1. Go to the jmaki_INSTALL/samples directory, which contains a set of samples, each of which includes a README file explaining how to build and run the sample.
  2. Go to the mapit sample directory.
  3. Run the following command:
    ant 
  4. Go to the jMaki_INSTALL/samples/mapIt/dist directory to locate the WAR file you created in the previous step.
  5. Deploy the WAR file to your web server.
  6. Run the sample by copying the following URL into your browser address field:
    http://localhost:8080/jmaki-mapit

    You can run the other samples in a similar way.

Build and Deploy All Samples:

  1. Go to jmaki_INSTALL/samples.
  2. Run the following command to deploy all of the samples.
    ant deploy-all

  3. To run the samples, open your browser to the following URL:
    http://localhost:8080/jmaki
    Click on one of the links to run that sample.  The next section explains how to create your own jMaki application.

Creating a jMaki Web Application

The jMaki framework distribution includes a blank example directory build structure that you can use to get started.  It is located at jMaki_INSTALL/core.  The web application WAR file that you build from this directory is called jMaki-core.war

Alternatively to using the core blank application, you can create your own application by making a copy of the core directory and naming it whatever you like:
  1. Go to jMaki_INSTALL.
  2. Make a copy of the core directory at the same level as the core directory and call it myApp.
  3. Go to jMaki_INSTALL/myApp.
  4. Open build.xml in an editor and change all occurrances of jmaki_core to myApp so that the WAR file you create in the next step will be called myApp.war instead of jMaki-core.war.
  5. Build the application by running the following command:
    ant dist
  6. Deploy the WAR file you created by running the following command:
    ant deploy
  7. Run the application by copying this URL into your browser:
    http://localhost:8080/myApp

    For now, all you see is a page that welcomes you to jMaki.  This page includes a couple custom jMaki widgets that display "hello" and "hello Duke".  The resource files for these custom widgets are located in jMaki_INSTALL/myApp/resources.  You can delete these widget files if you want to, but be sure to remove the widget tags named hello and hello2 on the index.jsp page as well.
Next, you'll add a jMaki widget to this application.


Adding a jMaki Widget to Your Application

In this section, you'll add the Dojo combobox widget to the application you created in the previous section.

  1. Go to jMaki_INSTALL/myApp.
    Add the Dojo combobox widget to the application by running the following command:
    ant -Dwidget=dojo.combobox addWidget
    This command adds the resource files for the Dojo combobox widget to the jMaki_INSTALL/myApp/resources directory.
  2. Create a new text file called combobox.jsp and save it to the  jMaki_INSTALL/myApp/web/ directory.
  3. Open combobox.jsp in a text editor and add the following jMaki tag library declaration and widget tag to it:
    <%@ taglib prefix="a" uri="http://jmaki/v1.0/jsp" %>
    <a:widget name="dojo.combobox" />
    This adds the Dojo combobox widget to the JSP page.
  4. Save combobox.jsp.
  5. Go to jMaki_INSTALL/myApp and run the following command:
    ant dist
  6. Deploy the application by running the following command:
    ant deploy

  7. Run the application by copying this URL into your browser:

    http://localhost:8080/myApp/combobox.jsp

    This combobox doesn't do very much now because it doesn't have any data associated with it.  You'll see how to link it up to a data source in the next section.

The next section shows how to add your own data to this widget.


Adding Your Own Data to a jMaki Widget

For this task, you will add data to the combobox widget you created in the previous task.

  1. Create a directory called src under jMaki_INSTALL/myApp.
  2. Create a directory called myApp under jMaki_INSTALL/myApp/src.
  3. Create a text file called ApplicationBean.java and save it to jMaki_INSTALL/myApp/src/myApp.
  4. Copy the following code to ApplicationBean.java:
    package myApp;
    import org.json.*;
    public class ApplicationBean{
        protected String[] states= new String[] {
    "Alaska", "Arizona", "California", "Oregon"};
        protected String[] stateCodes = new String[] {
    "AK", "AZ", "CA", "OR" };
        public ApplicationBean(){}
        public String getStates() throws JSONException {
            JSONArray statesData = new JSONArray();
            JSONObject stateData = new JSONObject();
            for (int loop = 0; loop < states.length; loop++) {
                stateData.put("label", states[loop]);
                stateData.put("value", stateCodes[loop]);
                statesData.put(stateData);
                stateData = new JSONObject();
            }
            return jsonArrayToString(statesData, new StringBuffer());
        }
    // boilerplate code that will be included in jMaki in a future
    // release
        public String jsonToObjectLibertal(JSONObject jo,
    StringBuffer buff)  throws JSONException {
            if (buff == null) buff = new StringBuffer("{");
            else buff.append("{");
            JSONArray names = jo.names();
            for (int l=0; (names != null) && l < names.length(); l++) {
                String key = names.getString(l);
                String value = null;
                if (jo.optJSONObject(key) != null){
                    value = key + ":";
                    buff.append(value);
                    jsonToObjectLibertal(jo.optJSONObject(key), buff);
                }else if (jo.optJSONArray(key) != null) {
                    value = key + ":";
                    buff.append(value);
                    jsonArrayToString(jo.optJSONArray(key), buff);
                } else if (jo.optLong(key, -1) != -1) {
                    value = key + ":" + jo.get(key) + "";
                    buff.append(value);
                } else if (jo.optDouble(key, -1) != -1) {
                    value = key + ":" + jo.get(key) + "";
                    buff.append(value);
                } else if (jo.opt(key) != null) {
                    Object obj = jo.opt(key);
                    if (obj instanceof Boolean) {
                        value = key + ":" + jo.getBoolean(key) + "";
                    } else {
                        value = key + ":" + "'" + jo.get(key) + "'";
                    }
                    buff.append(value);
                }
                if (l < names.length() -1) buff.append(",");
            }
            buff.append("}");
            return buff.toString();
        }
        public String jsonArrayToString(JSONArray ja,
    StringBuffer buff)  throws JSONException {
            if (buff == null) buff = new StringBuffer("[");
            else buff.append("[");
            for (int key=0; (ja != null) && key < ja.length(); key++) {
                String value = null;
                if (ja.optJSONObject(key) != null){
                    jsonToObjectLibertal(ja.optJSONObject(key), buff);
                } else if (ja.optJSONArray(key) != null) {
                    jsonArrayToString(ja.optJSONArray(key), buff);
                } else if (ja.optLong(key, -1) != -1) {
                    value = ja.get(key) + "";
                    buff.append(value);
                } else if (ja.optDouble(key, -1) != -1) {
                    value = ja.get(key) + "";
                    buff.append(value);
                } else if (ja.optBoolean(key)) {
                    value = ja.getBoolean(key) + "";
                    buff.append(value);
                } else if (ja.opt(key) != null) {
                    Object obj = ja.opt(key);
                    if (obj instanceof Boolean) {
                        value = ja.getBoolean(key) + "";
                    } else {
                        value = "'" + ja.get(key) + "'";
                    }
                    buff.append(value);
                }
                if (key < ja.length() -1) buff.append(",");
            }
            buff.append("]");
            return buff.toString();
        }
    }
  5. Save ApplicationBean.java.
  6. Open combobox.jsp in a text editor.
  7. Add the following useBean tag right before the widget tag:
    <jsp:useBean id="ApplicationBean" scope="session"
    class="myApp.ApplicationBean"/>

  8. Add a value attribute to the widget tag and give it an EL expression that points to the states property of ApplicationBean:

    <a:widget name="dojo.combobox" value="${ApplicationBean.states}"/>

  9. Save combobox.jsp.
  10. Modify the build file to correct a bug (This will be fixed in the next release):
    1. Go jMaki_INSTALL/myApp.
    2. Open build.xml in a text editor.
    3. Go to line 15 of the build file and add the letter 's' onto the property "has-java-source", so the line looks like this:
        <condition property="has-java-sources">
    4. Save the build file.

  11. Go to jMaki_INSTALL/myApp and run the following command:
    ant dist -Dsrc.home="src/myApp"
  12. Deploy the application:
    ant deploy

  13. Run the application again by copying the following URL into your browser:
    http://localhost:8080/myApp/combobox.jsp

  14. Click on the combobox and you will see the list of states, Alaska, Arizona, California, and Oregon in the combobox.

The next task involves adding event handling to this widget.

Adding Behavior to a Widget

This section describes how to get your application to respond to the event of a user selecting a value from the combobox.

  1. Go to jMaki_INSTALL/scripts.
  2. Open glue.js in a text editor.
  3. Add the following event handler to the very end of the file:
    jmaki.subscribe("/combobox/onSelect", function(args){
    var value = args.value;
    var targetDiv = document.getElementById("newvalue");
    if(targetDiv)
    targetDiv.innerHTML = "The postal code for this state is " + value;
    });
  4. Save glue.js.
  5. Go to jMaki_INSTALL/myApp/web.
  6. Open combobox.jsp in a text editor.
  7. Add a publish attribute to the widget tag and set it to the topic, "/combobox":
    <a:widget name="dojo.combobox" value="${ApplicationBean.states}" publish="/combobox"/>
  8. At the end of combobox.jsp, add the following div tag:
    <div id="newvalue"></div>
  9. Save combobox.jsp and close it.
  10. Go to jMaki_INSTALL/myApp and run the following command:
    ant dist
  11. Deploy the application again:
    ant deploy

  12. Run the application again by copying the following URL into your browser:
    http://localhost:8080/myApp/combobox.jsp
  13. Select Arizona from the combobox. The page should display the message, "The postal code for this state is AZ".

 

Next Steps

For more in-depth information on the topics discussed in this guide, along other jMaki features, see the following documents: