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').

  • A DIV is created with the view HTML for the new scene, and inserted into the DOM.

  • A SceneController for myScene is instantiated.

  • A scene assistant for myScene is instantiated, if available.

  • The new scene is placed on the stage's scene stack.

  • SceneController and assistant's setup() methods are called.

  • The scene transition begins.

  • Widgets (divs that specify x-mojo-element) are instantiated and added to the DOM.

  • The assistant's ready() method is called.

  • The widgets are rendered; the scene transition completes.

  • The assistant's aboutToActivate() method is called.

    At this point, the scene should now be ready for initial display, even if the app is waiting for a service request to complete to provide dynamic data to fill out the scene.

  • The StageController transitions the scene onto the stage.

  • When the transition is complete, the scene controller and assistant's activate() method is called, and the scene is ready for action.

Scene is Active

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

  • User interacts with scene.

  • Another scene may get pushed on top of the current one.

    • The current scene's deactivate() method is called.
    • The new scene's setup() and activate() methods are called.
    • More scenes may be pushed onto and popped off of the scene stack, but these do not affect the scene we're following.

  • Eventually, the scene "covering" our scene is popped, and our scene becomes active again.

    • The covering scene's cleanup() method is called, and it is removed from the document and scene stack.
    • Our scene's activate() method is called, since it is once again the top scene on the stack.

Pop - Removing the Scene

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

  • The scene controller and assistant's deactivate() methods are called.

  • The StageController transitions the scene off the stage.

  • The SceneController and assistant's cleanup() methods are called.

    • The SceneController removes the scene's div from the document body.

  • The StageController removes the scene from the scene stack.