At the end of Chapter 2, we added a scene to the News application using HTML buttons and the back gesture. While it’s not really visible in the UI, we’re going to replace the HTML buttons with Button widgets so you can see how to add a simple widget. If you think you are already clear on how this works, you can skip ahead to the section on Lists.

The first change is simple: replace the button tags in storyView-scene.html with widget declarations:

<div id="storyViewScene">
    <div class="palm-page-header multi-line">
        <div class="palm-page-header-wrapper">
            <div id="storyViewTitle" class="title left">
            </div>
        </div>
    </div>
    <div class="palm-text-wrapper">
        <div id="storyViewSummary" class="palm-body-text">
        </div>
    </div>

    <div x-mojo-element="Button" id="previousStory"></div>
    <div x-mojo-element="Button" id="nextStory"></div>

</div>

The next change is to the storyView-assistant.js; add the widget setup in front of the listeners for the button taps. We’re not changing the button id in either case, so we don’t have to change the listener setup functions at all:

StoryViewAssistant.prototype.setup = function() {
    this.nextModel = {disabled: false};
    this.previousModel = {disabled: false};

    if (this.storyIndex === 0)    {
        this.previousModel.disabled = true;
    }

    if (this.storyIndex == this.storyFeed.stories.length-1)    {
        this.nextModel.disabled = true;
    }

    this.controller.setupWidget("previousStory", {label: "Previous"}, 
    this.previousModel);
    this.controller.setupWidget("nextStory", {label: "Next"}, this.nextModel);

    this.nextStoryHandler = this.nextStory.bindAsEventListener(this);
    this.previousStoryHandler = this.previousStory.bindAsEventListener(this);
    this.controller.listen("nextStory", Mojo.Event.tap,
      this.nextStoryHandler);
    this.controller.listen("previousStory", Mojo.Event.tap,
      this.previousStoryHandler);

    // Update story title in header and summary
    var storyViewTitleElement = this.controller.get("storyViewTitle");
    var storyViewSummaryElement = this.controller.get("storyViewSummary");
    storyViewTitleElement.innerHTML = this.storyFeed.stories[this.storyIndex].title;
    storyViewSummaryElement.innerHTML = this.storyFeed.stories[this.storyIndex].text;
};

The rest of the code stays the same. When you run this version of the application, it behaves the same as the previous version even though it uses Button widgets instead of the HTML button.

A Check Box widget (Figure 3-2) controls and indicates a binary state value in one element.

Figure 3-2. A Check Box widget example

Tapping a check box on the screen will toggle its state, presenting or removing a checkmark, depending on the previous state. The framework handles the display changes and will manage the widget’s data model for you, toggling between two states that you defined at setup time.

The Toggle Button is another widget for displaying and controlling a binary state value. As with a check box, a toggle button (Figure 3-3) will switch between two states each time it is tapped.

Figure 3-3. A Toggle Button widget example

If you need a single widget to select from among multiple choices while also showing selection status, then a Radio Button (Figure 3-4) is a good choice. Mojo provides a classic radio button, which presents each button as a labeled selection option in a horizontal array, where only one option can be selected at a time.

The number of options is variable, constrained only by the width of the display and the minimum button size that can be pleasingly presented or selected. You can expect to handle between two and five states, given the typical screen size for a webOS device, but the framework won’t limit you.

Figure 3-4. A Radio Button widget example

Even though you might expect to find the List Selector as one of the List widgets, it behaves and is managed as a selector. It enables the selection of one of many options, presented in a pop-up list in which there is no practical limit to the number of options presented. It is similar to the Submenu widget’s behavior. Figure 3-5 shows an example of the List Selector widget.

Figure 3-5. A List Selector widget example

The selection options are defined in a required choices array, which defines each selection’s displayed label and a corresponding value. If the choices are static, meaning they never change over the life of the scene, you define the array as a property in the widget’s attributes. If the choices are subject to change, attach them as a model property instead.

<div class="palm-group unlabeled">
  <div class="palm-list">
    <div class="palm-row first">
      <div id="trainSelector" x-mojo-element="ListSelector"></div>
    </div>
    <div class="palm-row">
      <div id="departureSelector" x-mojo-element="ListSelector"></div>
    </div>
    <div class="palm-row">
      <div id="destinationSelector" x-mojo-element="ListSelector"></div>
    </div>
    <div class="palm-row last">
      <div id="timeSelector" x-mojo-element="ListSelector"></div>
    </div>
  </div>
 </div>

The List Selector is like the List widget in its styling. To have the webOS look and feel, you’ll need to wrap your widget declaration with styling divs like those used with the List widget, and you may need to style those List classes with your own CSS. See the below section for more information.

The last widget in this group of selectors is the Slider, which presents a range of selection options in the form of a horizontal slider with a control knob that users can drag to the desired location. You must specify minimum (leftmost) and maximum (rightmost) values for the slider. Figure 3-6 shows an example of the Slider widget.

Figure 3-6. A Slider widget example