Correcting views_multiple_devices example.

docs/dev_guide/code_exs/views_multiple_devices.rst

@@ -9,19 +9,21 @@ Creating Views for Different Devices
 **Difficulty Level:** Intermediate
 
 Summary
-#######
+=======
 
-This example shows how to create specialized views for different wireless devices, such as iPhones, BlackBerries, and Android phones. Each device uses different view templates but the 
+This example shows how to create specialized views for different wireless devices, such as iPhones, 
+BlackBerries, and Android phones. Each device uses different templates but the 
 same data from the controller.
 
 The following topics will be covered:
 
+- configuring application to recognize device-associated templates
 - creating specialized views for wireless devices
 - using query parameters to select the device view
 - using the user agent to select the device view
 
 Implementation Notes
-####################
+====================
 
 The following screenshots show you how the application appears on different devices.
 
@@ -37,18 +39,86 @@ The following screenshots show you how the application appears on different devi
    :height: 368px
    :width: 401px
 
-For each device's customized view, you need to create a view template. This code example uses the view templates ``index.iphone.hb.html``, ``index.android.hb.html``, and ``index.blackberry.hb.html`` 
-to create customized views for iPhones, Android phones, and BlackBerries. The ``hb`` in the view template file names represents the Handlebars rendering engine that renders Handlebars exressions.
-
-Mojito uses two ways to determine what device is making an HTTP request for a page. The first way is to use the value assign to the query string parameter ``device``. For example, 
-if Mojito received an HTTP GET request on the URL below, it would render the iPhone view into HTML and serve the page to the device.
+Configuring Application to Use Device-Specific Templates
+--------------------------------------------------------
+
+Context Configurations
+######################
+
+Mojito allows you to map contexts to a set of configurations based on runtime factors.
+The context is defined by the ``setting`` property in the JSON configuration files.
+The default value for ``setting`` is ``master``. Mojito will first look to see if a base context was
+set on the command line with the ``--context`` option, then at the HTTP headers and
+query string. In this example, we want contexts defined for different devices,
+so, in the ``application.json`` file, we'll define contexts 
+for Android, Blackberry, and iPhone with the following:
+
+.. code-block:: javascript
+
+   [
+     {
+       "settings": [ "master" ],
+       ...
+     },
+     { 
+       "settings": [ "device:android" ],
+       ...
+     },
+     { 
+       "settings": [ "device:blackberry" ], 
+       ...
+     },
+     { 
+       "settings": [ "device:iphone" ],
+       ...  
+     }
+   ]
+   
+You can also have contexts for environment, language, and region configurations, or create
+custom contexts. See `Using Context Configurations <../topics/mojito_using_contexts.html>`_.
+
+selector Property
+#################
+
+How does Mojito know which template file to use for a device? Mojito identifies files resources
+using the ``selector`` property in configuration files. In the ``application.json`` file,
+we can use the contexts for our devices with the ``selector`` property so Mojito knows what
+file resources to use for the context associated with devices.
+
+.. code-block:: javascript
+
+   { 
+     "settings": [ "device:android" ], 
+     "selector": "android" 
+   },
+   { 
+     "settings": [ "device:blackberry" ], 
+     "selector": "blackberry" 
+   },
+   { 
+     "settings": [ "device:iphone" ], 
+     "selector": "iphone" 
+   }
+
+For example, when given the context ``device:iphone``, Mojito will look for file resources that have 
+for identifier ``iphone``. For more information about the ``selector`` property, 
+see `Resource Store: selector Property <../topics/mojito_resource_store.html#selector-property>`_.
+
+Determining Context
+###################
+
+Mojito uses two ways to determine what device is making an HTTP request for a page. The first way 
+is to use the value assign to the query string parameter ``device``. For example, if Mojito received 
+an HTTP GET request on the URL below, it would render the iPhone view into HTML and serve the page 
+to the device.
 
 ::
 
    http://localhost:8666?device=iphone
 
-Mojito also uses the HTTP User-Agent header field to decide which view to render and serve. In this example HTTP header, the User-Agent field indicates that the HTTP request is coming from an Android device, 
-so Mojito would use the Android view template and serve the rendered HTML to the device.
+Mojito also uses the HTTP User-Agent header field to decide which view to render and serve. In this 
+example HTTP header, the User-Agent field indicates that the HTTP request is coming from an Android 
+device, so Mojito would use the Android template and serve the rendered HTML to the device.
 
 ::
 
@@ -60,18 +130,39 @@ so Mojito would use the Android view template and serve the rendered HTML to the
    Accept: application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
    Accept-Charset: utf-8, iso-8859-1, utf-16, *;q=0.7
 
-How does Mojito know which view template file to use? Mojito determines which view template file to use based on a file naming convention. The naming convention has three parts based on the action and 
-the device as shown here:
 
-``{action}.{device}.{rendering_engine}.html``
+Creating Templates for Devices
+------------------------------
+
+For each device's customized view, you need to create a template. 
+This code example uses the templates to create customized views for iPhones, Android phones, and 
+BlackBerries. 
+
+Naming Convention for Templates
+###############################
+
+The naming convention for template files have the following syntax, where ``{selector}``
+is the string identifier (defined by the ``selector`` property) of a device, such as "iphone":
+
+``{action}.{selector}.{rendering_engine}.html``
+
+Templates for This Example
+##########################
+
+This code example uses the following template files, where ``hb`` represents
+the Handlebars rendering engine:
+
+- ``index.iphone.hb.html``
+- ``index.android.hb.html``
+- ``index.blackberry.hb.html`` 
 
-Thus, if an iPhone was making an HTTP GET request on the index (action) file and the view template was being rendered by the Handlebars rendering engine, Mojito would use ``index.iphone.hb.html`` 
-and serve the rendered view as HTML to the iPhone.
+Thus, if an iPhone was making an HTTP GET request on the ``index`` (action) file and the template 
+was being rendered by the Handlebars rendering engine, Mojito would use ``index.iphone.hb.html`` 
+and serve the rendered view to the iPhone.
 
-The view templates used in this code example use the controller to get the data for the Handlebars expression ``{{mojit_view_id}}``, but each view template uses customized CSS.
 
 Setting Up this Example
-#######################
+=======================
 
 To set up and run ``device_views``:
 
@@ -92,15 +183,28 @@ To set up and run ``device_views``:
       [
         {
           "settings": [ "master" ],
+          "appPort": 8666,
           "specs": {
-            "device" : {
-              "type": "device"
+            "device": {
+              "type" : "device"
             }
           }
+        },
+        { 
+          "settings": [ "device:android" ], 
+          "selector": "android" 
+        },
+        { 
+          "settings": [ "device:blackberry" ], 
+          "selector": "blackberry" 
+        },
+        { 
+          "settings": [ "device:iphone" ], 
+          "selector": "iphone" 
         }
       ]
 
-#. To configure routing, create the file ``routes.json`` with the following:
+#. To configure routing, replace the contents of the file ``routes.json`` with the following:
 
    .. code-block:: javascript
 
@@ -137,7 +241,7 @@ To set up and run ``device_views``:
         };
       }, '0.0.1', {requires: []});
 
-#. To modify the default view template, replace the code in ``views/index.hb.html`` with the following:
+#. To modify the default template, replace the code in ``views/index.hb.html`` with the following:
 
    .. code-block:: html