Application Launch Cycle

When an application is launched, a new DOM page is created and the application's base document is loaded -- either index.html or the file named by the main property in appinfo.json. This document must request loading of mojo.js: 

<script src="/usr/palm/frameworks/mojo/mojo.js"
  type="text/javascript" x-mojo-version="1" >

Once loaded, mojo.js is executed, initializing the Prototype library and loading the requested framework version. The rest of the base document is processed, typically loading application stylesheets, before loading required application sources from sources.json.

The framework creates an application controller object and an application assistant if the application provides one. The application then calls the assistant's setup method, which sets up asynchronous operations such as database loading or Ajax requests.

Many application assistants have a handleLaunch method as an entry point for launch directly from the framework; the handleLaunch method is called after setup; you can consolidate all launch handling here.

A stage controller is created. If the application includes a defined Stage Assistant, it is instantiated and its setup method is called. If there is no Stage Assistant, or if the stage assistant does not push an initial scene, then the framework looks for a scene named main to push as the first scene.

The simplest single-card applications do not need either an application assistant or a stage assistant.

Scene Lifecycle

Once a scene is pushed, it sets in motion another cycle managed by the framework. Scenes are pushed onto other scenes, popped to reveal a previously pushed scene, bringing it back to the foreground, or sometimes a combination of pushes and pops simulate swapping scenes, or popping multiple scenes to get to a particular point in the scene stack. The framework manages the transition of one scene to another, and maintains the scene stack and related controllers.

Lifecycle Details

A scene is pushed by an assistant within the same application or as a result of external actions. These actions could be from another application using a service call or a cross-app scene push (see "Services" for a description of these features) or they could be as a result of a user action at the System UI level, such as moving an app from foreground to background, tapping the notification bar, or any of a number of other actions.

initialize

The scene lifecycle is initiated once a scene is pushed. The framework looks for a constructor function matching the pushed scene's name and if found, calls it, creating the scene and adding it to the DOM. Alternately, the framework will call the SceneAssistant's initialize method if using the Class.Create function. Any input arguments must be retained as properties to the scene assistant and any other initialization actions performed. The framework gets the scene assistant and attaches a controller to it, then finds the scene's view template and loads it into the DOM.

A naming convention allows the framework to correlate the scene name specified in the pushScene call with the SceneAssistant and the scene's view file. The convention is that if a scene named first is pushed, then the framework will look for a scene assistant in the loaded JavaScript code with the name FirstAssistant. The full algorithm will search for the assistant constructor using the scene name with dashes removed, each word converted to camel case, and the string 'Assistant' appended to the end. For example, if the scene were named my-first-scene then the scene assistant's constructor function would be named MyFirstSceneAssistant.

The scene's view file is also located by convention. The framework will look for a view file at this location: app/views/first/first-scene.html, where first is again the name of the pushed scene. Here the scene's name is used for the views directory, and as a prefix to the scene template file.



Once initialized, the framework sequentially calls different scene methods, alternating those calls with transition tasks. Setup follows initialize to handle widget setup and other scene preparations. Between setup and activate, there are two other methods for scene assistants, ready and aboutToActivate, which are designed to give applications some finer-grained access within the lifecyle.

Once activated, the scene is in view until a new scene is pushed. When that occurs, the new scene's constructor function is called, followed by a call to the current scene's deactivate method and the lifecycle starts with a new scene. If the scene is popped, perhaps the user swipes back or the application is closed, then the deactivate method call is followed immediately with a call to the cleanup method and the scene is removed from the DOM. There is very little time for deactivate and cleanup; the scene removal from the DOM is happening virtually at the same time, so only the most minimal processing can take place here. There is no time, for instance, to save databases; you need to save data as you go along.

Scene Assistant Methods - Summary

Method Description
initialize A call to the constructor function or the initialize method if using the Class.Create function. Any input arguments must be retained as properties to the scene object and any other initialization actions performed. The framework creates the scene assistant, attaches a controller to it and puts the scene's view template into the DOM.
setup Called before scene is visible, before any transitions take place, and before widgets are instantiated. Used to set up widgets, add event listeners or perform other tasks that are needed before the scene is rendered. Once this is complete, the framework completes the transition and the scene's activate method is called where it can follow the frameworks rendering tasks with any of it's own and begin whatever active operations it is designed for. The scene transition begins after this method returns.
ready After the scene assistant's setup method completes, the framework instantiates the widgets and creates the widget assistants. At this point, the scene assistant's ready method is called to give access to the widgets after they've been instantiated.
aboutToActivate Just before the scene is activated, the aboutToActivate method is called for any final preparation. When this method is called, there is less than 500 ms before the scene activates; the framework will not wait for the aboutToActivate work to complete, so you have to limit what's done in this method.
activate Called each time the scene becomes the top scene on the stack. When the scene is pushed, this is after scene is visible, and after the on-stage transition is complete. Otherwise, it's called when the "covering scene" is popped, and this one is once again the top of the stack. This is intended for setup work that should be repeated each time the scene becomes active. There may be arguments passed into the activate method, in the case of a cross-app scene push.
deactivate Called each time the scene is no longer the top scene on the stack (when it's popped, or when another scene is pushed on top). In the case where the scene is being popped, this is called before the off-stage transition begins.
cleanup Called when the scene is popped from the scene stack, after any transitions are complete, but before removing the scene from the DOM. Scene assistants may release any external resources associated with the scene, or provide default save/cancel behavior.

Pushing and Popping a Scene - An Example

Push - Adding the Scene

An app calls stageController.pushScene('myScene').

Scene is Active

This is the main portion of the scene's lifecycle, and all user interaction occurs here.

Pop - Removing the Scene

At some point, app calls stageController.popScene() to pop 'myScene'.