Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

[docs bz5681099] Rewrote and reorganized context configuration doc. #555

Closed
wants to merge 4 commits into from
This page is out of date. Refresh to see the latest.
Showing with 212 additions and 133 deletions.
  1. +212 −133 docs/dev_guide/topics/mojito_using_contexts.rst
View
345 docs/dev_guide/topics/mojito_using_contexts.rst
@@ -5,67 +5,102 @@ Using Context Configurations
============================
Introduction
-############
+============
-The Mojito framework allows you to define sets of configurations for different environments, languages, and devices. Your applications can either
-statically apply configurations when the application is started or dynamically apply configurations based on incoming HTTP requests. In both static and
-dynamic cases, Mojito determines which configurations to apply by a string consisting of key-value pairs known as the *context*. In the case of applying
-configurations per request, Mojito looks for the context in the HTTP headers or the query string. If no context is found, Mojito uses
-the :ref:`context_config_exs-defaults_json`.
+Context configurations are how Mojito enables different configurations to be used based on various
+runtime factors. Many factors are predefined such as language and device, but you can
+create custom ones as well. These runtime factors are called **contexts** in Mojito
+and are mapped to user-defined configurations. For example, you could set the configuration
+``logLevel`` to ``ERROR`` in the production context and set it to ``INFO`` in the development
+context.
Why Use Context Configurations?
-###############################
+-------------------------------
+
+Context configurations make it possible to do the following:
+
+- Create sets of configurations associated with environments without affecting the application
+ running with the *master* configurations ``"setting: ["master"]``.
+- Customize content for users: Applications can dynamically apply language and device
+ configurations by determining the user's language preferences and the device making the HTTP request.
+
+
+What is a Context?
+==================
+
+The context is the runtime parameters that are either statically set (base context)
+on the command line or dynamically set (request context) in the HTTP headers and/or the
+request query string. The configurations for request contexts override those of the base context.
+
+
+Base Context
+------------
+
+The base context is statically set with the ``--context`` option when you start an application.
+
+Syntax
+######
-Context configurations make it easier to develop applications by allowing developers to create sets of configurations associated to environments.
-Developers can experiment or make modifications to configurations mapped to a testing environment context without affecting the application running
-with the default configurations. Context configurations also make it easier to customize content for users. Applications can dynamically apply language
-and device configurations by determining the user's language preferences and the device making the HTTP request. Mojito provides default contexts that
-you can define configurations for, but you can also `create custom contexts <#creating-custom-contexts>`_ to meet your application's needs.
+The base context has the following syntax:
-Flow of Using Context Configurations
-####################################
+``"key1:value1[,key2:value2]"``
+
+Example
+#######
-#. **Create context configurations:**
+The following starts the application with the base context ``environment:production``:
- Define context configurations in ``application.json``, ``routes.json``, and default context configurations for your mojits in the ``defaults.json`` file in your mojit directory.
+``$ mojito start --context "environment:production"``
-#. **Start application:**
+Request Contexts
+----------------
- - Use the default configurations by not specifying a base context: ``$ mojito start``
- - Specify the base context with the ``--context`` option. Mojito will apply the configurations mapped to the base context. For example: ``$ mojito start --context "environment:test"``
+Contexts that are dynamically invoked by HTTP requests are called request contexts. When Mojito
+receives an HTTP request that specifies a context, the configurations mapped to that context will be
+dynamically applied. The contexts can be specified in HTTP request as a parameter in the query
+string or in the HTTP header.
-#. **Receive HTTP requests:**
+Request Headers
+###############
- *Request new context:*
- Mojito will look at the HTTP headers for language and device contexts and the query string parameters for any of the default contexts.
- Contexts found in the request are referred to as request contexts. Mojito will then merge the default configurations or the
- configurations of the base context with the configurations of the request context. The configurations of the request context override
- default configurations or those of the base context.
- *Change configurations:*
- The application can dynamically change configurations by having a parent mojit execute a child with new configuration values.
+The contexts for languages can be requested using the HTTP header ``Accept-Language``. After
+starting an application with the context ``"environment:testing"``, you can dynamically apply the
+configurations for the context ``"environment:testing,lang:fr"`` by sending the HTTP header
+``"Accept-Language: fr"``. In the same way, the contexts for devices can be requested using the HTTP
+header ``User-Agent``. The configurations for the context "device:android" could be requested with
+the HTTP header ``"User-Agent: Mozilla/5.0 (Linux; U; Android 2.3; en-us)"``.
-Contexts
-########
+Query String Parameters
+#######################
-The context is a string consisting of key-value pairs that map to a set of configurations. Mojito provides default contexts for environments, devices, and languages.
-If none of the default contexts meet your needs, you can create :ref:`context_configs-custom`.
+The key and value pairs in the context are dynamically set by the query string.
Syntax
-======
+``````
+
+``?key1=value1,key2=value2``
-The context has the following syntax :
+Example
+```````
-``"key1:value1[,key2:value2]"``
+For example, if an application is started with the base context ``"environment:testing"`` and you
+want to dynamically apply the context ``"environment:testing,device:iphone"``, you could append the
+following query string to the application URL:
-.. _contexts-defaults:
+``?device=iphone``
-Default Contexts
-================
-The following lists the contexts that are defined by Mojito. You can define configurations for these default contexts. You can combine multiple contexts to
-form a compound context as well. For example, if you wanted a context to map to configurations for Android devices in a testing environment, you could use the
-following compound context: ``"environment:test,device:android"``
+
+.. _contexts-predefined:
+
+Mojito Predefined Contexts
+--------------------------
+
+The following lists the contexts that are defined by Mojito. You can define configurations for these
+predefined contexts. You can combine multiple contexts to form a compound context as well. For
+example, if you wanted a context to map to configurations for Android devices in a testing
+environment, you could use the following compound context: ``"environment:test,device:android"``
- ``environment:development``
- ``environment:production``
@@ -83,43 +118,103 @@ following compound context: ``"environment:test,device:android"``
- ``device:palm``
- ``lang:{BCP 47 language tag}``
-You can view the supported BCP 47 language tags and default contexts in the `dimensions.json <https://github.com/yahoo/mojito/blob/develop/source/lib/dimensions.json>`_ file of Mojito.
-Configuration Precedence
-========================
+You can view the supported BCP 47 language tags and default contexts in the
+`dimensions.json <https://github.com/yahoo/mojito/blob/develop/source/lib/dimensions.json>`_ file
+of Mojito. You can also :ref:`create custom contexts <context_configs-custom>` if the Mojito
+default contexts don't meet the needs of your application.
-Mojito evaluates configurations in the following order:
-#. default context configurations specified in the configuration object with the ``setting`` array with the "master" string.
-#. configurations associated with a context specified on the command line with the ``--context`` option.
-#. configurations associated with a context set using the query string, HTTP headers, or through the execution of a child mojit with configuration information.
+How Does Mojito Resolve Context Configurations?
+===============================================
+
+When a request is made to a Mojito application, Mojito has to resolve
+configurations, defined contexts (``dimensions.json``), and the base/requested contexts
+before the correct context configurations can be applied.
+
+The following are the steps taken by Mojito to apply the correct context
+configurations:
+
+#. **Determines Valid Contexts:**
+
+ Mojito looks for a local ``dimensions.json``. If one is found, Mojito replaces
+ Mojito's ``dimensions.json`` with it. Mojito then uses ``dimensions.json`` to determine
+ which contexts are valid. Contexts defined earlier in ``dimensions.json`` override
+ contexts defined later in the file.
+
+#. **Merges Configurations**
+
+ Mojito merges configurations for all contexts, with the configurations
+ in ``application.json`` overriding those in ``defaults.json``. If contexts
+ are found that are not defined in ``dimensions.json``, Mojito will throw
+ an error.
+
+#. **Determines Context**
+
+ - Mojito checks if a base context was specified (statically) on the command line with
+ the ``--context`` option.
+ - When Mojito receives an HTTP request, it looks for a request context in
+ the query string, HTTP headers, or through the execution of a child mojit with configuration
+ information.
+ - Mojito merges the base context (if any) with the request context (if any). For example,
+ if the base context is ``"environment:develop``" and the request context found in the query string
+ is ``"?lang=de"``, then the compound context in the ``setting`` array in
+ configuration files would be ``["environment:development", "lang:de"]``. Mojito will
+ use the most qualified context possible. If the appropriate compound context does not exist,
+ Mojito uses the request context over the base context.
+ - If no base or request context is found, Mojito then uses the default context ``master``.
+
+#. **Resolves Context Configurations**
+
+ Mojito then searches for configurations associated with the determined context.
+ The contexts are found in the ``setting`` object in configuration files.
+ Mojito will use the more qualified contexts if present over more general contexts.
+ For example, if the merged base and request context is ``"environment:prod, device:iphone"``,
+ then Mojito will use it over either ``"device:iphone"`` or ``"env:prod"``. If
+ ``"environment:prod, device:iphone"`` is not present, Mojito will use the request context
+ over the base context as the resolved context.
+
+
+#. **Applies Context Configuration**
+
+ Mojito applies the configurations associated with the resolved context.
+
+
+
Defining Configurations for Contexts
-####################################
+====================================
-Configurations for contexts are defined in the application configuration file ``application.json``. Routing configurations for contexts are defined in the
-routing configuration file ``routes.json``. Default configurations are defined in the ``defaults.json`` file of a mojit. All configurations are merged when
-an application starts. The configuration values in ``application.json`` override those
+Configurations for contexts are defined in the application configuration file ``application.json``.
+Routing configurations for contexts are defined in the routing configuration file ``routes.json``.
+Default configurations are defined in the ``defaults.json`` file of a mojit. All configurations are
+merged when an application starts. The configuration values in ``application.json`` override those
in ``defaults.json``.
Configuration Objects
-=====================
+---------------------
-The ``application.json`` and ``routes.json`` files in the application directory and the ``defaults.json`` file in a mojit's directory consist of an array of configuration objects.
-The configuration object has a ``settings`` array that specifies the context. The configuration objects in ``application.json`` also have a ``specs`` object
-containing mojit instances, which may also have a ``config`` object that has data in the form of key-value pairs. The configuration objects in ``defaults.json`` do not
-have a ``specs`` object because they do not define mojits, but do have a ``config`` object for storing key-value pairs. The ``routes.json`` file specifies routing
-configuration such as the path, HTTP methods, actions, and routing parameters, but does not contain a ``specs`` or a ``config`` object.
+The ``application.json`` and ``routes.json`` files in the application directory and the
+``defaults.json`` file in a mojit's directory consist of an array of configuration objects. The
+configuration object has a ``settings`` array that specifies the context. The configuration objects
+in ``application.json`` also have a ``specs`` object containing mojit instances, which may also have
+a ``config`` object that has data in the form of key-value pairs. The configuration objects in
+``defaults.json`` do not have a ``specs`` object because they do not define mojits, but do have a
+``config`` object for storing key-value pairs. The ``routes.json`` file specifies routing
+configuration such as the path, HTTP methods, actions, and routing parameters, but does not contain
+a ``specs`` or a ``config`` object.
setting
--------
+#######
-The ``settings`` array specifies the context or the default ("master") that is then mapped to configurations.
+The ``settings`` array specifies the context or the default ("master") that is then mapped to
+configurations.
Default Configurations
-~~~~~~~~~~~~~~~~~~~~~~
+``````````````````````
-Default configurations are used when no context is given. These configurations are found in the object where the settings array has the string "master" as seen below.
+Default configurations are used when no context is given. These configurations are found in the
+object where the settings array has the string "master" as seen below.
.. code-block:: javascript
@@ -134,7 +229,7 @@ Default configurations are used when no context is given. These configurations a
]
Simple Context Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+````````````````````````````
The context is specified in the ``settings`` array of the configuration object.
@@ -152,9 +247,10 @@ The context is specified in the ``settings`` array of the configuration object.
]
Compound Context Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``````````````````````````````
-Compound contexts are specified in the settings array as a series of contexts separated by commas as seen below.
+Compound contexts are specified in the settings array as a series of contexts separated by commas
+as seen below.
.. code-block:: javascript
@@ -170,7 +266,7 @@ Compound contexts are specified in the settings array as a series of contexts se
]
Routing Context Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`````````````````````````````
.. code-block:: javascript
@@ -191,7 +287,7 @@ Routing Context Configuration
specs
------
+#####
The ``specs`` object contains the mojit instances associated with a context.
@@ -211,7 +307,7 @@ The ``specs`` object contains the mojit instances associated with a context.
]
config
-------
+######
The ``config`` object stores configuration for a mojit that is mapped to the context.
@@ -234,13 +330,14 @@ The ``config`` object stores configuration for a mojit that is mapped to the con
]
Examples
-========
+--------
application.json
-----------------
+################
-The configuration objects in ``application.json`` below define default configurations and three context configurations. The last context configuration contains
-two strings containing key-value pairs and is, thus, called a compound context configuration.
+The configuration objects in ``application.json`` below define default configurations and three
+context configurations. The last context configuration contains two strings containing key-value
+pairs and is, thus, called a compound context configuration.
.. code-block:: javascript
@@ -294,9 +391,10 @@ two strings containing key-value pairs and is, thus, called a compound context c
.. _context_config_exs-defaults_json:
defaults.json
--------------
+#############
-The configuration ``gamma`` in the example ``defaults.json`` below is mapped to contexts for languages.
+The configuration ``gamma`` in the example ``defaults.json`` below is mapped to contexts for
+languages.
.. code-block:: javascript
@@ -324,7 +422,7 @@ The configuration ``gamma`` in the example ``defaults.json`` below is mapped to
]
routes.json
------------
+###########
.. code-block:: javascript
@@ -348,56 +446,21 @@ routes.json
]
-Applying Context Configurations
-###############################
-
-The configurations for a context can be applied statically or dynamically. The base context is used to statically apply configurations. The request context is used to
-dynamically apply configurations.
-
-Base Context
-============
-
-The base context is specified with the ``--context`` option when you start an application. The following starts the application with the base context ``environment:production``:
-
-``$ mojito start --context "environment:production"``
-
-Request Contexts
-================
-
-Contexts that are dynamically invoked by HTTP requests are called request contexts. When Mojito receives an HTTP request that specifies a context, the configurations mapped
-to that context will be dynamically applied. The contexts can be specified in HTTP request as a parameter in the query string or in the HTTP header.
-
-Request Headers
----------------
-
-The contexts for languages can be requested using the HTTP header ``Accept-Language``. After starting an application with the context ``"environment:testing"``, you can
-dynamically apply the configurations for the context ``"environment:testing,lang:fr"`` by sending the HTTP header ``"Accept-Language: fr"``. In the same way, the contexts
-for devices can be requested using the HTTP header ``User-Agent``. The configurations for the context "device:android" could be requested with the
-HTTP header ``"User-Agent: Mozilla/5.0 (Linux; U; Android 2.3; en-us)"``.
-
-Query String Parameters
------------------------
-
-The key and value pairs in the context are dynamically set by the query string using the standard syntax for query strings: ``?key1=value1,key2=value2``
-
-For example, if an application is started with the base context ``"environment:testing"`` and you want to dynamically apply the context ``"environment:testing,device:iphone"``, you could append the following query string to the application URL: ``?device=iphone``
-
-Merged Base and Request Contexts
-================================
-
-An application started with a base context can apply configurations for request contexts. Mojito will merge the configurations for both the base and request contexts.
-The configurations for request contexts override those of the base context.
Dynamically Changing Configurations
-###################################
+===================================
-You may dynamically change the configurations for any context by having a parent mojit execute a child mojit with new configurations. This is different than getting
-different configurations by requesting a new context or specifying a different base context. Regardless of the context being used, you can use the same context and change
-the configurations by executing a child mojit with new configurations. The parent mojit uses the ``execute`` method of the
+You may dynamically change the configurations for any context by having a parent mojit execute a
+child mojit with new configurations. This is different than getting different configurations by
+requesting a new context or specifying a different base context. Regardless of the context being
+used, you can use the same context and change the configurations by executing a child mojit with new
+configurations. The parent mojit uses the ``execute`` method of the
`Composite addon <../../api/classes/Composite.common.html>`_ to execute the child mojit.
Let's look at an example to see how it works.
-In the example controller below, if the ``child`` parameter is found in the routing, query string, or request body, a child instance with its own configuration is executed, allowing the application to add new or change configurations of the current context.
+In the example controller below, if the ``child`` parameter is found in the routing, query string,
+or request body, a child instance with its own configuration is executed, allowing the application
+to add new or change configurations of the current context.
.. code-block:: javascript
@@ -410,7 +473,8 @@ In the example controller below, if the ``child`` parameter is found in the rout
"type": "Child",
"action": "index",
"config": {
- "alpha": "Creating a new 'alpha' key or replacing the value of the alpha key mapped to the context being used. The context, however, does not change."
+ "alpha": "Creating a new 'alpha' key or replacing the value of the alpha key mapped
+ to the context being used. The context, however, does not change."
}
}
}
@@ -433,29 +497,40 @@ In the example controller below, if the ``child`` parameter is found in the rout
.. _context_configs-custom:
Creating Custom Contexts
-########################
+========================
-The Mojito framework defines default contexts that developers can map configurations to. These default contexts are defined in the ``dimensions.json`` file found in
-the Mojito source code. Developers can create an application-level ``dimensions.json`` to define custom contexts that can be mapped to configurations as well.
-Defining and applying configurations for custom contexts is done in the same way as for default contexts.
+The Mojito framework defines default contexts that developers can map configurations to. These
+default contexts are defined in the file ``dimensions.json <https://github.com/yahoo/mojito/blob/develop/source/lib/dimensions.json>`_
+found in the Mojito source code. Developers can create an application-level ``dimensions.json`` to
+define custom contexts that can be mapped to configurations as well.
+
+The local ``dimensions.json`` replaces the Mojito's ``dimensions.json``, so to create custom
+contexts, you will need to copy Mojito's ``dimension.json`` to your application directory and
+then add your custom contexts to the file. Defining and applying configurations for custom contexts
+is done in the same way as for default contexts.
Who Should Create Custom Contexts?
-==================================
+----------------------------------
-Developers who create applications that require a degree of personalization that extends beyond language and device would be good candidates to create custom contexts.
-Before beginning to create your own ``dimensions.json`` file, you should review the :ref:`contexts-defaults` to make sure that you truly need custom contexts.
+Developers who create applications that require a degree of personalization that extends beyond
+language and device would be good candidates to create custom contexts. Before beginning to create
+your own ``dimensions.json`` file, you should review the :ref:`contexts-predefined` to make sure that
+you truly need custom contexts.
Dimensions File
-===============
+---------------
-The key-value pairs of the context are defined in the ``dimensions.json`` file in the application directory. Once contexts are defined in the ``dimensions.file``,
-you can then map configurations to those contexts. If your application has configurations for a context that has not been defined by Mojito or at the application
-level in ``dimensions.json``, an error will prevent you from starting the application.
+The key-value pairs of the context are defined in the ``dimensions.json`` file in the application
+directory. Once contexts are defined in the ``dimensions.file``, you can then map configurations to
+those contexts. If your application has configurations for a context that has not been defined by
+Mojito or at the application level in ``dimensions.json``, an error will prevent you from starting
+the application.
Syntax for JavaScript Object
-----------------------------
+############################
-In the ``dimension.json`` file, the ``dimensions`` array contains JavaScript objects that define the contexts. The keys of the context are the names of the objects,
+In the ``dimension.json`` file, the ``dimensions`` array contains JavaScript objects that define the
+contexts. The keys of the context are the names of the objects,
and the values are the object's properties as seen below.
.. code-block:: javascript
@@ -475,7 +550,7 @@ and the values are the object's properties as seen below.
}
Example dimensions.js
----------------------
+`````````````````````
Based on the example ``dimensions.json`` below, the following are valid contexts:
@@ -489,17 +564,21 @@ Based on the example ``dimensions.json`` below, the following are valid contexts
[
{
"dimensions": [
+ ...
{
"account_type": {
"basic": null,
"premium": null
+ }
},
{
"region":{
"us": null,
"gb": null,
"fr": null
+ }
}
+ ...
}
]
Something went wrong with that request. Please try again.