-------------------------------------------------------------------------------
DojoX app 
-------------------------------------------------------------------------------
Version 0.1
Release date: 05/08/2011
-------------------------------------------------------------------------------
Project state: EXPERIMENTAL / Under Construction

This project is under active development with increasing capabilities beginning
in dojo 1.7, but is not yet capable or stable enough to use in production.

This project is licensed under the Dojo Tookit licensing scheme and contributions
provided under the Dojo CLA.
-------------------------------------------------------------------------------
Project authors
	Dustin Machi
	Stephen Zhang
	Eric Wang
	Ed Chatelain
	Christophe Jolif
-------------------------------------------------------------------------------
Project description

dojox/app is a small application framework providing a set of classes to manage the the lifecycle and behavior of a single page application delivered to a mobile or desktop platform.
The main class, Application, is responsible for providing the lifecycle of the application and is designed to be easily modified with additional custom behaviors.
An application instance contains views which provide the visible user interface.
The available views, module dependencies, and other information about the application are all passed into the Application class through a JSON configuration file.
-------------------------------------------------------------------------------
Dependencies:

Dojo Core (dijit, dojox/mobile).
-------------------------------------------------------------------------------
Documentation

config.json 

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

Example Config:
```javascript
{
	/* any object that complies with Dojo AMD loader configuration. */
	"loaderConfig" : {
		"paths": {
			"mypackage" : "can/be/found/here"
		}
	},

	/* 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"
	],

	/* Application Controllers. */
	"controllers": [
		"dojox/app/controllers/History",
		"my/custom/appController"
	],

	/* The Application level HTML template. template files store in application's templates folder by default */
	template: "./templates/example.html",
	
	/* Application level view definition. Application will have a root view even if it has no template.
	  "none" -- no definition for this view,
	  "./views/myView.js" -- load definition from "./views/myView.js",
	  no definition (by default) -- load definition from "./views/example.js" */
	"definition": "none",

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

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

	/* Views */
	"views": {

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

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

			/* template to use for this view */
			template: "./templates/home.html",

			/* view definition. "none" -- no definition for this view,
			  "./views/myHome.js" -- load definition from "./views/myHome.js",
			  no definition (by default) -- load definition from "./views/home.js" */
			"definition": "none"
		},
	
		/* tabs view contains three child views */
		"tabs": { 
			/* the tabs view template */
			"template": "./templates/tabScene.html",

			"definition": "none",

			/* the default view within tabs view */	
			"defaultView": "tab1",

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

			//the views available to tabs view
			"views": { 
				"tab1":{
					"template": "./templates/tabs/tab1.html"
					/* no definition define for tab1 view, load tab1 view definition from "views/tabs/tab1.js" */
				},
				"tab2":{
					"template": "./templates/tabs/tab2.html" 
				},
				"tab3":{
					"template": "./templates/tabs/tab3.html" 
				}
			},

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

	}
}
```

Property descriptions

	- loaderConfig -  This is the configuration that will be passed to the Dojo AMD loader. This allows to specify for example where the loader needs to find modules.
	 See: http://livedocs.dojotoolkit.org/loader/amd#module-identifiers

	- dependencies -  These are the modules that are required for the application to run when defined at the root of the configuration.
	 When defined inside of a view, the dependency property defines modules which must be loaded before that view can be instantiated.

	- modules -  The modules property defines application modules that will mixed into the Application class to control the lifecycle and behavior of the application. This property will become the array of mixins provided to a dojo/declare extending the base Application class. In other words, the Application class that is instantiated dynamically is created at run time using the base class and this list of modules.

	- controllers -  The controllers property defines application controllers that will be loaded during application startup to respond to events of the application. The controllers bind events on application's root domNode and the events can be triggered by application's trigger() method and documented actions.

	- template -  This is the template/HTML that is used for the application when defined at the root of the configuration.
	 Within the context of a view, it is the template/HTML for defining the view.

	- definition -  This is the view definition that is used for the application template view when defined at the root of the configuration. It implements the view's life cycle interface like init(), beforeActivate(), destroy(), etc. and allows one to control the view.

	- defaultView -  The defaultView defines the startup view for the application.

	- defaultTransition -  This is the default transition method for top level views when defined at the root of the configuration.
	 When defined within a view, it is the default transition method for the associated views only.

	- views -  The views property is a nested set of objects defining the views available to the application. Details of views classes is discussed below.

	- stores -  The dojo/store implementations that will be used by the application

	- models -  The models (potentially dojox/mvc models) connecting to the stores and exposing data to the application.

	- id - The identifier of the application, a global variable with the id name is created by the application.

Some additional properties, such as name and description are reserved for future use, but their exact use is still under development.

The Application module:

The Application class itself doesn't currently exist as an exported class.
This module exports a generation function, which when provided a configuration file will declare & instantiate the application class that will actually be used on a page. Finally it then starts it up at a specific node:

```javascript
	require(["dojox/json/ref", "dojox/app/main", "dojo/text!app/config.json"],function(json, Application, config){
		app = Application(json.parse(config));
	});
```

The View module:

The View module provides a View class to construct View instances, a template rendering engine to render view template and view lifecycle APIs. Each View can have one parent view and several children views. It provides a templated container to host the domNodes for the children views. Its purpose is to allow the layout of the view to be provided through an html template and to have a set of children views which the view transitions between. For example, to display a set of tabs, you would use a View with a child view for each tab. The view's template would define where within the view the children views are displayed and where any tab buttons and such are displayed.
In this case the  "template", for the base View is pretty simple. It is a simple HTML content. However, nodes within the template can be tagged with data-app-region="top" (bottom, left, right) to define where that node and its children should be displayed.
For example:

```html
<div  style="background:#c5ccd3;" class="view mblView"> 
	<div data-app-region="top" data-dojo-type="dojox/mobile/Heading">Tab View</div>
	<ul data-app-region="top" data-dojo-type="dojox/mobile/TabBar" barType="segmentedControl">
		<li data-dojo-type="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 data-dojo-type="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 data-dojo-type="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 template for the tabs view defines two areas with region top, a header and the tab buttons. The will be placed at the top of this main view when rendered.

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

The application can also provide view definition modules to implement the View lifecyle APIs (like init(), destory(),...) for each view. The Transition controller controls the transition from one child view to another. This includes propagating transition events on to children if the active child is itself another view.

The Controller module:

The Controller module provides a base Class to control the application by binding events on application's root domNode. Several controllers required by the framework are implemented in dojox/app/controllers package:
	
   * Load controller: load view templates and view definitions
   * Transition controller: respond to "startTransition" event and do transition between views
   * Layout controller: perform views layout
   * History controller: maintain application's history. This is based on HTML5 history APIs and will not work on platforms that do not support it like IE, Android 3 & 4, iOS4, etc.
   * HistoryHash controller: maintain application's history. This is based on URL hash and has limitation if refresh the browser and back to an URL which out of current application's history stack.
	
A developer using the dojox/app framwork can define additional custom controller by extending the base class (dojox/app/Controller) and specifying them in the application configuration file. The events binding to application's root domNode is done by default.
A developer can use Controller's bind() method to bind event to document, window or dojo/Evented object if needed.
	
```javascript
define(["dojo/_base/lang", "dojo/_base/declare"], function(lang, declare){

	return declare("myApp.myController", Controller, {

		constructor: function(app, events){
			// summary:
			//		bind "myEvent1" and "myEvent2" events on application's root domNode.
			//		bind "resize" event on window
			// app:
			//		dojox.app application instance.
			// events:
			//		{event : handler}
			this.events = {
				"myEvent1": this.myEvent1,
				"myEvent2": this.myEvent2
			};
			this.inherited(arguments);

			// bind "resize" event on window
			this.bind(window, "resize", this.onResize);
		},
		
		myEvent1: function(){
			// add your code here
		},
		
		myEvent2: function(){
			// add your code here
		},
		
		onResize: function(){
			// add your code here
		}
	});
});
```

TODO:

dojox/app is still an experimental framework with several key pieces still under design and development before a final release. This final release is expected to occur prior to the Dojo 2.0 release. The following items are piece that are under development and testing and we see as requirements prior to the final release:

- Model/Store support. We have a couple of preliminary implementations of model/store support, including one for dojox/mvc.
However, additional work and testing are required to come to a simple and agreed up on API for these components.  While MVC systems such as dojox/mvc should be supported with first class capabilities, they should not be required. An application developer can 'control' the html of any one view by simply extending the view class and using javascript if they so desired.

- Desktop/Mobile Branching -  Dojox/app is not to be specific to any one particular web platform.
Using css media selectors and definitions within the config, there will be support for choosing which set of views and parameters to use based on the users browser.

- Intelligent build support -  For performance, especially on the mobile side, an appropriate build of the application is required.
Rather than adding a build profile for the app, there will be a wrapper utility that runs the build from the config.json. This will allow us to intelligently build the base layers and dynamically loaded layers which should be defined by dependencies and default views as well as other information.