Module: Sprockets::Helpers

Included in:
Context
Defined in:
lib/sprockets/helpers.rb,
lib/sprockets/helpers/version.rb,
lib/sprockets/helpers/base_path.rb,
lib/sprockets/helpers/file_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.2.3'.freeze

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.are_using_sprockets_3 ⇒ Object

Indicates whenever we are using Sprockets 3.x.



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

def are_using_sprockets_3
  @are_using_sprockets_3
end

.asset_host ⇒ Object

Link to assets from a dedicated server.



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

def asset_host
  @asset_host
end

.debug ⇒ Object

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

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



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

def debug
  @debug
end

.default_path_options ⇒ Object

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



64
65
66
67
68
69
70
71
72
73
 
# File 'lib/sprockets/helpers.rb', line 64

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

.digest ⇒ Object

When true, the asset paths will return digest paths.



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

def digest
  @digest
end

.environment ⇒ Object

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



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

def environment
  @environment
end

.expand ⇒ Object

When true, expand assets.



22
23
24
 
# File 'lib/sprockets/helpers.rb', line 22

def expand
  @expand
end

.manifest ⇒ Object

The manifest file used for lookup



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

def manifest
  @manifest
end

.prefix ⇒ Object

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



40
41
42
43
 
# File 'lib/sprockets/helpers.rb', line 40

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

.protocol ⇒ Object

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



49
50
51
 
# File 'lib/sprockets/helpers.rb', line 49

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

.public_path ⇒ Object

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



57
58
59
 
# File 'lib/sprockets/helpers.rb', line 57

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.



83
84
85
86
87
88
89
90
91
92
 
# File 'lib/sprockets/helpers.rb', line 83

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:



77
78
79
 
# File 'lib/sprockets/helpers.rb', line 77

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'



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/sprockets/helpers.rb', line 127

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

  options[:prefix] = Sprockets::Helpers.prefix unless options[:prefix]

  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, source, 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) 


154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/sprockets/helpers.rb', line 154

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'



204
205
206
 
# File 'lib/sprockets/helpers.rb', line 204

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'



228
229
230
 
# File 'lib/sprockets/helpers.rb', line 228

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'



252
253
254
 
# File 'lib/sprockets/helpers.rb', line 252

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'



277
278
279
 
# File 'lib/sprockets/helpers.rb', line 277

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

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



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

def javascript_tag(source, options = {})
  options = Helpers.default_path_options[:javascript_path].merge(options)
  asset_tag(source, options) do |path|
    %Q(<script src="#{path}" type="text/javascript"></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'



302
303
304
 
# File 'lib/sprockets/helpers.rb', line 302

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

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



176
177
178
179
180
181
182
183
 
# File 'lib/sprockets/helpers.rb', line 176

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" type="text/css" 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'



326
327
328
 
# File 'lib/sprockets/helpers.rb', line 326

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