Class: Sprockets::Context

Relationships & Source Files
Namespace Children
Classes: `ENVProxy`
Inherits:	Object
Defined in:	lib/sprockets/context.rb

Overview

They are typically accessed by ERB templates. You can mix in custom helpers by injecting them into Environment#context_class. Do not mix them into Context directly.

environment.context_class.class_eval do
  include MyHelper
  def asset_url; end
end

<%= asset_url "foo.png" %>

The Context also collects dependencies declared by assets. See DirectiveProcessor for an example of this.

Class Method Summary

.new(input) ⇒ Context constructor

Instance Attribute Summary

#content_type readonly

Returns content type of file.
#environment readonly
#filename readonly
#load_path (also: #root_path) readonly

Returns the environment path that contains the file.
#logical_path readonly

Returns logical path without any file extensions.
#root_path readonly

Alias for #load_path.

Instance Method Summary

#asset_data_uri(path)

Returns a data: URI with the contents of the asset at the specified path, and marks that path as a dependency of the current file.
#asset_path(path, options = {})

Expands logical path to full url to asset.
#audio_path(path)

Expand logical audio asset path.
#depend_on(path)

depend_on allows you to state a dependency on a file without including it.
#depend_on_asset(path)

depend_on_asset allows you to state an asset dependency without including it.
#depend_on_env(key)

depend_on_env allows you to state a dependency on an environment variable.
#env_proxy
#font_path(path)

Expand logical font asset path.
#image_path(path)

Expand logical image asset path.
#javascript_path(path)

Expand logical javascript asset path.
#link_asset(path)

link_asset declares an external dependency on an asset without directly including it.
#load(uri)

Public: Load Asset by AssetURI and track it as a dependency.
#metadata
#require_asset(path)

require_asset declares path as a dependency of the file.
#resolve(path, **kargs)

Public: Given a logical path, resolve will find and return an Asset URI.
#stub_asset(path)

stub_asset blacklists path from being included in the bundle.
#stylesheet_path(path)

Expand logical stylesheet asset path.
#video_path(path)

Expand logical video asset path.

Constructor Details

.new(input) ⇒ `Context`

[ GitHub ]

# File 'lib/sprockets/context.rb', line 42


def initialize(input)
  @environment  = input[:environment]
  @metadata     = input[:metadata]
  @load_path    = input[:load_path]
  @logical_path = input[:name]
  @filename     = input[:filename]
  @dirname      = File.dirname(@filename)
  @content_type = input[:content_type]

  @required     = Set.new(@metadata[:required])
  @stubbed      = Set.new(@metadata[:stubbed])
  @links        = Set.new(@metadata[:links])
  @dependencies = Set.new(input[:metadata][:dependencies])
end

Instance Attribute Details

#content_type (readonly)

Returns content type of file

'application/javascript'
'text/css'

[ GitHub ]

# File 'lib/sprockets/context.rb', line 88


attr_reader :content_type

#environment (readonly)

[ GitHub ]

# File 'lib/sprockets/context.rb', line 40


attr_reader :environment, :filename

#filename (readonly)

[ GitHub ]

# File 'lib/sprockets/context.rb', line 40


attr_reader :environment, :filename

#load_path (readonly) Also known as: #root_path

Returns the environment path that contains the file.

If app/javascripts and app/stylesheets are in your path, and current file is app/javascripts/foo/bar.js, load_path would return app/javascripts.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 73


attr_reader :load_path

#logical_path (readonly)

Returns logical path without any file extensions.

'app/javascripts/application.js'
# => 'application'

[ GitHub ]

# File 'lib/sprockets/context.rb', line 81


attr_reader :logical_path

#root_path (readonly)

Alias for #load_path.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 74


alias_method :root_path, :load_path

Instance Method Details

#asset_data_uri(path)

Returns a data: URI with the contents of the asset at the specified path, and marks that path as a dependency of the current file.

Uses URI encoding for SVG files, base64 encoding for all the other files.

Use asset_data_uri from ERB with CSS or JavaScript assets:

#logo { background: url(<%= asset_data_uri 'logo.png' %>) }

$('<img>').attr('src', '<%= asset_data_uri 'avatar.jpg' %>')

[ GitHub ]

# File 'lib/sprockets/context.rb', line 201


def asset_data_uri(path)
  asset = depend_on_asset(path)
  if asset.content_type == 'image/svg+xml'
    svg_asset_data_uri(asset)
  else
    base64_asset_data_uri(asset)
  end
end

#asset_path(path, options = {})

Expands logical path to full url to asset.

NOTE: This helper is currently not implemented and should be customized by the application. Though, in the future, some basic implementation may be provided with different methods that are required to be overridden.

Raises:

(NotImplementedError)

[ GitHub ]

# File 'lib/sprockets/context.rb', line 216


def asset_path(path, options = {})
  message = <<-EOS
Custom asset_path helper is not implemented

Extend your environment context with a custom method.

environment.context_class.class_eval do
  def asset_path(path, options = {})
  end
end
  EOS
  raise NotImplementedError, message
end

#audio_path(path)

Expand logical audio asset path.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 241


def audio_path(path)
  asset_path(path, type: :audio)
end

#depend_on(path)

depend_on allows you to state a dependency on a file without including it.

This is used for caching purposes. Any changes made to the dependency file will invalidate the cache of the source file.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 128


def depend_on(path)
  if environment.absolute_path?(path) && environment.stat(path)
    @dependencies << environment.build_file_digest_uri(path)
  else
    resolve(path)
  end
  nil
end

#depend_on_asset(path)

depend_on_asset allows you to state an asset dependency without including it.

This is used for caching purposes. Any changes that would invalidate the dependency asset will invalidate the source file. Unlike #depend_on, this will recursively include the target asset’s dependencies.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 144


def depend_on_asset(path)
  load(resolve(path))
end

#depend_on_env(key)

depend_on_env allows you to state a dependency on an environment variable.

This is used for caching purposes. Any changes in the value of the environment variable will invalidate the cache of the source file.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 153


def depend_on_env(key)
  @dependencies << "env:#{key}"
end

#env_proxy

[ GitHub ]

# File 'lib/sprockets/context.rb', line 64


def env_proxy
  ENVProxy.new(self)
end

#font_path(path)

Expand logical font asset path.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 246


def font_path(path)
  asset_path(path, type: :font)
end

#image_path(path)

Expand logical image asset path.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 231


def image_path(path)
  asset_path(path, type: :image)
end

#javascript_path(path)

Expand logical javascript asset path.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 251


def javascript_path(path)
  asset_path(path, type: :javascript)
end

#link_asset(path)

link_asset declares an external dependency on an asset without directly including it. The target asset is returned from this function making it easy to construct a link to it.

Returns an Asset or nil.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 184


def link_asset(path)
  asset = depend_on_asset(path)
  @links << asset.uri
  asset
end

#load(uri)

Public: Load Asset by AssetURI and track it as a dependency.

uri - AssetURI

Returns Asset.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 116


def load(uri)
  asset = environment.load(uri)
  @dependencies.merge(asset.metadata[:dependencies])
  asset
end

#metadata

[ GitHub ]

# File 'lib/sprockets/context.rb', line 57


def metadata
  { required: @required,
    stubbed: @stubbed,
    links: @links,
    dependencies: @dependencies }
end

#require_asset(path)

require_asset declares path as a dependency of the file. The dependency will be inserted before the file and will only be included once.

If ERB processing is enabled, you can use it to dynamically require assets.

<%= require_asset "#{framework}.js" %>

[ GitHub ]

# File 'lib/sprockets/context.rb', line 166


def require_asset(path)
  @required << resolve(path, accept: @content_type, pipeline: :self)
  nil
end

#resolve(path, **kargs)

Public: Given a logical path, resolve will find and return an Asset URI. Relative paths will also be resolved. An accept type maybe given to restrict the search.

resolve("foo.js")
# => "file:///path/to/app/javascripts/foo.js?type=application/javascript"

resolve("./bar.js")
# => "file:///path/to/app/javascripts/bar.js?type=application/javascript"

path - String logical or absolute path accept - String content accept type

Returns an Asset URI String.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 104


def resolve(path, **kargs)
  kargs[:base_path] = @dirname
  uri, deps = environment.resolve!(path, **kargs)
  @dependencies.merge(deps)
  uri
end

#stub_asset(path)

stub_asset blacklists path from being included in the bundle. path must be an asset which may or may not already be included in the bundle.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 174


def stub_asset(path)
  @stubbed << resolve(path, accept: @content_type, pipeline: :self)
  nil
end

#stylesheet_path(path)

Expand logical stylesheet asset path.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 256


def stylesheet_path(path)
  asset_path(path, type: :stylesheet)
end

#video_path(path)

Expand logical video asset path.

[ GitHub ]

# File 'lib/sprockets/context.rb', line 236


def video_path(path)
  asset_path(path, type: :video)
end

Class: Sprockets::Context

Overview

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(input) ⇒ Context

Instance Attribute Details

#content_type (readonly)

#environment (readonly)

#filename (readonly)

#load_path (readonly) Also known as: #root_path

#logical_path (readonly)

#root_path (readonly)

Instance Method Details

#asset_data_uri(path)

#asset_path(path, options = {})

#audio_path(path)

#depend_on(path)

#depend_on_asset(path)

#depend_on_env(key)

#env_proxy

#font_path(path)

#image_path(path)

#javascript_path(path)

#link_asset(path)

#load(uri)

#metadata

#require_asset(path)

#resolve(path, **kargs)

#stub_asset(path)

#stylesheet_path(path)

#video_path(path)

.new(input) ⇒ `Context`