express-yui v1.4.1
Express YUI
Express extension for YUI applications.
Goals & Design
This component extends Express by adding a new app.yui
member to the Express
application. It is responsible for controlling and exposing both the YUI
configuration and the application state on the client side as well as
controlling the YUI instance on the server.
Installation
Install using npm:
$ npm install express-yui
Features
- Control YUI config and seed modules per request.
- Provide basic configurations for CDN, debugging, and other common conditions in YUI.
- Provide middleware to serve
static
assets from origin server. - Provide middleware to
expose
the appstate
object with the YUI config and seed URLs.
Usage
Extending Express functionality
express-yui
is a conventional express
extension, which means it will extend
functionality provided in express
by augmenting the Express app instance
with a new member called yui
. At the same time, express-yui
provides a set of
static methods that you can call directly off the express-yui
module. These
methods include utility methods and Express middleware.
Here is an example of how to extend an express
app with express-yui
:
var express = require('express'),
expyui = require('express-yui'),
app = express();
// extending the `express` app instance using extension pattern decribed here:
// https://gist.github.com/ericf/6133744
expyui.extend(app);
// using the new `yui` member off the app instance
app.yui.applyConfig({ fetchCSS: false });
As you can see in the example above, the yui
member is available off the app
instance after extending the express
app.
Exposing app state into client
To expose the state of the app (which includes the computed YUI configuration
based on the configuration defined through the Express app instance), you can
call the expose
middleware for any route:
var express = require('express'),
expyui = require('express-yui'),
app = express();
expyui.extend(app);
app.get('/foo', expyui.expose(), function (req, res, next) {
res.render('foo');
});
By doing expyui.expose()
, express-yui
will provision a property called state
that
can be used in your templates as a javascript blob that sets up the page to run
YUI with some very specific settings coming from the server. If you use handlebars
you will do this:
<script>{{{state}}}</script>
<script>
app.yui.ready(function () {
// you can use YUI now
});
</script>
And this is really the only thing you need to do in your templates to get YUI ready to roll!
Note: In order to be efficient by default, once the first request comes in
the expose()
middleware will cache the state of the YUI config for the app.
This means if it needs to be mutated on a per-request basies, it must be re-exposed.
Using the locator plugin to build the app
express-yui
provides many features, but the real power of this package can be seen when
using it in conjunction with the locator component and the locator-yui plugin.
var express = require('express'),
expyui = require('express-yui'),
LocatorClass = require('locator'),
LocatorYUI = require('locator-yui'),
app = express(),
loc = new LocatorClass({
buildDirectory: __dirname + '/build'
});
// mounting `locator` instance
app.set('locator', loc);
// extending app with `express-yui`
expyui.extend(app);
// serving static yui modules built by locator
app.use(expyui.static(__dirname + '/build'));
app.get('/foo', expyui.expose(), function (req, res, next) {
res.render('foo');
});
// adding plugins to locator to support different type of files
loc.plug(new LocatorYUI());
// triggering locator filesystem abstraction
loc.parseBundle(__dirname, {});
app.yui.ready(function (err) {
if (err) {
throw err;
}
// if everything was ready, we can start listening for traffic
app.listen(8080);
});
As a result, any YUI module under the __dirname
folder or any npm dependency marked as
a locator bundle will be built by the locator-yui
plugin, and become automatically
available on the client, and potentially on the server as well. This means you
no longer need to manually define loader metadata or any kind of YUI config to load those
modules, and express-yui
will be capable to handle almost everthing for you.
Using YUI modules on the server side
Using modules on the server is exactly the same that using them on the client through
app.yui.use()
statement. Here is an example of the use of YQL module to load the
weather forecast and passing the result into the template:
app.get('/forecast', expyui.expose(), function (req, res, next) {
req.app.yui.use('yql', function (Y) {
Y.YQL('select * from weather.forecast where location=90210', function(r) {
// r contains the result of the YQL Query
res.render('forecast', {
result: r
});
});
});
});
note: remember that req.app
holds a reference to the app
object for convenience.
Using Locator plugins
If you use locator
and express-view
components in conjuction with some
other locator plugins like locator-handlebars
and locator-yui
to
precompile templates, and shift yui modules, then when calling
res.render('foo')
and express-view
will resolve foo
automatically based
on the precompiled version. Check this example to see this in action:
Serving static assets from app origin
Ideally, you will use a CDN to serve all static assets for your application, but your Express app is perfectly capable of doing so, and even serving as the origin server for your CDN.
app.yui.setCoreFromAppOrigin();
app.use(expyui.static(__dirname + '/build'));
With this configuration, a group called foo
with version 1.2.3
, and yui
version 3.11.0
, it will produce URLs like these:
- /yui-3.11.0/yui-base/yui-base-min.js
- /foo-1.2.3/bar/bar-min.js
Any of those URLs will be valid because express-yui
static method produces an Express app
that can be mounted under your Express application to serve YUI core modules and application
specific modules (modules compiled by locator into the build
folder).
Serving static assets from CDN
If you plan to serve the locator-generated build
folder from your CDN, then make
sure you set the proper configuration for all groups so loader can know about them.
Here is the example:
app.set('yui default base', 'http://mycdn.com/path/to/build/');
app.set('yui combo config', {
comboBase: 'http://mycdn.com/path/to/combo?',
comboSep: '&',
maxURLLength: 1024
});
app.set('yui default root', 'build/');
In this case you don't need to use expyui.static()
middleware since you are not
serving local files, unless the app should work as origin server.
With this configuration, a group called foo
with version 1.2.3
will produce urls like these:
- http://mycdn.com/path/to/combo?build/foo-1.2.3/bar/bar-min.js&build/foo-1.2.3/baz/baz-min.js
- http://mycdn.com/path/to/build/foo-1.2.3/bar/bar-min.js
API Docs
You can find the API Docs under apidocs
folder, and you can browse it through this URL:
License
This software is free to use under the Yahoo! Inc. BSD license. See the LICENSE file for license text and copyright information.
Contribute
See the CONTRIBUTING file for info.
10 years ago
10 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago