Resource Store¶

Intended Audience¶

Only advanced Mojito application developers needing finer grain control over the management of resources or to extend the functionality of the resource store need to read this documentation.

Prerequisites¶

In addition to being an advanced Mojito user, you should also understand the following before using the Resource Store:

• YUI Plugin
• Mojito addons
• aspect-orient programming (AOP)

How Can the Resource Store Help Developers?¶

What is a Resource?¶

In Mojito, the meaning of the term resource is different depending on the context. Before we discuss the Resource Store in more detail, let’s differentiate and define the definition of resource in the contexts of Mojito and the Resource Store.

Resource Versions¶

Because there can be multiple files that are all conceptually different versions of the same thing (e.g., views/index.hb.html and views/index.iphone.hb.html), the Resource Store defines resource version as the metadata about each file and resource as the metadata about the file chosen among the possible choices.

The process of choosing which version of a resource to use is called resolution (or “resolving the resource”). This act is one of the primary responsibilities of the Resource Store.

See Resolution and Priorities to learn how the Resource Store resolves different versions of the same resource.

Resource Scope¶

Resource Types¶

The resource type is defined by the type property in the metadata for a given resource. See Types of Resources for descriptions of the resource types. Developers can also create their own types of resources to fit the need of their applications.

Intro¶

The Resource Store uses metadata to track information about each resource. This metadata is used by the rest of Mojito to find, load, and parse the resources. The metadata is generated by the Resource Store or by Resource Store addons—it has no representation on the filesystem.

Metadata Object¶

Types of Resources¶

The type property of the metadata object can have any of the following values:

• config - a piece of configuration, sometimes for another resource
• controller - the controller for a mojit
• model - a model for a mojit
• view - a view for a mojit
• binder - a binder for a mojit
• asset - an asset (css, js, image, etc.)
• addon - an addon to the mojito system
• archetype - the commands to create resources as described in the output from mojito help create
• spec - the configuration for a mojit instance
• yui-lang - a YUI 3 language bundle
• yui-module - a YUI 3 module (that isn’t one of the above)

selector Property¶

The selector is an arbitrary user-defined string, which is used to select which version of each resource to use. The selector is defined in the application.json with the selector property. Because the selector is a global entity, you cannot define it at the mojit level. For example, you cannot define the selector in the defaults.json of a mojit.

The value of the selector property is a string that must not have a period ('.') or slash ('/') in it. In practice, it’s suggested to use alphanumeric and hyphen (‘-‘) characters only.

Only one selector can be used in each configuration object identified by the setting property, which defines the context. The specified selectors must match the selector found in the resource file names. So, for example, the template views/index.iphone.hb.html has the selector iphone.

[
  {
    "settings": ["master"],
    ...
  },
  {
    "settings": ["device:ipad"],
    "selector":"ipad",
    "specs": {
      "iPad": {
        "type": "iPadReader",
      }
    }
  }
]

Resource Versions¶

Resources can have many versions that are identified by the selector property and the affinity. The selector is defined by the user and indicates the version of the resource and the affinity is defined by the resource itself.

For example, developer might decide to use the selector selector: iphone for the iPhone version and selector: android for the Android version of a resource. Using these two selectors, you could have the following two versions of the index resource of type view:

• index.iphone.hb.html
• index.android.hb.html

Example¶

{
  "source": {
    "fs": {
      "fullPath": /"home/me/github-mojito/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr/views/index.hb.html",
      "rootDir": "/home/me/github-mojito/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr",
      "rootType": "mojit",
      "subDir": ".",
      "subDirArray": [],
      "isFile": true,
      "ext": ".html",
      "basename": "index.hb"
    },
    "pkg": {
      "name": "paged-yql",
      "version": "0.1.0",
      "depth": 0
    }
  },
  "type": "view",
  "name": "index",
  "id": "view--index",
  "mojit": "PagedFlickr",
  "affinity": "common",
  "selector": "iphone",
  "view": {
    "outputFormat": "html",
    "engine": "hb"
  },
  "url": "/static/PagedFlickr/views/index.hb.html"
}

Overview¶

In short, the resource store walks through the application-level, mojit-level, and npm module files (in that order) of a Mojito application, determines what type of resource each file is, creates metadata about the resource, and then registers the resource.

During this process, the resource store also does the following:

• pre-calculates (“resolves”) which resource versions are used for each version of the mojit.
• also keeps track of application-level resources (archetypes, commands, config files, and middleware).
• provides methods and events, including those specialized for AOP.
• explicitly uses the addons selector and config.

In the following sections, we’ll look at the process in a little more details. To see the code for the resource store, see the server.store.js file.

Walking the Filesystem¶

Resource versions are discovered by the Resource Store at server-start time. The Resource Store method preload first walks all the files in the application, excluding the node_modules directory. Next, all the files in the packages in node_modules are walked. The packages are walked in breadth-first fashion, so that shallower packages have precedence over deeper ones. (Not all the packages are used: only those that have declared themselves as extensions to Mojito.) Finally, if Mojito wasn’t found in node_modules, the globally-installed version of Mojito is walked.

After all that, the Resource Store knows about all the resource versions. Then it resolves those versions into the resources as described in Resolution and Priorities.

Resolution and Priorities¶

The resolving of resource version happens in the Resource Store preload method as well. The act of resolving the resource versions is really just resolving the affinities and selectors. See Resource Versions for a brief explanation about how affinities and selectors determine different versions of a resource. The following sections discuss what the Resource Store uses to resolve versions and create a priority-ordered selector list (POSL).

Getting Data from the Resource Store¶

Besides the standard ways that Mojito uses the resource store, there are two generic methods for getting resources and resource versions from the Resource Store.

• getResourceVersions(filter)
• getResources(env, ctx, filter)

The APIs are intentionally similar. Both return an array of resources, and the filter argument can be used to restrict the returned resources (or versions). The filter is an object whose keys and values must match the returned resources (or versions). Think of it as a template or partial resource that all resources must match. For example, a filter of {type:'view'} will return all the views.

For mojit-level resources or resource versions, specify the mojit name in the filter. For example, filter {mojit:'Foo'} will return all resources (or versions) in the Foo mojit.

To get mojit-level resources (or versions) from multiple mojits, you’ll have to call the method getResourceVersions or getResources for each mojit. You can call listAllMojits to get a list of all mojits.

Intro¶

In this section, we will discuss the key methods, events, and give a simple example of a custom Resource Store addon. By using the provided example as a model and referring to the ResourceStore.server Class in the API documentation, you should be able to create your own custom Resource Store addons.

Anatomy of a Resource Store Addon¶

The resource store addons are implemented using the YUI Plugin mechanism. In essence, a Mojito addon is a YUI plugin, so the skeleton of a Resource Store addon will be the same as that of a YUI Plugin.

See the ResourceStore.server Class for the parameters and return values for the Resource Store methods.

Example¶

YUI.add('addon-rs-text', function(Y, NAME) {

  var libpath = require('path');

  function RSddonText() {
    RSAddonText.superclass.constructor.apply(this, arguments);
  },
  RSAddonText.NS = 'text';
  RSAddonText.ATTResourceStore = {};

  Y.extend(RSAddonText, Y.Plugin.Base, {

    initializer: function(config) {
      this.appRoot = config.appRoot;
      this.mojitoRoot = config.mojitoRoot;
      this.afterHostMethod('findResourceVersionByConvention', this.findResourceVersionByConvention, this);
      this.beforeHostMethod('parseResourceVersion', this.parseResourceVersion, this);
    },

    destructor: function() {
      // TODO:  needed to break cycle so we don't leak memory?
    },

    /**
    * Using AOP, this is called after the ResourceStore's version.
    * @method findResourceVersionByConvention
    * @param source {object} metadata about where the resource is located
    * @param mojitType {string} name of mojit to which the resource likely belongs
    * @return {object||null} for config file resources, returns metadata signifying that
    */
    findResourceVersionByConvention: function(source, mojitType) {
      // We only care about files
      if (!source.fs.isFile) {
        return;
      }

      // We only care about txt files
      if ('.txt' !== source.fs.ext) {
        return;
      }

      return new Y.Do.AlterReturn(null, {
        type: 'text'
      });
    },

    /**
    * Using AOP, this is called before the ResourceStore's version.
    * @method parseResourceVersion
    * @param source {object} metadata about where the resource is located
    * @param type {string} type of the resource
    * @param subtype {string} subtype of the resource
    * @param mojitType {string} name of mojit to which the resource likely belongs
    * @return {object||null} for config file resources, returns the resource metadata
    */
    parseResourceVersion: function(source, type, subtype, mojitType) {
      var res;

      if ('text' !== type) {
        return;
      }
      res = {
        source: source,
        type: 'text',
        affinity: 'server',
        selector: '*'
      };
      if ('app' !== source.fs.rootType) {
        res.mojit = mojitType;
      }
      res.name = libpath.join(source.fs.subDir, source.fs.basename);
      res.id = [res.type, res.subtype, res.name].join('-');
      return new Y.Do.Halt(null, res);
    }
  });
  Y.namespace('mojito.addons.rs');
  Y.mojito.addons.rs.text = ResourceStoreAddonText;

}, '0.0.1', { requires: ['plugin', 'oop']});

YUI.add('addon-ac-text', function(Y, NAME) {

  var libfs = require('fs');

  function Addon(command, adapter, ac) {
    this._ctx = ac.command.context;
  }
  Addon.prototype = {

    namespace: 'text',

    setStore: function(store) {
      this._store = store;
    },
    list: function() {
      var r, res, ress, list = [];
      ress = this._store.store.getResources('server', this._ctx, {type:'text'});
      for (r = 0; r < ress.length; r += 1) {
        res = ress[r];
        list.push(res.name);
      }
      return list;
    },
    read: function(name, cb) {
      var ress;
      ress = this._store.store.getResources('server', this._ctx, {type:'text', name:name});
      if (!ress || 1 !== ress.length) {
        cb(new Error('Unknown text file ' + name));
      }
      libfs.readFile(ress[0].source.fs.fullPath, 'utf-8', function(err, body) {
        cb(err, body);
      });
    }
  };
  Y.mojito.addons.ac.text = Addon;
  }, '0.1.0', {requires: ['mojito']}
);

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

  Y.namespace('mojito.controllers')[NAME] = {

    index: function(ac) {
      var chosen; // TODO:  use form input to choose a text file
      if (!chosen) {
        var list;
        list = ac.text.list();
        chosen = list[0];
      }
      ac.assets.addCss('./index.css');
      ac.text.read(chosen, function(err, body) {
        if (err) {
          return ac.error(err);
        }
        ac.done({body: body});
      });
    }
  };
}, '1.0.1', {requires: ['mojito', 'mojito-assets-addon', 'addon-ac-text']});

Intro¶

Mojito comes with built-in resource store addons that are used by the Resource Store and the Mojito framework. These resource store addons are required by the Resource Store and the Mojito framework. Thus, particular care must be taken when creating custom versions of them.

The Resource Store comes with the following four built-in addons:

• config

  • registers new resource type config found in JSON configuration files
  • provides an API for reading both contextualized and straight-JSON files
  • provides sugar for reading an application’s dimensions

• selector

  • decides the priority-ordered list (POSL) to use for a context
  • looks for selector in application.json. Because application.json is a context configuration file, the selector can be contextualized there.

• url

  • calculates the static handler URL for appropriate resources (and resource versions)
  • stores the URL in the url key of the resource
  • calculates the asset URL base for each mojit

• yui

  • registers new resource type yui-module found in the directories yui_modules or autoload
  • registers new resource type yui-lang found in the lang directory
  • calculates the yui metadata for resource versions that are YUI modules
  • pre-calculates corresponding YUI module dependencies when resources are resolved for each version of each mojit
  • appends the pre-calculated YUI module dependencies for the controller and binders when Mojito queries the Resource Store for the details of a mojit (getMojitTypeDetails method)
  • provides methods used by Mojito to configure its YUI instances

Creating Custom Versions of Built-In Resource Store Addons¶

We will be examining the selector and url addons to help you create custom versions of those addons. We do not recommend that you create custom versions of the config or yui addons, so we will not be looking at those addons. Also, this documentation explains what the Resource Store expects the addon to do, so you can create your own version of the addons. To learn what the Resource Store built-in addons do, please refer to the ResourceStore.server Class in the API documentation.