Module: Sprockets::Helpers

Included in:
Context
Defined in:
lib/sprockets/helpers.rb,
lib/sprockets/helpers/version.rb,
lib/sprockets/helpers/file_path.rb,
lib/sprockets/helpers/base_path.rb,
lib/sprockets/helpers/asset_path.rb,
lib/sprockets/helpers/manifest_path.rb

Defined Under Namespace

Classes: AssetPath, BasePath, FilePath, ManifestPath

Constant Summary collapse

VERSION =
'1.1.0'

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.asset_hostObject

Link to assets from a dedicated server.


13
14
15
# File 'lib/sprockets/helpers.rb', line 13

def asset_host
  @asset_host
end

.debugObject

When true, force debug mode :debug => true equals

:expand   => true
:digest   => false
:manifest => false

26
27
28
# File 'lib/sprockets/helpers.rb', line 26

def debug
  @debug
end

.default_path_optionsObject

The default options for each asset path method. This is where you can change your default directories for the fallback directory.


61
62
63
64
65
66
67
68
69
70
# File 'lib/sprockets/helpers.rb', line 61

def default_path_options
  @default_path_options ||= {
    :audio_path => { :dir => 'audios' },
    :font_path => { :dir => 'fonts' },
    :image_path => { :dir => 'images' },
    :javascript_path => { :dir => 'javascripts', :ext => 'js' },
    :stylesheet_path => { :dir => 'stylesheets', :ext => 'css' },
    :video_path => { :dir => 'videos' }
  }
end

.digestObject

When true, the asset paths will return digest paths.


16
17
18
# File 'lib/sprockets/helpers.rb', line 16

def digest
  @digest
end

.environmentObject

Set the Sprockets environment to search for assets. This defaults to the context's #environment method.


30
31
32
# File 'lib/sprockets/helpers.rb', line 30

def environment
  @environment
end

.expandObject

When true, expand assets.


19
20
21
# File 'lib/sprockets/helpers.rb', line 19

def expand
  @expand
end

.manifestObject

The manifest file used for lookup


33
34
35
# File 'lib/sprockets/helpers.rb', line 33

def manifest
  @manifest
end

.prefixObject

The base URL the Sprocket environment is mapped to. This defaults to '/assets'.


37
38
39
40
# File 'lib/sprockets/helpers.rb', line 37

def prefix
  @prefix ||= '/assets'
  @prefix.respond_to?(:first) ? "/#{@prefix.first}" : @prefix
end

.protocolObject

Customize the protocol when using asset hosts. If the value is :relative, A relative protocol ('//') will be used.


46
47
48
# File 'lib/sprockets/helpers.rb', line 46

def protocol
  @protocol ||= 'http://'
end

.public_pathObject

The path to the public directory, where the assets not managed by Sprockets will be located. Defaults to './public'


54
55
56
# File 'lib/sprockets/helpers.rb', line 54

def public_path
  @public_path ||= './public'
end

Class Method Details

.append_features(context) ⇒ Object

Hack to ensure methods from Sprockets::Helpers override the methods of Sprockets::Context when included.


80
81
82
83
84
85
86
87
88
89
# File 'lib/sprockets/helpers.rb', line 80

def append_features(context) # :nodoc:
  context.class_eval do
    context_methods = context.instance_methods(false)
    Helpers.public_instance_methods.each do |method|
      remove_method(method) if context_methods.include?(method)
    end
  end

  super(context)
end

.configure {|_self| ... } ⇒ Object

Convience method for configuring Sprockets::Helpers.

Yields:

  • (_self)

Yield Parameters:


74
75
76
# File 'lib/sprockets/helpers.rb', line 74

def configure
  yield self
end

Instance Method Details

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

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'

121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
# File 'lib/sprockets/helpers.rb', line 121

def asset_path(source, options = {})
  uri = URI.parse(source)
  return source if uri.absolute?

  if Helpers.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, options)
  if options[:expand] && path.respond_to?(:to_a)
    path.to_a
  else
    path.to_s
  end
end

#asset_tag(source, options = {}, &block) ⇒ Object

Raises:

  • (::ArgumentError)

145
146
147
148
149
150
151
152
153
154
155
156
157
158
# File 'lib/sprockets/helpers.rb', line 145

def asset_tag(source, options = {}, &block)
  raise ::ArgumentError, 'block missing' unless block
  options = { :expand => Helpers.debug || Helpers.expand, :debug => Helpers.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 = {}) ⇒ Object Also known as: path_to_audio

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'

195
196
197
# File 'lib/sprockets/helpers.rb', line 195

def audio_path(source, options = {})
  asset_path source, Helpers.default_path_options[:audio_path].merge(options)
end

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

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'

219
220
221
# File 'lib/sprockets/helpers.rb', line 219

def font_path(source, options = {})
  asset_path source, Helpers.default_path_options[:font_path].merge(options)
end

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

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'

243
244
245
# File 'lib/sprockets/helpers.rb', line 243

def image_path(source, options = {})
  asset_path source, Helpers.default_path_options[:image_path].merge(options)
end

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

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'

268
269
270
# File 'lib/sprockets/helpers.rb', line 268

def javascript_path(source, options = {})
  asset_path source, Helpers.default_path_options[:javascript_path].merge(options)
end

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


160
161
162
163
164
165
# File 'lib/sprockets/helpers.rb', line 160

def javascript_tag(source, options = {})
  options = Helpers.default_path_options[:javascript_path].merge(options)
  asset_tag(source, options) do |path|
    %Q(<script src="#{path}"></script>)
  end
end

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

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'

293
294
295
# File 'lib/sprockets/helpers.rb', line 293

def stylesheet_path(source, options = {})
  asset_path source, Helpers.default_path_options[:stylesheet_path].merge(options)
end

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


167
168
169
170
171
172
173
174
# File 'lib/sprockets/helpers.rb', line 167

def stylesheet_tag(source, options = {})
  media = options.delete(:media)
  media_attr = media.nil? ? nil : " media=\"#{media}\""
  options = Helpers.default_path_options[:stylesheet_path].merge(options)
  asset_tag(source, options) do |path|
    %Q(<link rel="stylesheet" href="#{path}"#{media_attr}>)
  end
end

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

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'

317
318
319
# File 'lib/sprockets/helpers.rb', line 317

def video_path(source, options = {})
  asset_path source, Helpers.default_path_options[:video_path].merge(options)
end