datapimp / emcee

Package web components in Rails applications using the asset pipeline

Emcee

Emcee is an extension to the Rails Asset Pipeline. It allows you to import and package web components exactly as you would Javascript or CSS.

Table of contents

• Installation
• Usage
• Compilation
• Bower
• Concatenation
• Testing
• Contributing
• Special thanks

Installation

Add Emcee to your Gemfile:

gem 'emcee'

and then execute:

$ bundle install

Finally, run:

$ rails generate emcee:install

This will insert <%= html_import_tag "application" %> into your application layout. Also, it will create 'components' directories under '/assets' and '/vendor/assets'.

Usage

Once installed, you will have a manifest file located at /assets/components/application.html. Use sprockets directives to include web components located in one of the assets directories.

When referencing web components, you must point to an html file, not a directory. For example, if you have a sub-directory like this:

vendor
|- assets
  |- components
    |- ui-tabs
       |- ui-tabs.html

You must reference this in the manifest file as:

*= require ui-tabs/ui-tabs

Compilation

Emcee works great with compiling assets, such as CoffeeScript and Sass. Any external stylesheet or script tag references that have an extension that Sprockets recognizes will automatically be compiled.

For example, <link rel="stylesheet" href="test.css.scss"> and <script src="test.js.coffee"> will be respectively compiled to CSS and Javascript.

Bower

When installed, Emcee configures Bower to install components to vendor/assets/components. Anything installed with bower can be referenced directly in your application.js, application.css, or application.html manifest files.

Concatenation

In a development environment, all web components referenced in the manifest will be included in the application as seperate html imports. Importing web components a.html, b.html, and c.html will result in:

<link rel="import" href="a.html">
<link rel="import" href="b.html">
<link rel="import" href="c.html">

In production, they will be concatenated into one import, and will have comments and blank lines removed.

<link rel="import" href="application-908e25f4bf641868d8683022a5b62f54.html">

Notice the fingerprint hash appended to the file name. This depends on the contents of the included web components, and allows proper caching and cache-busting.

Testing

To run the tests, simply run rake test.

Contributing

1. Fork it
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

Special Thanks

Special thanks to the Polymer Project, which Emcee was designed to work with. They've designed an amazing piece of technology that will change how web apps are made.