Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
[Plugin] JS and CSS Assets Manager for Rails

Ruby
branch: master

This branch is 5 commits ahead of sbecker:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
test
.gitignore
CHANGELOG
README
Rakefile
about.yml
init.rb
install.rb
uninstall.rb

README

h1. Manage JS & CSS with asset_manager

{info:title=Proposal}
This is a plugin for managing JavaScript and CSS in rails.  The idea is that we want to have css and javascript file in a directory structure and naming convention that will automatically include the correct files for a given controller if it exists.  We also want the ability to combine CSS or JavaScript files that are used together into a module and include them together by referencing the module name in a view.

This plugin allows you to declare assets at three scopes and group assets into modules:
* *[*Application Wide*| #scope_application]* (Defined in app/views/layouts/*)
* *[*Controller Wide*| #scope_controller]* (Loaded automatically by naming convention)
* *[*View Specific*| #scope_page]* (Defined in individual view templates)

* *[*Group Assets*| #group_assets]* (Group assets into _modules_ in a single config file)

In addition to these management features we want the capability to minify them and combine the files of each module into single files.
{info}

h3. Asset Directory Structure

The same directory structure would be used for JavaScript and CSS.  The files that are at the base level of public/stylesheets/views/ will be included automatically if they exist.  Other files within that directory will be included explicitly in the sections that need them by the web developer.

See the example below.
{code}
public/stylesheets/
                   common/
                          application.css
                          reset.css
                          ie6.css
                          ...
                   vendor/
                          facebook.css                  # must be required where it's needed
                          wysiwyg/
                                  jquery.wysiwyg.css    # must be required where it's needed
                                  jquery.wysisyg.gif
                          ...
                   views/
                         about.css                      # automatic  (domain.com/about/*)
                         about_forms.css                # must be required where it's needed
                         admin/
                               goals.css                # automatic  (domain.com/admin/goals/*)
                         business.css                   # automatic  (domain.com/business/*)
                         ...
{code}
{anchor:group_assets}

h3. Group Assets Into Modules

js/css files that are commonly used together can be grouped into _modules_ through a single configuration file.  A module can be called from any view, but most often from the main layout/application.html.erb file to be included universally. Consider the following example:
{note:title=Files within a module are returned in the order they are listed.}
{note}

h6. config/asset_manager.yml

{code}
---
javascripts:
- base:
  - vendor/jquery
  - common/application
- ui:
  - vendor/effects
  - vendor/dragdrop
  - vendor/controls
- lightbox:
  - common/ie_patch
  - vendor/lightbox

stylesheets:
- base:
  - common/reset
  - common/global
  - common/application
- ie_support:
  - common/ie6
  - common/ie7
- facebook:
  - common/fb_global
  - vendor/fb_box
- lightbox:
  - vendor/lightbox
{code}
{tip:title=Call modules using a :symbol and individual files using 'path/to/file'}
* Include application-wide assets using *stylesheet_manager_base* & *javascript_manager_base*
* Include page specific assets using *stylesheet_manager* & *javascript_manager*
{tip}

h6. app/view/layout/application.html.erb

{code}
<html>
  <head>
    <%= stylesheet_manager_base :base, :ie_support  %>
    ...
  </head>
  <body>
    ...
    <%= javascript_manager_base :base, :ui %>
  </body>
</html>
{code}

h6. app/view/goals/index.html.erb

{code}
<% javascript_manager :lightbox, 'view/goals/something_fancy_and_big' -%>
<% stylesheet_manager :lightbox, 'view/goals/something_fancy_and_big' -%>
{code}
\\
\\

----
h2. +Setup+


h4. Install Plugin


h6. Download the Plugin

{code}
./script/plugin install http://svn.sf.akqa.com/Akqa.LaMancha/trunk/rails/plugins/asset_manager
{code}
This technique uses a modified version of [http://github.com/sbecker/asset_packager].
\\
\\

h4. Add Content Hooks to Layouts

The plugin collects call for js/css files from anywhere within a view and neatly loads them here:

h6. app/views/layouts/application.html.erb

{code:none}
<html>
  <head>
    <%= stylesheet_manager_base :base, :ie_support  %>
    ...
  </head>
  <body>
    ...
    <%= javascript_manager_base :base, :ui %>
  </body>
</html>
{code}
Add these lines to the beginning and end of your layout.
\\

h2. +Usage+

{anchor:scope_application}

h4. Application: Always Include Assets

Include application wide assets on every page by adding the following calls to the application layout:
_(before yield :page_etc)_
* stylesheet_link_merged
* javascript_include_merged

h6. app/views/layouts/application.html.erb

{code:none}
<head>
  <%= stylesheet_manager_base :base, "application" %>
  ...
  <%= javascript_manager_base :base %>
<body/>
{code}
{note:title=Be sure to use <%= ... %> }
{note}
\\

{anchor:scope_controller}

h4. Controller: Automatically Load Matching Assets

Similar to Rails' template convention, the plugin automatically loads js/css files that match the controllers name. If no file exist, no file is loaded.
{code:none}
app/views/blog/*

Automatically loads:
 - public/javascripts/views/blog.js
 - public/stylesheets/views/blog.css
{code}
\\

{anchor:scope_page}

h4. Page: Declare Page Specific Assets

Include assets from within any view-template using the 'stylesheets' & and 'javascript' helpers.

h6. app/views/\*

{code:none}
<% stylesheet_manager 'random-y', 'lightbox/random-z'  %>
<% javascript_manager 'random-z' %>
{code}
{note:title=Be sure to use <% ... %> }
{note}
\\

h6. Passes the following to to the application layout:

{code:none}
<link href="/stylesheets/random-y.css"                                    media="screen" rel="stylesheet" type="text/css" />
<link href="/stylesheets/lightbox/random-z.css?1271967808"                media="screen" rel="stylesheet" type="text/css" />
{code}
{code:none}
<script src="/javascripts/random-z.js?1271912562"                         type="text/javascript"></script>
{code}
\\

h4. File Order

Assets are loaded in the following order:
* *[*Application Wide*| #scope_application]* (Defined in app/views/layouts/*)
* *[*Controller Wide*| #scope_controller]* (Loaded automatically by naming convention)
* *[*View Specific*| #scope_page]* (Defined in individual view templates)

Files _within_ a module are returned in the order they are listed.  Modules can be mixed-in with individual files.

h6. config/asset_manager.yml

{code:none}
---
javascripts:
- base:
  - prototype
  - application
- ui:
  - effects
  - dragdrop
  - controls
stylesheets:
- base:
  - reset
  - common
  - scaffold
{code}
In a given call, assets are loaded in the order they are specified.
{code:none}
<% javascript_manager 'must_be_first', :base, :ui, 'next_to_last', 'last' %>
{code}
 *returns:*
{code:none}
<script src="/javascripts/must_be_first.js?1271913222"                type="text/javascript"></script>
<script src="/javascripts/prototype.js?1271912562"                    type="text/javascript"></script>
<script src="/javascripts/effects.js?1271912562"                      type="text/javascript"></script>
<script src="/javascripts/dragdrop.js?1271912562"                     type="text/javascript"></script>
<script src="/javascripts/controls.js?1271912562"                     type="text/javascript"></script>
<script src="/javascripts/application.js?1271912562"                  type="text/javascript"></script>
<script src="/javascripts/next_to_last.js?1271912562"                 type="text/javascript"></script>
<script src="/javascripts/last.js?1271912562"                         type="text/javascript"></script>
{code}
\\
\\

----
h2. +Implementation+

1) Install the plugin
2) Add manager_base calls to application layouts.
3) Correct the load order of the files in config/asset_manager.yml

h6. app/views/layouts/application.html/erb

{code}
<html>
  <head>
    <%= stylesheet_manager_base %>
    ...
  </head>
  <body>
    ...
    <%= javascript_manager_base %>
  </body>
</html>
{code}
{note:title=Be sure to use <%= ... %> }
{note}
\\

h4. Rake Tasks

{code:none}
rake asset:manager:build_all        # Merge and compress assets
rake asset:manager:create_yml       # Generate asset_manager.yml from existing assets
rake asset:manager:delete_all       # Delete all asset builds
{code}
\\
Something went wrong with that request. Please try again.