Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
executable file 288 lines (234 sloc) 8.38 KB
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}
\\
Jump to Line
Something went wrong with that request. Please try again.