Module: Merb::AssetsMixin
- Includes:
- Merb::Assets::AssetHelpers
- Defined in:
- lib/merb-assets/assets_mixin.rb
Overview
The AssetsMixin module provides a number of helper methods to views for linking to assets and other pages, dealing with JavaScript and CSS.
Merb provides views with convenience methods for links images and other assets.
Constant Summary collapse
- ABSOLUTE_PATH_REGEXP =
%r{^#{Merb::Const::HTTP}s?://}
Constants included from Merb::Assets::AssetHelpers
Merb::Assets::AssetHelpers::ASSET_FILE_EXTENSIONS
Class Method Summary collapse
-
.append_random_query_string?(intention, allow_default = true) ⇒ Boolean
This tests whether a random query string shall be appended to a url.
-
.append_timestamp_query_string?(intention, allow_default = true) ⇒ Boolean
This tests whether a timestamp query string shall be appended to a url.
Instance Method Summary collapse
-
#asset_exists?(asset_type, asset_path) ⇒ Boolean
Parameters asset_type
: A symbol representing the type of the asset. -
#auto_link ⇒ String
Automatically generates link for CSS and JS.
-
#auto_link_css ⇒ String
We want all possible matches in the file system upto the action name for CSS.
-
#auto_link_js ⇒ Object
Parameters none.
-
#auto_link_paths ⇒ Object
Parameters none.
-
#css_include_tag(*stylesheets) ⇒ String
Generate CSS include tag(s).
-
#escape_js(javascript) ⇒ Object
Parameters javascript
:: Text to escape for use in JavaScript. -
#image_tag(img, opts = {}) ⇒ String
Generate IMG tag.
-
#include_required_css(options = {}) ⇒ Object
A method used in the layout of an application to create
<link>tags for CSS stylesheets required in in templates and subtemplates using require_css. -
#include_required_js(options = {}) ⇒ Object
A method used in the layout of an application to create
<script>tags to include JavaScripts required in in templates and subtemplates using require_js. -
#js(data) ⇒ Object
Parameters data
-
#js_include_tag(*scripts) ⇒ String
Generate JavaScript include tag(s).
-
#link_to(name, url = '', opts = {}) ⇒ Object
Parameters name<~to_s>:: The text of the link.
-
#require_css(*css) ⇒ Object
The require_css method can be used to require any CSS file anywhere in your templates.
-
#require_js(*js) ⇒ Object
The require_js method can be used to require any JavaScript file anywhere in your templates.
-
#required_css(options = {}) ⇒ Object
All css files to include, without duplicates.
-
#required_js(options = {}) ⇒ Object
All javascript files to include, without duplicates.
-
#uniq_css_path(*assets) ⇒ Object
Parameters *assets:: Creates unique paths for stylesheet files (prepends "/stylesheets" and appends ".css").
-
#uniq_css_tag(*assets) ⇒ Object
Parameters *assets:: As uniq_css_tag but has unique path.
-
#uniq_js_path(*assets) ⇒ Object
Parameters *assets:: Creates unique paths for javascript files (prepends "/javascripts" and appends ".js").
-
#uniq_js_tag(*assets) ⇒ Object
Parameters *assets:: As js_include_tag but has unique path.
-
#uniq_path(*assets) ⇒ Object
Parameters *assets:: The assets to include.
Methods included from Merb::Assets::AssetHelpers
Class Method Details
.append_random_query_string?(intention, allow_default = true) ⇒ Boolean
This tests whether a random query string shall be appended to a url.
Basically, you tell it your intention and if it's ok to use default config values, and it will either use your intention or the value set in Merb::Config
25 26 27 |
# File 'lib/merb-assets/assets_mixin.rb', line 25 def self.append_random_query_string?(intention, allow_default = true) intention.nil? && allow_default ? Merb::Config[:reload_templates] : intention end |
.append_timestamp_query_string?(intention, allow_default = true) ⇒ Boolean
This tests whether a timestamp query string shall be appended to a url.
40 41 42 |
# File 'lib/merb-assets/assets_mixin.rb', line 40 def self.(intention, allow_default = true) intention.nil? && allow_default ? Merb::Plugins.config[:asset_helpers][:asset_timestamp] : intention end |
Instance Method Details
#asset_exists?(asset_type, asset_path) ⇒ Boolean
Parameters
asset_type
Returns
exists?
Examples
This tests whether a give asset exists in the file system.
98 99 100 |
# File 'lib/merb-assets/assets_mixin.rb', line 98 def asset_exists?(asset_type, asset_path) File.exists?(Merb.root / asset_path(asset_type, asset_path, true)) end |
#auto_link ⇒ String
Automatically generates link for CSS and JS
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)
56 57 58 |
# File 'lib/merb-assets/assets_mixin.rb', line 56 def auto_link [auto_link_css, auto_link_js].join(Merb::Const::NEWLINE) end |
#auto_link_css ⇒ String
We want all possible matches in the file system upto the action name for CSS. The reason for separating auto_link for CSS and JS is performance concerns with page loading. See Yahoo performance rules (http://developer.yahoo.com/performance/rules.html)
66 67 68 69 70 |
# File 'lib/merb-assets/assets_mixin.rb', line 66 def auto_link_css auto_link_paths.map do |path| asset_exists?(:stylesheet, path) ? css_include_tag(path) : nil end.compact.join(Merb::Const::NEWLINE) end |
#auto_link_js ⇒ Object
Parameters
none
Returns
html
Examples
We want all possible matches in the file system upto the action name for JS. The reason for separating auto_link for CSS and JS is performance concerns with page loading. See Yahoo performance rules (http://developer.yahoo.com/performance/rules.html)
83 84 85 86 87 |
# File 'lib/merb-assets/assets_mixin.rb', line 83 def auto_link_js auto_link_paths.map do |path| asset_exists?(:javascript, path) ? js_include_tag(path) : nil end.compact.join(Merb::Const::NEWLINE) end |
#auto_link_paths ⇒ Object
Parameters
none
Returns
paths
Examples
This is an auxiliary method which returns an array of all possible asset paths for the current controller/action.
111 112 113 114 115 116 117 |
# File 'lib/merb-assets/assets_mixin.rb', line 111 def auto_link_paths paths = (controller_name / action_name).split(Merb::Const::SLASH) first = paths.shift paths.inject( [first] ) do |memo, val| memo.push [memo.last, val].join(Merb::Const::SLASH) end end |
#css_include_tag(*stylesheets) ⇒ String
Generate CSS include tag(s).
Options
css_include_tag :style, :media => :print
=>
css_include_tag :style, :charset => 'iso-8859-1'
=>
css_include_tag :style, :prefix => "http://static.example.com"
=>
css_include_tag :style, :suffix => ".#MyApp.version"
=>
622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 |
# File 'lib/merb-assets/assets_mixin.rb', line 622 def css_include_tag(*stylesheets) = stylesheets.last.is_a?(Hash) ? stylesheets.pop : {} return nil if stylesheets.empty? css_prefix = [:prefix] || Merb::Plugins.config[:asset_helpers][:css_prefix] css_suffix = [:suffix] || Merb::Plugins.config[:asset_helpers][:css_suffix] if (bundle_name = [:bundle]) && Merb::Assets.bundle? && stylesheets.size > 1 bundler = Merb::Assets::StylesheetAssetBundler.new(bundle_name, *stylesheets) bundled_asset = bundler.bundle! return css_include_tag(bundled_asset) end = "" reload = .delete(:reload) = .delete(:timestamp) for stylesheet in stylesheets href = css_prefix.to_s + asset_path(:stylesheet, stylesheet) if css_suffix ext_length = ASSET_FILE_EXTENSIONS[:stylesheet].length + 1 href.insert(-ext_length,css_suffix) end href = append_query_string(href, reload, ) attrs = { :href => href, :type => "text/css", :rel => "Stylesheet", :charset => [:charset] || "utf-8", :media => [:media] || :all } << %Q{<link #{attrs.to_xml_attributes} />} end return end |
#escape_js(javascript) ⇒ Object
Parameters
- javascript
Text to escape for use in JavaScript.
Examples
escape_js("'Lorem ipsum!' -- Some guy") # => "\'Lorem ipsum!\' -- Some guy"
escape_js("Please keep text\nlines as skinny\nas possible.")
# => "Please keep text\\nlines as skinny\\nas possible."
211 212 213 |
# File 'lib/merb-assets/assets_mixin.rb', line 211 def escape_js(javascript) (javascript || '').gsub('\\','\0\0').gsub(/\r\n|\n|\r/, "\\n").gsub(/["']/) { |m| "\\#{m}" } end |
#image_tag(img, opts = {}) ⇒ String
Generate IMG tag
All other options set HTML attributes on the tag.
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 |
# File 'lib/merb-assets/assets_mixin.rb', line 176 def image_tag(img, opts={}) return "" if img.blank? if img[0].chr == Merb::Const::SLASH opts[:src] = "#{Merb::Config[:path_prefix]}#{img}" else opts[:path] ||= if img =~ ABSOLUTE_PATH_REGEXP absolute = true '' else "#{Merb::Config[:path_prefix]}/images/" end opts[:src] ||= opts.delete(:path) + img end opts[:src] = append_query_string(opts[:src], opts.delete(:reload), opts.delete(:timestamp), !absolute) %{<img #{ opts.to_xml_attributes } />} end |
#include_required_css(options = {}) ⇒ Object
A method used in the layout of an application to create <link> tags for
CSS stylesheets required in in templates and subtemplates using
require_css.
Parameters
- options
Options to pass to css_include_tag.
Returns
- String
The CSS tag.
Options
:bundle<~to_s>::
The name of the bundle the stylesheets should be combined into.
:media<~to_s>::
The media attribute for the generated link element. Defaults to :all.
Examples
my_action.herb has a call to require_css 'style'
File: layout/application.html.erb
include_required_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"/>
475 476 477 |
# File 'lib/merb-assets/assets_mixin.rb', line 475 def include_required_css( = {}) required_css().map { |req_js| css_include_tag(*req_js) }.join end |
#include_required_js(options = {}) ⇒ Object
A method used in the layout of an application to create <script> tags
to include JavaScripts required in in templates and subtemplates using
require_js.
Parameters
- options
Options to pass to js_include_tag.
Options
:bundle<~to_s>::
The name of the bundle the scripts should be combined into.
Returns
- String
The JavaScript tag.
Examples
my_action.herb has a call to require_js 'jquery'
File: layout/application.html.erb
include_required_js
=>
# 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>
443 444 445 |
# File 'lib/merb-assets/assets_mixin.rb', line 443 def include_required_js( = {}) required_js().map { |req_js| js_include_tag(*req_js) }.join end |
#js(data) ⇒ Object
Parameters
- data
Object to translate into JSON. If the object does not respond to :to_json, then data.inspect.to_json is returned instead.
Examples
js(=> 'Lewis', 'page' => 'home')
=> "\"user\":\"Lewis\",\"page\":\"home\""
js([ 1, 2, {"a"=>3.141}, false, true, nil, 4..10 ])
# => "[1,2,{\"a\":3.141},false,true,null,\"4..10\"]"
226 227 228 229 230 231 232 |
# File 'lib/merb-assets/assets_mixin.rb', line 226 def js(data) if data.respond_to? :to_json data.to_json else data.inspect.to_json end end |
#js_include_tag(*scripts) ⇒ String
Generate JavaScript include tag(s).
Options
:charset<~to_s>::
Charset which will be used as value for charset attribute
:bundle<~to_s>::
The name of the bundle the scripts should be combined into.
:prefix<~to_s>::
prefix to add to include tag, overrides any set in Merb::Plugins.config[:asset_helpers][:js_prefix]
:suffix<~to_s>::
suffix to add to include tag, overrides any set in Merb::Plugins.config[:asset_helpers][:js_suffix]
:reload
Override the Merb::Config[:reload_templates] value. If true, a random query param will be appended
to the js url
530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 |
# File 'lib/merb-assets/assets_mixin.rb', line 530 def js_include_tag(*scripts) = scripts.last.is_a?(Hash) ? scripts.pop : {} return nil if scripts.empty? js_prefix = [:prefix] || Merb::Plugins.config[:asset_helpers][:js_prefix] js_suffix = [:suffix] || Merb::Plugins.config[:asset_helpers][:js_suffix] if (bundle_name = [:bundle]) && Merb::Assets.bundle? && scripts.size > 1 bundler = Merb::Assets::JavascriptAssetBundler.new(bundle_name, *scripts) bundled_asset = bundler.bundle! return js_include_tag(bundled_asset) end = "" for script in scripts src = js_prefix.to_s + asset_path(:javascript, script) if js_suffix ext_length = ASSET_FILE_EXTENSIONS[:javascript].length + 1 src.insert(-ext_length,js_suffix) end src = append_query_string(src, .delete(:reload), .delete(:timestamp)) attrs = { :src => src, :type => "text/javascript", :charset => [:charset] || "utf-8" } << %Q{<script #{attrs.to_xml_attributes}></script>} end return end |
#link_to(name, url = '', opts = {}) ⇒ Object
Parameters
- name<~to_s>
The text of the link.
- url<~to_s>
The URL to link to. Defaults to an empty string.
- opts
Additional HTML options for the link.
Examples
link_to("The Merb home page", "http://www.merbivore.com/") # => The Merb home page
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>
134 135 136 137 |
# File 'lib/merb-assets/assets_mixin.rb', line 134 def link_to(name, url='', opts={}) opts[:href] ||= url %{<a #{ opts.to_xml_attributes }>#{name}</a>} end |
#require_css(*css) ⇒ Object
The require_css method can be used to require any CSS file anywhere in your templates. Regardless of how many times a single stylesheet is included with require_css, Merb will only include it once in the header.
Parameters
- *css<~to_s>
CSS files to include.
Examples
<% require_css('style') %>
A subsequent call to include_required_css will render...
=>
<% 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"/>
403 404 405 406 |
# File 'lib/merb-assets/assets_mixin.rb', line 403 def require_css(*css) @required_css ||= [] @required_css << css end |
#require_js(*js) ⇒ Object
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.
Parameters
- *js<~to_s>
JavaScript files to include.
Examples
<% require_js 'jquery' %>
A subsequent call to include_required_js will render...
=>
<% 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>
373 374 375 376 |
# File 'lib/merb-assets/assets_mixin.rb', line 373 def require_js(*js) @required_js ||= [] @required_js << js end |
#required_css(options = {}) ⇒ Object
All css files to include, without duplicates.
Parameters
- options
Default options to pass to css_include_tag.
412 413 414 |
# File 'lib/merb-assets/assets_mixin.rb', line 412 def required_css( = {}) extract_required_files(@required_css, ) end |
#required_js(options = {}) ⇒ Object
All javascript files to include, without duplicates.
Parameters
- options
Default options to pass to js_include_tag.
382 383 384 |
# File 'lib/merb-assets/assets_mixin.rb', line 382 def required_js( = {}) extract_required_files(@required_js, ) end |
#uniq_css_path(*assets) ⇒ Object
Parameters
- *assets
Creates unique paths for stylesheet files (prepends "/stylesheets" and appends ".css")
Returns
- Array
Full unique paths to assets OR
- String
if only a single path is requested
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"]
728 729 730 731 732 733 734 |
# File 'lib/merb-assets/assets_mixin.rb', line 728 def uniq_css_path(*assets) paths = [] assets.flatten.each do |filename| paths.push(Merb::Assets::UniqueAssetPath.build(asset_path(:stylesheet,filename))) end paths.length > 1 ? paths : paths.first end |
#uniq_css_tag(*assets) ⇒ Object
Parameters
- *assets
As uniq_css_tag but has unique path
Returns
- Array
Full unique paths to assets OR
- String
if only a single path is requested
Examples
uniq_css_tag("my") #=>
760 761 762 |
# File 'lib/merb-assets/assets_mixin.rb', line 760 def uniq_css_tag(*assets) css_include_tag(*uniq_css_path(assets)) end |
#uniq_js_path(*assets) ⇒ Object
Parameters
- *assets
Creates unique paths for javascript files (prepends "/javascripts" and appends ".js")
Returns
- Array
Full unique paths to assets OR
- String
if only a single path is requested
Examples
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"]
706 707 708 709 710 711 712 |
# File 'lib/merb-assets/assets_mixin.rb', line 706 def uniq_js_path(*assets) paths = [] assets.flatten.each do |filename| paths.push(Merb::Assets::UniqueAssetPath.build(asset_path(:javascript,filename))) end paths.length > 1 ? paths : paths.first end |
#uniq_js_tag(*assets) ⇒ Object
Parameters
- *assets
As js_include_tag but has unique path
Returns
- Array
Full unique paths to assets OR
- String
if only a single path is requested
Examples
uniq_js_tag("my") #=>
746 747 748 |
# File 'lib/merb-assets/assets_mixin.rb', line 746 def uniq_js_tag(*assets) js_include_tag(*uniq_js_path(assets)) end |
#uniq_path(*assets) ⇒ Object
Parameters
- *assets
The assets to include. These should be the full paths to any static served file
Returns
- Array
Full unique paths to assets OR
- String
if only a single path is requested
Examples
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"
![http://assets1.my-awesome-domain.com/images/hostsexypicture.jpg"](http://assets1.my-awesome-domain.com/images/hostsexypicture.jpg"){kind=link}
684 685 686 687 688 689 690 |
# File 'lib/merb-assets/assets_mixin.rb', line 684 def uniq_path(*assets) paths = [] assets.flatten.each do |filename| paths.push(Merb::Assets::UniqueAssetPath.build(filename)) end paths.length > 1 ? paths : paths.first end |