Stages

In Chapter 1, you were introduced to stages:

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, inbox and displays the email contents, but new emails 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.

We haven’t worked much with stages so far, but they are an essential part of the features discussed in this chapter. Each secondary card, dashboard summary, or pop-up notification is a separate window, and each window corresponds to a stage, with a stage controller that manages that window. Recall that each stage controller has a stack of scene controllers, with the topmost scene activated and in view within the stage’s window.

Before we build each feature into the News application, we’ll start with some general information about using stages.

Creating New Stages

All stages are created the same way, with a call to createStageWithCallback(), an application controller method, and a callback function, which at a minimum will push the first scene using the newly created stage controller:

var stageArguments = {name: "main", lightweight: true};
var pushMainScene = function(stageController) {
    stageController.pushScene("main");
};
this.controller.createStageWithCallback(stageArguments, pushMainScene, "card");

You can refer to the API documentation for the specifics of this call, but you should always do the following:

  • Name the stage; the name identifies the stage and you will use the name later to determine whether the stage exists.

  • Set the lightweight property to true (early on, Mojo included heavyweight and lightweight stages, but only lightweight stages are supported now).

  • Specify the callback function.

The last argument, the stage type, defaults to card, so it is optional for this example. The complete set of stage types are:

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

You can specify a stage assistant in stageArguments; otherwise, the stage will be created without a stage assistant.

Using Existing Stages

Often, you will want to create a stage only when it doesn’t already exist. If the stage exists, you will likely want to put focus on the stage or update its contents. Use getStageController() to get the stage controller; a return value of undefined means that the stage doesn’t exist, so you must create one. Otherwise, use the returned value as the stage controller to focus or update the existing stage:

// Look for an existing main stage by name.
var stageController = this.controller.getStageController("main");

if (stageController)    {
     stageController.window.focus();
} else {
     var pushMainScene = function(stageController) {
         stageController.pushScene("main");
     };
    var stageArguments = {name: "main", lightweight: true};
    Mojo.Controller.AppController.createStageWithCallback(stageArguments,
      pushMainScene, "card");
}

The getStageController() method will also return undefined when the stage controller has been created but is not available at the time of the call. Use getStageProxy() whenever you may be trying to access the stage close to where it is being created. The getStageProxy() method will still return undefined if the stage does not exist or hasn’t been created at the time of the call. However, you can’t use the returned object as a stage controller; the returned object simplify verifies the existence of the stage controller and can only be used with the delegateToSceneAssistant() method, which you’ll learn about later in this chapter.

Note

It can take as long as one second to create a stage in some instances. If your get request for the stage controller could occur within a second of the create request, you should use getStageProxy().

Working with Stages

The News application uses a single card stage, which is created automatically when the user launches the application. For most of the advanced features, we will be creating and accessing stages directly and turning News into a multistage application. When working with multistage applications you should follow these guidelines:

  • JavaScript must be loaded through sources.json. JavaScript cannot be loaded through script tags (other than the required script tag for mojo.js), so multistage applications will fail unless the source files are specified in sources.json.

  • Specify noWindow:true in appinfo.json; applications with an app-assistant and multiple stages need to indicate that they will initially launch as a no window or background app, creating their own stages, or windows, explicitly.

  • There is no support for Prototype’s $() function; get elements with methods from the scene or widget controller.

    Note

    Be careful about nested functions. With single stage applications, you could use the global $() function in a nested function, but now you must use:

    var controller = this.controller

    to put the appropriate scene controller in a local variable so it is visible to the nested function.

  • The Mojo.Controller.stageController global is not supported; replace it with the stage controller property of the scene or widget controller.

  • Do not use the window global; instead, use the window property of the stage, scene, or widget controller. You can still use the window global in the application assistant.

  • Do not use the document global; instead, use the document property from the stage, scene, or widget controller, or the ownerDocument property of an element if all you have is an element reference.

  • Don’t use document.viewport; instead, use:

    Mojo.View.getViewportDimensions(targetDocument);

You can follow these practices even when working with single-stage applications, though the convenience of using the framework to manage stage creation and the convenience of the prototype $() function are worth considering.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.116.14.111