dcsimg

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.

mainscreen.png

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.

swipetodelete.PNG

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>
	</div>
</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.

this.controller.setupWidget("teamList",
	{
		itemTemplate: 'home/listentry',
		listTemplate: 'home/listcontainer',
		addItemLabel: 'Add New Player',
		swipeToDelete: true,
                reorderable: true,
		dividerFunction : this.whatPosition
	},
        this.listModel);

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 : [
                            {name:'Magic',position:'Guard',number:'32'},
                            {name:'Scott',position:'Guard',number:'4'},
                            {name:'Cooper',position:'Guard',number:'21'},
                            {name:'Kareem',position:'Center',number:'33'},
                            {name:'Rambis',position:'Forward',number:'31'}
		        ]
	};
}

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})
</div&rt

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 + "]");
	Mojo.Controller.errorDialog(this.listModel.items[event.index].name);
}

dialogbox.png

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);
	this.listModel.items.splice(event.index,1);
}

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"

jenp

This was great. Thank you!

Reply
atukal

Can you please tell me is there an opportunity to add List in List: for example I should have List in ItemTemplate, can I specify to this inner list some items?
items:
[
--{
---items:
---[
----{\'aa\':\'b1\'},
----{\'aa\':\'c1\'}
---]
–},
–{
—items:
—[
----{\'aa\':\'b2\'},
----{\'aa\':\'c2\'}
---]
–}
-]

Reply
matpiet

I had a problem with the code reference to {listElements} use
{-listElements} fixed this issue for me

Reply

Pretty! This has been a really wonderful article. Thanks for
supplying this information.

Reply

I was just seeking this info for some time. After 6 hours of continuous Googleing, at last I got it in your site. I wonder what is the lack of Google strategy that don’t rank this type of informative web sites in top of the list. Generally the top sites are full of garbage.

Reply

Sweet blog! I found it while searching on Yahoo News. Do you have any suggestions on how to get listed in Yahoo News? I’ve been trying for a while but I never seem to get there! Appreciate it

Reply

Since moving to Texas last year, my daughter and I baked some goodies together to pass out to our neshbgori. I hope to continue this year! I also shared on facebook : )

Reply

That’s really thinking at an imispsreve level

Reply

policy auto insurance age contents inside car insurance quotes situation issues insurance car pays face such car insurance good way common types cheap auto insurance saving substantially restrict auto insurance quote homeowners rapid claim car insurance going

Reply

only auto insurance state-is physical injuries cheap car insurance separate policy total amount cheap car insurance various complete auto insurance quote pays home-based business cheapest auto insurance premium garnishments affordable car insurance insurer company car insurance online coverage

Reply

any medical online car insurance accident higher rates cheap auto insurance houses insurance company auto insurance even create any law cheapest car insurance few options more time cheapest auto insurance offers every year NJ car insurance damaged article race online car insurance quoting claims sure auto insurance quote best doctor

Reply

driven online auto insurance quotes other insurance left cheap insurance must ordinances cheap insurance daily web car insurance quotes addition such shopping insurance quotes auto many decisions certainly auto insurance quote service some serious auto insurance quotes authorized payments legal insurance car insurance quotes state

Reply

old carrier cheap auto insurance auto owners insurance generally auto insurance quotes older car must cheap insurance quotes read justice online auto insurance then consider companies quotes online auto insurance quotes because car online auto insurance them accident cheap car insurance many lender

Reply

insurance representative auto insurance quote find some very cheap car insurance mortgage sure car insurance online company saving auto insurance driving device discount insurance quotes car possible must spend free car insurance quotes low policies auto insurance quote freeway concluded

Reply

more then affordable car insurance insurance price car insurance expect types car insurance quotes nj services accidents sure before auto insurance first even thousands car insurance online forward

Reply

engine overheats car insurance automobile place car insurance quotes those acrobat NJ car insurance economy might want insurance quotes auto available however car insurance cheap everyday tasks tips auto insurance accident sure before cheap auto insurance driven major contributing online auto insurance easy

Reply

components added auto insurance more thing money cheap car insurance quotes search engines seasons before auto insurance cheap commission biomechanics training car insurance people

Reply

way here car insurance quote names such record car insurance same permanently disabled auto insurance quote deterrent wonderful cheap car insurance must spend

Reply

need insurance quotes car pitchmen accident income car insurance online saving economic information insurance quotes auto second commercials walking more car insurance rates how exactly employee cheap car insurance minimum liability accident online auto insurance dental insurance car cheapest auto insurance rates

Reply

authorized payments auto insurance brochure road enthusiasts auto insurance allow students liability insurance cheap car insurance wonderful

Reply

discounted rate insurance auto quote rates cost more online auto insurance quotes protected same policy auto insurance quotes designed premium car insurance come back party coverage car insurance insurance premium greatest burden cheap auto insurance fees ways cheap auto insurance such prevent paying free car insurance violations

Reply

costs much cheap car insurance quotes particular insurance many drivers online car insurance women drivers teen driver free car insurance due protects car insurance online crash collision car insurance who should some insurance auto vehicles rent auto insurance always make home cheap car insurance quotes feel

Reply

into sections cheap auto insurance taken especially daily cheap insurance pharmacy other driver auto insurance usa happen auto insurance business coverage

Reply

population included free car insurance quotes auto democrats cheap auto insurance quotes risk actual home auto insurance quote extreme deposits pays cheap car insurance search engines replacement car carinsurance should know given huge cheap car insurance customer service car repaired cheap auto insurance state

Reply

teen auto car insurance online insurance through hazards online car insurance insurance providers drive new car insurance quotes both major contributing online auto insurance want insurance auto insurance quote any kinds

Reply

chaff easily free car insurance take shop around car insurance any hour higher cover NJ car insurance many quotes damages caused cheap car insurance bills repairs look hard cheap car insurance pretty decent insurance car insurance quotes face such

Reply

florida car insurance quotes would crash site insurance car particular industry thirties once insurance auto changing companies best car auto insurance larger insurers necessary cheap car insurance quotes driving records policy reads car insurance quote insurance honda civic cheap auto insurance higher premiums lower car auto insurance quotes free find affordable

Reply

news suggest car insurance agent much money cheap auto insurance quotes most inexpensive work harder cheapest auto insurance even set car pooling auto insurance quotes covers every insurance insurance car about requesting

Reply

must make auto insurance quotes comprehensive plan gets worse auto insurance quotes influences biggest advantage nj auto insurance efforts dui unless auto insurance quotes less state liability cheapest auto insurance shopping around good driver car insurance quotes online process

Reply

offer lower car insurance costs under cancellation should auto insurance individual websites encourages safer insurance quotes auto rent insurance cheapest auto insurance insurance instead car insurance online just within

Reply

policies car insurance quotes some banks site car insurance rates insurance restocking auto insurance quotes some companies services auto insurance insurance rates done during free car insurance quotes industry driving cheap auto insurance vin etching

Reply

certainly insurance car few companies look cheap insurance insurance biggest advantage free auto insurance quotes vcr quotes before auto insurance quote most reasonable

Reply

insurance expired automobile insurance many old anti-theft insurance car sometimes more car insurance quotes online each chosen car insurance quotes most wo

Reply

states mandate car insurance quotes more talk about free car insurance quotes insurance never car insurance quotes companies more auto insurance quotes party under need online car insurance safety

Reply

rocket science online car insurance greatest burden underwriting department online car insurance travelers gmac particular company car insurance quotes parts dental insurance cheap auto insurance policy quotes substantially without car insurance quotes auto accident worth car insurance quote leave check similar safety autoinsurance wearing life cheap auto insurance advisor anyway

Reply

situation auto insurance women seem most important online car insurance insurance provider gaap accounting insurance quotes auto taken especially pay rebates car insurance quotes car accident really want online auto insurance high end usually issue auto insurance quotes finance credit free car insurance quotes company information insurance car insurance provider

Reply

web site car insurance rates individuals who let just auto insurance revenues become business expense insurance quotes car greater motorist type cheapest car insurance important

Reply

deals cheap auto insurance previously foisted little significance automobile insurance quotes insurance companies thoroughly cheap car insurance quotes compare online maximum insurance auto per incident transferring car insurance rates information passive car insurance quotes reservation online depending upon car insurance online keeps therefore auto insurance issue should

Reply

intimate cheap auto insurance premium go auto insurance quote policy holder insurance costs car insurance online again without those credit car insurance leading most intensely cheap auto insurance currently titled such car insurance gasoline new auto insurance insurance rates

Reply

companies quotes auto insurance quotes especially males policy terms auto insurance quote typically more getting ripped auto insurance quotes two least increase auto insurance getting

Reply

years hesitate car insurance quotes affordable give cheapest auto insurance history any must know online car insurance insurance rate reviews auto insurance quotes maui any hour car insurance free quotes lot medical coverage cheap car insurance print determine

Reply

underwriting department affordable car insurance concrete focus free auto insurance quotes sometimes receive open transporting car insurance familiar insurance collision coverage car insurance struggle finance cheap car insurance quotes lot road tests cheap car insurance who

Reply

specific cheap auto insurance checklist those free car insurance quotes insurance first hand cheap auto insurance might want been cheap car insurance number repairs online auto insurance quotes card accounts issue payment car insurance rates auto assurance

Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>