Woodstock @THEME_VERSION@ JavaScript Library Documentation
| JavaScript Libraries |
| @JS_NS@ |
Woodstock @THEME_VERSION@ JavaScript Library
|
Using the Woodstock @THEME_VERSION@ JavaScript Library
Getting Started
The Woodstock JavaScript library must be installed in your web
application
so that its widget and themed resources are available to your web
pages. In addition, the Woodstock object namespace should be
established in the web page <head> tag and the
JavaScript library bootstrap file included. Assuming you installed the
JavaScript library into the web application directory
$SRC/myapp/web/resources, the following code will load and initialize
the JavaScript library in the page.
<head>
<script type="text/javascript">
var @JS_NS@Config = {
namespace: "woodstock"
};
</script>
<script type="text/javascript"
src="/myapp/resources@THEME_PATH@/javascript/bootstrap.js"></script>
</head>
The global @JS_NS@Config variable is defined to
specify the a namespace path to the
functions in the Woodstock JavaScript library. Each version of the
JavaScript library contains a version number in its name space (this
is necessary when using the JavaScript library in a portal web
application). By defining the namespace, a new version of the
JavaScript library could be used without changing the name space paths
throughout the remainder of the web page. If this global variable is
not availble, @JS_NAME@Config will be used.
Widgets are rendered in the web page by adding a
createWidget function call in a JavaScript tag. Initial
properties can be specified for the widget via a JavaScript object
literal parameter. To create an instance of the staticText widget in
the page, for example, add the following JavaScript tag to the <body>
of the page at the point where the widget
should be displayed.
<span id="sp1">
<script type="text/javascript">
woodstock.widget.common.createWidget("sp1", {
id: "text1",
value: "This is the text to be rendered.",
widgetType: "staticText"
});
</script>
</span>
Note that the createWidget function accepts two
parameters. The first parameter specifies the identifier of a DOM
element in the page at which the HTML generated will be positioned,
when the widget is displayed by the browser. If the HTML element is a
<span> that is the immediate parent of the
<script> tag, a more efficient algorithm is used to
locate and render the widget. The second parameter is a JavaScript
object literal specifying inital values for the widget's
properties. Each widget must be specified with a unique identifier and
a widget type property. Additional properties are specific to the type
of widget. For a staticText widget, we provide the initial value of
the the text to be rendered. In many cases, the default value set for
a property when the widget is created in the browser will be
sufficient (so additional values do not need to be provided to the
createWidget function).
Widget Interfaces
Each widget provides several functional interfaces which can be used to
retrieve and update widget properties, to cause widget events to be
fired, or to execute helper functions specific to each widget. These
functions are typically called from web application JavaScript written
as event handlers on HTML elements; e.g., onClick, onMouseOver, etc.
They may also be called by web application event handlers which make
XMLHttpRequest calls to a server to read or update backend data stores,
or to refresh the properties of the widget.
With exception to the submit feature, most widgets define the following
functions:
Object getProps()
The getProps function is used to
retrieve widget properties. Returns a JavaScript object literal
containing the properties for the widget as name-value pairs.
boolean setProps(props, notify)
The setProps function sets widget
properties using JavaScript Object literals. The props parameter
contains name-value paris for only those properties to be updated (a
sparse list). The notify parameter is a boolean indicating
that with widget's state change event should be published after
updating the properties. Event handler JavaScript functions on the page
can subscribe to the event; e.g., to make an XMLHttpRequest to the
server to keep the client-side state synchronized to the server-side
state. Returns true if successful.
boolean refresh(execute)
Causes the widget to be refreshed. The
widget publishes its refresh.beginTopic event to inform subscribing
event handlers that an XMLHttpRequest call should be made to the server
to obtain updated data for the widget. An event payload
JavaScript object is provided that specifies the widget's identifier,
an event topic to be published upon the server call return, and the
optional list of other widget identifiers which are participating in
the event (specified in the execute parameter). The event handler
should obtain updated properties for the widget and reset those
properties in the widget by calling its setProps function. After
updating the widget's properties, the event handler should publish the
event topic specified in the payload, informing other interested
widgets of the refresh. Returns true if successful.
boolean submit(execute)
Causes the widget to publish an event
indicating widget properties should be submitted. The widget publishes
its submit.BeginTopic event to inform subscribing event handlers that
an XMLHttpRequest call should be made to the server to submit the
widget values. An event payload JavaScript object is provided that
specifies the widget's identifier, an event topic to be published upon
the server call return, and the optional list of other widget
identifiers which are participating in the event (specified in the
execute parameter). The event handler should submit the widget values
and publish the event specified in the payload, informing other
interested widgets of the submit. Returns true if successful.
Widget Events
Each widget defines event topics that are used to publish events for
asynchronous processing on the page. Web application developers may
provide event handler JavaScript functions in the page which subscribe
to a widget's events. The event provides a JavaScript object literal as
a payload, specifying name-value pairs of property information
pertinent to the specific event topic. The "id" property indicating the
identifier of the widget generating the event is always include in the
payload object, and together with the event topic (being subscribed to)
provides sufficient information for the event handler JavaScript to
process data for the event.
<script type="text/javascript">
var foo = {
/**
* Process refresh event.
*
* @param {Object}
props Key-Value pairs of properties.
*/
processRefreshEvent:
function(props) {
// Get the
widget id.
if (props.id ==
"text1") { // Do something... }
}
}
// Subscribe to refresh event.
woodstock.widget.common.subscribe(woodstock.widget.staticText.event.refresh.endTopic,
foo, "processRefreshEvent");
</script>
Most widget events are associated with asynchronous operations
involving XMLHttpRequest calls to the server. For this type of event,
the widget will publish a "beginTopic" event with a payload object that
includes an associated "endTopic" event. The event handler is expected
to extract relevant data from the payload object and/or the widget
itself, format an XMLHttpRequest to the server, process any response
data, and apply that data to the widget who published the event (for
example, by calling the widget's setProps function to update properties
with server data). The event handler should then publish the endTopic
event to inform interested widgets on the page that the event has
concluded.
Most widgets define the following event topics:
event.refresh.beginTopic
Inidicates that a widget needs its data
to be refreshed from the server, and its properties updated. The event
payload JavaScript object contains:
{id: "widget_identifier", endTopic: "event_name", execute:
"list_of_widget_ids"}
where list_of_widget_ids is a comma separated list of widget
identifiers for other widgets participating in the refresh event and
endTopic is the name of the event to publish when the event processing
finishes.
event.refresh.endTopic
Indicates that a refresh event has been
processed for a widget. The event handler publishing this event may add
a JavaScript object literal payload to the event; for example,
containing the name-value pairs of the properties that were updated in
the widget that published the associated beginTopic event.
event.state.beginTopic
Indicates that the properties of a
widget have been updated. This event is published when the widget's
setProps function is called with the notify parameter set to
true. The event payload JavaScript object contains:
{id: "widget_identifier", endTopic: "event_name", prop_1:
"value_1", ...}
where prop_1, ... are properties that have been updated, and
endTopic is the name of the event to publish when the event processing
finishes. The event handler is expected to communicate the state change
to the server by making an XMLHttpRequest; that is, this event is used
to synchronize state changes in the widget with the server side.
event.state.endTopic
Indicates that a state change event has
been processed for a widget. The event handler publishing this event
may add a JavaScript object literal payload to the event; for example,
containing the name-value pairs of the properties that were changed in
the widget that published the associated beginTopic event. Unlike
the refresh event, the widget publishing the state change event is not
updated with data from the server.
Widget Form Data
Since widgets are used to render HTML elements onto the web page,
there may be form submitted values which occur from those rendered HTML
elements. These values can be used by the server to obtain
values that apply to the server code supporting the widget (for eample,
in a server framework such as JSF). It is the responsibility of
the server code to re-associate these submitted values with the
corresponding widget information.
Custom Widgets
Interfaces marked with an '_' character are considered
private and are intended to be used by Woodstock developers
only. Since the Woodstock JavaScript library is open source, custom
widget developers are free to take a snapshot at anytime. However,
there are no guarantees that interfaces marked private will not change
in the future. Such users must continue to use their snapshot if
compatibility is a factor, or must port to a new snapshot. Before
Woodstock can consider buying back a customized or new widget, it must
conform to the current set of Woodstock APIs at the time
of the buy back.