Sample widgets overview

You will develop two widgets which communicate with each other.

You will build two widgets, one which lists some WebSphere products in a drop-down list called Selection and, when used, sends notification (known as firing an event) to the second widget called Details. The Details widget receives the notification and shows the details of the product selection in a table.

To create any widget, including the two you will create, you must understand some basic concepts. These concepts are discussed in the following list along with a look at the two widgets you will create.

Widget definition

To create a Business Space widget, you must provide two things: a widget definition, and a widget implementation.

The widget definition is an XML file that describes the widget properties. The properties include the widget's name, description, attributes, and the events that it may produce or that it may accept. This XML file must conform to the iWidget definition. A reference to this specification and other related programming information you can use to develop your widget definition can be found in the Widget programming guide.

An example of a widget definition and a discussion of its attributes, events, modes and resources is shown in Creating the Selection widget and Creating the Details widget.

Widget implementation

The widget implementation is, as its name implies, the implementation of the widget. It is typically written in JavaScript and uses a Dojo class as an entry point to an iContext class at runtime.

The iContext is a class that is supplied by the widget runtime environment and provides the widget with services such as access to global variables, a shared state, local variable storage, widget communication using events, remote services, mode support and many other useful capabilities. The iContext class is central to the widget runtime environment and provides all the environmental services that are required.

In the following runtime diagram, each widget has a corresponding Dojo class. This class is the entry point to the widget. As a widget writer you may choose any suitable language to implement the core of your widget, however, you must provide an entry point that is a Dojo 1.0.2 class (for Business Space 6.2 or 6.2.0.1) or Dojo 1.0.3 class (for Business Space 6.2.0.3). This entry point is also known as the widget's "scope" and is the part of the widget that interacts with the environment through the iContext class.

The iContext class is discussed in the iWidget specification referenced in the Widget programming guide

Interaction of widgets at runtime using events

An example of a widget implementation and a discussion of its attributes, events, resources and modes is shown in Creating the Selection widget and Creating the Details widget.

Widget attributes

Attributes control a widget's look and feel and data sources. Attributes are often exposed as points of configuration for the widget. For example, a widget displaying hotel information in Canada might define an attribute for the Canadian postal code format and use it as a default for Canadian hotels showing address information. The persistence and lifecycle for attributes are managed by the iContext class.

Widget events

Events provide a transitory means of sharing information. Widgets typically use events when widgets need to share information with each other.

Widgets can both send and receive events. Each widget decides when to send events and which events to receive. This is done through a publish/subscribe model in the widget's definition. The widget's definition specifies which events can be published (sent) by the widget, and which events that the widget can handle (receive).

Widget resources

Resources are additional items your widget can use. For example, a resource could be a script or a Cascading Stye Sheet (CSS) file. Resources are typically referenced in the iWidget definition as discussed in the iWidget specification. See the Widget programming guide.

Widget modes

A mode specifies what type of markup to generate for the user. For example, a mode might be a view mode, which would be the normal user markup, or an edit mode, which would be used for editing the widgets attributes. Another mode is an attachment mode, which provides a snapshot of a widget or a widget captured at a moment in time. This attachment can be persisted to a server, stored in another widget, and displayed to a user.

The edit and attachment modes are optional, but every widget is assumed to be in view mode when it is first instantiated.

An example of a widget definition, implementation and a discussion of its attributes, events, resources and modes is shown in Creating the Selection widget and Creating the Details widget.

Selection and Details widgets

The Selection and Details sample widgets give you an opportunity to study a working example of widget definitions and implementations. These widgets communicate with each other using events, and contain in their definition attributes the elements discussed previously.

The code for the these widgets is provided. In your temporary directory where you unzipped the samples widgets, you will find the Selection widget code in the following directory:

<temporary directory>\IBM_BSPACE_SAMPLES.ear\BSpaceWidgetsSamples.war\iWidget\widgets\samples\selectionSample

You will find the Details widget code in the following directory:

<temporary directory>\IBM_BSPACE_SAMPLES.ear\BSpaceWidgetsSamples.war\iWidget\widgets\samples\detailsSample

Begin creating your own widget by looking at the Selection widget in Creating the Selection widget.