There aren’t any long operations in News other than the feed updates, which are asynchronous. We’ll add a spinner to the feed list whenever an update is in progress, demonstrating a simple application of an indicator.

This will also demonstrate the technique for including widgets within a list entry, a powerful Mojo feature introduced in Chapter 3. You already know that you can use widgets to display dynamic data; by combining them into lists you can create complex UI controls with the widgets as building blocks. You may want to review Chapter 3 if you have questions after reading these next few paragraphs.

You can design list entries to include other widgets, including other lists, in almost the same way that you use widgets outside of lists. The differences are that the list’s model includes the widgets’ models, and that you declare widgets within the list’s itemTemplate, using a name attribute to identify each widget.

In this example, a Spinner widget is included in each feedListWgt entry, which will be activated when the corresponding news feed is updated through an Ajax request. Start by adding the spinner declaration into the feedListWgt’s row template, views/feedList/feedRowTemplate.html:

<div class="feedlist-info icon right" id="info"></div>
<div x-mojo-element="Spinner" class="right" name="feedSpinner"</div>
<div class="feedlist-title truncating-text">#{title}</div>
<div class="feedlist-url truncating-text">#{-url}</div>

The new line is the div with the name feedSpinner and is simply a declaration of the Spinner widget. The syntax should start to seem familiar by now.

By including it into the feedListWgt list item’s template, we have implicitly directed the List widget to insert a new spinner element in the DOM whenever it creates a new entry. It’s the same as creating a spinner outside of a list, except in one major way: the spinner’s model property must be part of the feedListWgt’s items array.

We still have to set up the Spinner widget, which we do in the setup method of feedList-assistant.js, but we don’t include a model in the call to setupWidget(), as that is assumed to be part of the feedListWgt’s items array:

    // Setup the feed list, but it's empty
this.controller.setupWidget("feedListWgt",
     {
        itemTemplate:"feedList/feedRowTemplate",
        listTemplate:"feedList/feedListTemplate",
        addItemLabel:"Add...",
        swipeToDelete:true,
        renderLimit: 40,
        reorderable:true
    },
    this.feedWgtModel = {items: this.feeds.list});

// Setup event handlers: list selection, add, delete and reorder feed entry
this.showFeedHandler = this.showFeed.bindAsEventListener(this);
this.controller.listen("feedListWgt", Mojo.Event.listTap,
    this.showFeedHandler);
this.addNewFeedHandler = this.addNewFeed.bindAsEventListener(this);
this.controller.listen("feedListWgt", Mojo.Event.listAdd,
    this.addNewFeedHandler);
this.listDeleteFeedHandler = this.listDeleteFeed.bindAsEventListener(this);
this.controller.listen("feedListWgt", Mojo.Event.listDelete,
    this.listDeleteFeedHandler);
this.listReorderFeedHandler = this.listReorderFeed.bindAsEventListener(this);
this.controller.listen("feedListWgt", Mojo.Event.listReorder,
    this.listReorderFeedHandler);

// Setup spinner for feedlist updates
this.controller.setupWidget("feedSpinner", {property: "value"});

Most of the feedList assistant’s setup method is shown in this code sample; the only addition is the last line of code (and preceding comment). It sets up the spinner, naming the model property as value, but the model is not in the arguments list; the list’s model, this.feedWgtModel, is used implicitly as the spinner’s model.

The feedList default data is defined at the beginning of the stage-assistant.js. Add the value property to each default list entry, and set it to false. This is the spinner’s model, and will start as false since there is no activity. You need to include this for every feedList entry, as in this example:

{
   title:"New York Times",
   url:"http://www.nytimes.com/services/xml/rss/nyt/HomePage.xml",
   type:"rss", value:false, numUnRead:0, newStoryCount:0, stories:[]
},

There’s one other place where a new feed list entry is created; in the checkOk method of addDialog-assistant.js:

//  If a new feed, push the entered feed data on to the feedlist and
//  call processFeed to evaluate it.
if (this.feedIndex === null) {
    this.feeds.list.push({title:this.nameModel.value,
        url:this.urlModel.value, type:"", value:false, numUnRead:0,
        stories:[]});
    // processFeed - index defaults to last entry
    feedError = this.feeds.processFeed(transport);
}
else    {
    this.feeds.list[this.feedIndex] = {title:this.nameModel.value,
        url:this.urlModel.value, type:"", value:false, numUnRead:0,
        stories:[]};
    feedError = this.feeds.processFeed(transport, this.feedIndex);
}

The spinner is set up and integrated into the list’s template and model. All that remains is to activate and deactivate the spinner at the right times. Those times are just before the Ajax request is made (spinner activated) and after the response is received (spinner deactivated) whether the request was successful or not.

There are four changes to make, all in the feeds model:

The sample below shows the changes to updateFeedSuccess(), which includes both an activate and a deactivate call:

// Process the feed, passing in transport holding the updated feed data
var feedError = this.processFeed(transport, this.feedIndex);

// If successful processFeed returns News.errorNone,
if (feedError !== News.errorNone)    {
    // There was a feed process error; unlikely, but could happen if the
    // feed was changed by the feed service. Log the error.
    if (feedError == News.invalidFeedError)    {
        Mojo.Log.info("Feed ", this.nameModel.value,
          " is not a supported feed type.");
    }
}

News.feedListChanged = true;
// Change feed update indicator & update widget
var spinnerModel = this.list[this.feedIndex];
spinnerModel.value = false;
this.updateListModel();

// If NOT the last feed then update the feedsource and request next feed
this.feedIndex++;
if(this.feedIndex < this.list.length) {
    this.currentFeed = this.list[this.feedIndex];

    // Request an update for the next feed but first
    // change the feed update indicator & update widget
    spinnerModel = this.list[this.feedIndex];
    spinnerModel.value = true;
    this.updateListModel();

    this.updateFeedRequest(this.currentFeed);
} else {

    // Otherwise, this update is done. Reset index to 0 for next update
    this.feedIndex = 0;
    News.feedListUpdateInProgress = false;

}
     .
     .
     .

In each case, we set the spinnerModel.value and call this.updateListModel() to update the model changing the state of the spinner. The spinner’s model is accessed by referencing the this.feedIndex, the array index for the feed that is being updated, then setting that entry’s value property to change just the spinner in that list entry.

Run the application, and the feeds will update one after another. If you wait for the feed interval to pass, they will update again. You will see a spinner appear between the feed title and the unread count badge on the left side, as shown in Figure 5-1, with the spinner on the BBC News feed item.

Figure 5-1. Spinner on News feed updates

Spinners only take up space when they’re active. In some cases, if the feed title is long enough, you’ll see the title truncated to accommodate the spinner, then resize to fill the vacated space after the spinner is deactivated. Elegant integration of indicators is the type of polish that makes an application appealing and easy to do with Mojo’s widgets.

Use a Progress Pill widget (Figure 5-2) to show download progress when loading from a database, or anytime you initiate a long-running operation and have a sense of the duration.

Figure 5-2. A Progress Pill widget example

The indicator is designed to show a pill image that corresponds to the model’s value property, where a value of 0 has no pill exposed and a value of 1 has the pill completely filling the container. Initialize the indicator’s model value to 0, then progressively update the model property until it has a value of 1.

It’s best to use an interval timer. At each interval callback, increase the progress indicator’s value property and call the updateModel function. For example, start with the progress pill’s value property set to 0 and set an interval timer for 600 ms. Assuming the planned operation will take about 3 seconds, you would increase the value property from 0 to 0.2 at the first update and again by 0.2 at each update thereafter:

if (this.progressCounter > 1) {
    // This operation is complete!
    this.completeProgress();
}
else {
    this.pillModel.progress = this.pillModel.progress + 0.2;
    this.controller.modelChanged(this.pillModel);
}

The Progress Bar widget is exactly the same as the progress pill, except that you use x-mojo-element="ProgressBar" in your scene file. Otherwise, you code it and manage it just as you do the progress pill. Figure 5-3 shows a progress bar.

Figure 5-3. A Progress Bar widget example

In the default style, there isn’t room on the bar for a title or image, but the properties are supported nonetheless.

For media or other applications where you want to show progress as part of a tracking slider, the Progress Slider widget is an ideal choice. Combining the Slider widget with the progress pill, the behavior is fully integrated, but not all of the configuration options are represented. Figure 5-4 shows a progress slider.

Figure 5-4. A Progress Slider widget example

All of the slider properties are represented, and you configure the progress slider just as you would a Slider widget. You have a model property of value, which can be renamed through the attributes property. You manage it exactly as you would the progress pill, by progressively increasing the value property from 0 to 1.

this.controller.setupWidget("my-widget", Attr, this.widgetModel);

this.target = this.controller.get("an-element");
this.target.innerHTML = "<div id='my-widget' x-mojo-element='List'></div>";

this.controller.update($("an-element"), "<div id='my-id' x-mojo-element='List'></div>")