GitHub - slimGap/asset_manager: [Plugin] JS and CSS Assets Manager for Rails

slimGap / asset_manager Public

forked from sbecker/asset_packager

Notifications You must be signed in to change notification settings
Fork 2
Star 1

[Plugin] JS and CSS Assets Manager for Rails

Group & Include assets from three scopes: Application, Controller, and View

1 star 102 forks Branches Tags Activity

Star

Notifications

Branches Tags

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
lib		lib
test		test
.gitignore		.gitignore
CHANGELOG		CHANGELOG
README		README
Rakefile		Rakefile
about.yml		about.yml
init.rb		init.rb
install.rb		install.rb
uninstall.rb		uninstall.rb

Repository files navigation

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}
\\