Oracle Blog

Blog for dmitry

Tuesday May 20, 2008

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-sidelibrary. A few
major use cases are presented, analyzed and implemented.[Read More]

Tuesday Oct 30, 2007

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.

Tuesday Sep 25, 2007

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 codecan 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.

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)

// for example: retrieve new value and notify //
useralert(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.

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.

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.