• Palm

• Log in
  

  ---

• • Home | Forums | Blog
  • • Search

• webOSdev Overview
• Palm App Distribution Program
• The webOSdev Magazine
• webOSdev Community
• Palm webOS: The Book

• Download SDK
• Install and Get Started
• Hello World
• Application Checklist
• Best Practices

• webOS Tools
• Developer Guide
• API Reference
• User Interface Guidelines
• Submit Your webOS Apps
• FAQ and Resources

• IRC
• Forums
• Blog

webOS Application Basics

A webOS application is composed of one or more distinct scenes, rendered on a stage. The stage roughly corresponds to an application's card, and each scene provides the content for the card. Think of the stage as a window or tab in a browser, and each scene as a different web page, and you'll get the idea. Each scene has underlying Javascript code that provides the behavior of the scene.

Within a scene, the application presents Widgets, or controls, to the user. When the user interacts with a widget (or performs a gesture), an event is generated. By listening for events, your application can respond to user input. If you have developed user interface code in Javascript, widgets and events will already be familiar to you.

In fact, the scene and its elements conform to the W3C DOM (Document Object Model), an interface that provides access to all elements on a web page so that the content can by dynamically updated or manipulated.

The Palm Mojo Framework includes a Services API that provides access to system and hardware capabilities. Using services, your application can send and receive messages from a remote server, communicate with other applications on the device, set alarms and calendar events, play media files, and so on.

Your application can store and retrieve data using the HTML5 database interface, or using the Cookie and Depot objects provided by the framework.

The following sections provide additional detail about the application structure.

A Tour of the Application Directory

The HTML, Javascript, CSS and image files that make up the application are stored in a specific directory structure that the framework relies on when it runs the application. This tour shows the files and directories that might exist in a simple application.

Contains the assistants, models, and views that make up the webOS application. The framework associates assistants and views by finding similar filenames  — first-assistant.js and first-scene.html, for example.
An assistant is a set of Javascript functions that uses controllers provided by the SDK to customize the behavior of a stage, scene or application.

Contains any data models used by the application. Not all applications use data models, and it is not unusual for the models directory to be empty or missing.
A directory for each scene, containing the scene's main HTML view file and any templates used by the scene to display dynamic data.

If the application uses images other than standard UI and the icon that appears in the launcher, put them here.

Contains any application-specific CSS used to override the default look and feel of the application.

A file that contains any style customization for the application.

An XML file that contains information for building the application.

The appinfo.json object contains information needed to load and launch your application. The most important property is the id, which is unique for each application and corresponds to the name of the application directory.
The icon that the application displays in the Launcher. The dimensions are 64 pixels by 64 pixels.

The HTML layout file for the stage. This provides the overall layout for the application. As scenes are pushed onto the stage, their HTML (from the views directory) is incorporated into index.html.
A file that tells the framework which assistant and view to use for each scene (as well as the stage assistant and the application assistant, if they are present).

Stages and Scenes

The simplest applications have a single stage (a single card) and a few scenes. The Calendar application is a good example. The main scene (the main view) shows the current day, week, or month. Actions by the user cause different scenes to be pushed onto the stage by the application. For example, selecting Prefs & Accounts pushes the Preferences and Accounts scene. Subsequently choosing Add an Account pushes the Choose Account Type scene. The result is a stack of scenes on the stage --- called, appropriately enough, the scene stack. Each scene pops itself off the stack when its task is completed.

Assistants and Controllers

Each scene has an assistant, Javascript code that provides the scene's behavior and capabilities. The stage also has an assistant, and the application can have an assistant as well. The assistants differ somewhat in their roles:

• application assistant — sets up non-standard stages. The application assistant is usually only present in applications that have multiple stages, or background applications that have no stages at all.
• stage assistant — sets up any application-wide objects, and pushes the first scene.
• scene assistant — provides the scene's behavior, including handling events, displaying data, pushing the next scene, and popping itself off the stack when necessary.

Each assistant has an instance of its own type of controller:

• application controller — creates the application assistant, and provides functions for creating and managing stages. Every application has an application controller, regardless of whether it has an application assistant.
• stage controller — provides functions for creating and managing scenes. Every application has a stage controller for each stage, for access by the corresponding stage assistant.
• scene controller  — provides functions for managing objects and elements within a scene. Each scene has a scene controller. The stage controller has access to the stack of scene controllers.

Events

The Mojo framework defines event types that support the hardware, gestures, application launch, widgets, and so on. Applications can define their own event types (for special widgets, for example) and broadcast them. Events propagate to any code that is subscribed as a listener.

For more information about events, see Events.

Application Launch Cycle

A webOS application is launched by the user from the Launcher, or by another application. Most webOS applications present a single card, and are intended to run mainly in the foreground — that is, they are there to use the screen for interaction with the user. The user can put a foreground application in the background by minimizing the card, and can bring a card back to the foreground by maximizing the card to fill the screen. Some applications are designed to run only in the background, and do not present a card at all. These background applications interact with the user mainly by displaying alerts and notifications.

Here is a simple launch cycle example, a foreground application with two scenes:

• The application is launched.
  • The application assistant (if present) becomes active.
    • The stage assistant becomes active and pushes the first scene.
      • The first scene is active, receiving events and updating its display.
      • The first scene assistant pushes the second scene (in response to an event).
        • The second scene is active, receiving events and updating its display.
        • The second scene is popped (in response to an event).
      • The first scene is active again.
    • The first scene is popped (in response to an event).
• The application is closed (in response to an event).

For more information about the launch cycle, see Launch Cycle.

Additional Information