Tuesday May 20, 2008

Illustrated Guide on Woodstock Client-Side Library

The Woodstock Client-Side Library provides a rich set of Web-based components. These components can be used client-side, independent of server implementation. This document provides basic concepts of working with the Woodstock client-side library. A few major use cases are presented, analyzed and implemented.[Read More]

Tuesday Oct 30, 2007

Creating autocomplete entry field with Woodstock

Woodstock components (https://woodstock.dev.java.net/index.html) provide powerful and flexible set of client side Web components. Like living cells, not only components represent complete functional units by themselves, they can also be connected together to create new forms of functionality.

This document shows how a textField and listBox can be connected together to build a so-called autocomplete entry field – the one that presents to the user dynamic set of completing entered data or suggestions based on what information user is typing.

All sources and Netbeans ( NB 6 Beta 2) project are attached at the end of this document.

[Read More]

Tuesday Sep 25, 2007

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

Friday Sep 07, 2007

Running Woodstock JSF Components in Portlet environment

This document presents a 'brief' overview on how Woodstock components could be used within a portal server.[Read More]

Dmitry Kushner


« July 2016