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

Extended by:
SassDeclarationHelper, Sass::Script::Value::Helpers
Includes:
Sass::Script::Value::Helpers
Included in:
Sass::Script::Functions
Defined in:
lib/compass/sass_extensions/functions/sprites.rb

Defined Under Namespace

Modules: VariableReader

Constant Summary collapse

ZERO = 
number(0)
BOOL_FALSE = 
bool(false)
VALID_SELECTORS = 
%w(hover active target focus)
IDENTIFIER_RX =

Determines if the CSS selector is valid

/\A#{Sass::SCSS::RX::IDENT}\Z/

Instance Method Summary collapse

Methods included from SassDeclarationHelper

declare

Instance Method Details

#inline_sprite(map) ⇒ Object

Returns the sprite file as an inline image

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



59
60
61
62
63
64
 
# 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) ⇒ Object

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;



96
97
98
99
100
101
102
103
 
# 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) ⇒ Object

Returns boolean if sprite has a parent



133
134
135
136
137
138
 
# 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) ⇒ Object

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



118
119
120
121
122
123
124
125
126
127
128
129
 
# 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) ⇒ Object

Returns boolean if sprite has the selector



155
156
157
158
159
160
161
162
163
 
# 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) ⇒ Object 



169
170
171
172
173
174
 
# 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) ⇒ Object

Returns the height of the generated sprite map



31
32
33
34
35
36
 
# 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 = {}) ⇒ Object

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.



76
77
78
79
 
# 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) ⇒ Object

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



111
112
113
114
 
# 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) ⇒ Object

Returns a list of all sprite names



41
42
43
44
 
# 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) ⇒ Object

Returns the system path of the sprite file



48
49
50
51
 
# 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) ⇒ Object

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%;



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# 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, %Q(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) ⇒ Object

return the name of the selector file

Raises:

  • (Sass::SyntaxError) 


142
143
144
145
146
147
148
149
150
 
# 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) ⇒ Object

Returns a url to the sprite image.



177
178
179
180
181
 
# 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) ⇒ Object

Returns the width of the generated sprite map



21
22
23
24
25
26
 
# 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