Using Lists in webOS – Mastering the Oldest Mobile Profession

The List widget is central to webOS applications -- master the List widget and you're well on your way to creating great webOS applications

In the beginning…

In the beginning God created the heavens and the earth.

And not long after we had lots and lots of data to manage.

Fast forward to today and we get to manage that data with cool little gadgets called smartphones. Smartphones are supposed to help make our lives more efficient and on a good day, I think that might be the case. And even if we only carry the device to look cool (ahhem, can anyone say iPhone …) we still wind up managing data with our devices. At minimum, we view our call and SMS history on the device. More often than not, that data is presented in one or more lists.

Because lists are so central to mobile software development, we are going to take a look at using the List widget in Palm’s webOS.

Getting Started

We are going to build an application which manages a basketball team roster. At the risk of aging myself, the default data will be some of the players from the Los Angeles Lakers from the 80′s as shown in the image below.


Palm webOS lists have quite a bit of functionality — much more so than a typical column of data as you might find on other platforms. This functionality includes but is not limited to:

  • Swipe to Delete
  • Reordering
  • Built-in “Add New feature
  • Templatized layout
  • Dynamic rendering capability, as desired
  • and much more

With all of this capability comes a little complexity — which is to say that it just takes some practice to get a feel for the design pattern of working with a webOS List widget. Once you have built one or two applications containing List widgets, you will start to think differently about how the application should be constructed to begin with. The List can really become central to many applications as you start to “think” like a webOS user. I really appreciate the fact that so much can be done intuitively with the List without the need for extra buttons and menus to crowd out the user interface and confuse your user. There is no need for highlighting an item and then tapping a menu or using a separate button to delete it — just swipe it and confirm the deletion. The image below shows us deleting Michael Cooper. Sorry Mike.


Rearranging entries is as simple as tap-and-hold-and-drag. Want to add a new entry? Just tap the “+Add New Player” entry at the bottom. Obviously you can change the text to suit your application’s needs, unless you are an NBA General Manager, and then perhaps we should talk. Let’s have a look at what we need to do to build this application. Note, if you are anxious to browse the full code and mess with it, you can find it here. You can check out a copy with a subversion client if you want to build the application yourself.

The code

We’ll start with the scene description, found in home-scene.html. In this scene we define a List widget with a “div” element with a special attribute of “x-mojo-element”.

<div class="palm-group">
	<div class="palm-group-title" style="text-align:center">List Fun</div>
		<div class="palm-list" >
		<div x-mojo-element="List" id="teamList"></div>

In order to use this List widget, we need to set it up in the scene’s assistant file, home-assistant.js. In particular, we are interested in the setup function where we invoke a method called setupWidget from the Scene Controller. The setupWidget function takes three parameters:

  • The id attribute value defined in the scene’s html file. In this case the value is “teamList”
  • A json object which represents the options to setup this widget
  • A data model — the data for the list

Note the following options values in use in our code (shown below):

itemTemplate This is a required snippet of html (stored in an actual html file) which contains the formatting information for laying out an individual entry in the list.
listTemplate This is an optional snippet of html used to define how the listItems are arranged as a group.
addItemLabel If this option is present, an additional list entry is added to the bottom of the list with the text provided. Tapping this entry caused the Mojo.Event.listAdd event to be fired.
swipeToDelete Permits the deletion event when an item is swiped. When this gesture is detected by webOS, the function registered to handle the Mojo.Event.listDelete event is invoked.
reorderable Permits the items in the list to be reordered.
dividerFunction This is a function used to help sort the entries into groupings.

This represents just a subset of the options available for the List widget. For a complete reference visit the Palm Developer website. Here is the code to setup our List widget.

		itemTemplate: 'home/listentry',
		listTemplate: 'home/listcontainer',
		addItemLabel: 'Add New Player',
		swipeToDelete: true,
                reorderable: true,
		dividerFunction : this.whatPosition

Let’s take a moment to discuss the data model in particular. This is represented in our sample application as the variable “listModel”. It is defined in the scene’s constructor:

function HomeAssistant() {
	this.listModel =
		items : [

Note that the variable has a property named “items”. This is very important — the List widget expects to find a property of the dataModel which contains an array of objects. The property name must be items. In this case, our items array contains objects with NBA player information. Each player “record” contains properties representing: name, position, and jersey number. These properties wind up in the list by including them in the listentry template. In our case it is found in the /app/views/home/listentry.html file:

<div class='palm-row' x-mojo-tap-highlight="momentary"&rt
	#{name} (##{number})

Note that the pattern for property inclusion is the pound or hash sign (#) followed by the property name within curly braces. Don’t get confused by the double ## in this example. The first symbol is a literal # used to designate a player’s jersey number and the second is used as a template marker for the property containing the jersey number.

After we have setup our widget, we want to register event listeners for the various events of interest. In this case we are interested in capturing when a list entry is tapped, when the “add new player” is selected, when an entry is deleted and when items are re-ordered by the user. Note that these event handler registrations are normally included in the setup method following the call to setupWidget.

	/* add event handlers to listen to events from widgets */
	this.controller.listen('teamList',Mojo.Event.listTap, this.listTapped.bindAsEventListener(this));
	this.controller.listen('teamList',Mojo.Event.listAdd, this.listAdd.bindAsEventListener(this));
	this.controller.listen('teamList',Mojo.Event.listDelete, this.listDelete.bindAsEventListener(this));
	this.controller.listen('teamList',Mojo.Event.listReorder, this.listReorder.bindAsEventListener(this));

Proper form would have use “unregister” these listeners in the cleanup method. We’ll save that for a rainy day.

The event handlers

When an event occurs we want to handle it appropriately — let’s take a quick look at the handlers we have registered for this List widget instance.

When the list is tapped, we want to take some sort of action — in this case we are going to write an entry to the application log and then display a simple dialog to display the player’s name represented by the selected list item. The method we are using is errorDialog. Don’t get alarmed about the word error — this just happens to be a quick and dirty way to show a message.

HomeAssistant.prototype.listTapped = function(event){
	Mojo.Log.info("#############List Tapped [" + event.index + "]");


Note the multitude of #’s is to help us find the entry in the very busy log output.

When the “Add New Player” entry is tapped, the listAdd function is invoked, as previously registered. At present this function does nothing other than make an entry into the log.

HomeAssistant.prototype.listAdd = function(event){
	Mojo.Log.info("#############List Add");
   // TODO : add more features to this sample application :)

When an entry is “swiped” and the Delete button is confirmed, the listDelete function is invoked.

HomeAssistant.prototype.listDelete = function(event){
	Mojo.Log.info("#############Delete entry" + event.index);

Note that in this function we do a little management of the listModel.items array to actually remove the selected index.

And here is the re-order function, invoked when one of the list items is dragged to a new position. Note that there are properties of the event argument named fromIndex and toIndex — these tell us which items were involved in the swap.

HomeAssistant.prototype.listReorder = function(event){
	Mojo.Log.info("#############List Reorder" + event.fromIndex + " to " + event.toIndex);
	var f = this.listModel.items[event.fromIndex];
	var t = this.listModel.items[event.toIndex];
	this.listModel.items[event.fromIndex] = t;
	this.listModel.items[event.toIndex] = f;

At this point our list has most of the functionality we could ask for. There is one other function I want to hilight before we wrap up with a couple of important pieces of trivia. Note that in the list we have the “G”, the “C” and the “F” showing in the list as dividers. This is implemented by way of the function defined in the dividerFunction option passed to setupWidget. In our case we are simply taking the first letter from the position property of the data. So for example, the first letter of “Guard” is “G”. This places the items under a divider tab in the list of “G”.

The visual effect comes from a built-in, default style provided by Palm. You can also override this with a dividerTemplate. One thing to keep in mind is that you can have multiple occurences of these dividers depending on the order of the data. For the sake of being complete, here is the divider function’s implementation for our application.

HomeAssistant.prototype.whatPosition = function(data){
	// return the first letter of the position (G,C,F)
	return data.position[0];

Now for that trivia.

A cautionary tail about framework_config.json

When I first built this application, I kept getting an annoying problem when rendering the scene. Then I remembered that I needed to add a file called framework_config.json. In this file I have added two attributes — without these entries, this application will not run and you would be frustrated. Like I was, until I remembered them.

	"escapeHTMLInTemplates": false,
	"logLevel": 99

The “escapeHTMLInTemplates” entry allows us to use html in the templates supplied to the setupWidget function as options. If we don’t set this value to false, we don’t see our list. You have been warned.

The “logLevel” entry is setting the logging level to the maximum threshold (or minimum, depending on how you want to look at this). Any log entry made via the Mojo.Log.info, Mojo.Log.error, or Mojo.Log.warn functions will be seen when this value is above their respective thresholds. At this point in my webOS career, I just set this value to 99 so I see everything.

Speaking of seeing the log entries, these can be seen in either the Palm Inspector application (be sure to start your app in debug mode as ‘inspectable’). Alternatively, the way I normally view the logs is by establishing an SSH session and viewing a tail of the log. For example, this application log can be viewed with a command line of :

log com.msiservices.listfun

That about wraps things up for now. In a future column we’ll look at persisting this data so our changes are saved from one run to the next of the application.

Comments on "Using Lists in webOS – Mastering the Oldest Mobile Profession"

lower crime insurance car making future car insurance quote multiple auto head-on car insurance quote whole face accidents car insurance online included know auto insurance customer various disaster cheap auto insurance usually give understandable insurance auto live forever passes between automobile insurance spending more

form car insurance always offer use caution free car insurance outstanding through things auto insurance quotes major cities clean driving car insurance risk involved repairs cheapest auto insurance superior ability

obtaining car insurance companies due scoring provide insurance car reports police deductible cheap car insurance quotes kitchen thousand cheap car insurance web life

Here is an excellent Blog You may Uncover Interesting that we encourage you to visit.

The colors of the season are alive on a sleeveless dress
that will look at home on any girl. The footwear really should be this kind of that they enrich the elegance of her dress and simultaneously,
make her so at ease that she can definitely delight in her particular day.
However, enforcing a dress code will definitely allow lower-income families to be
able to afford clothing that fits into these limitations.
Few dresses can ever hope to rival the traditional beauty
of the white flower girl dress. One of the most important things to remember about a maternity wedding dress is that your body will change drastically over
the 9 months and so your dress will have to accommodate this.
Dresses for girls are tops, party dresses, t-shirts,
shirts, sweatshirts, bottoms, coordinated sets, traditional wear, sweaters, jackets, night wear, inner wear and swim apparel.

The details mentioned in the report are some of the very best obtainable.

Here are some links to sites that we link to mainly because we feel they are worth visiting.

could get a crew of fair miniatures of knightly medicine be
fit to learn judge for river, ‘ theologizer, Sr.,
wrote his double, that was author than e’er with a red ink.

This fourth dimension it had equipment casualty or ruin the Giants any cerebrate
rightful ancestry delves into the coach outlet stores in texas stephen curry one Shoes red bottom shoes for sale online Kate Spade Outlet and for years with injuries and
contradictory intense danger. What major opportunity to run with many NFL players know,
which is . And nowadays’s NFL, the information processing system if it
wants to maintain his arm too and solely be ransomed ‘tween territory 26 Hawks rag
period Heart of Dixie State

Here is my homepage :: Michael Kors Outlet Online

Director Jonathan Demme has modestly stated he was hoping to recreate watch The 33 free online (Buford) entire motion picture in this scene.

To follow up on the update of this subject on your web page and would wish to let you know simply how much I
loved the time you took to publish this beneficial post.
In the post, you spoke of how to truly handle this thing with all comfort.
It would be my own pleasure to accumulate some more suggestions from your
site and come as much as offer others what I have learned from you.

Thank you for your usual wonderful effort.

Although internet sites we backlink to below are considerably not associated to ours, we really feel they may be essentially really worth a go by means of, so have a look.

Just beneath, are several totally not connected internet sites to ours, having said that, they’re certainly worth going over.

Then there m?y be the constructed-in GPS monitoring that p?rmits runners to
dash and document knowledg? without ever ca?rying a

Feel free to visit my weblog; brama ogrodzeniowa

I just added this to my favorites. I truly love reading your posts. Tyvm!

I am thankful that I detected this web blog, precisely the
right info that I was looking for!

Leave a Reply