Module: Compass::SassExtensions::Functions::Sprites

### Home Classes Methods

### In Files

- lib/compass/sass_extensions/functions/sprites.rb

### Namespace

- MODULE Compass::SassExtensions::Functions::Sprites::VariableReader

### Methods

- #convert_sprite_name
- #get_sprite_file
- #inline_sprite
- #missing_image!
- #missing_sprite!
- #reversed_color_names
- #sprite
- #sprite_does_not_have_parent
- #sprite_file
- #sprite_has_selector
- #sprite_has_valid_selector
- #sprite_height
- #sprite_map
- #sprite_map_name
- #sprite_names
- #sprite_path
- #sprite_position
- #sprite_selector_file
- #sprite_url
- #sprite_width
- #verify_map
- #verify_sprite

### Included Modules

- Sass::Script::Value::Helpers

### Class/Module Index

Quicksearch

- Compass
- Compass::Actions
- Compass::AppIntegration
- Compass::AppIntegration::Helpers
- Compass::AppIntegration::StandAlone
- Compass::AppIntegration::StandAlone::ConfigurationDefaults
- Compass::AppIntegration::StandAlone::Installer
- Compass::Commands
- Compass::Commands::Base
- Compass::Commands::CleanProject
- Compass::Commands::CleanProjectOptionsParser
- Compass::Commands::CompileProjectOptionsParser
- Compass::Commands::ConfigurationOptionsParser
- Compass::Commands::CreateProject
- Compass::Commands::CreateProjectOptionsParser
- Compass::Commands::Default
- Compass::Commands::DefaultOptionsParser
- Compass::Commands::ExtensionCommand
- Compass::Commands::ExtensionOptionsParser
- Compass::Commands::ExtensionsOptionParser
- Compass::Commands::Help
- Compass::Commands::HelpOptionsParser
- Compass::Commands::Imports
- Compass::Commands::InstallerCommand
- Compass::Commands::Interactive
- Compass::Commands::InteractiveOptionsParser
- Compass::Commands::ListFrameworks
- Compass::Commands::PrintVersion
- Compass::Commands::ProjectBase
- Compass::Commands::ProjectStats
- Compass::Commands::Registry
- Compass::Commands::Sprite
- Compass::Commands::SpriteOptionsParser
- Compass::Commands::StampPattern
- Compass::Commands::StampPatternOptionsParser
- Compass::Commands::StatsOptionsParser
- Compass::Commands::StructureOptionsParser
- Compass::Commands::UnpackExtension
- Compass::Commands::UpdateProject
- Compass::Commands::ValidateProject
- Compass::Commands::ValidationOptionsParser
- Compass::Commands::VersionOptionsParser
- Compass::Commands::WriteConfiguration
- Compass::Compiler
- Compass::Configuration
- Compass::Configuration::Comments
- Compass::Configuration::Data
- Compass::Configuration::FileData
- Compass::Configuration::Helpers
- Compass::Configuration::Serialization
- Compass::Deprecation
- Compass::Exec
- Compass::Exec::CommandOptionParser
- Compass::Exec::GlobalOptionsParser
- Compass::Exec::Helpers
- Compass::Exec::ProjectOptionsParser
- Compass::Exec::SubCommandUI
- Compass::FilesystemConflict
- Compass::Installers
- Compass::Installers::BareInstaller
- Compass::Installers::Base
- Compass::Installers::Manifest
- Compass::Installers::Manifest::Entry
- Compass::Installers::ManifestInstaller
- Compass::Installers::TemplateContext
- Compass::Logger
- Compass::MissingDependency
- Compass::NullLogger
- Compass::SassCompiler
- Compass::SassExtensions
- Compass::SassExtensions::Functions
- Compass::SassExtensions::Functions::SassDeclarationHelper
- Compass::SassExtensions::Functions::Sprites
- Compass::SassExtensions::Functions::Sprites::VariableReader
- Compass::SassExtensions::Sprites
- Compass::SassExtensions::Sprites::ChunkyPngEngine
- Compass::SassExtensions::Sprites::Engine
- Compass::SassExtensions::Sprites::Image
- Compass::SassExtensions::Sprites::ImageMethods
- Compass::SassExtensions::Sprites::ImageRow
- Compass::SassExtensions::Sprites::Images
- Compass::SassExtensions::Sprites::Layout
- Compass::SassExtensions::Sprites::Layout::Diagonal
- Compass::SassExtensions::Sprites::Layout::Horizontal
- Compass::SassExtensions::Sprites::Layout::Smart
- Compass::SassExtensions::Sprites::Layout::SpriteLayout
- Compass::SassExtensions::Sprites::Layout::Vertical
- Compass::SassExtensions::Sprites::LayoutMethods
- Compass::SassExtensions::Sprites::RowFitter
- Compass::SassExtensions::Sprites::SpriteMap
- Compass::SassExtensions::Sprites::SpriteMethods
- Compass::SpriteException
- Compass::SpriteImporter
- Compass::Sprites
- Compass::Sprites::Binding
- Compass::Stats
- Compass::Stats::CssFile
- Compass::Stats::SassFile
- Compass::Stats::StatsVisitor
- Compass::TestCase
- Compass::Version
- Sass
- Sass::Script
- Sass::Script::Functions
- QuickCache

No matching classes.

# Compass::SassExtensions::Functions::Sprites

### Constants

BOOL_FALSE
IDENTIFIER_RX

  Determines if the CSS selector is valid

VALID_SELECTORS
ZERO

### Public Instance Methods

inline_sprite(map) click to toggle source

Returns the sprite file as an inline image

    @include "icon/*.png";
     #{$icon-sprite-base-class} {
       background-image: inline-sprite($icon-sprites);
      }

    # File lib/compass/sass_extensions/functions/sprites.rb, line 59
    def inline_sprite(map)
      verify_map(map, "sprite-url")
      map.generate
      path = map.filename
      inline_image_string(data(path), compute_mime_type(path))
    end

sprite(map, sprite, offset_x = ZERO, offset_y = ZERO, use_percentages = BOOL_FALSE) click to toggle source

Returns the image and background position for use in a single shorthand property:

    $icons: sprite-map("icons/*.png"); // contains icons/new.png among others.
    background: sprite($icons, new) no-repeat;

Becomes:

    background: url('/images/icons.png?12345678') 0 -24px no-repeat;

If the `use_percentages` parameter is passed as true, percentages will be used to position the sprite. Example output:

    background: url('/images/icons.png?12345678') 0 50% no-repeat;

    # File lib/compass/sass_extensions/functions/sprites.rb, line 96
    def sprite(map, sprite, offset_x = ZERO, offset_y = ZERO, use_percentages = BOOL_FALSE)
      sprite = convert_sprite_name(sprite)
      verify_map(map)
      verify_sprite(sprite)
      url = sprite_url(map)
      position = sprite_position(map, sprite, offset_x, offset_y, use_percentages)
      list([url] + position.value, :space)
    end

sprite_does_not_have_parent(map, sprite) click to toggle source

Returns boolean if sprite has a parent

    # File lib/compass/sass_extensions/functions/sprites.rb, line 133
    def sprite_does_not_have_parent(map, sprite)
      sprite = convert_sprite_name(sprite)
      verify_map map
      verify_sprite sprite
      bool(map.image_for(sprite.value).parent.nil?)
    end

sprite_file(map, sprite) click to toggle source

Returns the path to the original image file for the sprite with the given name

    # File lib/compass/sass_extensions/functions/sprites.rb, line 118
    def sprite_file(map, sprite)
      sprite = convert_sprite_name(sprite)
      verify_map(map, "sprite")
      verify_sprite(sprite)
      if image = map.image_for(sprite.value)
        image_path = Pathname.new(File.expand_path(image.file))
        images_path = Pathname.new(File.expand_path(Compass.configuration.images_path))
        quoted_string(image_path.relative_path_from(images_path).to_s)
      else
        missing_image!(map, sprite)
      end
    end

sprite_has_selector(map, sprite, selector) click to toggle source

Returns boolean if sprite has the selector

    # File lib/compass/sass_extensions/functions/sprites.rb, line 155
    def sprite_has_selector(map, sprite, selector)
      sprite = convert_sprite_name(sprite)
      verify_map map
      verify_sprite sprite
      unless VALID_SELECTORS.include?(selector.value)
        raise Sass::SyntaxError, "Invalid Selctor did you mean one of: #{VALID_SELECTORS.join(', ')}"
      end
      bool map.send(:"has_#{selector.value}?", sprite.value)
    end

sprite_has_valid_selector(selector) click to toggle source

    # File lib/compass/sass_extensions/functions/sprites.rb, line 169
    def sprite_has_valid_selector(selector)
      unless selector.value =~ IDENTIFIER_RX
        raise Sass::SyntaxError, "#{selector} must be a legal css identifier"
      end
      bool true
    end

sprite_height(map, sprite=nil) click to toggle source

Returns the height of the generated sprite map

    # File lib/compass/sass_extensions/functions/sprites.rb, line 31
    def sprite_height(map, sprite=nil)
      verify_map(map, 'sprite-height')
      file = get_sprite_file(map, sprite)
      _, height = image_dimensions(file)
      number(height, "px")
    end

sprite_map(glob, kwargs = {}) click to toggle source

Creates a Compass::SassExtensions::Sprites::SpriteMap object. A sprite map, when used in a property is the same as calling sprite-url. So the following background properties are equivalent:

    $icons: sprite-map("icons/*.png");
    background: sprite-url($icons) no-repeat;
    background: $icons no-repeat;

The sprite map object will generate the sprite map image, if necessary, the first time it is converted to a url. Simply constructing it has no side-effects.

    # File lib/compass/sass_extensions/functions/sprites.rb, line 76
    def sprite_map(glob, kwargs = {})
      kwargs.extend VariableReader
      Compass::SassExtensions::Sprites::SpriteMap.from_uri(glob, self, kwargs)
    end

sprite_map_name(map) click to toggle source

Returns the name of a sprite map The name is derived from the folder than contains the sprites.

    # File lib/compass/sass_extensions/functions/sprites.rb, line 111
    def sprite_map_name(map)
      verify_map(map, "sprite-map-name")
      identifier(map.name)
    end

sprite_names(map) click to toggle source

Returns a list of all sprite names

    # File lib/compass/sass_extensions/functions/sprites.rb, line 41
    def sprite_names(map)
      verify_map(map, 'sprite-names')
      list(map.sprite_names.map { |f| identifier(f) }, :comma)
    end

sprite_path(map) click to toggle source

Returns the system path of the sprite file

    # File lib/compass/sass_extensions/functions/sprites.rb, line 48
    def sprite_path(map)
      verify_map(map, 'sprite-path')
      identifier(map.filename)
    end

sprite_position(map, sprite = nil, offset_x = ZERO, offset_y = ZERO, use_percentages = BOOL_FALSE) click to toggle source

Returns the position for the original image in the sprite. This is suitable for use as a value to background-position:

    $icons: sprite-map("icons/*.png");
    background-position: sprite-position($icons, new);

Might generate something like:

    background-position: 0 -34px;

You can adjust the background relative to this position by passing values for `$offset-x` and `$offset-y`:

    $icons: sprite-map("icons/*.png");
    background-position: sprite-position($icons, new, 3px, -2px);

Would change the above output to:

    background-position: 3px -36px;

If you set the `use_percentages` parameter to true, the position will be expressed in percentages. An example:

    background-position: sprite-position($icons, new, 0, 0, true);

Would result in something like this:

    background-position: 0 42%;

    # File lib/compass/sass_extensions/functions/sprites.rb, line 213
    def sprite_position(map, sprite = nil, offset_x = ZERO, offset_y = ZERO, use_percentages = BOOL_FALSE)
      assert_type offset_x, :Number
      assert_type offset_y, :Number
      sprite = convert_sprite_name(sprite)
      verify_map(map, "sprite-position")
      unless sprite.is_a?(Sass::Script::Value::String) || sprite.is_a?(Sass::Script::Value::Number)
        raise Sass::SyntaxError, %(The second argument to sprite-position must be a sprite name. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
      end
      image = map.image_for(sprite.value)
      unless image
        missing_image!(map, sprite)
      end
      if use_percentages.value
        xdivis = map.width - image.width;
        x = (offset_x.value + image.left.to_f) / (xdivis.nonzero? || 1) * 100
        x = x == 0 ? number(x) : number(x, "%")
        ydivis = map.height - image.height;
        y = (offset_y.value + image.top.to_f) / (ydivis.nonzero? || 1) * 100
        y = y == 0 ? number(y) : number(y, "%")
      else
        if offset_x.unit_str == "%"
          x = offset_x # CE: Shouldn't this be a percentage of the total width?
        else
          x = offset_x.value - image.left
          x = x == 0 ? number(x) : number(x, "px")
        end
        y = offset_y.value - image.top
        y = y == 0 ? number(y) : number(y, "px")
      end
      list(x, y, :space)
    end

sprite_selector_file(map, sprite, selector) click to toggle source

return the name of the selector file

    # File lib/compass/sass_extensions/functions/sprites.rb, line 142
    def sprite_selector_file(map, sprite, selector)
      sprite = convert_sprite_name(sprite)
      image = map.image_for(sprite)
      if map.send(:"has_#{selector.value}?", sprite.value)
        return identifier(image.send(selector.value).name)
      end

      raise Sass::SyntaxError, "Sprite: #{sprite.value} does not have a #{selector} state"
    end

sprite_url(map) click to toggle source

Returns a url to the sprite image.

    # File lib/compass/sass_extensions/functions/sprites.rb, line 177
    def sprite_url(map)
      verify_map(map, "sprite-url")
      map.generate
      generated_image_url(identifier("#{map.path}-s#{map.uniqueness_hash}.png"))
    end

sprite_width(map, sprite=nil) click to toggle source

Returns the width of the generated sprite map

    # File lib/compass/sass_extensions/functions/sprites.rb, line 21
    def sprite_width(map, sprite=nil)
      verify_map(map, 'sprite-width')
      file = get_sprite_file(map, sprite)
      width, _ = image_dimensions(file)
      number(width, "px")
    end

### Protected Instance Methods

convert_sprite_name(sprite) click to toggle source

    # File lib/compass/sass_extensions/functions/sprites.rb, line 268
    def convert_sprite_name(sprite)
      case sprite
        when Sass::Script::Value::Color
          rgb = if reversed_color_names.keys.first.size == 3
                  sprite.rgb
                else
                  # Sass 3.3 includes the alpha channel
                  sprite.rgba
                end
          identifier(reversed_color_names[rgb])
        when Sass::Script::Value::Bool
          identifier(sprite.to_s)
        else
          sprite
      end
    end

get_sprite_file(map, sprite=nil) click to toggle source

    # File lib/compass/sass_extensions/functions/sprites.rb, line 252
    def get_sprite_file(map, sprite=nil)
      if sprite
        map.image_for(sprite).file
      else
        map.filename
      end
    end

missing_image!(map, sprite) click to toggle source

    # File lib/compass/sass_extensions/functions/sprites.rb, line 297
    def missing_image!(map, sprite)
      raise Sass::SyntaxError, "No sprite called #{sprite} found in sprite map #{map.path}/#{map.name}. Did you mean one of: #{map.sprite_names.join(", ")}"
    end

missing_sprite!(function_name) click to toggle source

    # File lib/compass/sass_extensions/functions/sprites.rb, line 301
    def missing_sprite!(function_name)
      raise Sass::SyntaxError, %(The first argument to #{function_name}() must be a sprite map. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
    end

reversed_color_names() click to toggle source

    # File lib/compass/sass_extensions/functions/sprites.rb, line 260
    def reversed_color_names
      if Sass::Script::Value::Color.const_defined?(:HTML4_COLORS_REVERSE)
        Sass::Script::Value::Color::HTML4_COLORS_REVERSE
      else
        Sass::Script::Value::Color::COLOR_NAMES_REVERSE
      end
    end

verify_map(map, error = "sprite") click to toggle source

    # File lib/compass/sass_extensions/functions/sprites.rb, line 285
    def verify_map(map, error = "sprite")
      unless map.is_a?(Compass::SassExtensions::Sprites::SpriteMap)
        missing_sprite!(error)
      end
    end

verify_sprite(sprite) click to toggle source

    # File lib/compass/sass_extensions/functions/sprites.rb, line 291
    def verify_sprite(sprite)
      unless sprite.is_a?(Sass::Script::Value::String) || sprite.is_a?(Sass::Script::Value::Number)
        raise Sass::SyntaxError, %(The second argument to sprite() must be a sprite name. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
      end
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.