This year, Brian Leonard, and I (diva #2) are putting on the Developing (J)Ruby on Rails Applications with the NetBeans™ IDE hands-on lab at JavaOne. If you haven't tried developing a web application using Ruby on Rails, this is a good opportunity to get your feet wet. For those of you who are familiar with Ruby but haven't tried it in the IDE, you will also find this lab helpful. In this lab, you build the classic Ruby web log, you access the FreeTTS Java API to speach-enable the application, and you deploy the application to the GlassFish application server.

Speaking of JavaOne, in last year's hands-on-lab, one of the exercises was to use Dynamic Faces to build a chat room application. This section has been turned into the Building an Ajax Chat Room with the Ajax Transaction Dynamic Faces Component tutorial which is available from the NetBeans Web Application Learning Trail.

About the picture. Right behind me is flowing lava. To be able to walk right up to 1200 degree Celsius lava flow was an awesome experience. Fortunately, because the lava contains a large amount of glass, the lava flows very slowly.

If you have installed the NetBeans IDE support for Ruby and you are interested in integrating jMaki in your Ruby on Rails projects, here is a five-minute tutorial that will get you started. In this tutorial, you add a Yahoo data table to a Ruby on Rails view. (If you have not yet installed the NetBeans IDE 6.0 or if you need to add Ruby support to your NetBeans IDE, learn how to here.)

1. If you haven't installed the jMaki plugin for the NetBeans IDE, it takes just a minute. Select Tools > Plugins from the main menu, select jMaki Ajax Support, click Install and follow the instructions.
   
   
2. Follow the steps in the "Working With Ruby on Rails Files" section in the Getting Started With Ruby and Rails. This should take just a few minutes as no database is involved. Finish all the steps up to but not including the "Practicing What You Have Learned" subsection. It is important that you add the routing code (Code Sample 10) to the routes.rb file and delete the Public > index.html file.
   
   Note: If you already have done these sections, but added the jMaki plugin after you created the project, you need to create a new project in order to have jMaki included.
   
   
3. Edit the Views > item > index.rhtml file.
   
   
4. Remove the <table> including the nested <tr> and <td> tags. You will replace this HTML table with the Yahoo Data Table.
   
   
5. Choose Window > Palette from the main menu to view the Palette window.
   
   
6. Expand the jMaki Yahoo section in the Palette, then drag and drop the Data Table onto the index.rhtml.
   
   
7. Replace the jmaki_widget tag with the following code:
   
   

   <%= jmaki_widget 'yahoo.dataTable', :value => {:columns => [ { :label => 'Id', :id => 'id'}, { :label =>'Type', :id => 'type'}, { :label => 'Price', :id => 'price'}, ], :rows => @items } -%>

   
   
   
8. Click the small x button in the bottom right corner of the IDE to stop the WEBrick server.
   
   
9. Click the Run Main Project button and the browser should display a nice Yahoo table that contains the item data.

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.

For those of you who were not able to attend our JavaOne 2007 hands-on lab, the lab is now available online at http://developers.sun.com/learning/javaoneonline/j1labs.jsp?track=8&yr=2007.

The lab starts off showing how to use dynamic faces Ajax zones to easily enable plain old JavaServer Faces components to send Ajax requests, and, in turn, dynamically update other components with the Ajax response. You also use an Ajax Transaction to continually poll the server. When you have completed the exercise, you have a simple chat room, like the one shown above. In the instructor-led lab, we had the web app running on the demo machine so you could watch us chatting with the lab attendees. The lab file contains an older version of the dynamic faces component library. To get the more recent one, see Installing the Currency Trader Sample Application at the NetBeans Visual Web Application documentation page.

In the second part of the lab, Winston and the Andersons show how to build a JavaServer Faces component from scratch, and use dynamic faces internally to Ajaxify the component.

The final section shows how to leverage jMaki to create a JavaScript component from one of the popular frameworks into a JavaServer Faces component. You can learn more about jMaki at ajax.dev.java.net and about the componentized widgets at widgets.dev.java.jet.

For the past few months, I have been collaborating with a great group of people to bring you a fantastic hands on lab for JavaOne. This lab, session # LAB-4460 Building Ajax-Enabled JavaServer Faces Components and Web Applications With jMaki, Dynamic Faces, and the NetBeans IDE, was put together by Craig McClanahan, Matthew Bohm, Gail and Paul Anderson, Winston Prakash, and myself. It starts out by showing how to use Dynamic Faces (JSF Extensions) to add Ajax functionality to plain old JavaServer Faces components. It then teaches you how to build your own JSF Ajax-enabled component and add design-time features so that you can use it in the NetBeans Visual Web Pack. Last, it shows how to build a JSF component from a jMaki widget. By leveraging an existing jMaki widget and specialized base classes, you quickly build an Ajax-enabled JavaServer Faces component offering a rich user interface with a minimum of code.

They will also be handing out CDs of the hands on labs. The CDs contain additional labs including another lab (4420) that Craig, Matt, and I wrote that covers some of the above material as well as how to use the jMaki-wrapped DHTML Goodies Tooltip widget. In addition, the CD contains lab 4450. I contributed a section to this lab that shows how to use the jMaki-wrapped Dojo Fisheye widget.

Good news. We just released a new AJAX tutorial, Using the AJAX Rating Component. In this blog, Gail interviews Matthew Bohm, the developer who authored the Rating component. Matt had some interesting things to say about the Rating component and his other contributions to the Sun Java Studio Creator IDE. Be sure to read to the end of the blog, where we ask Matt about his interests outside of work.

Gail: Why do a Rating component?
Matt: We decided to write the Rating component for two reasons. First, it is one of the components used in the Java Pet Store. Second, AJAX is intrinsically part of the UI paradigm established by Rating components on the web; that is, they almost always use AJAX and provide a great use case for demonstrating AJAX.

Gail: Briefly explain the component.
Matt: The Rating component, of course, lets the user assign a rating to an item, such as a book or movie. It displays a row of stars the user can click on. It also can display controls to indicate the user is "not interested" in the item, to clear the rating, and to toggle between normal and average mode. There are properties for specifying the text and hover texts to be displayed. When the user assigns a rating, the client sends that rating to the server via an AJAX request, and the server sends the values of several properties back to the client via the AJAX response. There are also a number of advanced properties, including those that let you execute your own client-side scripting when the user assigns a new rating, mouses over a control, or toggles the mode.

Gail: The mode toggle feature is an innovation. Can you say more about it?
Matt: When I looked at rating controls on existing web sites, I was disappointed with how they presented the user's rating and the average rating in combination. In most cases, the user and average ratings for an item were shown in separate rating instances. In the case where they were shown in the same rating instance, the user could not view the average rating after assigning a user rating. I felt we could do better. So in the Rating component for the Java Studio Creator IDE, we have a mode toggle control that lets the user alternately view the user and average rating for an item within the same rating instance.

Gail: What's another of your favorite contributions to the Java Studio Creator IDE?
Matt: My biggest contribution is definitely the invention of virtual forms. Without them, writing applications in the IDE would be much more difficult. The team's sample application developers particularly like them.

Gail: You were a technical writer in a previous life, and we owe you a thanks for writing the script for the Rating tutorial.  What made you switch to development?
Matt: Actually, my technical writing career lasted only two months or so. I had my eye on development from the start. I was working in a data warehousing group and wrote a much-needed intranet application at a time when the development team was stretched for resources. The group's director, with whom I still keep in touch,
quickly moved me into development.

Gail: Tell me something about yourself not related to work.
Matt: I write classical music. Currently I'm setting some poems by the great Argentine poet Alejandra Pizarnik for soprano and piano. Pizarnik is not so well known; she died in 1972 at age thirty-six, and her poetry is dark and surreal. My wife, who is also a poet and Argentine, introduced me to her work.