dojox.app: A single-Page Application Framework

By on September 30, 2011 2:00 am

dojox.app is a small application framework providing a set of classes to manage the lifecycle and behavior of a single page application hosted on mobile or desktop platforms. The main class, Application, is responsible for managing the lifecycle of the application and is designed to be easily modified with additional custom behaviors. An Application instance contains Scene objects and View objects which provide the visible user interface. The available views, scenes, module dependencies, and other information about the application are all passed into the Application class using a JSON configuration file (by convention).

config.json

The main configuration file defines all of the dependencies, application behaviors, top level views and scenes, and any other information required for the application to function.

Example config

{
	/* global application dependencies */
	"dependencies": [
		"dojox/mobile/Heading",
		"dojo/mobile/RoundRect",
		"my/custom/module"
	],

	/* Application Modules.  These are implicitly added
	  to the above set of dependencies */
	"modules": [
		"dojox/app/module/history",
		"my/custom/appModule"
	],

	/* The html template for the application itself */
	"template": "example.html",

	/* the view to start on by default */
	"defaultView": "home",

	/* transition to use if none has been provided */
	"defaultTransition": "slide",

	/* Views and Scenes */
	"views": {

		/* home is a top level dojox.app.view */
		"home": {

			/* class to instantiate this view as */
			"type": "dojox.app.view",

			/* dependencies specific to this view */
			"dependencies": [
				"dojox/mobile/ListItem",
				"dojox/mobile/EdgeToEdgeCategory"
			],

			/* template to use for this view */
			"template": "views/home.html"
		},
	
		/* tabscene is a dojox.app.scene,
		  and it contains three child views */
		"tabscene": { 
			/* class to instantiate, a scene in this case */
			"type": "dojox.app.scene",

			/* the scene's template */
			"template": "tabScene.html",

			/* the default view within this scene */	
			"defaultView": "tab1",

			/* when transitioning between tabs,
			  use a flip animation by default */
			"defaultTransition": "flip",

			/* the views available to this scene */
			"views": { 
				"tab1":{
					"template": "views/tabs/tab1.html" 
				},
				"tab2":{
					"template": "views/tabs/tab2.html" 
				},
				"tab3":{
					"template": "views/tabs/tab3.html" 
				}
			},

			/* dependencies specific to this scene */
			"dependencies": [
				"dojox/mobile/RoundRectList",
				"dojox/mobile/ListItem",
				"dojox/mobile/EdgeToEdgeCategory"
			]
		}
	}
}

Configuration property descriptions

  • dependencies – When defined at the root of the configuration, this property defines the modules that are required for the whole application. When defined under a scene or a view, this property defines which modules must be loaded before that view/scene can be instantiated.
  • modules – This property defines application modules that will be mixed into the Application class to control the lifecycle and behavior of the application. In other words, the Application class that is instantiated for a given site is dynamically created at runtime using the base Application class plus this list of modules.
  • template – When defined at the root of the configuration, this property defines the template that is used for the application’s layout. Within the context of a view or a scene, this property defines the template used to define the view or scene.
  • defaultView – This property defines the initial view that is loaded by the application.
  • defaultTransition – When defined at the root of the configuration, this property defines the default visual transition method used for top level views/scenes. When defined under a scene, it is the default transition method for the associated scene only.
  • views – The views property is a nested set of objects defining the views and scenes available to an application or scene. These will be discussed in greater detail later.

Some additional properties, such as models, stores, id, name, and description are reserved for future use; their exact definitions and usages are still under development.

The Application class

The Application class itself is actually an abstract class and is never used directly. It is a very simple extension of the Scene class (described below). dojox.app provides a generator function, which, when passed a configuration object, will build and automatically start the actual Application instance for the site. Its usage looks like this:

require(["dojo/json", "dojox/app", "dojo/text!./config.json"],
function(json, makeApplication, config){
	makeApplication(json.parse(config));
});

The Scene class

The Scene class provides a templated container for views. Its purpose is to allow the layout of a scene to be provided using an HTML template and to define a set of child views that the scene can transition between. For example, to display a set of tabs, you would use a Scene configured with a child View for each tab. The scene’s template would define where to display the tab controls and the view.

Internally, Scene steals some concepts from dijit.layout and dijit._Templated. The default template for the base Scene class is pretty simple and not really much of a template—it simply outputs whatever content is in the current view. Elements within a scene’s template can use the region attribute to define where that element and its children should be displayed, similar to a dijit.layout.BorderContainer. For example, to implement a tab scene, the template might look like this (using components from dojox.mobile):

<div style="background:#c5ccd3;" class="view mblView"> 
	<div region="top" dojoType="dojox.mobile.Heading">
		Tab Scene
	</div>
	<ul region="top" dojoType="dojox.mobile.TabBar"
		barType="segmentedControl">
		<li dojoType="dojox.mobile.TabBarButton"
			icon1="images/tab-icon-16.png"
			icon2="images/tab-icon-16h.png"
			transitionOptions='{title:"TabScene-Tab1",
				target:"tabscene,tab1",
				url: "#tabscene,tab1"}' selected="true">Tab 1</li>
		<li dojoType="dojox.mobile.TabBarButton"
			icon1="images/tab-icon-15.png"
			icon2="images/tab-icon-15h.png"
			transitionOptions='{title:"TabScene-Tab2",
				target:"tabscene,tab2",
				url: "#tabscene,tab2"}'>Tab 2</li>
		<li dojoType="dojox.mobile.TabBarButton"
			icon1="images/tab-icon-10.png"
			icon2="images/tab-icon-10h.png"
			transitionOptions='{title:"TabScene-Tab3",
				target:"tabscene,tab3",
				url: "#tabscene,tab3"}'>Tab 3</li>
	</ul>
</div>

This above template defines two areas with region="top": a header and list of tab buttons. They will both be placed at the top of this scene when rendered.

Normally, when using a BorderContainer, one would also have a region="center" section. In the case of a Scene, however, the “center” region will be applied automatically to the currently active view (the current tab, for example).

In addition to the code that supports the appropriate lifecycle of the scene and its rendering, Scene provides a transition method which controls the transition of content from one child view to another. Scenes can contain both views and other scenes.

The View class

Views, like scenes, are also containers of content. However, instead of containing additional views as children, they contain only the content defined by their template. Unlike a Scene, a View cannot contain any other scenes or views.

Summary

All three of these classes are intended to be as simple and feature-free as possible, providing only the basic structure and lifecycle described above (though additional core methods & lifecycle hooks will be added in time). A developer using the dojox.app framework can define additional custom view or scene types by extending the base classes (or implementing equivalent functionality) and defining them in the application’s configuration file.

TODO

dojox.app is an experimental framework with several key pieces still under development. This final release is expected to occur prior to Dojo 2.0. The following items are currently under development:

  • Model/Store support – We have a couple of preliminary implementations of model/store support, including one for dojox.mvc. However, additional work is required to complete an agreed-upon API for these components. While MVC systems will be given first class support, they will not be required—an application developer will be able to “control” the HTML of a view just as well by extending the View class instead.
  • Desktop/Mobile Branching – dojox.app is designed to be platform-agnostic. Using CSS media selectors and property definitions within the configuration file, there will be support for choosing which set of views and parameters to use based on the user’s browser.
  • Intelligent build support – For performance, especially on the mobile side, an appropriate build of the application is required. Rather than add a separate build profile for the app, a wrapper utility will be created to intelligently generate builds directly from the configuration file.