Configuring Mojito¶

JSON¶

By default, configuration files in Mojito have a general top-level structure and are in JSON format. At the top level of each configuration file is an array. Each item of the array is an object containing configuration that targets a specific context and runtime. This allows you to have discrete configurations for different regions, devices, and development environments.

The context for a configuration object is specified by the settings property. For each configuration object in a file, the settings property must specify a unique context, otherwise Mojito fails. For example, the application.json file cannot have two configuration objects specifying the context environment:development. See Using Context Configurations for more information about contexts.

Below is the skeleton of a configuration file with two configuration objects, each identified by contexts defined by the settings property. See Application Configuration and Mojit Configuration for details about specific configuration files.

application.json

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

YAML¶

Mojito also supports configuration files in YAML format (JSON is a subset of YAML). The YAML file extension could be .yaml or .yml. Mojito allows comments in the YAML files. When both the JSON file (e.g., application.json) and the YAML file (e.g., application.yaml) are present, the YAML file is used and a warning is issued. For the data types of the YAML elements, please see the JSON configuration tables in Application Configuration, Routing, and Mojit Configuration.

application.yaml

---
  # Example application configuration in YAML, which allows comments.
  -
    # The master context for default configurations.
    settings:
      - "master"

    # You can create mojit instances in the 'specs' object.
    specs:
  -
    # The context 'environment:development' that you can use for development.
    settings:
      - "environment:development"
    specs:

To convert JSON to YAML, we recommend using a command-line utility such as the npm module json2yaml.

builds Object¶

specs Object¶

The specs object can contain one or more mojit instances that are named by the developer. Each mojit instance is represented by an object and has a type that specifies a mojit that was created with mojito create mojit <mojit_name> or a built-in frame mojit. The table below contains the properties that a mojit instance object can contain.

staticHandling Object¶

viewEngine Object¶

yui Object¶

See Example Application Configurations for an example of the yui object.

Application With Multiple Mojits¶

Your application configuration can specify multiple mojit instances of the same or different types in the specs object. In the example application.json below, the mojit instances sign_in and sign_out are defined:

application.json

[
  {
    "settings": [ "master" ],
    "specs": {
      "sign_in": {
        "type": "SignIn"
      },
      "sign_out": {
        "type": "SignOut"
      }
    }
  }
]

application.yaml

---
  -
    settings:
      - "master"
    specs:
      sign_in:
        type: "SignIn"
      sign_out:
        type: "SignOut"

Parent Mojit With Child Mojit¶

A mojit instance can be configured to have a child mojit using the child object. In the example application.json below, the mojit instance parent of type Parent has a child mojit of type Child.

application.json

[
  {
    "settings": [ "master" ],
    "specs": {
      "parent": {
        "type": "Parent",
        "config": {
          "child": {
            "type": "Child"
          }
        }
      }
    }
  }
]

application.yaml

---
  -
    settings:
      - "master"
    specs:
      parent:
        type: "Parent"
        config:
          child:
            type: "Child"

Parent Mojit With Children¶

A mojit instance can also be configured to have more than one child mojits using the children object that contains mojit instances. To execute the children, the parent mojit would use the Composite addon. See Composite Mojits for more information.

In the example application.json below, the mojit instance father of type Parent has the children son and daughter of type Child.

application.json

[
  {
    "settings": [ "master" ],
    "specs": {
      "father": {
        "type": "Parent",
        "config": {
          "children": {
            "son": {
              "type": "Child"
            },
            "daughter": {
              "type": "Child"
            }
          }
        }
      }
    }
  }
]

application.yaml

---
  -
    settings:
      - "master"
    specs:
      father:
        type: "Parent"
        config:
          children:
            son:
              type: "Child"
            daughter:
              type: "Child"

Child Mojit With Children¶

A parent mojit can have a child that has its own children. The parent mojit specifies a child with the child object, which in turn lists children in the children object. For the child to execute its children,it would use the Composite addon. See Composite Mojits for more information.

The example application.json below creates the parent mojit first_level with a child that has the children third_level_a and third_level_b.

application.json

[
  {
    "settings": [ "master" ],
    "specs": {
      "first_level": {
        "type": "FirstLevel",
        "config": {
          "child": {
              "type": "SecondLevel",
              "children": {
                "third_level_a": {
                  "type": "ThirdLevel"
                },
                "third_level_b": {
                  "type": "ThirdLevel"
                }
              }
            }
          }
        }
      }
    }
  }
]

application.yaml

---
  -
    settings:
      - "master"
    specs:
      first_level:
        type: "FirstLevel"
        config:
          child:
              type: "SecondLevel"
              children:
                third_level_a:
                  type: "ThirdLevel"
                third_level_b:
                  type: "ThirdLevel"

The child mojits can also have their own children, but beware that having so many child mojits may cause memory issues. In our updated example application.json below, the third_level_b mojit now has its own children:

application.json

[
  {
    "settings": [ "master" ],
    "specs": {
      "first_level": {
        "type": "FirstLevel",
        "config": {
          "child": {
            "type": "SecondLevel",
            "children": {
              "third_level_a": {
                "type": "ThirdLevel"
              },
              "third_level_b": {
                "type": "ThirdLevel",
                "children": {
                  "fourth_level_a": {
                     "type": "FourthLevel"
                  },
                  "fourth_level_b": {
                     "type": "FourthLevel"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
]

application.yaml

---
  -
    settings:
      - "master"
    specs:
      first_level:
        type: "FirstLevel"
        config:
          child:
            type: "SecondLevel"
            children:
              third_level_a:
                type: "ThirdLevel"
              third_level_b:
                type: "ThirdLevel"
                children:
                  fourth_level_a:
                    type: "FourthLevel"
                  fourth_level_b:
                    type: "FourthLevel"

What Gets Deployed?¶

The following is deployed to the client:

• Mojito framework
• binders (and their dependencies)

When a binder invokes its controller, if the controller has the client or common affinity, then the controller and its dependencies are deployed to the client as well. If the affinity of the controller is server, the invocation occurs on the server. In either case, the binder can invoke the controller.

Example¶

The example application.json below uses the deploy property to configure the application to be deployed to the client.

application.json

[
  {
    "settings": [ "master" ],
    "specs": {
      "frame": {
        "type": "HTMLFrameMojit",
        "config": {
          "deploy": true,
          "child": {
            "type": "Pager"
          }
        }
      }
    }
  }
]

application.yaml

---
  -
    settings:
      - "master"
    specs:
      frame:
        type: "HTMLFrameMojit"
        config:
          deploy: true
          child:
            type: "Pager"

Using Mojit Instances¶

When a mojit instance is defined in application.json, you can map an action of that mojit instance to a routing path in app.js. Actions are references to functions in the mojit controllers. When a client makes an HTTP request on a defined routing path, the function in the mojit controller that is referenced by the action from the mojit instance is called.

For example, the application.json below defines the foo mojit instance of the mojit type Foo.

[
  {
    "settings": [ "master" ],
    "specs": {
      "foo": {
        "type": "Foo",
        "config": {
          "message": "hi"
        }
      }
    }
  }
]

The routes.json below uses the foo instance to call the index action when an HTTP GET request is made on the root path. The index action references the index function in the controller of the Foo mojit.

use strict';

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

app = express();
app.set('port', process.env.PORT || 8666);
libmojito.extend(app);

app.use(libmojito.middleware());

app.get('/', libmojito.dispatch("foo.index."));

app.listen(app.get('port'), function () {
    debug('Server listening on port ' + app.get('port') + ' ' +
          'in ' + app.get('env') + ' mode');
});

Single Route¶

To create a route, you need to create a mojit instance that can be mapped to a path. In the application.json below, the hello instance of type Hello is defined.

application.json

[
  {
    "settings": [ "master" ],
    "specs": {
      "hello": {
        "type": "Hello"
      }
    }
  }
]

application.yaml

---
  -
    settings:
      - "master"
    specs:
      hello:
        type: "Hello"

The hello instance and a function in the Hello controller can now be mapped to a route path in routes.json file. In the routes.json below, the index function is called when an HTTP GET call is made on the root path.

routes.json

[
  {
    "settings": [ "master" ],
    "hello index": {
      "verbs": ["get"],
      "path": "/",
      "call": "hello.index"
    }
  }
]

routes.yaml

---
  -
    settings:
      - "master"
    hello index:
      verbs:
        - "get"
      path: "/"
      call: "hello.index"

Instead of using the hello mojit instance defined in the application.json shown above, you can create an anonymous instance of Hello for mapping an action to a route path. In the routes.json below, an anonymous instance of Hello is made by prepending “@” to the mojit type.

routes.json

[
  {
    "settings": [ "master" ],
    "hello index": {
      "verbs": ["get"],
      "path": "/",
      "call": "@Hello.index",
      "params": { "first_visit": true }
    }
  }
]

routes.yaml

---
  -
    settings:
      - "master"
    hello index:
      verbs:
        - "get"
      path: "/"
      call: "@Hello.index"
      params:
        first_visit: true

Multiple Routes¶

To specify multiple routes, you create multiple route objects that contain verb, path, and call properties in routes.json as seen here:

routes.json

[
  {
    "settings": [ "master" ],
    "root": {
      "verb": ["get"],
      "path": "/*",
      "call": "foo-1.index"
    },
    "foo_default": {
      "verb": ["get"],
      "path": "/foo",
      "call": "foo-1.index"
    },
    "bar_default": {
      "verb": ["get"],
      "path": "/bar",
      "call": "bar-1.index",
      "params": { "page": 1, "log_request": true }
    }
  }
]

routes.yaml

---
  -
    settings:
      - "master"
    root:
      verb:
        - "get"
      path: "/*"
      call: "foo-1.index"
    foo_default:
      verb:
        - "get"
      path: "/foo"
      call: "foo-1.index"
    bar_default:
      verb:
        - "get"
      path: "/bar"
      call: "bar-1.index"
      params:
        page: 1
        log_request: true

The routes.json and routes.yaml files above create the following routes:

• http://localhost:8666
• http://localhost:8666/foo
• http://localhost:8666/bar
• http://localhost:8666/anything

Notice that the routes.json above uses the two mojit instances foo-1 and bar-1; these instances must be defined in the application.json file before they can be mapped to a route path. Also, the wildcard used in root object configures Mojito to call foo-1.index when HTTP GET calls are made on any undefined path.

application.json¶

The controller functions that are passed an actionContext object can get the application configurations in application.json with the method getAppConfig of the Config addon.

For example, if you wanted to access the specs object defined in application.json, you would use ac.config.getAppConfig().specs as shown here:

YUI.add('mymojit', function(Y, NAME) {
  Y.namespace('mojito.controllers')[NAME] = {
    index: function(ac) {
      // Get the 'specs' object from the application configuration
      // through the Config addon.
      var app_specs = ac.config.getAppConfig().specs;
      Y.log(app_specs);
      ac.done({ status: "Showing app config in the log."});
    }
  };
}, '0.0.1', {requires: ['mojito', 'mojito-config-addon']});

app.js¶

One of the functions of the app.js is for defining routing paths. You can access the defined routing paths with the method getRoutes of the Config addon.

YUI.add('mymojit', function(Y, NAME) {
  Y.namespace('mojito.controllers')[NAME] = {
    index: function(ac) {
      // Get the routing configuration through
      // the Config addon.
      var route_config = ac.config.getRoutes();
      Y.log(route_config);
      ac.done({ status: "Showing routing config in the log."});
    }
  };
}, '0.0.1', {requires: ['mojito', 'mojito-config-addon']});

Controller¶

Controllers can access mojit-level configurations from the actionContext object using the Config addon. Use ac.config.get to access configuration values from application.json and defaults.json and ac.config.getDefinition to access definition values from definition.json.

Model¶

The init function in the model is also passed the mojit-level configurations. If other model functions need the configurations, you need to save the configurations to the this reference because no actionContext object is passed to the model, so your model does not have access to the Config addon.

Binder¶

As mentioned earlier, you access configurations through the mojitProxy object by referencing the config property: mojitProxy.config