Few details of dynamic functionality in Woodstock components

The latest release of Woodstock components (https://woodstock.dev.java.net/) introduced lots of client-side functionality, including convenience of Ajax into Web componentry. Here is the overview of how this functionality works from within and how it can be used by web developers.


Before we start, take a look at the (simplified!) deployment diagram below. Diagram is reduced to show only relevant libraries.

The following is of note here:

  • Woodstock components have client and server side. While both sides are completely compliant to each other, they are independent. For example, one can use woodstock client library with another server side back end, ranging from simplest HTML files to complex frameworks

  • Since the default server side solution is JSF, Woodstock client side library by default uses JSF extensions (https://jsf-extensions.dev.java.net) for asynchronous communication with the server. Use of such library is decoupled from other functionality and can be replaced by the user at will ( requires knowledge of Javascript)

  • Woodstock client side library uses Dojo


Woodstock components are following Dojo widget design, where each component is rendered based on the HTML template and represents a set of DOM nodes and associated behavior. Thus once component is rendered ( even the simplest button), a developer can invoke misc. functions on it such as:

  • change content/value and other properties ( color, background, label)

  • enable/disable/hide/etc

  • async. update component value based on server data

  • async. submit component data to the server

  • component-specific functions such as start/stop progress bar

Most components share the same set of basic functionality ( see related functional specs https://woodstock.dev.java.net/Documentation.htm), and most have their own, specific only to one type of the component (i.e. Progress bar control, auto-save of text fields, etc).Notable among such functionality are Ajax based ones that introduce dynamic roundtrip behavior without page update, such as:

  • most components: submit and refresh

  • table – transparent runtime scrolling

  • text field and editable field– auto-validation

  • text area – auto-save ( timer based)

  • progress bar – real status ( which is sort of refresh from server)

  • etc

Basic interactions

Once page is rendered, all components are instantiated and (usually) visually rendered .

Any component on the page and (!!) developer's code can interact with other components in one of the following ways:

  • Do nothing and let components live through their lifecycle ( present data, accept and submit data to the server)

  • Dynamically modify/control components through the use of javascript. For example, the following code makes textField with id “form1:textField1” required and visible.

    var domNode = document.getElementById("form1:textField1");
        required: true,
        visible: true

    Or the following code opens up the bubble help with id “form1:nameBubble”


  • Listen and react to the events of Woodstock organism. Components publish major lifecycle events to the Dojo event bus. Such events are described in individual functional specs (https://woodstock.dev.java.net/Documentation.htm). For example, the following code subscribes and “does something” in response to textField's end of update event ( when textField is updated/refreshed from the server, user will be presented with an alert with the new value)

    // Subscribe to refresh event.
        dojo.event.topic.subscribe(webui.suntheme.widget.textField.event.<eventname>.endTopic, processEvents, "update");

      var processEvents = {   update: function(props) {
    // Do something...

    // for example: retrieve new value and notify
    // user


  • Taking it further, developer may enjoy built-in component awareness of each other. For example, an alert can be automatically presented to the user if textField validation failed. The usage and diagram for this case are presented below, but in short alert is using the same event system:

    • Alert subscribes to the notification event from textField.

    • When validation fail, text field posts a notification event with the details of failure

    • Alert receives event and presents it.


Woodstock components can be used in a few different ways. The most typical way to use a component is with the JSP tag from within a JSF based application. Using JSP tag provides for convenient and bullet-proof way to generate TextField component presentation. JSP tag attributes are automatically translated into corresponding properties of the client side component.

Example: to include a TextField in the JSP page, the web app developer will include tags like this.

<webuijsf:textArea autoSave=5000/>


<webuijsf:textField autoValidate=”true”
label="Enter Credit Card Number"

Example 1: Dynamic Alert upon (Ajax) validation of the field.

As mentioned above, this exampe shows how an alert can be dynamically presented to the user upon validation of the data in the text field.

a. usage

We will use JSP tag to define alert and textField:

<webuijsf:form id="form1">
<webuijsf:alert id="alert1" type="error" visible="false"/>

<webuijsf:bubble id="nameBubble" title="#{msgs.nameBubbleTitle}"> <webuijsf:staticText text="#{msgs.nameBubbleText}"/>


In the code above, we created:

  • form

  • alert (initially invisible)

  • textField ( with autoValidation activated. Validation will be performed by JSF bean Page1

  • bubble help associated with the text field ( initially invisible, activated on mouseOver event)

b. Ajax-call ( auto-validation interaction )

The following diagram presents basic interaction executed during asynchronous TextField auto-validate:

  • browser triggers onBlur

  • textField is susbscribed to onBlur ( via dojo event bus) and receives the event.

  • TextField publishes a begin Validation event.

  • TextField itself is subscribed to this very Validation event and receives it. Note that this step provides a point of decoupling of onBlur from how Ajax call is implementated – Ajax implementation can be replaced.

  • TextField uses JSFExtensions client side to submit content of itself to the server via Ajax

  • Server side processes Ajax request ( JSF Extensions PARTIAL_LIFECYCLE) and validates it. Let's say the data is wrong – validator throws JsfMessages which are returned to the textField in the browser ( Ajax caller)

  • TextField updates itself and invalidates the label associated with it.

c. interaction between components ( textField -> alert)

The following diagram shows interaction between components within a browser. This interaction results in alert shown up on error,or dismissed on correct validation.

d. controlling component through its interface

Remember within textField we had :


The following simple diagram shows what happens:

e. final result

So here how textField and alert look together:

Example 2. Auto Save

I will not go through as much details with this example.

Auto-save features allows to save content of the TextArea every N msec. Data is saved by submitting the content of the TextArea via asynchronous call.

The following diagram presents basic interaction executed during asynchronous TextArea auto-save.

  1. TextArea sets interval calls on itself for ever N msec

  2. Every interval call TextArea publishes a begin event.

  3. TextArea itself is subscribed to this very event and further submission is triggered as a result of the event. Again, note that this step provides a point of decoupling of timer event from how Ajax call is implementated – Ajax implementation can be replaced.

  4. TextArea submits data via asynchronous call

  5. Upon return of the asynchronous call, another event ( end of submit) is published.

Note that there are 2 events published denoting the beginning and the end of the auto-save process. The Begin event (webui.@THEME@.widget.textArea.submit.beginEventTopic) contains id of the component and triggers Ajax auto-save, and the end event published in the result of the Ajax callback returned (webui.@THEME@.widget.textArea.submit.endEventTopic) contains newly rendered json object of textArea. Typically, a developer does not need to subscribe to either event, but could use this to update other widgets in the page.

The End


Awesome write up.. Maybe you can give a link to this from the woodstock wiki page..

Posted by Venky on September 25, 2007 at 04:17 PM MDT #

This is comment

Posted by guest on October 23, 2007 at 01:18 AM MDT #


Posted by guest on December 17, 2007 at 04:34 PM MST #


Posted by guest on January 23, 2008 at 09:28 AM MST #

Posted by guest on February 14, 2008 at 11:48 PM MST #


Posted by guest on May 02, 2008 at 06:52 AM MDT #


Posted by guest on May 12, 2008 at 01:05 AM MDT #


Posted by guest on May 12, 2008 at 04:55 AM MDT #

I have been using Woodstock components in my projects since last one month and initially I was not aware as of how to use newly added components like bubble help and accordin tabs. This really helps

Posted by Pankaj Wahane on July 02, 2008 at 03:48 PM MDT #

Can you send me this complete example?

Thank you!

Posted by Gustavo on July 03, 2008 at 02:12 AM MDT #


I work at NetBeans 6.1 and use Visual Web JSF components (Woodstock v.4.2) in my web project.

How to refresh (asynchronous) the Woodstock Table component (<webuijsf:table>)?


Posted by Sergey on July 07, 2008 at 02:43 PM MDT #

I am using dynamic Faces and woodstock components in my JSF web application. when I include woodstock calender component Id inside render option in the fireAjaxTransaction, the page is getting reload, when I remove that from render option it is working perfectly So please give me the suggestion for this problem, even I kept immediate=true to skip the validation phase but no luck......

Posted by J.Naveen on August 04, 2008 at 03:26 PM MDT #


Posted by guest on August 07, 2008 at 01:27 AM MDT #


Posted by guest on August 20, 2008 at 09:55 AM MDT #


Posted by guest on September 11, 2008 at 08:32 PM MDT #


Posted by guest on September 13, 2008 at 05:07 AM MDT #


Posted by guest on September 14, 2008 at 04:41 PM MDT #

why their is no upadtes available for woodstock component for few months.

Posted by jayson on January 05, 2009 at 04:14 PM MST #

Post a Comment:
  • HTML Syntax: NOT allowed

Dmitry Kushner


« July 2016