Palm’s user experience architecture provides for a greater degree of application scope than is normally considered in a web application. To support this and specific functions of the framework, Palm has introduced a structure for webOS applications built around stages and scenes.

A stage is similar to a conventional HTML window or browser tab. Applications can have one or more stages, but typically the primary stage will correspond to the application’s card. Other stages might include a dashboard, a pop-up notification, or secondary cards for handling specific activities within the application. Refer to email as an example of a multistage application, where the main card holds the account lists and inbox, and displays the email contents, but new email messages are composed in a separate card to allow for switching between compose and other email activities. Each card is a separate stage but still part of a single application.

Scenes are mutually exclusive views of the application within a stage. Most applications will provide a number of different kinds of scenes within the same stage, but some very simple applications (such as the Calculator) will have just a single scene. An application must have at least one scene, supported by a controller, a JavaScript object referred to as a scene assistant, and a scene view, which is a segment of HTML representing the layout of the scene.

Most applications will have multiple scenes. You will need to specifically activate (or push) the current scene into the view and pop a scene when it’s no longer needed. Typically, a new scene is pushed after a user action, such as a tap on a UI widget and an old scene is popped when the user gestures back.

As the terms imply, scenes are managed like a stack with new scenes pushed onto and off of the stack with the last scene on the stack visible in the view. Mojo manages the scene stack, but you will need to direct the action through provided functions and respond to UI events that trigger scene transitions. Mojo has a number of stage controller functions specifically designed to assist you, and are described in Chapter 2, Application Basics, and Chapter 3, Widgets.

Palm webOS applications are required to use directory and file structure conventions to enable the framework to run the applications without complex configuration files. At the top level the application must have an appinfo.json object, providing the framework with the essential information needed to install and load the application. In addition, all applications will have an index.html file, an icon.png for the application’s Launcher icon, and an app folder, which provides a directory structure for assistants and views.

By convention, all of an application’s images, other JavaScript, and application-specific CSS should be contained in folders named images, javascripts, and stylesheets, respectively. This is not required, but makes it simpler to understand the application’s structure.

Launching a webOS application starts with loading the index.html file and any referenced stylesheets and JavaScript files, as would be done with any web application or web page. However, the framework intervenes after the loading operations and invokes the application, stage, and scene assistants to perform the application’s setup functions and to activate the first scene. From this point, the application is driven either by user actions or dynamic data.

Significantly, this organizational model makes it possible for you to build an application that will manage multiple activities that will be in different states (active, monitoring, and background) at the same time.

Applications can range from the simple to the complex:

Palm webOS supports the standard DOM Level 2 event model. For DOM events, you can use conventional techniques to set up listeners for any of the supported events and assign event handlers in your JavaScript code.

There are a number of custom events for UI widgets. These are covered in more detail in Chapter 3. For these events, you will need to use custom event functions provided within the framework. Mojo events work within the DOM event model, but include support for listening to and generating custom Mojo event types and are stricter with parameters.

The webOS Services work a bit differently, with registered callbacks instead of DOM-style events, and are covered starting in Chapter 8. The event-driven model isn’t conventional to web development, but has been part of modern OS application design and derives from that.

Mojo supports the HTML 5 database APIs directly and provides high-level functions to support simple create, read, update, or delete (CRUD) operations on local databases. Through these Cookie and Depot functions, you can use local storage for application preferences or cache data for faster access on application launch or for use when the device is disconnected.

You must declare widgets within your HTML as an empty div with an x-mojo-element attribute. For example, the following declares a Toggle Button widget:

  <div x-mojo-element="ToggleButton" id="my-toggle"></div>

The x-mojo-element attribute specifies the widget class used to fill out the div when the HTML is added to the page. The id attribute must be unique and is required to reference the widget from your JavaScript.

Typically, you would declare the widget within a scene’s view file, then direct Mojo to instantiate the widget during the corresponding scene assistant setup method using the scene controller’s setupWidget() method:

  //  Setup toggle widget and an observer for when it is changed.
  //  this.toggle        attributes for the toggle widget, specifying the 'value'
  //                     property to be set to the toggle's boolean value
  //  this.togglemodel   model for toggle; includes 'value' property, and sets
  //                    'disabled' to false meaning the toggle is selectable
  //
  //  togglePressed      Event handler for any changes to 'value' property

  this.controller.setupWidget('my-toggle',
    this.toggle = { modelProperty : 'value' },
    this.toggleModel = { value : true, disabled : false });

  this.controller.listen('my-toggle', Mojo.Event.propertyChange,
    this.togglePressed.bindAsEventListener(this));

This code directs the scene controller to set up my-toggle, which passes a set of attributes called this.toggle and a data model called this.toggleModel to use when instantiating the widget and to register the togglePressed function for the widget’s propertyChange event. The widget will be instantiated whenever this scene is pushed onto the scene stack.

To override the default style for this widget, select #my-toggle in your CSS and apply the desired styling (or use .sliding-toggle-container to override the styling for all toggle buttons in your application). For example, the following will override the default positioning of the toggle button to the right of its label so that it appears to the left of the label:

#my-toggle    {  float:left;
              }

There’s a lot more to come, so you shouldn’t expect to be able to use this to start working with any of these widgets yet. Chapters 3, 4, and 5 describe each of the widgets and styles in complete detail.