antw-kin 0.3.2 → 0.3.3

data/lib/kin/nav/helper_mixin.rb

@@ -44,7 +44,7 @@ module Kin
       # @api public
       #
       def display_navigation(name, options = {})
-        (options[:formatter] || Merb::Plugins.config[:kin][:nav_formatter]).new(
+        (options[:formatter] || Kin::Nav.get(name).formatter).new(
           Kin::Nav.get(name), self, options
         ).to_html
       end

data/lib/kin/sprites.rb

@@ -0,0 +1,100 @@
+require 'rmagick'
+
+module Kin
+  ##
+  # Takes 16x16 pixel icons and smushes them all together in to one sprite.
+  # Not auto-loaded, so remember to require 'kin/sprites' if you need it.
+  #
+  module Sprites
+    SpriteError = Class.new(StandardError)
+
+    ##
+    # A simple class which represents a list of icons (wrapper around an
+    # array).
+    #
+    class IconSet
+      include Enumerable
+
+      ##
+      # Creates a new IconSet instance.
+      #
+      # @param [Array<String>] icons
+      #   An array of source icon files.
+      #
+      def initialize(icons)
+        @icons = icons.uniq
+      end
+
+      ##
+      # Returns the vertical offset of a given icon in a sprite.
+      #
+      # @param [String]
+      #   The name of an icon which appears in the list.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   list = IconSet.new(%w( one two three ))
+      #   list.location_of('one')   # => 0
+      #   list.location_of('two')   # => 40
+      #   list.location_of('three') # => 80
+      #
+      # @raise [ArgumentError]
+      #   Raises an ArgumentError if the given icon does not appear in the
+      #   list.
+      #
+      def location_of(icon)
+        unless @icons.include?(icon)
+          raise ArgumentError, "Icon does not appear in the list: #{icon}"
+        end
+
+        @icons.index(icon) * 40
+      end
+
+      ##
+      # Loops through, and yields, each icon in turn.
+      #
+      # @yield [String] The icon name.
+      #
+      def each
+        @icons.each { |i| yield i }
+      end
+
+      ##
+      # Returns the number of icons in this set.
+      #
+      # @return [Integer]
+      #
+      def length
+        @icons.length
+      end
+
+      ##
+      # Returns a slice of the set. Note: This returns a Set, not an IconSet.
+      #
+      # @param [Numeric, Range] slice
+      #   The element or range of elements to return.
+      #
+      # @return [Set]
+      #
+      def [](*slice)
+        @icons[*slice]
+      end
+
+      ##
+      # Returns a hash for the icon list. Assuming the list contains the same
+      # icons, and in the same order, the hash will always be the same.
+      #
+      # @return [String]
+      #
+      def hash
+        Digest::SHA256.hexdigest(@icons.join("|"))
+      end
+    end # IconSet
+  end # Sprites
+end # Kin
+
+sprites = File.expand_path(File.join(File.dirname(__FILE__), 'sprites'))
+
+require File.join(sprites, 'image_generator')
+require File.join(sprites, 'sass_generator')

data/lib/kin/sprites/image_generator.rb

@@ -0,0 +1,75 @@
+module Kin
+  module Sprites
+    ##
+    # Responsible for taking source icon files and creating a sprite.
+    #
+    class ImageGenerator
+      IconNotReadable = Class.new(SpriteError)
+      TargetNotWriteable = Class.new(SpriteError)
+
+      ##
+      # Creates a new Generator instance.
+      #
+      # @param [IconSet] set
+      #   An IconSet instance.
+      # @param [String] source_dir
+      #   A path to the directory in which the source files reside.
+      #
+      # @api public
+      #
+      def initialize(set, source_dir)
+        @set, @source_dir = set, source_dir
+      end
+
+      ##
+      # Uses RMagick to create a transparent PNG containing the individual
+      # icons as a sprite.
+      #
+      # If a file already exists at the given path it will be overwritten.
+      #
+      # @param [String] path
+      #   The path at which to save the sprite.
+      #
+      # @raise [Kin::Sprites::ImageGenerator::IconNotReadable]
+      #   Raised when an icon could not be found.
+      #
+      # @raise [Kin::Sprites::ImageGenerator::TargetNotWriteable]
+      #   Raised when RMagick couldn't save the image because the target path
+      #   was not writeable.
+      #
+      # @raise [Magick::ImageMagickError]
+      #   Raised if some other error occured with RMagick.
+      #
+      # @api public
+      #
+      def save(path)
+        list = @set.inject(Magick::ImageList.new) do |m, icon|
+          m << Magick::Image.read(File.join(@source_dir, "#{icon}.png"))[0]
+        end
+
+        # RMagick uses instance_eval, @set isn't available in the block below.
+        set_length = @set.length
+
+        montage = list.montage do
+          # Transparent background.
+          self.background_color = '#FFF0'
+          # Each icon is 16x16 with 12 pixels of top & bottom padding = 16x40.
+          self.geometry = Magick::Geometry.new(16, 16, 0, 12)
+          self.tile = Magick::Geometry.new(1, set_length)
+        end
+
+        # Remove the blank space from both the top and bottom of the image.
+        montage.crop!(0, 12, 0, (40 * set_length) - 24)
+        montage.write("PNG32:#{path}")
+      rescue Magick::ImageMagickError => ex
+        # Nicely rescue and re-raise if the target directory wasn't writable,
+        # or if one of the icon files could not be opened.
+        case ex.message
+          when /Permission denied/ then raise TargetNotWriteable, ex.message
+          when /unable to open/    then raise IconNotReadable, ex.message
+          else                          raise ex
+        end
+      end
+    end # ImageGenerator
+  end # Sprites
+end # Kin

data/lib/kin/sprites/rake_runner.rb

@@ -0,0 +1,179 @@
+require 'digest/sha2'
+
+module Kin
+  module Sprites
+    ##
+    # A Rake helper which generates all the sprites for a given application.
+    #
+    # RakeRunner expects a sprites.yml config file which defines the sprites
+    # and the icons in each sprite. The contents of each sprites are hashed
+    # and cached in a .hashes file (the the same directory as the saved
+    # sprites) so that re-running the task won't result in them being
+    # re-generated. See README for examples.
+    #
+    # Not auto-loaded by requiring either 'kin' or 'kin/sprites'; if you want
+    # this Rake helper you need to require it explicitly.
+    #
+    class RakeRunner
+      TEMPLATE = File.read(__FILE__).split(/^__END__/)[1]
+
+      SetInfo = Struct.new(:name, :set, :skipped)
+
+      ##
+      # Creates a new Generator instance.
+      #
+      # @param [String] sprites_yml
+      #   The path to the sprites.yml file which defines the sprites.
+      # @param [String] sprites_dir
+      #   The path to sprites directory, in which the generated sprites will
+      #   be saved. The source icons will be assumed to be in a src/
+      #   subdirectory.
+      # @param [String] sass_partial
+      #   The path where the SASS partial should be saved.
+      #
+      # @raise [SpriteError]
+      #   Raised if the sprites.yml file wasn't at the specified path.
+      #
+      # @api public
+      #
+      def initialize(sprites_yml, sprites_dir, sass_partial)
+        @sprites_yml  = sprites_yml
+        @sprites_dir  = sprites_dir
+        @sass_partial = sass_partial
+        @source_dir   = File.join(@sprites_dir, 'src')
+        @dot_hashes   = File.join(@sprites_dir, '.hashes')
+
+        unless File.exists?(@sprites_yml)
+          raise SpriteError,
+            "sprites.yml not found; expected to be at: #{@sprites_yml}"
+        end
+
+        @sets = YAML.load(File.read(@sprites_yml)).map do |name, icons|
+          SetInfo.new(name, Kin::Sprites::IconSet.new(icons), false)
+        end
+
+        # Sort the sets in alphanumeric order such that SASS partials don't
+        # radically change when regenerated (since Ruby 1.8's hash is
+        # unordered)
+        @sets.sort! { |left, right| left.name <=> right.name }
+      end
+
+      ##
+      # Generates the sprite images, and creates a _sprites.sass partial.
+      #
+      # @param [Boolean] force
+      #   Regenerate sprite images even if the existing image contains the
+      #   exact same icons as the new one will.
+      #
+      # @api public
+      #
+      def generate!(force = false)
+        @sets.each do |set|
+          generate_sprite!(set, force)
+        end
+
+        if @sets.any? { |set| not set.skipped }
+          generate_sass!
+          dump_hashes!
+        end
+
+        $stdout.puts
+        $stdout.puts("All done.")
+      end
+
+      private # ==============================================================
+
+      ##
+      # Generates a single sprite.
+      #
+      # @api private
+      #
+      def generate_sprite!(setinfo, force)
+        if requires_regenerating?(setinfo) or force
+          gen = Kin::Sprites::ImageGenerator.new(setinfo.set, @source_dir)
+          gen.save(File.join(@sprites_dir, "#{setinfo.name}.png"))
+          $stdout.puts("Regenerated #{setinfo.name.inspect} sprite.")
+        else
+          # Existing sprite file is identical, and the user doesn't want to
+          # force re-creating the file.
+          setinfo.skipped = true
+          $stdout.puts("Ignoring #{setinfo.name.inspect} sprite (unchanged).")
+        end
+      end
+
+      ##
+      # Generates the SASS partial for all sprites.
+      #
+      # @api private
+      #
+      def generate_sass!
+        sass = @sets.map do |setinfo|
+          set_sass = "// #{setinfo.name} sprite "
+          set_sass += "=" * (80 - 13 - setinfo.name.length)
+          set_sass += Kin::Sprites::SassGenerator.new(
+            setinfo.set, setinfo.name).to_sass('/images/sprites')
+        end.join("\n")
+
+        FileUtils.mkdir_p(File.dirname(@sass_partial))
+
+        File.open(@sass_partial, 'w') do |f|
+          f.puts(TEMPLATE.sub(/^SASS/, sass))
+        end
+
+        $stdout.puts('Saved SASS partial.')
+      end
+
+      ##
+      # Creates a fresh .hashes file containing hashes for the currently
+      # loaded sets.
+      #
+      # @api private
+      #
+      def dump_hashes!
+        hashes = @sets.inject({}) do |hashes, setinfo|
+          hashes[setinfo.name] = setinfo.set.hash ; hashes
+        end
+
+        File.open(@dot_hashes, 'w') do |f|
+          f.puts(YAML.dump(hashes))
+        end
+      end
+
+      ##
+      # Returns if a sprite needs to be regenerated.
+      #
+      # @api private
+      #
+      def requires_regenerating?(setinfo)
+        hash_for(setinfo.name) != setinfo.set.hash ||
+          (! File.exists?(File.join(@sprites_dir, "#{setinfo.name}.png")))
+      end
+
+      ##
+      # Returns the hash checksum for the current sprite file, if it exists.
+      #
+      # @param [String] name
+      #   The name of the sprite to check.
+      #
+      # @return [String, nil]
+      #   Returns a string if a hash was available, otherwise nil.
+      #
+      # @api private
+      #
+      def hash_for(name)
+        @_sprite_hashes ||= begin
+          File.exists?(@dot_hashes) ? YAML.load(File.read(@dot_hashes)) : {}
+        end
+
+        @_sprite_hashes[name]
+      end
+    end # RakeTaskRunner
+  end # Sprites
+end # Kin
+
+__END__
+// The mixins in this file are automatically generated by the `sprites` rake
+// task provided in the Kin gem. Don't edit this file directly; rather you
+// should change config/sprites.yaml and then run `rake sprites`.
+
+SASS

data/lib/kin/sprites/sass_generator.rb

@@ -0,0 +1,81 @@
+module Kin
+  module Sprites
+    ##
+    # Converts an IconSet to a SASS partial.
+    #
+    class SassGenerator
+      TEMPLATE = File.read(__FILE__).split(/^__END__/)[1]
+
+      ##
+      # Creates a new Generator instance.
+      #
+      # @param [IconSet] set
+      #   An IconSet instance.
+      # @param [String] name
+      #   The name of this sprite.
+      #
+      # @api public
+      #
+      def initialize(set, name)
+        @set, @name = set, name
+      end
+
+      ##
+      # Converts the icon set to a SASS partial.
+      #
+      # @param [String] dir
+      #   The web directory in which the sprite files are located (no trailing
+      #   space please).
+      #
+      # @api public
+      #
+      def to_sass(dir)
+        # Holds all the if/else statements.
+        conditions = []
+        conditions << if_statement(@set[0], true)
+        @set[1..-1].each { |icon| conditions << if_statement(icon) }
+
+        # Permits supplying an offset, rather than an icon name.
+        conditions << '  @else'
+        conditions << '    !pos = !icon'
+        conditions << ''
+
+        # Put the data into the template.
+        template = TEMPLATE.dup
+        template.gsub!(/NAME/, @name)
+        template.gsub!(/DIR/, dir)
+        template.gsub!(/CONDITIONS/, conditions.join("\n"))
+        template
+      end
+
+      private
+
+      ##
+      # Creates an if statement for the given icon.
+      #
+      # @param [String] icon
+      #   The name of an icons
+      # @param [Boolean] is_first
+      #   Is this the first icon to appear in the if statement?
+      #
+      def if_statement(icon, is_first = false)
+        else_modifier = is_first ? '' : 'else '
+
+        %[  @#{else_modifier}if !icon == "#{icon}"\n] +
+        %[    !pos = -#{@set.location_of(icon)}px]
+      end
+    end # SassGenerator
+  end # Sprites
+end # Kin
+
+__END__
+
+=NAME-icon(!icon, !hpos = 0px, !voff = 0px)
+  !pos = !voff
+CONDITIONS
+  :background = "url(DIR/NAME.png)" !hpos !pos "no-repeat"
+
+=NAME-icon-pos(!icon, !hpos = 0px, !voff = 0px)
+  !pos = !voff
+CONDITIONS
+  :background-position = !hpos !pos