Using Context Configurations¶

Introduction¶

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.

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.

var express = require('express'),
    libmojito = require('mojito'),
    app = express();

libmojito.extend(app, {
    context: {
        runtime: 'server',
        environment: 'development'
    }
});

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:

1. 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.

2. 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.

3. 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"].
   • If no base or request context is found, Mojito then uses the default context master.

4. 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 "environment:prod". If "environment:prod, device:iphone" is not present, Mojito will use the request context over the base context as the resolved context.

5. 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. 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.

[
  {
    "settings": [ "master" ],
    "specs": {
      ...
    }
  },
  ...
]

[
  ...
  {
    "settings": [ "environment:development" ],
    "specs": {
     ...
    }
  },
  ...
]

[
  ...
  {
    "settings": [ "environment:development", "device:android" ],
    "specs": {
      ...
    }
  },
  ...
]

[
  {
    "settings": [ "master" ],
    "master_route": {
      ...
    }
  },
  {
    "settings": [ "environment:development"],
    "dev_route" : {
      ...
    }
  }
]

[
  ...
  {
    "settings": [ "environment:production" ],
    "specs": {
      "photos": {
        "type": "Photo"
      }
    }
  },
  ...
]

[
  ...
  {
    "settings": ["device:iphone"],
    "specs": {
      "iphone": {
        "type": "iPhone",
        "config": {
          "viewport_width": 320
        }
      }
    }
  },
  ...
]

[
  {
    "settings": [ "master" ],
    "specs": {
      "mainPage": {
        "type": "Test"
        "config": {
          "env": "This is the default environment."
        }
      }
    }
  },
  {
    "settings": [ "environment:development" ],
    "specs": {
      "mainPage": {
        "type": "Test",
        "config": {
          "env": "I am in the development environment."
        }
      }
    }
  },
  {
    "settings": [ "environment:production" ],
    "specs": {
      "mainPage": {
        "type": "Test",
        "config": {
          "env": "I am in the production environment."
        }
      }
    }
  },
  {
    "settings": [ "environment:production", "device:kindle" ],
    "specs": {
      "mainPage": {
        "type": "Test",
        "config": {
          "env": "I am in the production environment for Kindles."
        }
      }
    }
  }
]

[
  {
    "settings": [ "master" ],
    "config": {
      "alpha" : "I am the first!",
      "beta" : "I am the second!",
      "gamma": "I am the third!"
    }
  },
  {
    "settings": [ "lang:de" ],
    "config": {
      "gamma": "I am (when lang=de is passed) the third!"
    }
  },
  {
    "settings": [ "lang:fr" ],
    "config": {
      "gamma": "defaults.json - (when lang=fr is passed) the third!"
    }
  }
]

Static Configurations¶

Certain context configurations can only be set once by the base context. In other words, once the application starts with a given base context, the values for certain configurations are static: they will not change until the application is started with another base context that’s either specified on the command line or configured in the server.js file.

The following configurations are static:

• actionTimeout
• builds - (only used by the mojito build command)
• mojitDirs
• mojitsDirs
• routesFiles
• staticHandling
• tunnelPrefix
• viewEngine
• yui

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 Composite addon 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.

YUI.add('test', function(Y, NAME) {
  Y.namespace('mojito.controllers')[NAME] = {
    index: function(ac) {
      var cfg = {
        children: {
          "one": {
            "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."
            }
          }
        }
      };
      var child = ac.params.getFromMerged('child');
      if (child){
        ac.composite.execute(cfg, function (data,meta){
          ac.done(data["one"]);
        });
      } else{
        ac.done(
          'config key "alpha": ' + ac.config.get('alpha', '[alpha not found]')
        );
      }
    }
  };
}, '0.0.1', {requires: ['mojito', 'mojito-config-addon', 'mojito-params-addon', mojito-composite-addon']});

Creating Custom Contexts¶

The Mojito framework defines default contexts that developers can map configurations to. These default contexts are defined in the file 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.

[
  {
    "dimensions":[
      {
        "region": {
        "us": null,
        "jp": null,
        "cn": null
      },
      ...
     ]
  }
}

[
  {
    "dimensions": [
      ...
      {
        "account_type": {
          "basic": null,
          "premium": null
        }
      },
      {
        "region":{
          "us": null,
          "gb": null,
          "fr": null
        }
      }
      ...
  }
]