express-yui/lib/yui.js

Express extension for YUI Applications

/*
 * Copyright (c) 2013, Yahoo! Inc.  All rights reserved.
 * Copyrights licensed under the New BSD License.
 * See the accompanying LICENSE file for terms.
 */

/*jslint node:true, nomen: true */

/**
The `express-yui` middleware provides the foundation and some basic
features to attach information into the `res.locals` object
that could be used to boot `YUI` in the client runtime.

@module express-yui
**/

'use strict';

var express = require('express'),
    appProto = express.application,
    defaultConfiguration = appProto.defaultConfiguration,
    middleware = require('./middleware'),

    // sub-modules
    cdn     = require('./cdn'),
    seed    = require('./seed'),
    origin  = require('./origin'),
    groups  = require('./groups'),
    shifter = require('./shifter'),
    loader  = require('./loader'),
    server  = require('./server'),
    view    = require('./view'),

    // constants
    NODE_ENV   = process.env.NODE_ENV || 'development',

    // utilities
    utils = require('./utils'),
    debug = require('debug')('express:yui');

/**
The `express-yui` extension provides the foundation and some basic
features to attach information into the `res.locals` object
that could be used to boot `YUI` in the client runtime.

When the `"seed"` sub-module is used, it will automatically
mix itself into `app.yui.expose()`, and it exposes a local variable
in a form of an array of object with the information to
build the script tag or tags that forms the seed:

The following is an example of how these features can be used:

    // Creates a new express app.
    var app = express();

    // Set some basic configs
    app.yui.applyConfig({
        fetchCSS: false
    });

    // Use helpers to do advanced configurations
    app.yui.debugMode());

    // Call expose middleware when a route match.
    app.get('/index.html', app.yui.expose(), anotherRoute);

In the example above, the few things will be exposed
thru `res.locals.*`, which means you can use it in your
templates by doing something like this:

    <script>
    YUI({{{yui_config}}}).use('node', function (Y) {
        Y.one('#content').setContent('<p>Ready!</p>');
    });
    </script>

In this particular case, `yui_config` will hold all the
appropiated settings generated by `yui` middleware and
its extensions.

@class yui
@static
@constructor
@uses *express, *express-expose, utils, cdn, seed, origin, groups, shifter, loader, server, view
*/
function ExpressYUIExtension(app) {
    var YUI;

    this._app = app;
    this._config = {};

    try {
        YUI = require('yui' + (NODE_ENV === 'development' ? '/debug' : ''));
    } catch (e) {
        throw new Error('Error trying to require("yui"). ' +
            '`express`, `express-yui` and `yui` are peerDependencies.');
    }

    this.YUI  = YUI.YUI;
    this.version = YUI.YUI.version;
    this.path = YUI.path();
    debug('Using yui@' + this.version + ' from [' + this.path + '] in ' + NODE_ENV + ' mode.');

    // for better readibility, we expose the version
    this._config = {
        version: this.version
    };
}

ExpressYUIExtension.prototype = {

    /**
    Turns on debug mode for YUI Loader by setting
    `debug=true`, `logLevel="debug"` and `filter="debug"`
    into the static configuration. More available settings
    [in the YUI API Docs](http://yuilibrary.com/yui/docs/api/classes/config.html).

        app.yui.debug({});

    @method debugMode
    @public
    @param {Object} config optional object to overrule
    specific settings when in debug mode.

        @param {boolean} config.debug default to `true`
        @param {string}  config.logLevel default to `"debug"`
        @param {string}  config.filter default to `"debug"`

    @chainable
    **/
    debugMode: function (config) {

        // storing static config
        this.config({
            debug: true,
            filter: 'debug',
            logLevel: 'debug',
            useBrowserConsole: true
        }, config);

        return this;
    },

    /**
    Extends the static configuration with the supplier
    object(s). You can use it like this:

        // Disable CSS computations
        app.yui.applyConfig({
            fetchCSS: false
        });

    @method applyConfig
    @public
    @param {Object*} supplier objects to be mixed with the
    static configuration. All available settings
    [from the YUI API Docs](http://yuilibrary.com/yui/docs/api/classes/config.html).
    can be used here.
    @chainable
    **/
    applyConfig: function () {
        this.config.apply(this, Array.prototype.slice.call(arguments));
        return this;
    },

    /**
    Extends the static configuration with the supplier object(s)
    or returns the current static configuration reference. This
    configuration is static, and attached to the server object.
    Once you call `yui.expose()` middleware for the first time,
    this configuration becomes inmutable.

    @method config
    @protected
    @param {Object*} supplier Optional supplier objects
    that, if passed, will be mix with the static configuration.
    @return {object} static configuration
    **/
    config: function () {

        var args = Array.prototype.slice.call(arguments);

        // Mix in current `arguments` into `this._config`
        if (args.length) {
            args.unshift(this._config);
            utils.extend.apply(utils, args);
        }

        return this._config;
    }

};

utils.extend(ExpressYUIExtension.prototype, cdn, seed, origin, groups, shifter, loader, server, view);

module.exports = utils.extend(ExpressYUIExtension, middleware); // exposing middleware as members of the constructor

// replacing the original `defaultConfiguration` method with the wrapper to include
// the creating of app.yui as part of the init in express
appProto.defaultConfiguration = function () {
    defaultConfiguration.apply(this, arguments);
    if (!this.yui) {
        this.yui = new ExpressYUIExtension(this);
    } else {
        debug('skipping the creation of `app.yui` because it was already defined.');
    }
};