module ActionView::Helpers::AssetUrlHelper - actionview-4.2.3 Documentation

# module ActionView::Helpers::AssetUrlHelper

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"
    )

### Constants

ASSET_EXTENSIONS
ASSET_PUBLIC_DIRECTORIES

  Maps asset types to public directory.

URI_REGEXP

### Public Instance Methods

asset_path(source, options = {}) click to toggle source

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

    # 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

Also aliased as: path_to_asset
asset_url(source, options = {}) click to toggle source

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

    # 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

Also aliased as: url_to_asset
audio_path(source, options = {}) click to toggle source

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

    # 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

Also aliased as: path_to_audio
audio_url(source, options = {}) click to toggle source

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.

    # 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

Also aliased as: url_to_audio
compute_asset_extname(source, options = {}) click to toggle source

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

    # 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 = {}) click to toggle source

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).

    # 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 = {}) click to toggle source

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.

    # 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 = {}) click to toggle source

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

    # 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

Also aliased as: path_to_font
font_url(source, options = {}) click to toggle source

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

    # 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

Also aliased as: url_to_font
image_path(source, options = {}) click to toggle source

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.

    # 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

Also aliased as: path_to_image
image_url(source, options = {}) click to toggle source

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

    # 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

Also aliased as: url_to_image
javascript_path(source, options = {}) click to toggle source

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

    # 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

Also aliased as: path_to_javascript
javascript_url(source, options = {}) click to toggle source

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.

    # 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

Also aliased as: url_to_javascript
path_to_asset(source, options = {})
Alias for: asset_path
path_to_audio(source, options = {})
Alias for: audio_path
path_to_font(source, options = {})
Alias for: font_path
path_to_image(source, options = {})
Alias for: image_path
path_to_javascript(source, options = {})
Alias for: javascript_path
path_to_stylesheet(source, options = {})
Alias for: stylesheet_path
path_to_video(source, options = {})
Alias for: video_path
stylesheet_path(source, options = {}) click to toggle source

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

    # 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

Also aliased as: path_to_stylesheet
stylesheet_url(source, options = {}) click to toggle source

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.

    # 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

Also aliased as: url_to_stylesheet
url_to_asset(source, options = {})
Alias for: asset_url
url_to_audio(source, options = {})
Alias for: audio_url
url_to_font(source, options = {})
Alias for: font_url
url_to_image(source, options = {})
Alias for: image_url
url_to_javascript(source, options = {})
Alias for: javascript_url
url_to_stylesheet(source, options = {})
Alias for: stylesheet_url
url_to_video(source, options = {})
Alias for: video_url
video_path(source, options = {}) click to toggle source

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

    # 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

Also aliased as: path_to_video
video_url(source, options = {}) click to toggle source

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.

    # 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

Also aliased as: url_to_video