2. Mojits: Powering Your App¶

Time Estimate¶

15 minutes

What We’ll Cover¶

• mojit definitions and instances
• mojit MVC
• the ActionContext object and the `ActionContext` addons
• templates

Final Product¶

You’ll see that our application now shows something other than the default information. We’ve created new mojits and reworked the Github mojit to show some information, which required changing the controller, model, and templates).

Before Starting¶

What is a Mojit?¶

Mojits can be thought of as both physical entities represented physically by a directory structure and as executable code. The physical files of a mojit are what we call the mojit definition and where you most clearly see the mojit’s MVC structure. The executable code, or the instantiation of the mojit definition, is called the mojit instance.

We’re going to take a closer look at both the mojit definition and instance, and how they are created and used.

Mojit Definitions¶

To create the mojit definition, you use the command create that we looked at in the previous module. When you run mojito create mojit <mojit_name>, Mojito creates a directory structure with boilerplate code for your controller, model, view (template) as well as tests and configuration.

As you can see from the directory structure of the default mojit below, the mojits live under the mojits directory and have subdirectories for models, tests, and views:

Github
├── assets
│   └── index.css
├── binders
│   └── index.js
├── controller.server.js
├── defaults.json
├── definition.json
├── models
│   └── model.server.js
├── tests
│   ├── controller.server-tests.js
│   └── models
│       └── model.server-tests.js
└── views
    └── index.hb.html

Controllers, Models, and YUI¶

If you have worked with YUI before, you’ll notice pretty quickly that mojit controllers and models are simply custom YUI modules that are registered with YUI.add. The skeleton of these custom modules include the controller namespace and the requires array for specifying dependencies:

controller.server.js

YUI.add('github', function (Y, NAME) {

  Y.namespace('mojito.controllers')[NAME] = {
   // Code here
  };
}, '0.0.1', {requires: ['mojito', 'mojito-models-addon', 'github-model']});

model.server.js

YUI.add('github-model', function(Y, NAME) {

  Y.namespace('mojito.models')[NAME] = {
    init: function(config) {
      Y.log(config);
      this.config = config;
    }
  };
}, '0.0.1', {requires: []});

ActionContext Object¶

In mojit controllers, functions in the mojito.controller namespace are passed a special object called the Action Context. We’ll be calling it the ActionContext object or ac for short.

The ActionContext object gives you access to important features of the Mojito framework. One critical feature is the ability to send data to templates and have those templates executed. Mojito also provides a library that can be accessed through the ac object through a mechanism called addons.

For your mojits to render templates, controller functions need to call the method ac.done. The done method also allows you to choose the view to render and pass meta data, which we will cover in later chapters. If a routing path is mapped to an action (controller function) that doesn’t call ac.done, your application will hang until it times out.

ActionContext Addons¶

The ActionContext addons provide functionality that lives both on the server and client. Each addon provides additional functions through a namespacing object that is appended to the ActionContext object. To use addons, the controller need to require the addons by listing the addons in the requires array. The default Mojito application uses the Models and Assets addon. As our application gets more complicated, we’ll be relying on addons to do more work.

Requiring Addons¶

You require an addon by including an associated string in the requires array of your controller. For example, in the controller below, the Config addon is required by adding the string 'mojito-config-addon' to the requires array.

YUI.add('github', function(Y, NAME) {
  Y.namespace('mojito.controllers')[NAME] = {
    index: function(ac) {
      var title = ac.config.get(‘title’);
    }
  };
  // Require the addon by adding the param name to the requires array
}, '0.0.1', {requires: ['mojito', 'mojito-config-addon']});

Controller Methods¶

When we say controller methods or functions we are referring to those methods in the controller namespace as shown below.

...
  Y.namespace('mojito.controllers')[NAME] = {
    index: function(ac) {
      ac.done({ data: { status: "This is an example controller method." }});
  };
...

Templates¶

The templates for Mojito applications are HTML files that may contain semantic templates for variable substitution. The default templating system used by Mojito is Handlebars. You can use other templating systems as well, but for the purposes of this tutorial, we’ll only be covering Handlebars.

If you know nothing about Handlebars, we suggest that you read the Handlebars documentation. When a controller function calls ac.done with an object as a parameter, the object can be passed to the template file. The value of the property or key will replace the Handlebars expression.

For example, in the controller function index below, the object { status: "It’s working" } is passed by default to the template index.hb.html.

...
  index: function(ac) {
    ac.done({ status: "This is an example controller method." });
...

In the index.hb.html file below, the Handlebars expression is replaced by the string "This is an example controller method." when the template is rendered.

<div id="">
  <b></b>
</div>

Mojit Configuration Files¶

Mojits have two files for defining configurations. The file defaults.json allows the mojit to have defaults that can be overridden. The file definition.json allows the mojit to define key-value pairs that can be accessed by the controller. You can also use the settings property to specify a context for a runtime environment.

In the defaults.json file, you list configurations in the config object as shown below. These configurations are defaults that will be used unless a mojit instance has configurations with the same keys.

[
  {
    "settings": [ "master" ],
    "config": {
      "gh_mojito": "https://github.com/yahoo/mojito.git",
      "gh_yui3": "https://github.com/yui/yui3.git"
    }
   },
   {
     "settings": [ "environment:development" ],
     "config": {
       "gh_mojito": "https://github.com/yahoo/mojito.git",
       "gh_mojito_remote": "git@github.com:yahoo/mojito.git",
       "gh_yui3": "https://github.com/yui/yui3.git",
       "gh_yui3_remote": "git@github.com:yui/yui3.git"
     }
   }
 ]

The configurations in definition.json do not need to be in a config object. You just list key-value pairs:

[
  {
    "settings": [ "master" ],
    "gh_mojito": "https://github.com/yahoo/mojito.git",
    "gh_yui3": "https://github.com/yui/yui3.git"
  },
  {
    "settings": [ "environment:development" ],
    "gh_mojito": "https://github.com/yahoo/mojito.git",
    "gh_mojito_remote": "git@github.com:yahoo/mojito.git",
    "gh_yui3": "https://github.com/yui/yui3.git",
    "gh_yui3_remote": "git@github.com:yui/yui3.git"
  }
]

Mojit Instances¶

We have already seen that Mojito creates anonymous instances of mojit definitions by prepending the symbol @ the the mojit name, allowing you to execute a mojit action. Generally though, you define a mojit instances in configuration, so that the Mojito framework can create the instances. The configuration file that is used for defining mojit instances and many other application-level configurations is application.json. When you run the start command, the Mojito framework parses and loads the application configuration, so mojit instances can be dispatched and their actions (controller functions) can be executed.

[
  {
    "settings": [ "master" ],
    "specs": {
      "github": {
        "type": "Github"
      }
    }
  }
]

Mapping Routing Paths to Actions¶

Because of the anonymous mojit instances that Mojito creates with a mojit definition, your application also gets some default routing paths that let you execute mojit actions with a URL. We use the term action to differentiate the controller functions of the mojit definition from the same functions run by a mojit instance. When you create a mojit, as you might have already guessed, you can use the following URL schema to execute mojit actions: http://{domain}:{port}/@{mojit_name}/{action}/

As with using anonymous instances, you obviously don’t want to use these default routes created by Mojito. You instead map routing paths to mojit actions in the configuration file app.js. The configuration object that defines routing information has properties for defining the routing path, HTTP methods that are accepted, parameters, and the mojit actions to execute. In the example app.js below, the application is configured to execute the action index of the mojit github when an HTTP GET call is made to the path "/":

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

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

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

From HTTP Request to Mojit Action¶

The diagram below shows the relationship of mojit definition, mojit instance, and routing paths. In addition, you can also see the relationship of the application within the framework. Notice also that the mojit controller has the function index that maps to the action ``index``specified in the routing configuration.

Recommended Naming Conventions for Mojits¶

When creating mojits (mojit definitions) with the command-line tool, we will be using upper camel case for the mojit name, such as Github. For mojit instances, we will be using lower case, such as github. This is the typical convention when defining a class and creating an object, so you can think of the mojit definition as the class definition and the mojit instance as an instance or object of that class.

Route Not Being Found¶

If you started the application, went to http://localhost:8666/body, and got the following error Cannot GET /body, It appears that you started Mojito from the wrong location. Try changing to the application directory, which in this example is 02_mojits, and then run app.js.

Error: listen EADDRINUSE¶

If you start Mojit and get the following error, it means that Mojito is already running. You’ll need to kill that process before you can restart Mojito.

Questions¶

• What is a mojit?
• What is the difference between a mojit instance and a mojit definition?
• Name four configuraton files used in Mojito applications.

Additional Exercises¶

• Create an additional mojit and a routing path that allows your application to execute an action for that mojit.
• Modify the mojit you created so that the model passes data to controller and that data is rendered in the template.