Permalink
Browse files

Updating docs per Bill's request

  • Loading branch information...
1 parent 60267a6 commit c3e64efd89774ed827d361ccaf158d51a91ee775 @SitePenDavidWalsh committed Jan 16, 2012
Showing with 54 additions and 79 deletions.
  1. +40 −59 dojox/app.rst
  2. +4 −6 dojox/app/bind.rst
  3. +1 −1 dojox/app/model.rst
  4. +6 −10 dojox/app/module/history.rst
  5. +2 −2 dojox/app/scene.rst
  6. +1 −1 dojox/app/view.rst
View
@@ -1,5 +1,6 @@
.. _dojox/app:
+=========
dojox.app
=========
@@ -16,99 +17,86 @@ and tablets will be configurable and buildable for easy and fast deployment.
There are two core modules that will need to work together to accomplish these goals:
----------
dojox/app
----------
+=========
A library that provides high-level application controllers, defined by metadata which describes the overall structure and navigation of the application and it's views.
----------
dojox/mvc
----------
+=========
A library that provides the ability to have view concerns separated from model or data concerns but have simple bindings or connections between them that can keep either side in sync, as well as respond to events or actions. The library also provides the ability to generate data-bound forms and views dynamically, built on key elements of mvc and app.
Overview
---------
+=========
The following diagram represents layout management. The difference between a scene and a view is that scenes may have multiple children views but a view does not have a child.
dojox.app Components
---------------------
+====================
``dojox.app`` is constructed of seven core modules; each very focused and compact.
-======================================
:ref:`dojox.app.view <dojox/app/view>`
-======================================
+--------------------------------------
``dojox.app.view`` provides a view like ``dojox.mobile.View``. It contains a template string which will be rendered with user defined template segments. A view should have no child view.
-======================================
:ref:`dojox.app.bind <dojox/app/bind>`
-======================================
+--------------------------------------
``dojox.app.bind`` is used to query ``dojox.mvc`` widgets and get/set binding data for each widgets with "ref" or data-dojo-props="ref: xxx" tag. ``dojoType``, ``data-dojo-type``, ``ref`` and ``data-dojo-props`` attributes are compatible in a view.
-========================================
:ref:`dojox.app.model <dojox/app/model>`
-========================================
+----------------------------------------
``dojox.app.model`` creates a ``StatefulModel`` data source with JSON data or dojo data store. The data model can be ``binded`` to a ``dojox.mvc`` widget using ``dojox.app.bind``.
-========================================
:ref:`dojox.app.scene <dojox/app/scene>`
-========================================
+----------------------------------------
``dojox.app.scene`` is used to create the layout for each child view, manage the transition between views, and resize the layout to fit the display area. A scene can contain one or more children views or scenes. The difference between scene and view is that scene can have multiple children scenes views but view cannot have children.
-====================
dojox.app.module.env
-====================
+--------------------
``dojox.app.module.env`` provides the dojo, dijit, and dojox environments.
-==========================================================
:ref:`dojox.app.module.history <dojox/app/module/history>`
-==========================================================
+----------------------------------------------------------
``dojox.app.module.history`` manages transitions forward and backward between views/scenes. A view can use 'transitionOptions' or 'href' to navigate forward or backward by utilizing HTML5 history API.
-======================================
:ref:`dojox.app.main <dojox/app/main>`
-======================================
+--------------------------------------
``dojox.app.main`` (Application) is used to create a ``dojox.app`` application by the configuration in ``config.json``. The main responsibilities of ``dojox.app.main`` include loading the application configuration, loading data from data source, creating views, creating data models, binding data models to views using ``dojox.app.bind``, creating scenes between views, and parsing the application with ``dojo.parser.parse``.
The Configuration Object
-------------------------
+========================
Configuration comes in the form of a basic object with several key, pre-defined properties:
-==
id
-==
+--
String. The ``dojox.app`` application's id.
-.. code-block :: javascript
+.. js ::
id: "sampleApp",
-====
name
-====
+----
String. The ``dojox.app`` application's name.
-.. code-block :: javascript
+.. js ::
name: "Sample App",
-===========
description
-===========
+-----------
String. The description of the ``dojox.app`` application
-.. code-block :: javascript
+.. js ::
description: "Sample application that does what is needed",
-============
dependencies
-============
+------------
Array. Dependencies of ``dojox.app`` application. It can be defined as global
dependencies for application or as view dependencies in a view.
Represented as array of string paths to dependencies.
-.. code-block :: javascript
+.. js ::
"dependencies": [
"dojox/mobile/TabBar",
@@ -119,30 +107,28 @@ Represented as array of string paths to dependencies.
"dojox/mobile/Heading"
],
-=======
modules
-=======
+-------
Array. Modules for the application. Used as the mixins in
``dojo.declare()`` for the application. They modify the top level behavior
of the application, how it processes the config, or any other life cycle
Represented as array of string paths to modules.
-.. code-block :: javascript
+.. js ::
"modules": [
"dojox/app/module/env",
"dojox/app/module/history"
],
-======
stores
-======
+------
Object. Dojo data stores which are used by ``dojox.app`` the data model. A data
store is composed by store name, store type and store parameters.
Represented as an object with sub-objects, with type and
params properties to be passed to store during initialization.
-.. code-block :: javascript
+.. js ::
"stores": {
"store1":{
@@ -159,23 +145,21 @@ params properties to be passed to store during initialization.
}
},
-========
template
-========
+--------
String. HTML file which will act as the application template.
-.. code-block :: javascript
+.. js ::
"template": "application.html",
-======
models
-======
+------
Object. Models and instantiation parameters for the models including 'type' as
a property allows one to override the class that will be used for the
model. By default it is ``dojox.mvc.model``.
-.. code-block :: javascript
+.. js ::
"models": {
"names": {
@@ -185,30 +169,27 @@ model. By default it is ``dojox.mvc.model``.
}
},
-===========
defaultView
-===========
+-----------
String. The name of the scene/view to load when the application is initialized.
-.. code-block :: javascript
+.. js ::
"defaultView": "home",
-=================
defaultTransition
-=================
+-----------------
String. The default animation type for the view transition.
-.. code-block :: javascript
+.. js ::
"defaultTransition": "slide",
-=====
views
-=====
+-----
Object. The children views/scenes of the application or current scene. Dependencies may be defined via views for optimization and organization purposes. View types, models, and transition properties may be defined, along with the template.
-.. code-block :: javascript
+.. js ::
"views": {
//simple view without any children views or scenes
@@ -271,11 +252,11 @@ This configuration serves two purposes: configuring the application within the
Sample dojox.app Usage
-----------------------
+======================
As with any Dojo-based web application, it's important to create your HTML page with a ``SCRIPT`` tag referencing ``dojo.js`` and a ``SCRIPT`` tag referencing the application configuration file:
-.. code-block :: html
+.. html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
@@ -297,7 +278,7 @@ As with any Dojo-based web application, it's important to create your HTML page
The next step is registering the modules path for the custom application namespace which will be called "app". After the module is registered, the base dependencies are loaded via ``require()`` including the ``dojox/app`` base as well as application configuration:
-.. code-block :: javascript
+.. js ::
//Get current path
var path = window.location.pathname;
@@ -320,7 +301,7 @@ Upon loading the ``dojox.app`` configuration file, views, scenes, and models are
The complete configuration for the sample app could look like:
-.. code-block :: javascript
+.. js ::
{
"id": "sampleApp",
@@ -453,7 +434,7 @@ An application may have as many scenes and views as required. The end product w
Comparison with dojox.mobile.app
---------------------------------
+================================
The main difference between ``dojox.app`` and ``dojox.mobile.app`` is listed as following.
* ``dojox.app`` enables the model binding
View
@@ -9,28 +9,26 @@ dojox.app.bind
``dojox.app.bind`` provides a function to query ``dojox.mvc` widgets, and get and set binding data for each widgets with "ref" or data-dojo-props="ref: xxx" tag. ``dojoType``, ``data-dojo-type``, ``ref`` and ``data-dojo-props`` are compatible in a view.
Binding API
------------
+===========
The method signature of the bind function ``dojox.app.bind`` is:
.. js ::
function(/*Array of widgets*/ widgets, /*Object*/ models)
Parameters Detail
------------------
+=================
--------
widgets
-------
An array of dojo widgets where bind function will search for bindable ``dojox.mvc`` widgets
-------
models
------
An object which contains pairs of model name and its associated ``dojo.Stateful`` model object
Sample Binding
---------------
+==============
Sample raw data could look like:
.. js ::
@@ -104,7 +102,7 @@ The result would look like:
Sample Summary
---------------
+==============
In this sample, “stores” use “modelApp.names” data to create a dojo.store.Memory store named “namesStore”. While “models” use “namesStore” to create a ``dojox.mvc.StatefulModel` model. Then simple.html template bind the model to infoGroup with ref="'names.0'", and each ``dojox.mobile.TextBox`` widget bind a data with “ref” property.
After the application startup, you can see the data was bound to the view (in the red rectangle) and there's no data operation in user's code to complete this function.
View
@@ -11,7 +11,7 @@ dojox.app.model
Models can be declared in the application configuration at application level or different view levels. The model declared at application level can be accessed by all scenes and views in this application. The model declared at view level can be accessed by this view or its children views.
Sample Model
-------------
+============
dojox.app.model creates statefulModel data objects using JSON data or dojo data store. The data model can be bound to a dojox.mvc widget by dojox.app.bind.
Models can be declared in the application configuration at application level or different view levels. The model declared at application level can be accessed by all scenes and views in this application. The model declared at view level can be accessed by this view or its children views.
@@ -9,7 +9,7 @@ dojox.app.module.history
``dojox.app.module.history`` manages transition forward and backward between views/scenes. A view can use ``transitionOptions`` or ``href`` to navigate forward or backward by utilizing HTML5 history API.
Usage
------
+=====
``trasitionOptions`` can be used on any ``dojox.mobile`` widgets which inherit from ``dojox.mobile._ItemBase``. The following sample will result in transition to the 'second' view in 'main' scene of the application.
@@ -20,33 +20,31 @@ Usage
</li>
Transition Attributes
----------------------
+=====================
-------
target
------
String. The target view or scene id path. Note the value for the target|String
should be the complete id path from its ancestor scene to the
leaf view.
----
url
---
String. The url that will be used to update the location value in
browser's address bar after the transition.
Forward Transition Using ``href``
----------------------------------
+=================================
Besides the ``transitionOptions`` on mobile widgets, the ``href`` attribute in a hyperlink can also start the transition in ``dojox.app``. The following HTML snippet results in a transition to the 'main' view of 'main' scene.
.. html ::
<a href="#main,main">to main,main</a>
-Backward transition
--------------------
+Backward Transition
+===================
To start the backward transition, all we need to do is to add a back button on the Heading widgets of ``dojox.mobile``. The back attribute declares the back button label on the heading in the following sample.
.. html ::
@@ -55,10 +53,9 @@ To start the backward transition, all we need to do is to add a back button on t
Sample App Navigation
----------------------
+=====================
A sample excerpt of view template with regarding to navigation and history would look like:
----------
main.html
---------
@@ -78,7 +75,6 @@ main.html
</li>
</ul>
------------
second.html
-----------
View
@@ -9,11 +9,11 @@ dojox.app.scene
``dojox.app.scene`` is used to create the layout for each child view, manage the transition between views, resize layout to fit the display area. A scene can contains one or more children views or scenes. The difference between scene and view is that scene can have multiple children scenes views but view does not have child.
Usage
------
+=====
If there is no child scene in the application, it is not necessary to declare the view as type ``dojox.app.scene`` because ``dojox.app.main`` inherits ``dojox.app.scene`` and the application itself is a scene. For the application contains child scene, the child scene needs to be declared as ``dojox.app.scene`` in the application like the ``tabscene`` in the following sample.
Sample Configuration
---------------------
+====================
A sample application, including scene configuration, could look like:
.. js ::
Oops, something went wrong.

0 comments on commit c3e64ef

Please sign in to comment.