Ed Burns's Blog

Adding Dynamic Faces Support to a jMaki widget

In this entry, I show how I added Dynamic Faces support to the Dojo Inline Editor widget in jMaki.

Background and History

If you've read my blog before, you know that I think JSF is a good fit for handling the motherhood and apple pie requirements of web applications. What you may not know is that jMaki intentionally leaves the work of satisfying these requirements as an exercise for the developer. No problem, just use jMaki and JSF together. This is indeed a valid answer, but there is a subtlety that bears clarification.

When using jMaki + JSF under J2EE 1.4 (the default target audience for jMaki), you miss out on the following features:

• Ability to have the jMaki widget POST back to the faces page while preserving the JSF view state.

• Ability to use jMaki widgets that represent components that accept user input within an iterating component such as dataTable.

• Ability to attach valueChangeListeners to jMaki components in the view.

• Ability to attach converters and validators to jMaki components in the view.

• Ability to attach action and/or actionListeners to jMaki components in the view.

These deficiencies stem both from missing features in the built-in jMaki JSF support and from missing features in JSF 1.1 commonly used with J2EE 1.4.

The story about jMaki and Dynamic Faces

By using jMaki with Dynamic Faces on top of JavaEE 5, however, all of these deficiencies can be addressed (with the exception of the last two, and issues have been filed for these features). This section discusses how using jMaki and Dynamic Faces addresses all of the deficiencies mentioned above.

Ability to have the jMaki widget POST back to the faces page while preserving the JSF view state.

This is the big one, and it was at the heart of the JavaOne presentation in which I participated. The lack of this feature in many Ajax + JSF solutions is what prompted us to title the session, "Ajax done right". When you do not have the JSF view state, you cannot do any of the things that JSF does well. Including the JSF View state in the Ajax transaction is essential.

By using Dynamic Faces to send and receive Ajax transactions from the browser to the JSF view, the JSF view state is correctly preserved, allowing the entire JSF lifecycle to be used, including conversion, validation, events, etc.

Ability to use jMaki widgets that represent components that accept user input within an iterating component such as dataTable.

This one is near and dear to Jacob Hookom's heart. Not only do you need the JSF view state, but you need a way to apply individual values to an individual components within a composite component (such as a table or tree). This capability did not exist in JSF until version 1.2, and Dynamic Faces takes full advantage of it.

Ability to attach valueChangeListeners to jMaki components in the view.

This didn't exist in jMaki until issue 3 was fixed. However, even though you can add a valueChangeListener to a jMaki component now, you still need to preserve the JSF view state in order for it to ever have a chance of being invoked. Again, Dynamic Faces is the answer.

Ability to attach converters and validators to jMaki components in the view.

Ability to attach action and/or actionListeners to g jMaki components in the view.

As with valueChangeListener, these two need to be first implemented in jMaki, then they need to be used with Dynamic Faces.

How To

The whole point of jMaki is to put today's hot JavaScript widget libraries in the hands of Java web application developers. Each widget library has different ways of doing things, and indeed, each widget within each library does too. jMaki solves this by having specific files with each widget. Therefore, adding Dynamic Faces support to each widget involves making some modifications to the widget specific files. Currently, the only widgets that have been modified are the Dojo FishEye and Inline Editor, and the Scriptaculous Inplace Editor. This section shows some high level guidelines for how to add Dynamic Faces support to an arbitrary jMaki widget.

The widget specific files for a jMaki widget are:

In general, you'll probably just need to modify component.js to add Dynamic Faces support. Please follow Jennifer's Tutorial for how to get started with jMaki and Dynamic Faces. Once you've done that, you need to make sure to include the Dynamic Faces taglib and script tag in the page on which you are using the jMaki widgets.

Syntax highlighting courtesy of http://www.nopaste.com/.

Listing 1, the JSP Page

<%@ taglib prefix="a" uri="http://java.sun.com/jmaki-jsf" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib prefix="jsfExt" uri="http://java.sun.com/jsf/extensions/dynafaces"%> 
 
<h2>Editor Using JSF</h2>
<hr>
 
<f:view>
 
<jsfExt:scripts />
 
<h:form prependId="false">
  <h:dataTable id="table" rows="10" binding="#{ResultSetBean.data}"
               value="#{ResultSetBean.list}" var="customer">
 
    <h:column>
      <f:facet           name="header">
        <h:outputText  value="Account Id"/>
      </f:facet>
      <h:outputText        id="accountId"
                     value="#{customer.accountId}"/>
    </h:column>
 
    <h:column>
      <f:facet           name="header">
        <h:outputText  value="Customer Name"/>
      </f:facet>
 <a:ajax name="dojo.inlineedit" value="#{customer.name}" />
    </h:column>
 
    <h:column>
      <f:facet           name="header">
        <h:outputText  value="Symbol"/>
      </f:facet>
      <h:outputText        id="symbol"
                     value="#{customer.symbol}"/>
    </h:column>
 
    <h:column>
      <f:facet           name="header">
        <h:outputText  value="Total Sales"/>
      </f:facet>
      <h:outputText       id="totalSales"
                     value="#{customer.totalSales}"/>
    </h:column>
 
  </h:dataTable>
 
</h:form>
 
</f:view>
 

Line 4 has the taglib for Dynamic Faces, line 11 uses the scripts tag. Line 29 has the use of the jMaki ajax component.

Let's take a look at the component.js for the Dojo Inline Edit widget, before Dynamic Faces support was added.

Listing 2, the component.js before Dynamic Faces is added

dojo.require("dojo.widget.*");
dojo.require("dojo.widget.InlineEditBox");
dojo.require("dojo.event.*");
 
var container = document.getElementById(widget.uuid);
var w = dojo.widget.createWidget(container);
 
w.getValue = function() {
    return w.textValue;
}
 
// add a saveState function
if (typeof widget.valueCallback != 'undefined') {
    w.onSave = function(newValue, oldValue) {   
        // we need to be able to adjust this
        var url = widget.valueCallback;
        dojo.io.bind({
                url: url + "?cmd=update",
                method: "post",
            content: { "value" : newValue  },
            load: function (type,data,evt) {
                // do something if there is an error
            }
        });
    }
}
w.saveState = w.onSave;
jmaki.attributes.put(widget.uuid, w);

On lines 1 - 3 we have the dojo includes: uninteresting. Line 5 of listing 2 is interesting. The "widget" refererred to is this instance of this widget in the page. In this case, it's the widget on line 29 of Listing 1. However, keep in mind that line 29 of listing 1 is inside of a dataTable, therefore, there will be 10 instances of this widget in the page, each corresponding to an actual JavaScript object in the JavaScript VM. Therefore, the value of widget.uuid will be different for each widget, and will, most importantly, correspond to the JSF Client Id for the widget in the JSF view. This is important because in order to address the widget in the JSF view, you need its client id.

For example, the widget.uuid values for this page happen to be table:n:j_id_id34 where n is the numbers 0 to 9.

Returning to line 5 of listing 2, the actual DOM element returned by the call to document.getElementById is what jMaki renders based on the content of the component.htm file. For the dojo inline editor, this file is:

<div id="${uuid}" dojoType="inlineEditBox" class="dInlineEdit">${value}</div>

The jMaki AjaxWrapperRenderer will cause the component.htm file to be rendered like this in the page from listing 1.

<div id="table:0:j_id_id34" dojoType="inlineEditBox" class="dInlineEdit">name_0</div>

Therefore, when line 5 of listing 2 executes, the value of container is the div element with id table:n:j_id_id34, where n, of course, is the current row in the table.

Line 6 of listing 2 uses the dojo createWidget to create an instance of the inline edit box inside of the container element.

Lines 14 - 25 of listing 2 declares the JavaScript function that will be called when the user presses the "save" button in the widget UI.

Now, let's take a look at the changes to component.js necessary to add Dynamic Faces support, expressed as a diff.

Listing 3, the diffs to component.js to add Dynamic Faces support

--- component-pre-DF.js	2006-12-07 10:32:25.000000000 -0500
+++ component.js	2006-12-07 10:31:19.000000000 -0500
@@ -12,6 +12,16 @@
 // add a saveState function
 if (typeof widget.valueCallback != 'undefined') {
     w.onSave = function(newValue, oldValue) {   
+
+      if (typeof _globalScope.DynaFaces != 'undefined') {
+	  DynaFaces.fireAjaxTransaction(container, 
+					{
+					execute: widget.uuid,
+					render: "none",
+					postBody: widget.uuid + "=" + newValue
+					});
+      }
+      else {
         // we need to be able to adjust this
         var url = widget.valueCallback;
         dojo.io.bind({
@@ -22,7 +32,8 @@
                 // do something if there is an error
             }
         });
+      }
     }
 }
 w.saveState = w.onSave;
-jmaki.attributes.put(widget.uuid, w);
\ No newline at end of file
+jmaki.attributes.put(widget.uuid, w);

The only change is a conditional within the onSave function. jMaki defines a _globalScope global variable that allows you to access all things globally defined in the page. It so happens that the scripts included by virtue of line 11 of listing 1 define a global variable called DynaFaces. This JavaScript object has all the functions exposed by the Dynamic Faces JavaScript library. Therefore, you can safely test for the existing of Dynamic Faces in a page as shown on line 8 of listing 3. If Dynamic faces is not being used in the page, then the normal jMaki operation of the widget takes place, as shown on lines 17 - 23 of the diff.

Lines 9 - 14 of listing 3 cause a Dynamic Faces Ajax transaction to be made back to the JSF page currently being viewed in the browser. This transaction includes all the view state for the current f:view. The first argument to fireAjaxTransaction is the DOM element from which the transaction should be fired. It is important that this be the DOM element that corresponds to the actual JSF UIComponent in the view. The second argument to fireAjaxTransaction is a JavaScript associative array. In this case, we're saying three things:

• do the 'execute' portion of the JSF lifecycle just on the JSF UIComponent for this widget instance.

• do not re-render anything to the browser (in this case, Dojo handles it).

• In the HTTP POST body of the request, include the name value pair for the currently entered value of the widget.

Note that newValue, on line 6 of listing 3, is an argument to the onSave function. It is the new value entered by the user.

For more information on the JavaScript functions exposed from Dynamic Faces, see the Dynamic Faces Reference.

Summary

jMaki gives you cool widgets. Dynamic Faces + jMaki gives you cool widgets you can use in a real enterprise web application.

Comments

• This is very nice, but I am using jmaki dojo calender(dropdownDate picker) in my JSF web pages, recently I am applying Dynamic faces for ajaxfy the components exactly here I got a problem that is after I apply DynamicFaces.transaction the calender components got disappeared for debugging purpose I used firebug there I found after fireAjax Transaction there is no scripts loaded corresponding jmaki. Please provide me the solution.

  Posted by: jaininaveen on May 01, 2008 at 03:00 AM

This work is licensed under a Creative Commons License.