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.
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:
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.
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.
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()
.
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.
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.
3.135.194.130