File: README

# README

Path: | README
Last Update: | Sun Mar 22 08:28:23 -0600 2009

merb-assets

###### =====

Provides extra functionality related to assets:

            # Assets bundling.
            # Assets hosts.
            # Helpers to add asset links to views.
            # Deployment-time assets processing (for instance, with YUI Compressor).

Quick overview of the API

###### ========================

      # asset_path generates path for asset taking type and name.
            # UniqueAssetPath class handles generation of paths using subdomains.
            # AbstractAssetBundler is the base asset bundlers class.

            # auto_link generates conventional asset tags based on controller/action.
            # link_to creates anchor tag (a tag).
            # image_tag creates img tag.

            # escape_js escapes JavaScript.
            # js method translates object into JSON.

            # require_js is smart(-er) way to do includes just once per page no matter
              how many times partial use it.
            # require_css is like require_js but for JavaScript.

            # js_include_tag is used when you need to include script tag with bundling.
            # css_include_tag works like js_include_tag but for stylesheets.
            # include_required_js generates script tags for previously included files.
            # include_required_css generates link tags for previously included files.

            # uniq_js_path generates a script tag for path with asset subdomain.
            # uniq_css_path generates a link tag for path with asset subdomain.

Examples

###### =====

auto_link to include asset tags using convention:

      We want all possible matches in the FileSys up to the action name
         Given:  controller_name = "namespace/controller"
                 action_name     = "action"
      If all files are present should generate link/script tags for:
         namespace.(css|js)
         namespace/controller.(css|js)
         namespace/controller/action.(css|js)

link_to and image_tag to make anchor and image tags:

      image_tag('foo.gif')
      # => <img src='/images/foo.gif' />

      image_tag('foo.gif', :class => 'bar')
      # => <img src='/images/foo.gif' class='bar' />

      image_tag('foo.gif', :path => '/files/')
      # => <img src='/files/foo.gif' />

      image_tag('http://test.com/foo.gif')
      # => <img src="http://test.com/foo.gif">

      image_tag('charts', :path => '/dynamic/')
      or
      image_tag('/dynamic/charts')
      # => <img src="/dynamic/charts">

      link_to("The Merb home page", "http://www.merbivore.com/")
        # => <a href="http://www.merbivore.com/">The Merb home page</a>

      link_to("The Ruby home page", "http://www.ruby-lang.org", {'class' => 'special', 'target' => 'blank'})
        # => <a href="http://www.ruby-lang.org" class="special" target="blank">The Ruby home page</a>

      link_to p.title, "/blog/show/#{p.id}"
        # => <a href="/blog/show/13">The Entry Title</a>

uniq_css_tag and uniq_js_tag for paths with asset subdomains:

      uniq_css_tag("my")
      #=> <link href="http://assets2.my-awesome-domain.com/stylesheets/my.css" type="text/css" />

      uniq_js_tag("my")
      #=> <script type="text/javascript" src="http://assets2.my-awesome-domain.com/javascripts/my.js"></script>

      uniq_js_path("my")
      #=> "http://assets2.my-awesome-domain.com/javascripts/my.js"

      uniq_js_path(["admin/secrets","home/signup"])
      #=> ["http://assets2.my-awesome-domain.com/javascripts/admin/secrets.js",
             "http://assets1.my-awesome-domain.com/javascripts/home/signup.js"]

re_js and require_css, include_required_js and include_requried_css quire assets in parts/partials just once:

     In your application layout:

       js_include_tag :prototype, :lowpro, :bundle => :base

     In your controller layout:

       require_js :bundle => :posts

     The require_js method can be used to require any JavaScript file anywhere
     in your templates. Regardless of how many times a single script is
     included with require_js, Merb will only include it once in the header.

       # File: app/views/layouts/application.html.erb

       <html>
         <head>
           <%= include_required_js %>
           <%= include_required_css %>
         </head>
         <body>
           <%= catch_content :layout %>
         </body>
       </html>

       # File: app/views/whatever/_part1.herb

       <% require_js  'this' -%>
       <% require_css 'that', 'another_one' -%>

       # File: app/views/whatever/_part2.herb

       <% require_js 'this', 'something_else' -%>
       <% require_css 'that' -%>

       # File: app/views/whatever/index.herb

       <%= partial(:part1) %>
       <%= partial(:part2) %>

       # Will generate the following in the final page...
       <html>
         <head>
           <script src="/javascripts/this.js" type="text/javascript"></script>
           <script src="/javascripts/something_else.js" type="text/javascript"></script>
           <link href="/stylesheets/that.css" media="all" rel="Stylesheet" type="text/css"/>
           <link href="/stylesheets/another_one.css" media="all" rel="Stylesheet" type="text/css"/>
         </head>
         .
         .
         .
       </html>

       # my_action.herb has a call to require_css 'style'
       # File: layout/application.html.erb
       include_required_css
       # => <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css"/>

       # my_action.herb has a call to require_css 'style', 'ie-specific'
       # File: layout/application.html.erb
       include_required_css
       # => <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css"/>
       #    <link href="/stylesheets/ie-specific.css" media="all" rel="Stylesheet" type="text/css"/>

       # my_action.herb has a call to require_js 'jquery'
       # File: layout/application.html.erb
       include_required_js
       # => <script src="/javascripts/jquery.js" type="text/javascript"></script>

       # my_action.herb has a call to require_js 'jquery', 'effects', 'validation'
       # File: layout/application.html.erb
       include_required_js
       # => <script src="/javascripts/jquery.js" type="text/javascript"></script>
       #    <script src="/javascripts/effects.js" type="text/javascript"></script>
       #    <script src="/javascripts/validation.js" type="text/javascript"></script>

       <% require_css('style') %>
       # A subsequent call to include_required_css will render...
       # => <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css"/>

       <% require_css('style', 'ie-specific') %>
       # A subsequent call to include_required_css will render...
       # => <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css"/>
       #    <link href="/stylesheets/ie-specific.css" media="all" rel="Stylesheet" type="text/css"/>

       <% require_js 'jquery' %>
       # A subsequent call to include_required_js will render...
       # => <script src="/javascripts/jquery.js" type="text/javascript"></script>

       <% require_js 'jquery', 'effects' %>
       # A subsequent call to include_required_js will render...
       # => <script src="/javascripts/jquery.js" type="text/javascript"></script>
       #    <script src="/javascripts/effects.js" type="text/javascript"></script>

css_include_tag and js_include_tag that do not use asset subdomains:

       css_include_tag 'style'
       # => <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css" charset="utf-8" />

       css_include_tag 'style.css', 'layout'
       # => <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css" charset="utf-8" />
       #    <link href="/stylesheets/layout.css" media="all" rel="Stylesheet" type="text/css" charset="utf-8" />

       css_include_tag :menu
       # => <link href="/stylesheets/menu.css" media="all" rel="Stylesheet" type="text/css" charset="utf-8" />

       css_include_tag :style, :screen
       # => <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css" charset="utf-8" />
       #    <link href="/stylesheets/screen.css" media="all" rel="Stylesheet" type="text/css" charset="utf-8" />

      css_include_tag :style, :media => :print
      # => <link href="/stylesheets/style.css" media="print" rel="Stylesheet" type="text/css" charset="utf-8" />

      css_include_tag :style, :charset => 'iso-8859-1'
      # => <link href="/stylesheets/style.css" media="print" rel="Stylesheet" type="text/css" charset="iso-8859-1" />

       js_include_tag 'jquery'
       # => <script src="/javascripts/jquery.js" type="text/javascript"></script>

       js_include_tag 'moofx.js', 'upload'
       # => <script src="/javascripts/moofx.js" type="text/javascript"></script>
       #    <script src="/javascripts/upload.js" type="text/javascript"></script>

       js_include_tag :effects
       # => <script src="/javascripts/effects.js" type="text/javascript"></script>

       js_include_tag :jquery, :validation
       # => <script src="/javascripts/jquery.js" type="text/javascript"></script>
       #    <script src="/javascripts/validation.js" type="text/javascript"></script>

Utility methods examples

###### ====================

      uniq_css_path("my")
      #=> "http://assets2.my-awesome-domain.com/stylesheets/my.css"

      uniq_css_path(["admin/secrets","home/signup"])
      #=> ["http://assets2.my-awesome-domain.com/stylesheets/admin/secrets.css",
             "http://assets1.my-awesome-domain.com/stylesheets/home/signup.css"]

      uniq_path("/javascripts/my.js","/javascripts/my.css")
      #=> ["http://assets2.my-awesome-domain.com/javascripts/my.js", "http://assets1.my-awesome-domain.com/javascripts/my.css"]

      uniq_path(["/javascripts/my.js","/stylesheets/my.css"])
      #=> ["http://assets2.my-awesome-domain.com/javascripts/my.js", "http://assets1.my-awesome-domain.com/stylesheets/my.css"]

      uniq_path(%w(/javascripts/my.js /stylesheets/my.css))
      #=> ["http://assets2.my-awesome-domain.com/javascripts/my.js", "http://assets1.my-awesome-domain.com/stylesheets/my.css"]

      uniq_path('/stylesheets/somearbitrary.css')
      #=> "http://assets3.my-awesome-domain.com/stylesheets/somearbitrary.css"

      uniq_path('/images/hostsexypicture.jpg')
      #=>"http://assets1.my-awesome-domain.com/images/hostsexypicture.jpg"

[Validate]