Module: ActionView::Helpers::AssetUrlHelper

Included in:
ActionView::Helpers, AssetTagHelper
Defined in:
lib/action_view/helpers/asset_url_helper.rb

Overview

This module provides methods for generating asset paths and urls.

image_path("rails.png")
# => "/assets/rails.png"

image_url("rails.png")
# => "http://www.example.com/assets/rails.png"

Using asset hosts

By default, Rails links to these assets on the current host in the public folder, but you can direct Rails to link to assets from a dedicated asset server by setting ActionController::Base.asset_host in the application configuration, typically in config/environments/production.rb. For example, you’d define assets.example.com to be your asset host this way, inside the configure block of your environment-specific configuration files or config/application.rb:

config.action_controller.asset_host = "assets.example.com"

Helpers take that into account:

image_tag("rails.png")
# => <img alt="Rails" src="http://assets.example.com/assets/rails.png" />
stylesheet_link_tag("application")
# => <link href="http://assets.example.com/assets/application.css" media="screen" rel="stylesheet" />

Browsers typically open at most two simultaneous connections to a single host, which means your assets often have to wait for other assets to finish downloading. You can alleviate this by using a %d wildcard in the asset_host. For example, “assets%d.example.com”. If that wildcard is present Rails distributes asset requests among the corresponding four hosts “assets0.example.com”, …, “assets3.example.com”. With this trick browsers will open eight simultaneous connections rather than two.

image_tag("rails.png")
# => <img alt="Rails" src="http://assets0.example.com/assets/rails.png" />
stylesheet_link_tag("application")
# => <link href="http://assets2.example.com/assets/application.css" media="screen" rel="stylesheet" />

To do this, you can either setup four actual hosts, or you can use wildcard DNS to CNAME the wildcard to a single asset host. You can read more about setting up your DNS CNAME records from your ISP.

Note: This is purely a browser performance optimization and is not meant for server load balancing. See www.die.net/musings/page_load_time/ for background.

Alternatively, you can exert more control over the asset host by setting asset_host to a proc like this:

ActionController::Base.asset_host = Proc.new { |source|
  "http://assets#{Digest::MD5.hexdigest(source).to_i(16) % 2 + 1}.example.com"
}
image_tag("rails.png")
# => <img alt="Rails" src="http://assets1.example.com/assets/rails.png" />
stylesheet_link_tag("application")
# => <link href="http://assets2.example.com/assets/application.css" media="screen" rel="stylesheet" />

The example above generates “assets1.example.com” and “assets2.example.com”. This option is useful for example if you need fewer/more than four hosts, custom host names, etc.

As you see the proc takes a source parameter. That’s a string with the absolute path of the asset, for example “/assets/rails.png”.

 ActionController::Base.asset_host = Proc.new { |source|
   if source.ends_with?('.css')
     "http://stylesheets.example.com"
   else
     "http://assets.example.com"
   end
 }
image_tag("rails.png")
# => <img alt="Rails" src="http://assets.example.com/assets/rails.png" />
stylesheet_link_tag("application")
# => <link href="http://stylesheets.example.com/assets/application.css" media="screen" rel="stylesheet" />

Alternatively you may ask for a second parameter request. That one is particularly useful for serving assets from an SSL-protected page. The example proc below disables asset hosting for HTTPS connections, while still sending assets for plain HTTP requests from asset hosts. If you don’t have SSL certificates for each of the asset hosts this technique allows you to avoid warnings in the client about mixed media. Note that the request parameter might not be supplied, e.g. when the assets are precompiled via a Rake task. Make sure to use a Proc instead of a lambda, since a Proc allows missing parameters and sets them to nil.

config.action_controller.asset_host = Proc.new { |source, request|
  if request && request.ssl?
    "#{request.protocol}#{request.host_with_port}"
  else
    "#{request.protocol}assets.example.com"
  end
}

You can also implement a custom asset host object that responds to call and takes either one or two parameters just like the proc.

config.action_controller.asset_host = AssetHostingWithMinimumSsl.new(
  "http://asset%d.example.com", "https://asset1.example.com"
)

Constant Summary collapse

URI_REGEXP = 
%r{^[-a-z]+://|^(?:cid|data):|^//}i
ASSET_EXTENSIONS = 
{
  javascript: '.js',
  stylesheet: '.css'
}
ASSET_PUBLIC_DIRECTORIES =

Maps asset types to public directory.

{
  audio:      '/audios',
  font:       '/fonts',
  image:      '/images',
  javascript: '/javascripts',
  stylesheet: '/stylesheets',
  video:      '/videos'
}

Instance Method Summary collapse

Instance Method Details

#asset_path(source, options = {}) ⇒ Object Also known as: path_to_asset

Computes the path to asset in public directory. If :type options is set, a file extension will be appended and scoped to the corresponding public directory.

All other asset *_path helpers delegate through this method.

asset_path "application.js"                     # => /assets/application.js
asset_path "application", type: :javascript     # => /assets/application.js
asset_path "application", type: :stylesheet     # => /assets/application.css
asset_path "http://www.example.com/js/xmlhr.js" # => http://www.example.com/js/xmlhr.js



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 123

def asset_path(source, options = {})
  source = source.to_s
  return "" unless source.present?
  return source if source =~ URI_REGEXP

  tail, source = source[/([\?#].+)$/], source.sub(/([\?#].+)$/, '')

  if extname = compute_asset_extname(source, options)
    source = "#{source}#{extname}"
  end

  if source[0] != ?/
    source = compute_asset_path(source, options)
  end

  relative_url_root = defined?(config.relative_url_root) && config.relative_url_root
  if relative_url_root
    source = File.join(relative_url_root, source) unless source.starts_with?("#{relative_url_root}/")
  end

  if host = compute_asset_host(source, options)
    source = File.join(host, source)
  end

  "#{source}#{tail}"
end

#asset_url(source, options = {}) ⇒ Object Also known as: url_to_asset

Computes the full URL to an asset in the public directory. This will use asset_path internally, so most of their behaviors will be the same. If :host options is set, it overwrites global config.action_controller.asset_host setting.

All other options provided are forwarded to asset_path call.

asset_url "application.js"                                 # => http://example.com/assets/application.js
asset_url "application.js", host: "http://cdn.example.com" # => http://cdn.example.com/assets/application.js



161
162
163
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 161

def asset_url(source, options = {})
  path_to_asset(source, options.merge(:protocol => :request))
end

#audio_path(source, options = {}) ⇒ Object Also known as: path_to_audio

Computes the path to an audio asset in the public audios directory. Full paths from the document root will be passed through. Used internally by audio_tag to build the audio path.

audio_path("horse")                                            # => /audios/horse
audio_path("horse.wav")                                        # => /audios/horse.wav
audio_path("sounds/horse.wav")                                 # => /audios/sounds/horse.wav
audio_path("/sounds/horse.wav")                                # => /sounds/horse.wav
audio_path("http://www.example.com/sounds/horse.wav")          # => http://www.example.com/sounds/horse.wav



333
334
335
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 333

def audio_path(source, options = {})
  path_to_asset(source, {type: :audio}.merge!(options))
end

#audio_url(source, options = {}) ⇒ Object Also known as: url_to_audio

Computes the full URL to an audio asset in the public audios directory. This will use audio_path internally, so most of their behaviors will be the same.



340
341
342
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 340

def audio_url(source, options = {})
  url_to_asset(source, {type: :audio}.merge!(options))
end

#compute_asset_extname(source, options = {}) ⇒ Object

Compute extname to append to asset path. Returns nil if nothing should be added.



173
174
175
176
177
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 173

def compute_asset_extname(source, options = {})
  return if options[:extname] == false
  extname = options[:extname] || ASSET_EXTENSIONS[options[:type]]
  extname if extname && File.extname(source) != extname
end

#compute_asset_host(source = "", options = {}) ⇒ Object

Pick an asset host for this source. Returns nil if no host is set, the host if no wildcard is set, the host interpolated with the numbers 0-3 if it contains %d (the number is the source hash mod 4), or the value returned from invoking call on an object responding to call (proc or otherwise).



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 202

def compute_asset_host(source = "", options = {})
  request = self.request if respond_to?(:request)
  host = options[:host]
  host ||= config.asset_host if defined? config.asset_host

  if host.respond_to?(:call)
    arity = host.respond_to?(:arity) ? host.arity : host.method(:call).arity
    args = [source]
    args << request if request && (arity > 1 || arity < 0)
    host = host.call(*args)
  elsif host =~ /%d/
    host = host % (Zlib.crc32(source) % 4)
  end

  host ||= request.base_url if request && options[:protocol] == :request
  return unless host

  if host =~ URI_REGEXP
    host
  else
    protocol = options[:protocol] || config.default_asset_host_protocol || (request ? :request : :relative)
    case protocol
    when :relative
      "//#{host}"
    when :request
      "#{request.protocol}#{host}"
    else
      "#{protocol}://#{host}"
    end
  end
end

#compute_asset_path(source, options = {}) ⇒ Object

Computes asset path to public directory. Plugins and extensions can override this method to point to custom assets or generate digested paths or query strings.



192
193
194
195
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 192

def compute_asset_path(source, options = {})
  dir = ASSET_PUBLIC_DIRECTORIES[options[:type]] || ""
  File.join(dir, source)
end

#font_path(source, options = {}) ⇒ Object Also known as: path_to_font

Computes the path to a font asset. Full paths from the document root will be passed through.

font_path("font")                                           # => /fonts/font
font_path("font.ttf")                                       # => /fonts/font.ttf
font_path("dir/font.ttf")                                   # => /fonts/dir/font.ttf
font_path("/dir/font.ttf")                                  # => /dir/font.ttf
font_path("http://www.example.com/dir/font.ttf")            # => http://www.example.com/dir/font.ttf



353
354
355
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 353

def font_path(source, options = {})
  path_to_asset(source, {type: :font}.merge!(options))
end

#font_url(source, options = {}) ⇒ Object Also known as: url_to_font

Computes the full URL to a font asset. This will use font_path internally, so most of their behaviors will be the same.



360
361
362
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 360

def font_url(source, options = {})
  url_to_asset(source, {type: :font}.merge!(options))
end

#image_path(source, options = {}) ⇒ Object Also known as: path_to_image

Computes the path to an image asset. Full paths from the document root will be passed through. Used internally by image_tag to build the image path:

image_path("edit")                                         # => "/assets/edit"
image_path("edit.png")                                     # => "/assets/edit.png"
image_path("icons/edit.png")                               # => "/assets/icons/edit.png"
image_path("/icons/edit.png")                              # => "/icons/edit.png"
image_path("http://www.example.com/img/edit.png")          # => "http://www.example.com/img/edit.png"

If you have images as application resources this method may conflict with their named routes. The alias path_to_image is provided to avoid that. Rails uses the alias internally, and plugin authors are encouraged to do so.



291
292
293
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 291

def image_path(source, options = {})
  path_to_asset(source, {type: :image}.merge!(options))
end

#image_url(source, options = {}) ⇒ Object Also known as: url_to_image

Computes the full URL to an image asset. This will use image_path internally, so most of their behaviors will be the same.



298
299
300
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 298

def image_url(source, options = {})
  url_to_asset(source, {type: :image}.merge!(options))
end

#javascript_path(source, options = {}) ⇒ Object Also known as: path_to_javascript

Computes the path to a JavaScript asset in the public javascripts directory. If the source filename has no extension, .js will be appended (except for explicit URIs) Full paths from the document root will be passed through. Used internally by javascript_include_tag to build the script path.

javascript_path "xmlhr"                              # => /assets/xmlhr.js
javascript_path "dir/xmlhr.js"                       # => /assets/dir/xmlhr.js
javascript_path "/dir/xmlhr"                         # => /dir/xmlhr.js
javascript_path "http://www.example.com/js/xmlhr"    # => http://www.example.com/js/xmlhr
javascript_path "http://www.example.com/js/xmlhr.js" # => http://www.example.com/js/xmlhr.js



244
245
246
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 244

def javascript_path(source, options = {})
  path_to_asset(source, {type: :javascript}.merge!(options))
end

#javascript_url(source, options = {}) ⇒ Object Also known as: url_to_javascript

Computes the full URL to a JavaScript asset in the public javascripts directory. This will use javascript_path internally, so most of their behaviors will be the same.



251
252
253
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 251

def javascript_url(source, options = {})
  url_to_asset(source, {type: :javascript}.merge!(options))
end

#stylesheet_path(source, options = {}) ⇒ Object Also known as: path_to_stylesheet

Computes the path to a stylesheet asset in the public stylesheets directory. If the source filename has no extension, .css will be appended (except for explicit URIs). Full paths from the document root will be passed through. Used internally by stylesheet_link_tag to build the stylesheet path.

stylesheet_path "style"                                  # => /assets/style.css
stylesheet_path "dir/style.css"                          # => /assets/dir/style.css
stylesheet_path "/dir/style.css"                         # => /dir/style.css
stylesheet_path "http://www.example.com/css/style"       # => http://www.example.com/css/style
stylesheet_path "http://www.example.com/css/style.css"   # => http://www.example.com/css/style.css



266
267
268
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 266

def stylesheet_path(source, options = {})
  path_to_asset(source, {type: :stylesheet}.merge!(options))
end

#stylesheet_url(source, options = {}) ⇒ Object Also known as: url_to_stylesheet

Computes the full URL to a stylesheet asset in the public stylesheets directory. This will use stylesheet_path internally, so most of their behaviors will be the same.



273
274
275
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 273

def stylesheet_url(source, options = {})
  url_to_asset(source, {type: :stylesheet}.merge!(options))
end

#video_path(source, options = {}) ⇒ Object Also known as: path_to_video

Computes the path to a video asset in the public videos directory. Full paths from the document root will be passed through. Used internally by video_tag to build the video path.

video_path("hd")                                            # => /videos/hd
video_path("hd.avi")                                        # => /videos/hd.avi
video_path("trailers/hd.avi")                               # => /videos/trailers/hd.avi
video_path("/trailers/hd.avi")                              # => /trailers/hd.avi
video_path("http://www.example.com/vid/hd.avi")             # => http://www.example.com/vid/hd.avi



312
313
314
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 312

def video_path(source, options = {})
  path_to_asset(source, {type: :video}.merge!(options))
end

#video_url(source, options = {}) ⇒ Object Also known as: url_to_video

Computes the full URL to a video asset in the public videos directory. This will use video_path internally, so most of their behaviors will be the same.



319
320
321
 
# File 'lib/action_view/helpers/asset_url_helper.rb', line 319

def video_url(source, options = {})
  url_to_asset(source, {type: :video}.merge!(options))
end