Prepare for the Pipeline feature

If planning to use SASS or CoffeeScript, you should run the diagnose command to see whether your environment is fit for the feature. Otherwise, skip to the next section.

# Diagnose and follow the instructions to get your environment prepared
$ train diagnose
# If you experience `command not found` error, you should add $GOPATH/bin to $PATH# or run the command as follow:
$ $GOPATH/bin/train

Quick Example

$ cd$GOPATH/src/github.com/shaoshing/train
$ go run example/main.go
# Visit localhost:8000 and play with the `include` directive and the SASS and CoffeeScript Pipeline.

In the example page, you can toggle the Include Directive feature, or try out the Pipeline feature by requesting a sass or coffee file.

Use it in your project

First, allow train to handle assets requests by adding handler to the http.ServeMux:

Include Directive

Train allows you specify dependency inside asset file by using the include directive, and when you include the file using Train's helper, Train will check the dependency and expand the file into related files.

SASS and CoffeeScript

The Include Directive is only available for js and css. However, SASS already has the @import directive, which is doing the same thing. For CoffeeScript, you will have to manage the dependencies in a regular way.

Pipeline

When handling js or css request, Train will first look for the asset file with the same extension in the assets folder. If the file cannot be found, it will keep searching for a alternative extension, which is .sass/.scss for .css and .coffee for .js . When found, Train will convert the file into the desired extension.

Take a look at an simple example:

├── assets
│ ├── stylesheets
│ │ ├── app.sass

In the html, you include the sass file as if it is a css file:

{{stylesheet_tag "app"}}

Configuration

There are several configuration options related to the Pipeline feature:

// From SASS's doc:// When set to true, causes the line number and file where a selector is defined to be// emitted into the compiled CSS in a format that can be understood by the browser. Useful in// conjunction with [the FireSass Firebug extension](https://addons.mozilla.org/en-US/firefox/addon/103988)// for displaying the Sass filename and line number.
train.Config.SASS.DebugInfo = true// false by default// From SASS's doc:// When set to true, causes the line number and file where a selector is defined to be emitted// into the compiled CSS as a comment. Useful for debugging, especially when using imports and mixins.
train.Config.SASS.LineNumbers = true// false by default// Show SASS and CoffeeScript errors.
train.Config.Verbose = true// false by default

Bundling and Fingerprinting Assets

You probably want to merge or convert the assets in production site for performance concern. This is done by running Train's command-line tool train without any option:

When Train detect the public/assets folder, it will disable the Include Directive and Pipeline features and serve from these static files directly. Template helpers will also stop expanding assets and generate with fingerprinted paths:

Why Fingerprinting?

From Rails' Assets Pipeline Document:

Fingerprinting is a technique that makes the name of a file dependent on the contents of the file.
When the file contents change, the filename is also changed. For content that is static or infrequently
changed, this provides an easy way to tell whether two versions of a file are identical, even across
different servers or deployment dates.

Deploy to Production Server

There are two ways to deploy the Bundled and Fingerprinted assets to your server:

Run the train command in the production server after each deployment. By doing this you can make sure to update public/assets to the latest. This is the simples way, but it requires your server have NodeJS and required npm if you are using the Pipeline feature.

Run the train command in your local machine and upload the assets to the production server. With this way, the production server doesn't need to have NodeJS and required npm for the command.