We have been blogging about jMaki for over a year, and, during that time, the technology has gone through many iterations, making most of our posts obsolete. With the release of 9.3, there became enough changes that it was time to start reposting these mini tutorials. So, to start, here are new instructions for adding jMaki to a Visual Web Application project or a Sun Java Studio Creator project.

Note: To learn about the modifications, see Carla Mott's Big changes in jMaki blog entry.

Aug 6, 2007 Update: With the later versions, such as 9.6.1, they abstracted some of the functionalities into a separate JSF Compounds library ( jsfcompounds-0.0.2.jar), which you can download from https://ajax.dev.java.net/servlets/ProjectDocumentList?folderID=7871. You must add this jar file to your classpath, by right-clicking the Libraries node in the Projects window, choosing Add Jar/Folder, navigating to and selecting jsfcompounds-0.0.2.jar, and clicking Open. A symptom of this missing jar file is getting the following error in the JSP editor: java.lang.NoClassDefFoundError: com/truchsess/faces/compound/webapp/CompoundChildTagBase

Doing the Set Up

1. Get the 9.3 jMaki zip. You can download it from http://ajax.dev.java.net/download.html.
   
   Note: There is also a NetBeans jMaki plug-in. In the past, we have written how to create a NetBeans jMaki project and copy the resources from that project into a Visual Web project. When I try it with the latest NBM, I get the following error: Unable to create an instance of jmaki.widgets.yahoo.tree.Widget. See the error log for more details. If I figure out what I am doing wrong, I will repost this with the added instrucitons.
   
   
2. Unzip it to a folder of your choice. I will refer to this folder as jmaki-dir.
   
   
3. Unzip the zip files in jmaki-dir/widgets for the desired widget libraries. In this mini tutorial, you will use the Tree widget from the Yahoo widget library, so, at a minimum, unzip the jmaki-yahoo zip so that you end up with jmaki-dir/widgets/resources/yahoo.
   
   
4. Create a project (if you are using the Visual Web Pack, create a Visual Web Application). In this example, I named mine Jmaki93Demo. I will refer to to the location of this project as project-dir.
   
   
5. 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-dir/scripts/glue.js to project-dir/web.
      
      
   2. Copy jmaki-dir/scripts/system-glue.js and jmaki-dir/scripts/jmaki.js to project-dir/web/resources.
      
      
   3. Copy jmaki-dir/core/web/resources/config.json to project-dir/web/resources.
      
      
6. In the Projects window right-click Libraries and choose Add Jar/Folder. Then, navigate to and select jmaki-dir/lib/ajax-wrapper-comp.jar, and click OK.
   
   This is the jMaki tag library.
   
   
7. Copy the desired widget resource libraries to jmaki-dir/widgets/resources. For this mini tutorial, you need to copy jmaki-dir/widgets/resources/yahoo to project-dir/web/resources.
   
   
8. In the IDE, click the JSP button in the editing toolbar to display the JSP tags for the page.
   
   
9. Add xmlns:a="http://jmaki/v1.0/jsf" to the <jsp:root> tag.

Adding the Yahoo Tree Widget

Now you are done setting up your project resources and you can add the Tree widget to your web page. One problem that you have to work around is that the jMaki widgets do not expose their features using the 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:widget> tag. Even if you were to use a component from the Pallette, if you wrap the component in an <a:widget> tag, the Visual Designer won't see it. To make it easier to work with the widgets in the Visual Designer, I usually put them inside layout components, such as the Grid Panel. That way, I can position the widgets and be able to see in the Visual Designer where the jMaki widgets are on the page.

Note: Work is in progress to provide the jMaki widgets in component libraries that will work in the Visual Designer. We did a JavaOne Hands-On Lab that covered how this is done.

1. Click Design in the editing toolbar to return to the Visual Designer.
   
   
2. Drag a Grid Panel component from the Layout section of the Palette and drop it on the page.
   
   While in the development stage, I like to set the border property to 1 to make it easier to visualize the location of the widget on the page. You can clear the border property when you are ready to deploy.
   
   
3. Click JSP in the editing toolbar to display the JSP tags for the page. Replace the <h:panelGrid> tag with the following (this assumes that the Grid Panel's id is gridPanel1. If not, change to match. It is OK if you change the style tag.

   <h:panelGrid binding="#{Page1.gridPanel1}" border="1" id="gridPanel1" style="position: absolute; left: 48px; top: 48px"> <a:widget name="yahoo.tree" value="{'root' : { 'title' : 'Food', 'expanded' : true, 'children' : [ {'title' : 'Nuts'}, {'title' : 'Fruit', 'children' : [ {'title' : 'Banana'} ] } ] } }"/> </h:panelGrid>

   You now have added a jMaki tag for the Yahoo Tree widget.
   
   
4. Click the Run button. When the page displays in the browser, view the source from the browser to see how the jMaki tags are rendered.
   
   
5. In future blogs, we will further explore the jMaki features. To keep this blog short, we will just show how to subscribe to the Tree widget's onClick topic get the widget's value. If necessary, click Design in the editing toolbar to display the page in the Visual Designer. Drag a Script component from the Advanced section of the Palette and drop it on a blank spot on the page.
   
   
6. Click JSP to view the JSP tags.
   
   
   • If you are using the Sun Java Studio Creator IDE, replace the <ui:script> tag as follows:

     <ui:script binding="#{Page1.script1}" id="script1"> var handler = function(message) { alert('You selected ' + message.value.label); } jmaki.subscribe("/yahoo/tree/onClick", handler); </ui:script>

   • If you are using the NetBeans Visual Web Pack, replace the <webuijsf:script> tag as follows:

     <webuijsf:script binding="#{Page1.script1}" id="script1"> var handler = function(message) { alert('You selected ' + message.value.label); } jmaki.subscribe("/yahoo/tree/onClick", handler); </webuijsf:script>

7. If the script tag appears before the <a:widget> tag, cut the script tag and paste it below the <a:widget> tag, or else you might get a jMaki undefined error when you run the web application and click on a tree node..
   
   
8. Run the web application again. When you click on a tree node (not the expansion box), you get an Alert box that shows what you just clicked.