Mojo Widgets are dynamic user interface controls provided by webOS to help application developers build feature-rich interactive applications. Types of widgets include static lists, dynamic lists, button controls, selectors, text fields, menus, dialogs, pickers, and viewers. For an up-to-date list of all widgets, check out our UI Widget reference. (At time of writing, the list may still be subject to change.)
Note: The info in this article was covered in Chapter 3 of Palm webOS by Mitch Allen. (For additional detail, consider purchasing access to the Rough Cuts book; a real bargain at $17.99.)
Common methods for declaring, instantiating and managing widgets make it possible to start using a wide variety of widgets in your application. In a sentence, Mojo widgets are set up through sceneController.setupWidget(), visually customized with CSS styles and managed through Mojo events.
Setting up a widget
As we've seen before, widgets are created by giving an empty div in a scene's view file an x-mojo-element attribute with a value set to the type of widget you want to display.
A widget is usually instantiated in a scene assistant's setup method or when a widget is specified in an HTML template used by another widget (e.g. a list widget containing a widget in each list element). At this point, the contents of the div are replaced with the HTML of the actual widget.
A widget is set up by calling SceneController.setupWidget(). This function takes takes 3 arguments:
| Argument | Description |
| Widget ID | The id or name of the div element in which the widget was declared |
| Attributes | Object containing the widget's static properties, normally options or attributes of the widget |
| Model | Object containing the widget's dynamic properties, usually data associated with the widget but occasionally having dynamic attributes |
Here's a ToggleButton example:
this.toggle = { trueValue:'on', trueLabel:'On', falseValue:'off', falseLabel:'Off' };
this.toggleModel = { value:'on', disabled:false };
this.controller.setupWidget('my-toggle', this.toggle, this.toggleModel);
Note that in this example the Attributes and Model arguments are both specified as JSON objects, which are then passed into the setupWidget function.
Widget ID ('my-toggle'): Note that the id or name attribute of the div element containing the widget can be used. As ids must be unique within a scene, if a the widget is instantiated more than once, you'll need to use the name attribute.
Attributes (this.toggle): Attributes are static properties that affect the behavior and display of the widget. They are specifiedat setup time and cannot be changed after the widget is instantiated. A Toggle button's attriburtes include trueValue and falseValue, which allow you to toggle between whatever values you choose (e.g. up/down, on/off), and trueLabel and falseLabel, which provide a visual cue that matches these values or displays some other text to the user.
Model (this.toggleModel): The Model argument contains the data model object that determines the actual data contained in the widget.
Separating attributes from the data model allows widgets being used as list elements to share common properties but still retain unique data in each element.
Updating a Widget's Data
When the contents of a data model are changed, widgets using that model do not automatically get updated.The application (scene assistant, in most cases) must call modelChanged() on the widget's scenecontroller, passing the model object that changed:
this.toggleModel.disabled = true; this.controller.modelChanged(this.toggleModel, this);
The scene controller then notifies all widgets using that model so they display the current model data. The first argument is the model object that was changed. The second argument identifies the object that changed the model, which ensures that objects are not notified of their own changes to the model.
Using modelChanged() updates a widget's copy of its model indirectly. setWidgetModel() changes the data model of a specific widget instance directly.
// Use a new model object in place of the old one:
this.newToggleModel = {value:'off'};
// Set the widget to use the new model:
this.controller.setWidgetModel("my-toggle", this.newToggleModel);
Event Handling
All widgets are supported by events. Some are common events, such as tap or propertyChange, others are widget specific, such as listDelete, listReorder, and scrollingStarted.
Palm recommends that event listeners be set up in the setup() method of scene assistants by adding listeners to the div element that declares the widget. For example, a Toggle Button sends a Mojo.Event.propertyChange event each time it is toggled, causing its model to change value. Here's how to set up listener code for this event:
This.controller.listen("my-toggle", Mojo.Event.propertyChanged,
this.handleSelectorChange.bindAsEventListener(this));
Summary
You have now seen how widgets are set up, how their data is managed and how to listen for and take action on widget events. For additional widget-specific info and examples, check out the ever-evolving UI widget list.
0 Comments