spriteful 0.2.0 → 0.3.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0368a10d14e6885315939bf705b93a6ee52da147
-  data.tar.gz: b1a79824842c4dd6d94ff7ac061d3344ee813684
+  metadata.gz: 9cf879ad9e9e6ef6d5979c18ba95057105fbdb43
+  data.tar.gz: ba2e166801f3893946ecd53330a2fa72d5da26bc
 SHA512:
-  metadata.gz: ce91faa1f865bc71bcd786fa376e609b62ea86fa147392ca9bca188e1e58af331e9f5fcfb58709345496ac31361156f70e18eba480eebf90efe36bfbabb394b1
-  data.tar.gz: 7e0e39fe26e733430c32e844bb5af0a99df132e3f1914be0ae3498fbaa666f8bc5f4dd50a3a9ee33207b2036a995e88d077fe5505aa18c951f2133695bcb882d
+  metadata.gz: 8e051ba566bc763e3c05c0c17959f5c96b9547854946605d548d1bcccad288debd826d11be58eb51e39e3084038e574be68b3cf228fcdd53aace8faf13c44b4f
+  data.tar.gz: dce408ad68c9a3518496ff6a0ea8e02a08a1c6cd63b42dbc607189e4c5bbbff976e4048bdc98a3291594288c7221d6a0a8947b8ae3e38e10df809d54c2e13317

data/README.md

@@ -121,6 +121,27 @@ images under `icons` will generate the `icons.png` and `icons.css` files. This c
 enforces previsibility over generated files and helps when regenating existing sprites whenever
 you need to add a new source to an existing sprite.
 
+## Custom templates
+
+If you need further customization of the sprite CSS, you can use a custom ERB template
+to be used instead of the builtin templates.
+
+```bash
+spriteful  image/icons --template custom_template.erb
+```
+
+In this case, the `custom_template.erb` file will be evaluated in the context of a
+`Spriteful::Template` instance. Please check this class documentation and source
+to see all the available attributes and helpers.
+
+You can copy one of the builtin templates to your working directory with the `template`
+subcommand.
+
+```bash
+spriteful template
+# create  spriteful.css
+```
+
 ## SVG Support
 
 Spriteful has a basic support for dealing with SVG images (and not only PNGs). SVG images
@@ -161,6 +182,7 @@ If you are using SVG images, the embedded SVG as data URI will be optimized with
 * `--destination` (`-d`) - Directory to save the generated image(s).
 * `--rails` (`-r`) - Forces rails specific settings, see [Spriteful and Rails](#spriteful-and-rails) for more info.
 * `--format` (`-f`) - Format to generate the sprite(s) stylesheet(s). Either "css" or "scss".
+* `--template` (`-t`) - The path for a custom Stylesheet template.
 * `--mixin` - Choose to use the Mixin Directives instead of Placeholder Selector.
 * `--horizontal` - Changes the sprite orientation to horizontal, since all sprites are combined vertically by default.
 * `--save` - Saves the provided arguments for later use.

data/lib/spriteful.rb

@@ -5,6 +5,7 @@ require 'spriteful/image'
 require 'spriteful/optimizer'
 require 'spriteful/sprite'
 require 'spriteful/stylesheet'
+require 'spriteful/template'
 
 module Spriteful
   class EmptySourceError < Thor::Error; end

data/lib/spriteful/cli.rb

@@ -12,6 +12,7 @@ module Spriteful
     class_option :stylesheets, aliases: '-s', banner: 'STYLESHEETS_DIR', type: :string, desc: 'Directory to save the generated stylesheet(s), instead of copying them to the clipboard.', default: Dir.pwd
     class_option :destination, aliases: '-d', banner: 'DESTINATION_DIR', type: :string, desc: 'Destination directory to save the combined image(s).', default: Dir.pwd
     class_option :root, aliases: '-r', banner: 'ROOT_DIR', type: :string, desc: 'Root folder from where your static files will be served.'
+    class_option :template, aliases: '-t', banner: 'TEMPLATE', type: :string, desc: 'Custom template file in ERB format to be used instead of the default.'
 
     class_option :mixin, type: :boolean, desc: 'Choose to use the Mixin Directives instead of Placeholder Selectors.'
     class_option :rails, type: :boolean, desc: 'Follow default conventions for a Rails application with the Asset Pipeline.'
@@ -46,7 +47,6 @@ module Spriteful
       end
 
       prepare_options!
-      Spriteful.options = ARGV.dup.uniq
 
       if sources.empty?
         self.class.help(shell)
@@ -61,6 +61,20 @@ module Spriteful
       save_options
     end
 
+    def template
+      create_file "spriteful.#{options.format}", Spriteful::Stylesheet.read_template(options.format)
+    end
+
+    protected
+    def self.dispatch(command, args, opts, config)
+      if args.first == 'template'
+        command = args.shift
+      else
+        command = 'execute'
+      end
+      super(command, args, opts, config)
+    end
+
     private
     # Internal: Gets an instance of `Spriteful::Optimizer`.
     def optimizer
@@ -92,19 +106,21 @@ module Spriteful
     #
     # Returns nothing.
     def save_options
-      if options.save?
-        options.delete(:save)
-        parts = sources + options.map { |key, value| ["--#{key}", value.to_s] }.flatten
-        create_file '.spritefulrc', Shellwords.join(parts) + "\n", force: true
+      if save_options?
+        parts = Shellwords.join(Spriteful.options)
+        create_file '.spritefulrc', parts + "\n", force: true
       end
     end
 
     def stylesheet_options
+      template = File.expand_path(options.template) if File.file?(options.template.to_s)
+
       {
         root: options.root,
         format: options.format,
         rails: options.rails?,
-        mixin: options.mixin?
+        mixin: options.mixin?,
+        template: template
       }
     end
 
@@ -120,11 +136,15 @@ module Spriteful
       }
     end
 
-    # Internal: Change the `options` hash if necessary, based on the
-    # 'rails' flag.
+    # Internal: Changes the `options` hash if necessary (based on the
+    # '--rails' flag) and store the original 'ARGV' array for further
+    # usage.
     #
     # Returns nothing.
     def prepare_options!
+      Spriteful.options = ARGV.dup.uniq
+      @save_options = !!Spriteful.options.delete('--save')
+
       if options.rails?
         sources.concat(detect_sources)
         set_rails_defaults
@@ -146,5 +166,13 @@ module Spriteful
       options['stylesheets'] = File.expand_path('app/assets/stylesheets/sprites')
       options['destination'] = File.expand_path('app/assets/images/sprites')
     end
+
+    # Internal: Checks if we should save the supplied user arguments into
+    # the rcfile.
+    #
+    # Returns true or false.
+    def save_options?
+      @save_options
+    end
   end
 end

data/lib/spriteful/stylesheet.rb

@@ -1,5 +1,3 @@
-require 'erb'
-require 'pathname'
 require 'base64'
 
 module Spriteful
@@ -15,6 +13,9 @@ module Spriteful
     # Public: returns the path where the Stylesheet should be stored.
     attr_reader :path
 
+    # Public: returns the custom template path.
+    attr_reader :template_path
+
     # Public: Initialize a Stylesheet
     #
     # sprite        - a 'Sprite' object to create the Stylesheet.
@@ -25,16 +26,14 @@ module Spriteful
     #                 :rails  - A flag to generate Asset Pipeline compatible Stylesheets.
     def initialize(sprite, destination, options = {})
       @sprite = sprite
-      @destination = Pathname.new(destination)
-      @root = nil
-      if options[:root]
-        @root = Pathname.new(File.expand_path(options[:root]))
-      end
+      @options = options
+      @destination = destination
+
       @format = options[:format]
-      @mixin = options.fetch(:mixin, false)
-      @rails = options.fetch(:rails, false)
+      @rails = !!options[:rails]
+      @template_path = options[:template] || self.class.expand_template_path(@format)
 
-      @path = @destination.join(name)
+      @path = File.join(@destination, name)
     end
 
     # Public: renders the CSS code for this Stylesheet.
@@ -43,8 +42,8 @@ module Spriteful
     #
     # Returns the CSS code as a 'String'.
     def render
-      source = File.expand_path("../stylesheets/template.#{format}.erb", __FILE__)
-      ERB.new(File.read(source), nil, '-').result(binding)
+      template = Template.new(@sprite, template_options)
+      template.render(File.read(template_path))
     end
 
     # Public: returns this Stylesheet name, based
@@ -56,26 +55,30 @@ module Spriteful
       "#{sprite_name}.#{extension}"
     end
 
-    protected
-
-    # Internal: returns the 'rails' flag.
-    def rails?
-      @rails
+    # Internal: Reads the default template Stylesheet for the given format.
+    #
+    # Returns a String.
+    def self.read_template(format)
+      path = expand_template_path(format)
+      File.read(path)
     end
 
-    # Internal: returns the 'mixin' flag.
-    def mixin?
-      @mixin
+    # Internal: Expands the path to the default stylesheet for the given format.
+    #
+    # Returns the path as a String.
+    def self.expand_template_path(format)
+      File.expand_path("../stylesheets/template.#{format}.erb", __FILE__)
     end
 
-    # Internal: select the extension prefix for the SCSS selector.
-    def extension_prefix
-      mixin? ? '@mixin ' : '%'
+    protected
+
+    def template_options
+      @options.merge(destination: @destination, cli_options: Spriteful.options)
     end
 
-    # Internal: select the extension strategy for the SCSS selector.
-    def extension_strategy
-      mixin? ? '@include ' : '@extend %'
+    # Internal: returns the 'rails' flag.
+    def rails?
+      @rails
     end
 
     # Internal: defines the file extension to be used with
@@ -100,38 +103,5 @@ module Spriteful
         "_#{sprite.name}"
       end
     end
-
-    # Internal: sanitizes the 'name' of a given object to
-    # be used as a CSS selector class.
-    #
-    # Returns a 'String'.
-    def class_name_for(object)
-      object.name.split('.').first.downcase.tr('_', '-')
-    end
-
-    # Internal: computes a relative path between the sprite
-    # path and the stylesheet expected location.
-    #
-    # Returns a 'String'.
-    def image_url(sprite)
-      path = Pathname.new(sprite.path)
-      if @rails
-        "sprites/#{sprite.filename}"
-      elsif @root
-        "/#{path.relative_path_from(@root)}"
-      else
-        path.relative_path_from(@destination)
-      end
-    end
-
-    # Internal: Gets an embeddable Data URI of the image if it
-    # is a SVG image.
-    #
-    # Returns a String.
-    def data_uri(image)
-      if image.svg?
-        %['data:image/svg+xml;base64,#{Base64.encode64(image.blob).gsub(/\r?\n/, '')}']
-      end
-    end
   end
 end

data/lib/spriteful/stylesheets/template.css.erb

@@ -1,7 +1,7 @@
 /*
  * This Stylesheet was generated by the 'spriteful' gem, with the following options:
 <%- if Spriteful.options -%>
- * 'spriteful <%= Spriteful.options.join(' ') %>'.
+ * 'spriteful <%= cli_options.join(' ') %>'.
 <%- end -%>
  * Below there are several CSS classes to use the '<%= sprite.name %>'
  * sprite on you HTML code, as in:

data/lib/spriteful/stylesheets/template.scss.erb

@@ -1,7 +1,7 @@
 // ============================================================================
 // This Stylesheet was generated by the 'spriteful' gem, with the following options:
 <%- if Spriteful.options -%>
-// 'spriteful <%= Spriteful.options.join(' ') %>'.
+// 'spriteful <%= cli_options.join(' ') %>'.
 <%- end -%>
 <%- if mixin? -%>
 // Below there are several [Mixin Directives]

data/lib/spriteful/template.rb

@@ -0,0 +1,113 @@
+require 'erb'
+require 'pathname'
+
+module Spriteful
+  # Public: The Template class is the public API available in the ERB templates
+  # that will render a CSS/SCSS stylesheet for a sprite.
+  class Template
+    # Public: Gets the sprite object that is being rendered with this template.
+    attr_reader :sprite
+
+    # Public: Gets the command line options used to create the current sprite.
+    attr_reader :cli_options
+
+    # Public: Initializes a Template object.
+    #
+    # sprite  - A instance of the Spriteful::Sprite object associated to this
+    #           template.
+    # options - The Hash options that configure this template (default: {}):
+    #           :mixin - A flag marking if the template should generate SCSS
+    #                    mixins instead of placeholders.
+    #           :rails - A flag marking if the template is being generated in a
+    #                    Rails app.
+    #           :root  - Root folder from where the generate stylesheets will be
+    #                    served.
+    #           :destination - Folder where styleshee will live.
+    def initialize(sprite, options = {})
+      @sprite = sprite
+      @options = options
+      @destination = Pathname.new(options[:destination])
+      @cli_options = options[:cli_options]
+
+      if @options[:root]
+        @root = Pathname.new(File.expand_path(options[:root]))
+      else
+        @root = nil
+      end
+    end
+
+    # Public: sanitizes the 'name' of a given object to be used as a CSS selector
+    # class.
+    #
+    # object - A Spriteful::Sprite or Spriteful::Image instance.
+    #
+    # Returns a String.
+    def class_name_for(object)
+      object.name.split('.').first.downcase.tr('_', '-')
+    end
+
+    # Public: Gets the extension prefix for the SCSS selector, based on the
+    # ':mixin' option.
+    #
+    # Returns a String.
+    def extension_prefix
+      mixin? ? '@mixin ' : '%'
+    end
+
+    # Internal: Gets the extension strategy for the SCSS selector, based on the
+    # ':mixin' option.
+    #
+    # Returns a String.
+    def extension_strategy
+      mixin? ? '@include ' : '@extend %'
+    end
+
+    # Public: Gets the ':mixin' flag.
+    def mixin?
+      !!@options[:mixin]
+    end
+
+    # Public: Gets the ':rails' flag.
+    def rails?
+      !!@options[:rails]
+    end
+
+    # Public: computes a relative path between the sprite path and the stylesheet
+    # expected location.
+    #
+    # sprite - A Spriteful::Sprite instance.
+    #
+    # Returns a String.
+    def image_url(sprite)
+      path = Pathname.new(sprite.path)
+      if rails?
+        "sprites/#{sprite.filename}"
+      elsif @root
+        "/#{path.relative_path_from(@root)}"
+      else
+        path.relative_path_from(@destination).to_s
+      end
+    end
+
+    # Public: Gets an embeddable Data URI of the image if it is a SVG image.
+    #
+    # image - A Spriteful::Image instance.
+    #
+    # Returns a String.
+    def data_uri(image)
+      if image.svg?
+        "data:image/svg+xml;base64,#{Base64.encode64(image.blob).gsub(/\r?\n/, '')}"
+      end
+    end
+
+    # Public: Renders the given source ERB template string in the context of the
+    # template object.
+    #
+    # source - A String containing the ERB template.
+    #
+    # Returns a String.
+    def render(source)
+      ERB.new(source, nil, '-').result(binding)
+    end
+  end
+end

data/lib/spriteful/version.rb

@@ -1,3 +1,3 @@
 module Spriteful
-  VERSION = '0.2.0'
+  VERSION = '0.3.0.beta1'
 end

data/spec/fixtures/template.erb

@@ -0,0 +1,23 @@
+/*
+ * This is a custom template.
+ */
+
+.my-custom-template-<%= class_name_for(sprite) %> {
+  <% if rails? -%>
+  background-image: url(<%%= image_url('<%= image_url(sprite) %>') %>);
+  <% else -%>
+  background-image: url(<%= image_url(sprite) %>);
+  <% end -%>
+  background-repeat: no-repeat;
+}
+<% sprite.each_image do |image| %>
+.my-custom-template-<%= class_name_for(sprite) %>.<%= class_name_for(image) %> {
+  background-position: <%= image.left %>px <%= image.top %>px;
+}
+<% if image.svg? %>
+.svg .my-custom-template-<%= class_name_for(sprite) %>.<%= class_name_for(image) %> {
+  background-image: url(<%= data_uri(image) %>);
+  background-position: 0 0;
+}
+<% end -%>
+<% end %>

data/spec/spriteful/template_spec.rb

@@ -0,0 +1,88 @@
+require 'spec_helper'
+
+describe Spriteful::Template do
+  let(:sprite) { double }
+  let(:options) { { destination: File.expand_path('tmp/output') } }
+  subject(:template) { Spriteful::Template.new(sprite, options) }
+
+  describe '#cli_options' do
+    it 'returns the cli_options provided in the options' do
+      options[:cli_options] = %w(one two three)
+      expect(template.cli_options).to eq(%w(one two three))
+    end
+  end
+
+  describe '#class_name_for' do
+    it 'formats the object name into a suitable CSS selector name' do
+      thing = double(name: 'Thing_name.jpg')
+      expect(template.class_name_for(thing)).to eq('thing-name')
+    end
+  end
+
+  describe '#extension_prefix' do
+    it 'returns the prefix to be used when defining the sprite CSS selector' do
+      expect(template.extension_prefix).to eq('%')
+      options[:mixin] = true
+      expect(template.extension_prefix).to eq('@mixin ')
+    end
+  end
+
+  describe '#extension_strategy' do
+    it 'returns prefix to be used when extending the SCSS selector' do
+      expect(template.extension_strategy).to eq('@extend %')
+      options[:mixin] = true
+      expect(template.extension_strategy).to eq('@include ')
+    end
+  end
+
+  describe '#mixin?' do
+    it 'returns true when the :mixin flag is true' do
+      options[:mixin] = true
+      expect(template.mixin?).to be(true)
+    end
+  end
+
+  describe '#rails?' do
+    it 'returns true when the :rails flag is true' do
+      options[:rails] = true
+      expect(template.rails?).to be(true)
+    end
+  end
+
+  describe '#image_url' do
+    it 'returns a path under sprites when the :rails flag is present' do
+      sprite = double(path: '/path', filename: 'icons.png')
+      options[:rails] = true
+
+      expect(template.image_url(sprite)).to eq('sprites/icons.png')
+    end
+
+    it 'returns an absolute path when the :root option is given' do
+      sprite = double(path: File.expand_path('tmp/sprites/icons.png'))
+      options[:root] = Pathname.new(File.expand_path('tmp'))
+
+      expect(template.image_url(sprite)).to eq('/sprites/icons.png')
+    end
+
+    it 'returns the sprite path relative to the destination path' do
+      sprite = double(path: File.expand_path('tmp/sprites/icons.png'))
+
+      expect(template.image_url(sprite)).to eq('../sprites/icons.png')
+    end
+  end
+
+  describe '#data_uri' do
+    it 'returns a Base64 encoded String for the SVG image' do
+      image = double(svg?: true, blob: '<svg />')
+      expect(template.data_uri(image)).to eq('data:image/svg+xml;base64,PHN2ZyAvPg==')
+    end
+  end
+
+  describe '#render' do
+    it 'renders the given ERB string in the template context' do
+      erb = 'ZOMG <%= self.class.name %>'
+
+      expect(template.render(erb)).to eq('ZOMG Spriteful::Template')
+    end
+  end
+end

data/spec/stylesheet_spec.rb

@@ -4,6 +4,7 @@ describe Spriteful::Stylesheet do
   let(:source) { File.expand_path('spec/fixtures/simple') }
   let(:destination) { File.expand_path('tmp') }
   let(:sprite) { Spriteful::Sprite.new(source, destination) }
+  let(:template) { File.expand_path('spec/fixtures/template.erb') }
 
   describe '#render' do
     it 'renders the CSS for the given sprite' do
@@ -71,5 +72,17 @@ describe Spriteful::Stylesheet do
         expect(output).to match(/^  .svg & \{/)
       end
     end
+
+    describe 'Custom templates' do
+      it 'renders the CSS using a custom template' do
+        stylesheet = Spriteful::Stylesheet.new(sprite, destination, format: 'scss', template: template)
+        output = stylesheet.render
+
+        expect(output).to match('This is a custom template.')
+        expect(output).to match(/.my-custom-template-simple \{/)
+        expect(output).to match(/.my-custom-template-simple.blue \{/)
+        expect(output).to match(/.my-custom-template-simple.red \{/)
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spriteful
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0.beta1
 platform: ruby
 authors:
 - Lucas Mazza
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-21 00:00:00.000000000 Z
+date: 2014-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -133,14 +133,17 @@ files:
 - lib/spriteful/stylesheet.rb
 - lib/spriteful/stylesheets/template.css.erb
 - lib/spriteful/stylesheets/template.scss.erb
+- lib/spriteful/template.rb
 - lib/spriteful/version.rb
 - spec/fixtures/simple/blue.png
 - spec/fixtures/simple/red.png
 - spec/fixtures/svg/green.svg
 - spec/fixtures/svg/red.png
+- spec/fixtures/template.erb
 - spec/image_spec.rb
 - spec/spec_helper.rb
 - spec/sprite_spec.rb
+- spec/spriteful/template_spec.rb
 - spec/stylesheet_spec.rb
 homepage: https://github.com/lucasmazza/spriteful
 licenses:
@@ -157,9 +160,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.2
@@ -171,7 +174,9 @@ test_files:
 - spec/fixtures/simple/red.png
 - spec/fixtures/svg/green.svg
 - spec/fixtures/svg/red.png
+- spec/fixtures/template.erb
 - spec/image_spec.rb
 - spec/spec_helper.rb
 - spec/sprite_spec.rb
+- spec/spriteful/template_spec.rb
 - spec/stylesheet_spec.rb