www.webOShelp.net

Article Index
First official webOS / Mojo SDK Tutorial from Palm Redux!
Scenes and Assistants
All Pages

Welcome to the second attempt at writing up Palm's first official webOS / Mojo SDK tutorial.  This incarnation is much shorter than the previous and is split into two parts; one for the application that was built during the webcast and the other for the more advanced stuff that was discussed briefly at the end of the presentation.  The second part will be posted tomorrow. Update: Will be posted Monday.

A great high-level overview of the material covered during the webcast by Mitch Allen was written up by Andrew last week. This article will get into the technical details of the code tutorial section. If you're new to web development, you may want to start with our beginner or intermediate tutorials before diving in.

Topics covered in this tutorial:

• appinfo.json - what makes this file so important
• index.html - what goes into this file
• stage assistants - a very simple example that demonstrates pushing the first scene of an application
• scenes - palm-specific css styles, UI widgets
• scene assistants - moving between scenes, passing data between scenes

If you're just here to grab the sample application code, you can find it here.   To view the actual webcast in which this material was presented, click here.

The first thing covered was the folder structure of a webOS app. Here is the complete structure for this tutorial application:

• [myapp]
  • [app]
    • [assistants]
      • first-assistant.js
      • second-assistant.js
      • stage-assistant.js
    • [models]
    • [views]
      • [first]
        • first-scene.html
      • [second]
        • second-scene.html
• [images]
• [stylesheets]
• appinfo.json
• icon.png
• index.html

[]=folder

Following file naming conventions is important because webOS uses scene names (in this case "first" and "second") to coordinate scenes with their assistants.

webOS applications follow a model-view-controller (MVC) architecture. Assistants are Javascript-based controller-like objects that help manage your application. Views are represented by scenes, which are HTML files. It's unclear at this point what type of files would go in the model folder, but it was evident from the tutorial that having model files is not a requirement to get your application to run, though certain applications would almost certainly benefit from them.

The most important file here is appinfo.json. This file contains some important configuration info and is required for webOS applications:

{
   "title": "MyApp",   
   "type": "web",   
   "main": "index.html"   
   "icon": "icon.png",  
   "id": "com.yourdomain.app.myapp",   
   "version": "1.0",   
   "vendorid": "com.yourdomain.app.myapp",   
   "removable": true   
}

The elements covered in the tutorial were:

• title: The title of your application, which will be displayed at the top of your application's card.
• icon: The file that will represent your application in the webOS launcher.
• id: Your application's id, which is used by webOS to properly communicate with your application. It must be unique among all applications. The reverse dns notation seen above was recommended to help quickly find a unique name for your app.

That was actually all that was covered during the tutorial. However, we can guess what a few of the other elements are:

• main: The main file of your application; probably the first one that gets loaded after appinfo.json.
• version: The current version of your application. Most likely will be used to automatically determine if an update for your application is available.

There are also a couple that inspire some speculation:

• removable: An indication as to whether this application is uninstallable? Probably not, as I would expect it be a requirement that all applications be removable. More likely it's a reference to whether the application can be installed on removable media vs. on the device's internal memory. This was a feature of older Palm devices, and although the Pre does not support removable memory, future webOS devices almost certainly will.
• type: A reference to other application types that may be available in the future? e.g. "native"? We can only hope.

The next file we went through was index.html. Code that was automatically generated by the SDK appears in black, and code that was added during the course of the tutorial appears in red:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" https://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd>
<html xmlns=https://www.w3.org/1999/xhtml xml:lang="en">
   <head>
      <title>MyApp</title>
      <script src="/usr/palm/frameworks/mojo/mojo.js" type="text/javascript" x-mojo-version="1"></script>
      <script src="/app/assistants/stage-assistant.js" type="text/javascript"></script>
      <script src="/app/assistants/first-assistant.js" type="text/javascript"></script>
      <script src="/app/assistants/second-assistant.js" type="text/javascript"></script>

      <!--application stylesheet should come in after the one loaded by the framework -->
      <link href="/stylesheets/main.css" media="screen" rel="stylesheet" type="text/css"        />
   </head>
   <body>
   </body>
</html>

There are several items of note here. The first is that you must include the mojo framework explicitly in every application. You must also include the stage assistant and assistants for your scenes. Mitch mentioned alternatives to managing your files this way, but didn't go into details during the tutorial.

The first file referenced after the mojo framework was stage-assistant.js:

function StageAssistant () {
}
StageAssistant.prototype.setup = function() {
   Mojo.Controller.stageController.pushScene ("first");
}

By default it contains the two functions above, which are both empty. We added the pushScene command to the setup function which is run when the application is launched.

The pushScene command displays the first scene of the application represented by first-scene.html:

<div class="palm-header">
<div class="palm-header-center">
   App 1 - Scene 1
</div>
<div class="palm-header-spacer"></div>
   This is our first scene together!
<div x-mojo-element="TextField" id=’myText’></div>
<button class="palm-button" id="myButton">Next Scene</button> 

There are a few things to note here:

• There are several built-in css styles (that seem to all begin with "palm-") that can be used with any application and overidden on any individual element or universally throughout your application.
• To use a Mojo UI widget in your application, you simply specify the appropriate x-mojo-element attribute in a div. You must also include a unique id so that you can reference the widget from Javascript.

When run, this scene displays the following output:

The div with the palm-header class appears as the black bar at the top.  The palm-header-spacer app adds a bit of space between the black bar and the text "This is our first scene together!"  The rest is self-explanatory.

The second scene was defined in second-scene.html:

<div class="palm-page-header" align="center">
   App 1 – Scene 2
</div>
This is our second scene a bit like the first.
Color is <span id="color"></span>

We'll see how this scene looks a bit later.

Once again, the span is given an id so that it can be referenced from Javascript.

To understand how the scenes communicate with each other, we need to look at the scenes' assistants. Here's first-assistant.js:

function FirstAssistant() {
   /* this is the creator function for your scene assistant object. 
   It will be passed all the additional parameters (after the scene 
   name) that were passed to pushScene.  The reference to the scene 
   controller (this.controller) has not been established yet, so any 
   initialization that needs the scene controller should be done in 
   the setup function below. */
}

FirstAssisstant.prototype.setup = function() {
   /* this function is for setup tasks that have to happen when the scene is first created */
   /* use Mojo.View.render to render view templates and add them to the scene, if needed. */
   /* setup widgets here */
   /* add event handlers to listen to events from widgets */
   
   this.textAttr = {
      hintText: "Enter Color",
      focus:true
   };
   this.textModel= {
      value: ""
   };
   this.controller.setupWidget("myText",this.textAttr,this.textModel);
   
   Mojo.Event.listen($("myButton"), "click", this.nextScene.bindAsEventListener(this));
}

FirstAsssistant.prototype.activate = function(event) {
   /* put in event handlers here that should only be in effect when 
   this scene is active.  For example, key handlers that are observing
   the document */
}

FirstAssistant.prototype.deactivate = function(event){
   /* remove any event handlers you added in activate and do any other
   cleanup that should happen before this scene is popped or another
   scene pushed on top */
}

FirstAssistant.prototype.cleanup = function(event) {
   /* this function should do any cleanup needed before the scene is
   destroyed as a result of being popped off the scene stack */
}

FirstAssistant.prototype.nextScene=function(event){
   Mojo.Controller.stageController.pushScene("second", this.textModel.value);
}

In the setup function we set up the TextField widget by passing it a couple of JSON objects. The first is the textAttr object that specifies a couple of TextField properties; the hintText appears in the field before the user has entered anything, and having focus=true ensures the user can start typing without having to first select the field on the screen. The textModel object specifies that the TextField can contain a value, which is initially set to blank.

The Mojo.Event.listen function listens for a click" action on the myButton object, and, when detected, calls the nextScene function.

The nextScene function calls Mojo.Controller.stageController.pushScene and specifies the scene to push (second) and passes the value the user entered in the TextField (this.textModel.value). The second scene is then pushed onto the scene stack.

Let's take a look at how the second scene handles this value. Here's second-assistant.js:

function SecondAssistant(text) {
   /* this is the creator function for your scene assistant object. 
   It will be passed all the additional parameters (after the scene 
   name) that were passed to pushScene.  The reference to the scene 
   controller (this.controller) has not been established yet, so any 
   initialization that needs the scene controller should be done in 
   the setup function below. */
   this.textString=text;
}

SecondAssisstant.prototype.setup = function() {
   /* this function is for setup tasks that have to happen when the scene is first created */
   /* use Mojo.View.render to render view templates and add them to the scene, if needed. */
   /* setup widgets here */
   /* add event handlers to listen to events from widgets */
}

SecondAsssistant.prototype.activate = function(event) {
   /* put in event handlers here that should only be in effect when 
   this scene is active.  For example, key handlers that are observing
   the document */
}

SecondAssistant.prototype.deactivate = function(event){
   /* remove any event handlers you added in activate and do any other
   cleanup that should happen before this scene is popped or another
   scene pushed on top */
   $("color").innerHTML=this.textString; 
}

SecondAssistant.prototype.cleanup = function(event) {
   /* this function should do any cleanup needed before the scene is
   destroyed as a result of being popped off the scene stack */
}

The assistant for the second scene receives the argument from the first scene in its creator function, invoked when the scene is pushed onto the stack. The text argument is defined as a function parameter in the first line (function SecondAssistant (text)) and is later assigned to an internal variable (this.textString=text).

The text is then used in the activate function which is called after the constructor function, and assigned to the innerHTML property of the element with id=color.

The net output of this program, then, is:

 

And that just about did it for the actual tutorial.  You should now have enough webOS know-how to build your own clone of Crysis using your favorite text editor and the Mojo toolkit.

After this, the webcast branched into a quick overview of local storage, notifications and services, which will be covered in a separate article.  If you want to grab the code from this tutorial to play around with or use as the basis for your own webOS application, you can find it here.

Questions? Comments? Glaring mistakes? Leave a comment!