module Sprockets::Helpers

Constants

VERSION

Attributes

are_using_sprockets_3_plus[RW]

Indicates whenever we are using Sprockets 3.x or higher.

are_using_sprockets_4_plus[RW]

Indicates whenever we are using Sprockets 4.x or higher.

settings[RW]

Public Class Methods

configure() { |settings| ... } click to toggle source

Convience method for configuring Sprockets::Helpers.

# File lib/sprockets/helpers.rb, line 29
def configure
  yield settings
end

Public Instance Methods

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

Returns the path to an asset either in the Sprockets environment or the public directory. External URIs are untouched.

Options

  • :ext - The extension to append if the source does not have one.

  • :dir - The directory to prepend if the file is in the public directory.

  • :digest - Wether or not use the digest paths for assets. Set Sprockets::Helpers.digest for global configuration.

  • :prefix - Use a custom prefix for the Sprockets environment. Set Sprockets::Helpers.prefix for global configuration.

  • :body - Adds a ?body=1 flag that tells Sprockets to return only the body of the asset.

Examples

For files within Sprockets:

asset_path 'xmlhr.js'                       # => '/assets/xmlhr.js'
asset_path 'xmlhr', :ext => 'js'            # => '/assets/xmlhr.js'
asset_path 'xmlhr.js', :digest => true      # => '/assets/xmlhr-27a8f1f96afd8d4c67a59eb9447f45bd.js'
asset_path 'xmlhr.js', :prefix => '/themes' # => '/themes/xmlhr.js'

For files outside of Sprockets:

asset_path 'xmlhr'                                # => '/xmlhr'
asset_path 'xmlhr', :ext => 'js'                  # => '/xmlhr.js'
asset_path 'dir/xmlhr.js', :dir => 'javascripts'  # => '/javascripts/dir/xmlhr.js'
asset_path '/dir/xmlhr.js', :dir => 'javascripts' # => '/dir/xmlhr.js'
asset_path 'http://www.example.com/js/xmlhr'      # => 'http://www.example.com/js/xmlhr'
asset_path 'http://www.example.com/js/xmlhr.js'   # => 'http://www.example.com/js/xmlhr.js'
# File lib/sprockets/helpers.rb, line 82
def asset_path(source, options = {})
  uri = URI.parse(source)
  return source if uri.absolute?

  options[:prefix] = sprockets_helpers_settings.prefix unless options[:prefix]

  if sprockets_helpers_settings.debug || options[:debug]
    options[:manifest] = false
    options[:digest] = false
    options[:asset_host] = false
  end

  source_ext = File.extname(source)

  if options[:ext] && source_ext != ".#{options[:ext]}"
    uri.path << ".#{options[:ext]}"
  end

  path = find_asset_path(uri, source, options)
  if options[:expand] && path.respond_to?(:to_a)
    path.to_a
  else
    path.to_s
  end
end
Also aliased as: path_to_asset
asset_tag(source, options = {}) { |path| ... } click to toggle source
# File lib/sprockets/helpers.rb, line 109
def asset_tag(source, options = {}, &block)
  raise ::ArgumentError, 'block missing' unless block
  options = { :expand => (!!sprockets_helpers_settings.debug && !::Sprockets::Helpers.are_using_sprockets_4_plus) || 
                         !!sprockets_helpers_settings.expand,
              :debug => sprockets_helpers_settings.debug }.merge(options)

  path = asset_path(source, options)
  output = if options[:expand] && path.respond_to?(:map)
    "\n<!-- Expanded from #{source} -->\n" + path.map(&block).join("\n")
  else
    yield path
  end

  output = output.html_safe if output.respond_to?(:html_safe)
  output
end
audio_path(source, options = {}) click to toggle source

Computes the path to a audio asset either in the Sprockets environment or the public directory. External URIs are untouched.

Examples

With files within Sprockets:

audio_path 'audio.mp3'            # => '/assets/audio.mp3'
audio_path 'subfolder/audio.mp3'  # => '/assets/subfolder/audio.mp3'
audio_path '/subfolder/audio.mp3' # => '/assets/subfolder/audio.mp3'

With files outside of Sprockets:

audio_path 'audio'                                # => '/audios/audio'
audio_path 'audio.mp3'                            # => '/audios/audio.mp3'
audio_path 'subfolder/audio.mp3'                  # => '/audios/subfolder/audio.mp3'
audio_path '/subfolder/audio.mp3                  # => '/subfolder/audio.mp3'
audio_path 'http://www.example.com/img/audio.mp3' # => 'http://www.example.com/img/audio.mp3'
# File lib/sprockets/helpers.rb, line 161
def audio_path(source, options = {})
  asset_path source, sprockets_helpers_settings.default_path_options[:audio_path].merge(options)
end
Also aliased as: path_to_audio
font_path(source, options = {}) click to toggle source

Computes the path to a font asset either in the Sprockets environment or the public directory. External URIs are untouched.

Examples

With files within Sprockets:

font_path 'font.ttf'            # => '/assets/font.ttf'
font_path 'subfolder/font.ttf'  # => '/assets/subfolder/font.ttf'
font_path '/subfolder/font.ttf' # => '/assets/subfolder/font.ttf'

With files outside of Sprockets:

font_path 'font'                                # => '/fonts/font'
font_path 'font.ttf'                            # => '/fonts/font.ttf'
font_path 'subfolder/font.ttf'                  # => '/fonts/subfolder/font.ttf'
font_path '/subfolder/font.ttf                  # => '/subfolder/font.ttf'
font_path 'http://www.example.com/img/font.ttf' # => 'http://www.example.com/img/font.ttf'
# File lib/sprockets/helpers.rb, line 185
def font_path(source, options = {})
  asset_path source, sprockets_helpers_settings.default_path_options[:font_path].merge(options)
end
Also aliased as: path_to_font
image_path(source, options = {}) click to toggle source

Computes the path to an image asset either in the Sprockets environment or the public directory. External URIs are untouched.

Examples

With files within Sprockets:

image_path 'edit.png'        # => '/assets/edit.png'
image_path 'icons/edit.png'  # => '/assets/icons/edit.png'
image_path '/icons/edit.png' # => '/assets/icons/edit.png'

With files outside of Sprockets:

image_path 'edit'                                # => '/images/edit'
image_path 'edit.png'                            # => '/images/edit.png'
image_path 'icons/edit.png'                      # => '/images/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'
# File lib/sprockets/helpers.rb, line 209
def image_path(source, options = {})
  asset_path source, sprockets_helpers_settings.default_path_options[:image_path].merge(options)
end
Also aliased as: path_to_image
javascript_path(source, options = {}) click to toggle source

Computes the path to a javascript asset either in the Sprockets environment or the public directory. If the source filename has no extension, .js will be appended. External URIs are untouched.

Examples

For files within Sprockets:

javascript_path 'xmlhr'        # => '/assets/xmlhr.js'
javascript_path 'dir/xmlhr.js' # => '/assets/dir/xmlhr.js'
javascript_path '/dir/xmlhr'   # => '/assets/dir/xmlhr.js'

For files outside of Sprockets:

javascript_path 'xmlhr'                              # => '/javascripts/xmlhr.js'
javascript_path 'dir/xmlhr.js'                       # => '/javascripts/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/sprockets/helpers.rb, line 234
def javascript_path(source, options = {})
  asset_path source, sprockets_helpers_settings.default_path_options[:javascript_path].merge(options)
end
Also aliased as: path_to_javascript
javascript_tag(source, options = {}) click to toggle source
# File lib/sprockets/helpers.rb, line 126
def javascript_tag(source, options = {})
  options = sprockets_helpers_settings.default_path_options[:javascript_path].merge(options)
  asset_tag(source, options) do |path|
    %Q(<script src="#{path}" type="text/javascript"></script>)
  end
end
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 either in the Sprockets environment or the public directory. If the source filename has no extension, .css will be appended. External URIs are untouched.

Examples

For files within Sprockets:

stylesheet_path 'style'          # => '/assets/style.css'
stylesheet_path 'dir/style.css'  # => '/assets/dir/style.css'
stylesheet_path '/dir/style.css' # => '/assets/dir/style.css'

For files outside of Sprockets:

stylesheet_path 'style'                                  # => '/stylesheets/style.css'
stylesheet_path 'dir/style.css'                          # => '/stylesheets/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/sprockets/helpers.rb, line 259
def stylesheet_path(source, options = {})
  asset_path source, sprockets_helpers_settings.default_path_options[:stylesheet_path].merge(options)
end
Also aliased as: path_to_stylesheet
stylesheet_tag(source, options = {}) click to toggle source
# File lib/sprockets/helpers.rb, line 133
def stylesheet_tag(source, options = {})
  media = options.delete(:media)
  media_attr = media.nil? ? nil : " media=\"#{media}\""
  options = sprockets_helpers_settings.default_path_options[:stylesheet_path].merge(options)
  asset_tag(source, options) do |path|
    %Q(<link rel="stylesheet" type="text/css" href="#{path}"#{media_attr}>)
  end
end
video_path(source, options = {}) click to toggle source

Computes the path to a video asset either in the Sprockets environment or the public directory. External URIs are untouched.

Examples

With files within Sprockets:

video_path 'video.mp4'            # => '/assets/video.mp4'
video_path 'subfolder/video.mp4'  # => '/assets/subfolder/video.mp4'
video_path '/subfolder/video.mp4' # => '/assets/subfolder/video.mp4'

With files outside of Sprockets:

video_path 'video'                                # => '/videos/video'
video_path 'video.mp4'                            # => '/videos/video.mp4'
video_path 'subfolder/video.mp4'                  # => '/videos/subfolder/video.mp4'
video_path '/subfolder/video.mp4                  # => '/subfolder/video.mp4'
video_path 'http://www.example.com/img/video.mp4' # => 'http://www.example.com/img/video.mp4'
# File lib/sprockets/helpers.rb, line 283
def video_path(source, options = {})
  asset_path source, sprockets_helpers_settings.default_path_options[:video_path].merge(options)
end
Also aliased as: path_to_video

Protected Instance Methods

assets_environment() click to toggle source

Returns the Sprockets environment asset_path uses to search for assets. This can be overridden for more control, if necessary. For even more control, you just need to override sprockets_helper_settings. Defaults to sprockets_helpers_settings.environment or the environment returned by environment.

# File lib/sprockets/helpers.rb, line 295
def assets_environment
  sprockets_helpers_settings.environment || environment
end
find_asset_path(uri, source, options = {}) click to toggle source
# File lib/sprockets/helpers.rb, line 306
def find_asset_path(uri, source, options = {})
  options = options.merge(:sprockets_helpers_settings => sprockets_helpers_settings,
                          :debug => sprockets_helpers_settings.debug)

  if sprockets_helpers_settings.manifest && options[:manifest] != false
    manifest_path = sprockets_helpers_settings.manifest.assets[uri.path]
    return Helpers::ManifestPath.new(uri, manifest_path, options) if manifest_path
  end

  if Sprockets::Helpers.are_using_sprockets_4_plus
    resolved, _ = assets_environment.resolve(uri.path, pipeline: options[:debug] ? :debug : nil)

    if resolved
      return Helpers::AssetPath.new(uri, assets_environment[uri.path, pipeline: options[:debug] ? :debug : nil], assets_environment, options)
    else
      return Helpers::FilePath.new(uri, options)
    end
  elsif Sprockets::Helpers.are_using_sprockets_3_plus
    resolved, _ = assets_environment.resolve(uri.path)

    if resolved
      return Helpers::AssetPath.new(uri, assets_environment[uri.path], assets_environment, options)
    else
      return Helpers::FilePath.new(uri, options)
    end
  else
    assets_environment.resolve(uri.path) do |path|
      return Helpers::AssetPath.new(uri, assets_environment[path], assets_environment, options)
    end

    return Helpers::FilePath.new(uri, options)
  end
end
sprockets_helpers_settings() click to toggle source

Returns the Sprockets helpers settings. This can be overridden for more control, for instance if you want to support polyinstantiation in your application.

# File lib/sprockets/helpers.rb, line 302
def sprockets_helpers_settings
  Helpers.settings
end