Note: See Using jMaki 9.3 With the NetBeans Visual Web Pack or the Sun Java Studio Creator IDE for updated instructions on how to add jMaki to a project.

In my last blog, I mentioned Greg Murray's jMaki project which enables Java developers to use JavaScript in their Java based applications as either a JSP tag library or a JSF component. Having struggled with the JavaScript part of our Building AJAX-based JavaServer Faces Web Applications With Sun Java Studio Creator hands-on lab, I was excited to learn about a tool that makes the JavaScript part of AJAX technology easier. Geertjan provides a NetBeans module that makes it easy to try out in the NetBeans IDE. I wondered whether I could use jMaki from the Creator IDE, and decided to give it a whirl. Here is how to use jMaki from the IDE.

1. Get the jMaki zip. You can download it from http://ajax.dev.java.net/. After you unzip the zip file, you need to unjar the jmaki.jar file. If you don't know how to unjar a jar file, one easy way is to rename it jmaki.zip and unzip it.
   
   
2. Create a Sun Java Studio Creator project. I named mine JmakiDemo.
   
   
3. Copy the supporting files to your project. You can use File > Add Existing Item to add files to your project. However, to cut down on the number of steps that I have to write up, I will explain up how to copy the files using the operating system instead of using the IDE.
   
   
   1. Copy jmaki/jmaki.js to creator-project-dir/web.
      
      
   2. Copy jmaki/WEB-INF/types.properties to creator-project-dir/web/WEB-INF.
      
      This properties file maps a type to the location of the supporting JavaScript libraries. If the widget uses JavaScript libraries, you set the type parameter in the jMaki ajax tag.
      
      
   3. Copy jmaki/WEB-INF/lib/ajax-wrapper-comp.jar to creator-project-dir/web/WEB-INF/lib.
      
      This is the jMaki tag library.
      
      
   4. Copy the directory that contains the widget's HTML template, CSS style, and JavaScript file containing bootstrap code from jmaki/resources to creator-project-dir/web/resources.
      
      For example, I copied the tree, list, and sudoku directories.
      
      The jMaki classes look in several places for the widget's files. One place it looks is /resources/widget-name. This is how the jMaki sample app is set up and I chose to put mine in the same place. Look at the Using jMaki widgets (https://ajax.dev.java.net/page-developer.html) documentation for alternative locations.
      
      
4. In the IDE, click the JSP button in the editing toolbar to display the JSP source for the page.
   
   
5. Add xmlns:a="http://java.sun.com/jmaki" to the <jsp:root> tag. The tag should look similar to this:
   
   

   <jsp:root version="1.2" xmlns:a="http://java.sun.com/jmaki" 
   xmlns:f="http://java.sun.com/jsf/core"
   xmlns:h="http://java.sun.com/jsf/html" 
   xmlns:jsp="http://java.sun.com/JSP/Page"
   xmlns:ui="http://www.sun.com/web/ui">

   
   
   
6. Now you are done setting up your project resources and you can start adding the widgets to your web page. One problem that you have to work around is that the jMaki widgets do not expose their features using the Java Studio Creator Design-Time API. What this means is that you will not be able to see the widgets in the Visual Designer. In addtion, with jMaki, you wrap the component in an <a:ajax> tag. Even if you were to use a component from the Pallette, if you wrap the component in an <a:ajax> tag, the Visual Designer won't see it. To make it easier to work with the widgets in the Visual Designer, I used a Grid Panel component to help me visualize where the widgets are on the page.
   
   
   
   Click Design in the editing toolbar to return to the Visual Designer.
   
   
7. Drag a Grid Panel component from the Layout section of the Palette and drop it on the page.
   
   For my project, I set the column property to 2 and set the border property to 1. By setting the border to 1, it makes it easier to visualize the page. You can clear the border property when you are ready to deploy.
   
   
8. For my project, I dropped a Label component in the left column and a Group Panel in the right column. The sole purpose of the Group Panel is to occupy the right column with something visual. I ended up with three rows, one each for tree, list, and sudoku.
   
   
9. Drop a Faces Verbatim component from the Advanced section of the Palette into each Group Panel. The <a:ajax> wrapper tags are nested in the <f:verbatim> tags. By nesting the <a:ajax> tag within an <f:verbatim> tag, you can control its position in the web page. Otherwise, the rendered output will put the widgets in places that have no relation to where you positioned the <a:ajax> tag in the page's JSP.
   
   
10. Each widget needs an <a:ajax> wrapper tag.
    
    Look in the widget's .jsp page in the jMaki sample application to see what the <a:ajax> tag should look like for that widget. For example, for the List widget, I looked at jmaki/list/index.jsp.
    
    Basically, you provide the name, type (if applicable), and service (if applicable). You also need to provide the names of the .js and .css files if their names do not match the name of the component or are not located in one of the default directories. Below is what my tags look like. Notice that I replaced <f:verbatim/> with start and ending tags.
    
    

    <h:panelGrid binding="#{Page1.gridPanel1}" 
        border="1" columns="2" id="gridPanel1" 
        style="position: absolute; left: 96px; top: 48px">
      <ui:label binding="#{Page1.label1}" id="label1" text="List Widget:"/>
      <ui:panelGroup binding="#{Page1.groupPanel1}" id="groupPanel1">
        <f:verbatim>
          <a:ajax name="list" service="listService.jsp"/>
        </f:verbatim>
      </ui:panelGroup>
      <ui:label binding="#{Page1.label2}" id="label2" text="Tree Widget:"/>
      <ui:panelGroup binding="#{Page1.groupPanel2}" id="groupPanel2">
        <f:verbatim>
          <a:ajax type="dojo" name="tree"/>
        </f:verbatim>
      </ui:panelGroup>
      <ui:label binding="#{Page1.label3}" id="label3" text="Sudoku Widget:"/>
      <ui:panelGroup binding="#{Page1.groupPanel3}" id="groupPanel3">
        <f:verbatim>
          <a:ajax name="sudoku"/>
        </f:verbatim>
      </ui:panelGroup>
    

    
    
    
11. The List widget uses a service .jsp file. Copy jmaki/web/listService.jsp to creator-project-dir/web.
    
    
12. Note that for the Tree widget, there is a type attribute set to dojo. This means that the widget uses the dojo library. So, you have to copy jmaki/web/resources/dojo to creator-project-dir/web/resources.
    
    Here is what my Projects window looks like:
    
    
    
    
13. There you have it. You are ready to hit the Run button. After you do, view the source from the browser to see how the ajax tags are rendered.