The Basics: Stages

This document contains the following sections:

For those of you who may need some background info about HP webOS and its application structure, we recommend that you read the following documents before going forward:

And of course the O'Reilly® book Palm webOS, by Mitch Allen, is an excellent resource too! Take a peek at the first chapter, which introduces you to the webOS operating system and the HP webOS Software Developer Kit (SDK), which the SDK documentation commonly refers to as Mojo or the framework.

Overview

This document is geared toward the beginning webOS developer. Here we discuss the basic concept of stages--what they are, where they are on the screen, what you can do with them, and how to create them.

Let's expand on some of the definitions found in the "Recommended Reading" documents:

Stages--Stages are one of the building blocks for webOS applications. A stage is the window, container, or card that holds the application scene. An application can have multiple scenes that reuse the same stage, or perhaps there is a different stage for each scene.

Scenes--It is the scene that the user sees and interacts with to perform a single task or a group of related tasks. Each scene has a scene assistant file and a main HTML view file, and may have optional template HTML view files.

Cards--Most application stages display their scene content in a card. You can zoom in and out among the following views:

Assistants--An assistant is a set of JavaScript functions that uses controllers provided by Mojo to customize behavior. An application can have three possible types of assistants:

Controllers--Each type of assistant has its own controller. An application controller is required; it creates the stages and optional application assistant. Each stage must have a stage controller; it creates the scenes for the stage. Each stage controller has access to the stack of scene controllers for the stage; it manages the scene's objects and elements.

Note: The terms stage, window, and card are basically interchangeable for the purpose of this document. You can find these and other terms from this document defined in the Glossary.

Stages

This section describes the stage properties you need to know about, available stage types, and explains the hierarchy when there are multiple stages. All applications require at least one visible window (stage) at all times, either a card or dashboard.

Stage Properties

There are two properties whose settings affect stages: noWindow and lightweight. The following table lists the locations and values for these properties.

Property Location Required Value Description
noWindow appinfo.json No false
(default)
Do not create a stage that runs in the background.
true Create a stage that runs in the background.
Applications with an application assistant and multiple stages need this setting to initially launch as a background application, and then create their own stages.
lightweight stageArguments Yes true This flag is passed to createStageWithCallback(). You must manually set the property to true in your source code for all applications.

Types of Stages

Mojo provides the following four types of stages with which to build an application:

When declaring the stage type in the application code, use all lowercase spelling and write the stage name as one word with quotation marks. The available stage types are as follows:

Mojo.Controller.StageType = {
  popupAlert: "popupalert",
  bannerAlert: "banneralert",
  dashboard: "dashboard",
  card: "card"
}; 

The following table summarizes the applicable stages for each type of application. The application types are single-stage, multistage, and dashboard. Later in this document, you can find descriptions and examples of these three application types.

Available Stages for Applications

Card stage Dashboard stage Banner alert stage Pop-up alert stage
Single-stage (card) application Yesa
(noWindow:false)
No No No
Multistage (card) application Yesa
(noWindow:true)
Yes Yes Yes
Dashboard (dashboard summary) application Yesb
(noWindow:true)
Yesa Yes No
  1. Required for this application type.
  2. Recommended for this application type.

Stage Hierarchy

Going back to the Overview discussion, an application can have one or more stages, and each stage can have one or more scenes. Each stage and scene have their own controller and assistant. That's a lot of elements to keep track of.

The following figure shows an example of an application's stage hierarchy. Notice that all stages are at the same hierarchical level, and that each stage controller has access to only its stack of scene controllers. The scenes are after (below) the stages in the hierarchy, and are grouped together per stage. You will learn more about the scene stacks, controllers, and assistants in another document.

For info about moving (transitioning) among scenes within the hierarchy, see User Interface Summary.

Stage Hierarchy
Example of Application Stage Hierarchy

Stage Proxy

You need to use a proxy at times because creating a stage is actually creating a window and loading its assets in an asynchronous operation. This operation can take up to a second to complete, so it is very likely that you will have cases where the controller is not available when you want to retrieve it for a subsequent operation.

Use getStageProxy() when trying to access the stage close to where it is created. Both getStageController() and getStageProxy return undefined if the stage does not exist, or if the stage controller was created but is not available at the time of the call. However, the return from getStageProxy is not always the stageController; it can be just the proxy. You cannot reliably use the returned object except with delegateToSceneAssistant() that takes a scene method name as the first argument with all other arguments passed in the method call.

For more info, see the delegateToSceneAssistant API. There is an example using the dashboard stages in Dashboards and Notifications.

Single-Stage Applications

Most simple applications have only one stage, which means you can see only one scene at a time from that application. An application that can have more than one scene open at the same time is a multistage application.

The webOS emulator has several applications that are built on one stage, such as the Calculator, Memos, and Tasks applications. Open the emulator and try out these applications. Move from scene to scene, and then zoom out to the Card view. If you see only one card associated with the application, it has only one stage. For example, after launching the Memos application (stage 1/scene 1 in the figure), you either click the NEW MEMO icon or select Memos > Add A Memo to open a new memo page. If you zoom out to the Card view, you can see that the previous scene is not shown in a card to the left of the current card (stage 1/scene 2). This means that there is one stage for both scenes.

Views of Memos application
Example of Single-Stage Application (Emulator)

Guidelines

Consider the following recommendations for creating a stage:

The following are recommended for multistage applications and optional for single-stage applications:

Creating a Stage

All stages are created with a call to createStageWithCallback(), an application controller method, and a callback function. As with other assistants, use the constructor function for initialization.

For any pre-launch setup, use the setup method. However, any launch handling is usually done in handleLaunch. The following code example uses a handleLaunch method. It either puts the primary card stage into focus, or if there is not a stage already, it creates one and pushes the first scene.

stageProxy is retrieved by using getStageProxy(); see the previous section. If it returns undefined, it does not exist and so a stage is created through a call to the appController method createStageWithCallback(), with a callback that pushes the first scene.

To use an existing stage, call getStageController(). A return value of undefined means the stage does not exist or is not available, which means a new stage is created.

The last argument, the stage type, is optional in this example because it defaults to card; the "Types of Stages" section above lists the other types.

Example:

var MainStageName = "main";

function AppAssistant (appController) {
}

AppAssistant.prototype.handleLaunch = function (launchParams) {
  // Look for an existing main stage by name.
  var stageProxy = this.controller.getStageProxy(MainStageName);
  var stageController = this.controller.getStageController(MainStageName);
  if (stageProxy) {
      // If the stage exists, just bring it to the front by focusing its window.
      // Or, if it is just the proxy, then it is being focused, so exit.
      if (stageController) {
          stageController.window.focus();
      }
  } else {
      // Create a callback function to set up the new main stage
      // after it is done loading. It is passed the new stage controller
      // as the first parameter.
      var pushMainScene = function(stageController) {
          stageController.pushScene("main");
      };
      var stageArguments = {name: "MainStageName", lightweight: true};
      // Specify the stage type with the last property.
      this.controller.createStageWithCallback(stageArguments, pushMainScene, "card");
  }
}; 

Multistage Applications

Multistage applications allow you to have more than one stage showing at the same time. These applications can include any combination of the four types of stages, with a least one being a card stage.

The Email application is an example of a multistage application. With this application, you can open the Inbox (stage 1) and have it remain open while composing an email message (stage 2), as shown in the following figure.

View of Email stages
Example of Multistage Application (Emulator)

Guidelines

All guidelines listed for single-stage applications are required for multistage applications.

Creating a Secondary (Child) Stage

You create secondary stages through the same framework functions as with the main stage. If you do not specify a stage assistant in stageArguments, the stage is created without one. The secondary stage name should be different unless you plan to reuse the stage for each card. If reusing the stage, use popScenesTo() with the pushScene() and activate() methods. Use getStageProxy() if it is possible for cardStage to be in the process of being brought up when calling this function.

Example:

NotificationAssistant.prototype.handleCardButton = function(){
  var appController = Mojo.Controller.getAppController();
  var cardStage = appController.getStageController("NewCardStage");

  if(cardStage) {
      cardStage.popScenesTo();
      cardStage.pushScene("list");
      cardStage.activate();
  } else {
      var pushCard = function(stageController){
          stageController.pushScene("secondary");
      };
      // Specify the stage type with the last property.
      appController.createStageWithCallback(
          {name: "NewCardStage", lightweight: true},
          pushCard, "card"
      );
  }
};

Dashboard Applications

Dashboard stages appear in the dashboard summary area, expanding to the Dashboard view size as shown below. Because of the limited space, dashboard applications are typically not task-oriented. Examples are a weather application that monitors the weather for a specified location and a traffic alert application that provides notifications of specified traffic events.

Although not required, dashboard applications typically include a card-based preferences scene for application configuration purposes. Therefore, most dashboard applications are considered to be multistage applications.

To learn more about dashboard stages and applications, see Background Applications and Dashboards and Notifications.

Other related topics include:

The next document in this series is about Scenes.