Tuesday September 25, 2007
Tuesday September 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.
Deployment
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
Components
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");
domNode.setProps({
required: true,
visible: true
});
Or the following code opens up the
bubble help with id “form1:nameBubble”
document.getElementById('form1:nameBubble').open(event);
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
alert(props.value);
}
}
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.
Usage
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/>
or
<webuijsf:textField
autoValidate=”true”
label="Enter
Credit Card
Number"
validatorExpression="#{Payment.cardValidator}"
/>
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:textField
autoValidate="true"
id="tfName"
label="#{msgs.nameLabel}"
notify="form1:alert1"
onMouseOut="document.getElementById('form1:nameBubble').close();"
onMouseOver="document.getElementById('form1:nameBubble').open(event);"
required="true"
text="#{Page1.name}"
validatorExpression="#{Page1.tfName_validate}"/>
<webuijsf:bubble
id="nameBubble" title="#{msgs.nameBubbleTitle}">
<webuijsf:staticText
text="#{msgs.nameBubbleText}"/>
</webuijsf:bubble>
</webuijsf:form>
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 :
onMouseOut="document.getElementById('form1:nameBubble').close();"
onMouseOver="document.getElementById('form1:nameBubble').open(event);"
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.
TextArea sets interval calls on itself for ever N msec
Every interval call TextArea publishes a begin event.
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.
TextArea submits data via asynchronous call
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
Posted at 08:50PM Sep 25, 2007 by Dmitry Kushner in Sun | Comments[18]