Example¶

// Controller logic
var device = ac.context.device,
    path = '/static/device/assets/simple';

if (device === 'iphone') {
    path += '.' + device;
}

path += '.css';
ac.assets.addCss(path, 'top');

Shaker takes care of all this logic through the assets naming convention. In addition, Shaker gives the user the ability to validate, transform, and combine (roll up) resources and deploy to CDNs. All this is done through a simple configuration, which the user can customize to maximize the performance of their application.

Assets Organization and Contextualization¶

Shaker automatically adds mojit and application level assets and picks the right versions based on the context. See Organizing Resources.

Transformation/Validation Tasks¶

Users can specify what kinds of transformation or validation tasks should be applied to each resource. They can define their own custom tasks or use the default tasks including JS/CSS linting and minification. See Tasks Configuration.

Rollups¶

A rollup consists of many resources and their dependencies that are combined (or rolled up) to produce one or more files. Since the number of files is reduced, rollups can drastically reduce the number of HTTP request and allows browsers to cache the most common resources. See Route Rollups Configuration.

CDN Locations¶

Rollups and transformed resources can be uploaded to one or more CDN locations. This allows resources to be served from fast servers designed to quickly deliver resources to clients. See Locations Configuration.

Settings and Runtime API¶

The user has absolute control in deciding where on the page particular resources should appear, whether they should be combo-loaded, and which CDN location should be used. During runtime, the Shaker API can be used on the server side to change any of these settings and data on the page such as the title and html class. See Settings and Runtime API.

Resources¶

The “resources” option specify which type of resources to process. If a property is set to false, then that type of resource is ignored by the Shaker compilation and is handled in Mojito’s default manner.

Tasks¶

The “tasks” option specifies the list of tasks that should be applied to each type of resource. This option is a map where each key is a resource type and the value is a map of task modules that will be applied to each resource that matches the type. The keys of this map is the name of the task module and each value is a configuration object (a false value disables the task, a true value is the equivalent of an empty configuration object).

Example¶

"tasks": {
    "js": {
        "jslint": true,
        "jsminify": {
            "squeeze": true,
            "mangle": true
        }
    },
    "css": {
        "csslint": true,
        "cssminify": {
            "yuicompress": true
        }
    }
}

If more than one resource type specified matches a particular resource, then the most specific type is used. The most specific type is determined through the type hierarchy shown below. Any of the resource type below is valid.

Note

Since both rollup and loader type resources are generated during compilation, they each respectively have default rollup and loader tasks predefined. Rollups have a empty list of tasks and loaders are only js-minified. To overwrite this behavior, explicitly specify custom rollup and loader tasks.

Route Rollups¶

The “routeRollups” option specifies a rollup module that is used to combine resources after tasks have been applied. Each output rollup is associated with an application route (Shaker loads the rollup for pages matching this route). Only one rollup module can be specified. Rollups are useful for reducing HTTP requests by combining the most common assets for a particular route. Rollups can take advantage of browser caching such that subsequent page requests load rapidly since the most common resources are cached.

"routeRollups": {
    "module": "mojitrollup",
    "rollups": {
        "<route1>": [
            "<Mojit1>",
            "<Mojit2.action1>",
            "<Mojit2.action2>"
        ],
        "<route2>": [
            "<Mojit1.action3>"
        ]
    }
}

Locations¶

The “locations” option lists the different locations that will be used to store the processed resources and rollups. To set the location that is used during runtime set the “serveLocation” under “settings” (see Settings). The “locations” option is a map, where each key is a location module and the value is a configuration object (a false value disables the location, a true value is the equivalent of an empty configuration object).

"locations": {
    "local": true,
    "<custom_module>": {
        <custom_module_config>
    }
}

Error Handling¶

By default each task or location is considered non-critical, which means that if a particular task or location fails, there will be a warning but compilation will continue. However there might be tasks or locations that are critical and compilation would not make sense if they fail. To make sure compilation stops due to an error, specify the option ‘errorStop’ as true under the task’s or location’s configuration. ‘errorStop’ can also be an integer value, specifying how many errors can occur before compilation is forced to stop.

Settings¶

The “settings” object is only used during runtime and allows the user to customize how assets should be deployed, without the need of re-compiling.

Runtime API¶

Shaker provides a runtine API to modify the behavior of Shaker per request. To use the Shaker API include “mojito-shaker-addon”. To use the shakerInline API include “shaker-inline-addon”.

Contextualization¶

Resources such as controllers, views, assets, and binders can be contextualize by appending the selector of a dimension to a resource’s filename. For example: a mojit may have two assets, styles.css and styles.iphone.css. styles.css is served for all contexts that do not contain the iphone dimension, while styles.iphone.css only appears in contexts that include the ‘iphone’ dimension. The dimension must be defined in dimensions.json (see Creating Custom Contexts). The selector must be defined in application.json (see Selector Property).

Action Specific Resources¶

In order to associate a resource with a particular mojit action, the asset’s name should match the mojit action. For example the assets home.css and home-base.js would only appear in the ‘home’ action. Resources that do not match the name of any action within the mojit, appear in all actions. This applies to assets, views, and binders.

Ordering Resources¶

Since the order of assets on the page can matter, Shaker always processes resources in alphabetical order. This ensures that assets of any particular type appear on the page in the same order regardless of inlining or the presence of rollups.

Inlining Assets¶

Assets can be inlined by appending ‘-inline’ to the filename. For example, the asset style-inline.css lets Shaker know that it should be inlined. To inline a group of assets, the assets can be moved to a directory called ‘inline’ within ‘assets’, without the need of renaming any asset. See Inlining Assets for more details on inlining.

Voiding Assets¶

Assets can be ignored by appending ‘-void’ to the filename. For example, the asset style-void.css lets Shaker know that it should be ignored. To ignore a group of assets, the assets can be moved to a directory called ‘void’ within ‘assets’, without the need of renaming any asset. This gives the user flexibility on how to handle certain assets manually.

Inlining Using inlineFile¶

A mojit can request to inline a particular application level resource by using the shakerInline.inlineFile API method. This is useful if a particular asset exists in a separate package and a mojit would like the asset to appear inline next to its HTML. The application level asset must have the ‘-inline’ marker in its filename (see Inlining Assets). The mojit that needs the asset must call shakerInline.inlineFile, with the first argument being the file’s basename, without the ‘-inline’ marker. The second argument is optional string specifying the type (‘css’, or ‘js’). The mojit must include the ‘shaker-inline-addon’ to use the method.

Build time¶

1. The shaker command gets executed, invoking Shaker Compiler.
2. Shaker Compiler gets the application configuration and calls Shaker Core.
3. Shaker Core analyzes all the application resources and returns a metadata object with all the information necessary to create the rollups.
4. Shaker Compiler takes the previously generated metadata, generates the minified precomputed rollups, and outputs them as files or to a CDN.
5. Shaker Compiler outputs a new metadata file which will be picked up at runtime to use the correct rollup based on the context.

Runtime¶

1. The Mojito server automatically selects the generated metadata file.
2. When a request arrives, Mojito computes everything normally until it reaches the ShakerHTMLFrame. Then the Shaker Addon gets executed.
3. Shaker Addon checks the current context and the executed mojits and chooses from the metadata the proper rollup to include in the page, overriding the required default Mojito assets.
4. All resources are deployed transparently to the developer.