forked from dmachi/dojox_application
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.txt
executable file
·270 lines (205 loc) · 13.3 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
-------------------------------------------------------------------------------
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 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 region="top" data-dojo-type="dojox/mobile/Heading">Tab View</div>
<ul 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 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.