From e47fccd2ed6222e7b870c9e5554b24b2bde590fc Mon Sep 17 00:00:00 2001 From: Scott Davis Date: Fri, 25 Mar 2011 12:48:18 -0400 Subject: [PATCH] rdoc updates for sprite classes --- lib/compass/sass_extensions/sprites/base.rb | 26 +++++++++++++--- .../sprites/engines/chunky_png_engine.rb | 1 - lib/compass/sass_extensions/sprites/image.rb | 30 ++++++++++++++----- .../sass_extensions/sprites/sprite_map.rb | 18 +++++++++-- .../sass_extensions/sprites/sprites.rb | 7 +++-- 5 files changed, 65 insertions(+), 17 deletions(-) diff --git a/lib/compass/sass_extensions/sprites/base.rb b/lib/compass/sass_extensions/sprites/base.rb index e2f7251e..c50d047e 100644 --- a/lib/compass/sass_extensions/sprites/base.rb +++ b/lib/compass/sass_extensions/sprites/base.rb @@ -2,6 +2,10 @@ module Compass module SassExtensions module Sprites class Base < Sass::Script::Literal + + + # Initialize a new aprite object from a relative file path + # the path is relative to the images_path confguration option def self.from_uri(uri, context, kwargs) sprite_map = ::Compass::SpriteMap.new(uri.value, {}) @@ -10,7 +14,8 @@ module Compass end new(sprites, sprite_map.path, sprite_map.name, context, kwargs) end - + + # Loads the sprite engine def require_engine! self.class.send(:include, eval("::Compass::SassExtensions::Sprites::#{modulize}Engine")) end @@ -41,13 +46,15 @@ module Compass # Calculates the overal image dimensions # collects image sizes and input parameters for each sprite + # Calculates the height def compute_image_metadata! @width = 0 init_images compute_image_positions! @height = @images.last.top + @images.last.height end - + + # Creates the Sprite::Image objects for each image and calculates the width def init_images @images = image_names.collect do |relative_file| image = Compass::SassExtensions::Sprites::Image.new(self, relative_file, options) @@ -66,27 +73,34 @@ module Compass image.top = last_image.top + last_image.height + [image.spacing, last_image.spacing].max end end - + + # Fetches the Sprite::Image object for the supplied name def image_for(name) @images.detect { |img| img.name == name} end + # Returns true if the image name has a hover selector image def has_hover?(name) !image_for("#{name}_hover").nil? end + # Returns true if the image name has a target selector image def has_target?(name) !image_for("#{name}_target").nil? end + # Returns true if the image name has an active selector image def has_active?(name) !image_for("#{name}_active").nil? end + # Return and array of image names that make up this sprite def sprite_names image_names.map { |f| File.basename(f, '.png') } end + + # Validates that the sprite_names are valid sass def validate! for sprite_name in sprite_names unless sprite_name =~ /\A#{Sass::SCSS::RX::IDENT}\Z/ @@ -108,11 +122,13 @@ module Compass Compass.configuration.run_callback(:sprite_generated, sprite_data) end end - + + # Does this sprite need to be generated def generation_required? !File.exists?(filename) || outdated? end + # Returns the uniqueness hash for this sprite object def uniqueness_hash @uniqueness_hash ||= begin sum = Digest::MD5.new @@ -128,6 +144,7 @@ module Compass @uniqueness_hash end + # Saves the sprite engine def save!(output_png) saved = output_png.save filename Compass.configuration.run_callback(:sprite_saved, filename) @@ -147,6 +164,7 @@ module Compass true end + # Mtime of the sprite file def mtime File.mtime(filename) end diff --git a/lib/compass/sass_extensions/sprites/engines/chunky_png_engine.rb b/lib/compass/sass_extensions/sprites/engines/chunky_png_engine.rb index 1483b762..3a17d9e4 100644 --- a/lib/compass/sass_extensions/sprites/engines/chunky_png_engine.rb +++ b/lib/compass/sass_extensions/sprites/engines/chunky_png_engine.rb @@ -11,7 +11,6 @@ module Compass # Returns a PNG object def construct_sprite - #require_png_library! output_png = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::TRANSPARENT) images.each do |image| input_png = ChunkyPNG::Image.from_file(image.file) diff --git a/lib/compass/sass_extensions/sprites/image.rb b/lib/compass/sass_extensions/sprites/image.rb index 4ed352be..4a73ee8f 100644 --- a/lib/compass/sass_extensions/sprites/image.rb +++ b/lib/compass/sass_extensions/sprites/image.rb @@ -9,23 +9,28 @@ module Compass @base, @relative_file, @options = base, relative_file, options @left = @top = 0 end - + + # The Full path to the image def file File.join(Compass.configuration.images_path, relative_file) end - + + # Width of the image def width dimensions.first end - + + # Height of the image def height dimensions.last end - + + # Basename of the image def name File.basename(relative_file, '.png') end + # Value of $#{name}-repeat or $repeat def repeat [ "#{name}-repeat", "repeat" ].each { |which| if var = options.get_var(which) @@ -35,46 +40,57 @@ module Compass "no-repeat" end + # Value of $#{name}-position or $position defaults o 0px def position options.get_var("#{name}-position") || options.get_var("position") || Sass::Script::Number.new(0, ["px"]) end - + + # Offset within the sprite def offset (position.unitless? || position.unit_str == "px") ? position.value : 0 end - + + # Spacing between this image and the next def spacing (options.get_var("#{name}-spacing") || options.get_var("spacing") || Sass::Script::Number.new(0)).value end + # MD5 hash of this file def digest Digest::MD5.file(file).hexdigest end - + + # mtime of this file def mtime File.mtime(file) end + # Has hover selector def hover? base.has_hover?(name) end + # Hover selector Image object if exsists def hover base.image_for("#{name}_hover") end + # Has target selector def target? base.has_target?(name) end + # Target selector Image object if exsists def target base.image_for("#{name}_target") end + # Has active selector def active? base.has_active?(name) end + # Active selector Image object if exsists def active base.image_for("#{name}_active") end diff --git a/lib/compass/sass_extensions/sprites/sprite_map.rb b/lib/compass/sass_extensions/sprites/sprite_map.rb index ece478a7..fcbc823d 100644 --- a/lib/compass/sass_extensions/sprites/sprite_map.rb +++ b/lib/compass/sass_extensions/sprites/sprite_map.rb @@ -6,34 +6,41 @@ module Compass @uri, @options = uri, options end + # Name of this spite def name ensure_path_and_name! @name end + # The on-disk location of this sprite def path ensure_path_and_name! @path end - + + # Returns the Glob of image files for this sprite def files @files ||= Dir[File.join(Compass.configuration.images_path, uri)].sort end + # Returns an Array of image names without the file extension def sprite_names @sprite_names ||= files.collect { |file| File.basename(file, '.png') } end + # Returns the sass options for this sprite def sass_options @sass_options ||= options.merge(:filename => name, :syntax => :scss, :importer => self) end + # Returns the mtime of all image files combined def mtime Compass.quick_cache("mtime:#{uri}") do files.collect { |file| File.mtime(file) }.max end end - + + # Returns a Sass::Engine for this sprite object def sass_engine Sass::Engine.new(content_for_images, options) end @@ -45,6 +52,7 @@ module Compass @path, @name = $1, $3 end + # Generates the Sass for this sprite file def content_for_images(skip_overrides = false) <<-SCSS @import "compass/utilities/sprites/base"; @@ -94,7 +102,11 @@ $#{name}-prefix: '' !default; } SCSS end - + + # Generates the override defaults for this Sprite + # $#{name}-#{sprite_name}-position + # $#{name}-#{sprite_name}-spacing + # #{name}-#{sprite_name}-repeat: def generate_overrides content = <<-TXT // These variables control the generated sprite output diff --git a/lib/compass/sass_extensions/sprites/sprites.rb b/lib/compass/sass_extensions/sprites/sprites.rb index 5dea8570..fcac8979 100644 --- a/lib/compass/sass_extensions/sprites/sprites.rb +++ b/lib/compass/sass_extensions/sprites/sprites.rb @@ -1,15 +1,18 @@ module Compass class Sprites < Sass::Importers::Base + def find_relative(*args) nil end - + + # Called by the sass engine to build a new SpriteMap def find(uri, options) if uri =~ /\.png$/ SpriteMap.new(uri, options).sass_engine end end - + + # Called by the sass engine to identift the SpriteMap def key(uri, options) [self.class.name + ":" + File.dirname(File.expand_path(uri)), File.basename(uri)]