diff --git a/docs/dev_guide/code_exs/views_multiple_devices.rst b/docs/dev_guide/code_exs/views_multiple_devices.rst index 60afb2554..76c4dd813 100644 --- a/docs/dev_guide/code_exs/views_multiple_devices.rst +++ b/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