Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Fetching latest commit…

Cannot retrieve the latest commit at this time

..
Failed to load latest commit information.
docs
lib
spec
.rspec
LICENSE
README.mkd
Rakefile
TODO
merb-assets.gemspec

README.mkd

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"
Something went wrong with that request. Please try again.