class Sprockets::Context - sprockets-2.11.3 Documentation

# class Sprockets::Context

`Context` provides helper methods to all `Tilt` processors. 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.

### Attributes

__LINE__[W]
_dependency_assets[R]
_dependency_paths[R]
_required_paths[R]
_stubbed_assets[R]
environment[R]
pathname[R]

### Public Class Methods

new(environment, logical_path, pathname) click to toggle source

    # File lib/sprockets/context.rb, line 29
    def initialize(environment, logical_path, pathname)
      @environment  = environment
      @logical_path = logical_path
      @pathname     = pathname
      @__LINE__     = nil

      @_required_paths    = []
      @_stubbed_assets    = Set.new
      @_dependency_paths  = Set.new
      @_dependency_assets = Set.new([pathname.to_s])
    end

### Public Instance Methods

asset_data_uri(path) click to toggle source

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

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' %>')

    # File lib/sprockets/context.rb, line 217
    def asset_data_uri(path)
      depend_on_asset(path)
      asset  = environment.find_asset(path)
      base64 = Base64.encode64(asset.to_s).gsub(/\s+/, "")
      "data:#{asset.content_type};base64,#{Rack::Utils.escape(base64)}"
    end

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

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 basics implemention may be provided with different methods that are required to be overridden.

    # File lib/sprockets/context.rb, line 230
        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

asset_requirable?(path) click to toggle source

Tests if target path is able to be safely required into the current concatenation.

    # File lib/sprockets/context.rb, line 162
    def asset_requirable?(path)
      pathname = resolve(path)
      content_type = environment.content_type_of(pathname)
      stat = environment.stat(path)
      return false unless stat && stat.file?
      self.content_type.nil? || self.content_type == content_type
    end

audio_path(path) click to toggle source

Expand logical audio asset path.

    # File lib/sprockets/context.rb, line 255
    def audio_path(path)
      asset_path(path, :type => :audio)
    end

content_type() click to toggle source

Returns content type of file

    'application/javascript'
    'text/css'

    # File lib/sprockets/context.rb, line 64
    def content_type
      environment.content_type_of(pathname)
    end

depend_on(path) click to toggle source

`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 with invalidate the cache of the source file.

    # File lib/sprockets/context.rb, line 118
    def depend_on(path)
      @_dependency_paths << resolve(path).to_s
      nil
    end

depend_on_asset(path) click to toggle source

`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 include recursively include the target asset's dependencies.

    # File lib/sprockets/context.rb, line 130
    def depend_on_asset(path)
      filename = resolve(path).to_s
      @_dependency_assets << filename
      nil
    end

evaluate(path, options = {}) click to toggle source

Reads `path` and runs processors on the file.

This allows you to capture the result of an asset and include it directly in another.

    <%= evaluate "bar.js" %>

    # File lib/sprockets/context.rb, line 177
    def evaluate(path, options = {})
      pathname   = resolve(path)
      attributes = environment.attributes_for(pathname)
      processors = options[:processors] || attributes.processors

      if options[:data]
        result = options[:data]
      else
        if environment.respond_to?(:default_external_encoding)
          mime_type = environment.mime_types(pathname.extname)
          encoding  = environment.encoding_for_mime_type(mime_type)
          result    = Sprockets::Utils.read_unicode(pathname, encoding)
        else
          result = Sprockets::Utils.read_unicode(pathname)
        end
      end

      processors.each do |processor|
        begin
          template = processor.new(pathname.to_s) { result }
          result = template.render(self, {})
        rescue Exception => e
          annotate_exception! e
          raise
        end
      end

      result
    end

font_path(path) click to toggle source

Expand logical font asset path.

    # File lib/sprockets/context.rb, line 260
    def font_path(path)
      asset_path(path, :type => :font)
    end

image_path(path) click to toggle source

Expand logical image asset path.

    # File lib/sprockets/context.rb, line 245
    def image_path(path)
      asset_path(path, :type => :image)
    end

javascript_path(path) click to toggle source

Expand logical javascript asset path.

    # File lib/sprockets/context.rb, line 265
    def javascript_path(path)
      asset_path(path, :type => :javascript)
    end

logical_path() click to toggle source

Returns logical path without any file extensions.

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

    # File lib/sprockets/context.rb, line 55
    def logical_path
      @logical_path.chomp(File.extname(@logical_path))
    end

require_asset(path) click to toggle source

`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" %>

    # File lib/sprockets/context.rb, line 145
    def require_asset(path)
      pathname = resolve(path, :content_type => :self)
      depend_on_asset(pathname)
      @_required_paths << pathname.to_s
      nil
    end

resolve(path, options = {}, &block) click to toggle source

Given a logical path, `resolve` will find and return the fully expanded path. Relative paths will also be resolved. An optional `:content_type` restriction can be supplied to restrict the search.

    resolve("foo.js")
    # => "/path/to/app/javascripts/foo.js"

    resolve("./bar.js")
    # => "/path/to/app/javascripts/bar.js"

    # File lib/sprockets/context.rb, line 79
    def resolve(path, options = {}, &block)
      pathname   = Pathname.new(path)
      attributes = environment.attributes_for(pathname)

      if pathname.absolute?
        if environment.stat(pathname)
          pathname
        else
          raise FileNotFound, "couldn't find file '#{pathname}'"
        end

      elsif content_type = options[:content_type]
        content_type = self.content_type if content_type == :self

        if attributes.format_extension
          if content_type != attributes.content_type
            raise ContentTypeMismatch, "#{path} is " +
              "'#{attributes.content_type}', not '#{content_type}'"
          end
        end

        resolve(path) do |candidate|
          if self.content_type == environment.content_type_of(candidate)
            return candidate
          end
        end

        raise FileNotFound, "couldn't find file '#{path}'"
      else
        environment.resolve(path, {:base_path => self.pathname.dirname}.merge(options), &block)
      end
    end

root_path() click to toggle source

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`, `root_path` would return `app/javascripts`.

    # File lib/sprockets/context.rb, line 46
    def root_path
      environment.paths.detect { |path| pathname.to_s[path] }
    end

stub_asset(path) click to toggle source

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

    # File lib/sprockets/context.rb, line 155
    def stub_asset(path)
      @_stubbed_assets << resolve(path, :content_type => :self).to_s
      nil
    end

stylesheet_path(path) click to toggle source

Expand logical stylesheet asset path.

    # File lib/sprockets/context.rb, line 270
    def stylesheet_path(path)
      asset_path(path, :type => :stylesheet)
    end

video_path(path) click to toggle source

Expand logical video asset path.

    # File lib/sprockets/context.rb, line 250
    def video_path(path)
      asset_path(path, :type => :video)
    end

### Private Instance Methods

annotate_exception!(exception) click to toggle source

Annotates exception backtrace with the original template that the exception was raised in.

    # File lib/sprockets/context.rb, line 277
    def annotate_exception!(exception)
      location = pathname.to_s
      location << ":#{@__LINE__}" if @__LINE__

      exception.extend(Sprockets::EngineError)
      exception.sprockets_annotation = "  (in #{location})"
    end

logger() click to toggle source

    # File lib/sprockets/context.rb, line 285
    def logger
      environment.logger
    end