asset_pipeline.md

##What asset pipeline is

The asset pipeline provides a framework to concatenate and minify or compress JavaScript and CSS assets. It also adds the ability to write these assets in other languages and pre-processors such as CoffeeScript, Sass and ERB. It allows assets in your application to be automatically combined with assets from other gems.

The asset pipeline is implemented by the sprockets-rails gem, and is enabled by default. Sprockets concatenates all JavaScript files into one master .js file and all CSS files into one master .css file.
You can disable it while creating a new application by passing the --skip-sprockets option.

##Features

• assets concatenations, which can reduce the number of requests
• asset minification or compression
• coding assets via a higher-level language, with precompilation down to the actual assets.
• Supported languages include Sass for CSS, CoffeeScript for JavaScript, and ERB for both by default

##Controller Specific Assets You generate a ProjectsController >> app/assets/javascripts/projects.coffee and app/assets/stylesheets/projects.scss By default these files will be ready to use by your application immediately using the require_tree directive.

You can also opt to include controller specific stylesheets and JavaScript files only in their respective controllers using the following:

<%= javascript_include_tag params[:controller] %> or <%= stylesheet_link_tag
params[:controller] %>

##Asset Organization

• app/assets is for assets that are owned by the application, such as custom images, JavaScript files or stylesheets.

  plugins folder has nothing to do here.

• lib/assets is for your own libraries' code that doesn't really fit into the scope of the application or those libraries which are shared across applications.

• vendor/assets is for assets that are owned by outside entities, such as code for JavaScript plugins and CSS frameworks. Keep in mind that third party code with references to other files also processed by the asset Pipeline (images, stylesheets, etc.), will need to be rewritten to use helpers like asset_path.

###Using Index Files Sprockets uses files named index (with the relevant extensions) for a special purpose.

For a jQuery library with many modules, stored in lib/assets/javascripts/library_name, the file lib/assets/javascripts/library_name/index.js serves as the manifest for all files in this library. This file could include a list of all the required files in order, or a simple require_tree directive.

The library as a whole can be accessed in the application manifest like so:

`//= require library_name``

###CSS and ERB If you add an erb extension to a CSS asset (for example, application.css.erb), then helpers like asset_path are available in your CSS rules:

`.class { background-image: url(<%= asset_path 'image.png' %>) }``

###CSS and Sass When using the asset pipeline, paths to assets must be re-written and sass-rails provides -url and -path helpers (hyphenated in Sass, underscored in Ruby) for the following asset classes: image, font, video, audio, JavaScript and stylesheet.

image-url("rails.png") returns url(/assets/rails.png)
image-path("rails.png") returns "/assets/rails.png"
The more generic form can also be used:

asset-url("rails.png") returns url(/assets/rails.png)
asset-path("rails.png") returns "/assets/rails.png"

##Manifest Files and Directives The require_tree directive tells Sprockets to recursively include all JavaScript files in the specified directory into the output. These paths must be specified relative to the manifest file. require_directory directive includes all JavaScript files only in the directory specified, without recursion.

Directives are processed top to bottom, but the order in which files are included by require_tree is unspecified. You should not rely on any particular order among those. If you need to ensure some particular JavaScript ends up above some other in the concatenated file, require the prerequisite file first in the manifest.

require_self puts the CSS contained within the file (if any) at the precise location of the require_self call.

If you want to use multiple Sass files, you should generally use the Sass @import rule instead of these Sprockets directives. When using Sprockets directives, Sass files exist within their own scope, making variables or mixins only available within the document they were defined in.

@import "*" and @import "**/*" = require_tree