middleman-scavenger 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c5f987b216ce954d071a8ead7860438bad4b07a0
+  data.tar.gz: 013256a957db369fde7469699762506ce7ec3140
+SHA512:
+  metadata.gz: 90ec031a8f5aadec70917fc66d454f2719c738d60b8299f7914c608298922e698eaef36c97505115327681af8694c86ae8f7528bea01d1a683bfd1937e938683
+  data.tar.gz: 2d87d48755fcf3c078e36653c9c7447a43bfdea05843d63d983b1b52c33dbc08d16510cce0088a9eaf00cbdc3f23d5bf2128c8e2be0b55cc24ed4f105b0efa80

data/.gitignore

@@ -0,0 +1,5 @@
+# Ignore bundler lock file
+/Gemfile.lock
+
+# Ignore pkg folder
+/pkg

data/Gemfile

@@ -0,0 +1,19 @@
+# If you do not have OpenSSL installed, update
+# the following line to use "http://" instead
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in middleman-scavenger.gemspec
+gemspec
+
+group :development do
+  gem "rake"
+  gem "rdoc"
+  gem "yard"
+end
+
+group :test do
+  gem "cucumber"
+  gem "fivemat"
+  gem "aruba"
+  gem "rspec"
+end

data/README.md

@@ -0,0 +1,75 @@
+# Middleman-scavenger
+
+A Middleman extension for creating svg sprite sheets. It's usable in modern (IE9+) browsers, uses `<symbol>` to include the svg:s, and can optionally inline the SVG images for speed. If you need legacy browser support it combines well with [svg4everybody](https://github.com/jonathantneal/svg4everybody).
+
+
+## Installation and quick start
+
+- Put the SVG:s you want to include in `source/images/svg`.
+- Add `gem "middleman-scavenger"` to your gemfile and run `bundle install`
+- Add `activate :middleman_scavenger` to your config.rb file
+- Add `//= require middleman-scavenger` to your all.js file
+
+Done! Now you can include your SVG images with the `svg` helper:
+```ruby
+  <%= svg "my-image", class: "my-image-class" %>
+```
+
+
+## Configuration
+
+If you don't like the default settings, you can change them at activation time. These are the three available configuration directives:
+
+```ruby
+  activate :middleman_scavenger do |config|
+    config.path = "./source/my-svg-directory/"
+    config.prefix = "icon-"
+    config.sprite_path = "another-directory/my-sprite.svg"
+  end
+```
+
+- `path` sets the directory where Middleman-scavenger looks for SVG files. Every time an SVG is added, removed, or changed, Middleman-scavenger will rebuild a sprite sheet from all the files it finds there
+- `prefix` sets an optional prefix for symbol ids. By default, when Middleman-scavenger finds an svg called `my-svg.svg` it will set the symbol id to the filename, so you can do `<%= svg "my-svg" %>`. If you prefer, you can set a prefix to use something like `<%= svg "icon-my-svg" %>` instead
+- `sprite_path` will change the path and filename for the static file that Middleman-scavenger writes to disk.
+
+## Helpers
+
+### Displaying images from the sprite
+
+Use `<%= svg "my-image" %>` to display an image from the sprite. Middleman-scavenger will insert an `svg` element for you that references an image inside the sprite sheet. You can append HTML attributes to that SVG element with an options hash, like this: `<%= svg "my-image", class: "my-image-class", width: 200, height: 100 %>`.
+
+### Inlining
+
+If you include the JS file, Middleman-scavenger will XHR load the sprite sheet and insert it into the DOM. If you prefer to inline the SVG document instead of loading it asynchronously, don't add the javascript file and use the `<%= inline_svg_sprite %>` helper instead. It will insert a hidden SVG, then you can use the `<%= svg %>` helper as usual.
+
+
+### Sprite path
+
+If you want to reference the sprite directly, you can use `scavenger_sprite_path`. It uses the built-in asset_path helper and is safe even when the `asset_hash` directive is activated.
+
+
+## How it works
+
+Middleman-scavenger uses an SVG processor based on [Nokogiri](http://www.nokogiri.org) to load and parse the SVG images in the folder into a sprite sheet, each image in its own `<symbol>` with its own viewBox. The sprite sheet is cached in memory and written to disk, so it can be asynchronously loaded or quickly inlined into the document. Whenever an SVG is added, removed, or changed in development mode Middleman-scavenger will make a new in-memory and on-disk version. The rebuild process fires at build time as well.
+
+The bundled javascript will asynchronously load the SVG sprite sheet as text and insert it at the top of the body. This makes it possible to control the SVG sprites via CSS. An externally referenced SVG will create a shadow DOM boundary that is impossible to cross, but inserting the sprite sheet into the document removes that obstacle and makes for easy transitions and hover states.
+
+
+## Gotchas
+
+### Sizing
+
+SVG sizing is always a little difficult, and even more so with sprite sheets. Middleman-scavenger uses [Nokogiri](http://www.nokogiri.org) to parse the SVG images and put them in `<symbol>` elements, so each image can have its own viewBox. That way, they will scale as expected when given width or height parameters. Including an SVG without sizing information will constrain it to the dimensions of the element it was included in, so it's advisable to add `width:` or `height:` or a styled CSS selector to the `svg` helper.
+
+
+### FONI
+
+Since default behavior is to asynchronously load the sprite sheet, you may experience a "flash of no images" while the script is fetching your SVGs. Depending on your application, this may or may not be acceptable. The solution is to inline the sprite as described under the "Inlining" section above, but beware - if you have a lot of SVG:s it will bloat the size of each page since the inlined sprite sheet won't be cached between pages.
+
+
+## Who made this?
+
+I'm [Johan Halse](https://www.twitter.com/hejsna) and I work at [Varvet](https://www.varvet.se). We do Ruby and Javascript and we're super friendly. You should totally hire us!
+
+## License
+[MIT](http://johanhalse.mit-license.org)

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'cucumber/rake/task'
+
+Cucumber::Rake::Task.new(:cucumber, 'Run features that should pass') do |t|
+  t.cucumber_opts = "--color --tags ~@wip --strict --format #{ENV['CUCUMBER_FORMAT'] || 'Fivemat'}"
+end
+
+require 'rake/clean'
+
+task test: ['cucumber']
+
+task default: :test

data/assets/javascripts/middleman-scavenger.js.erb

@@ -0,0 +1,15 @@
+(function() {
+  function requestListener () {
+    document.body.insertAdjacentHTML('afterbegin', this.responseText);
+    document.body.children[0].style.display = 'none';
+  }
+
+  function requestSprite() {
+    var oReq = new XMLHttpRequest();
+    oReq.addEventListener('load', requestListener);
+    oReq.open('GET', '<%= image_path svg_sprite_path %>');
+    oReq.send();
+  }
+
+  requestSprite();
+})();

data/features/support/env.rb

@@ -0,0 +1,4 @@
+PROJECT_ROOT_PATH = File.dirname(File.dirname(File.dirname(__FILE__)))
+require "middleman-core"
+require "middleman-core/step_definitions"
+require File.join(PROJECT_ROOT_PATH, "lib", "middleman-scavenger")

data/lib/middleman-scavenger.rb

@@ -0,0 +1,60 @@
+# Require core library
+require 'middleman-core'
+
+# Extension namespace
+class MiddlemanScavenger < ::Middleman::Extension
+  option :path, "./source/images/svg", "Directory containing SVG files"
+  option :prefix, "", "Optional prefix for icon names"
+  option :sprite_path, "sprite.svg", "Static file to write svg spritesheet to"
+
+  def initialize(app, options_hash={}, &block)
+    super
+
+    require "svg_processor"
+
+    processor_instance = SVGProcessor.new(options.path, options.prefix, options.sprite_path)
+    processor_instance.rebuild
+    app.set :svg_processor, processor_instance
+    app.set :svg_sprite_path, options.sprite_path
+
+    app.ready do
+      files.changed do |file|
+        if File.extname(file) == ".svg"
+          svg_processor.rebuild
+        end
+      end
+
+      files.deleted do |file|
+        if File.extname(file) == ".svg"
+          svg_processor.rebuild
+        end
+      end
+    end
+  end
+
+  helpers do
+    def scavenger_sprite_path
+      image_path svg_sprite_path
+    end
+
+    def inline_svg_sprite
+      "<svg style=\"display:none;\">#{svg_processor.to_s}</svg>"
+    end
+
+    def svg(name, options=nil)
+      if defined?(options)
+        attrs = options.map {|k,v| "#{k}=\"#{v}\"" }.join(" ")
+        "<svg #{attrs}><use xlink:href=\"##{name}\" /></svg>"
+      else
+        "<svg><use xlink:href=\"##{name}\" /></svg>"
+      end
+    end
+  end
+end
+
+# Register extensions which can be activated
+# Make sure we have the version of Middleman we expect
+# Name param may be omited, it will default to underscored
+# version of class name
+
+MiddlemanScavenger.register(:middleman_scavenger)

data/lib/middleman_extension.rb

@@ -0,0 +1 @@
+require "middleman-scavenger"

data/lib/svg_processor.rb

@@ -0,0 +1,45 @@
+class SVGProcessor
+  require "nokogiri"
+
+  def initialize(path, prefix, sprite_path)
+    @path = path
+    @prefix = prefix
+    @sprite_path = sprite_path
+  end
+
+  def rebuild
+    @svgs = Dir["#{@path}/*"].map { |file| get_svg(file) }
+    puts "rebuilding: #{@svgs.length} svgs found"
+    @symbols = @svgs.map { |svg| convert_to_symbol(svg) }
+
+    @symbol_string = @symbols.join("\n")
+
+    if @sprite_path != nil
+      File.write("./source/images/#{@sprite_path}", "<svg xmlns=\"http://www.w3.org/2000/svg\">#{@symbol_string}</svg>")
+    end
+  end
+
+  def to_s
+    @symbol_string
+  end
+
+  private
+
+  def get_svg(file)
+    f = File.open(file)
+    doc = Nokogiri::XML(f)
+    f.close
+
+    {
+      filename: File.basename(file, ".svg"),
+      xml: doc
+    }
+  end
+
+  def convert_to_symbol(svg)
+    svg[:xml].xpath('//@id').remove
+    g = svg[:xml].at_css("g")
+    viewbox_size = svg[:xml].xpath("//@viewBox").first.value
+    "<symbol viewBox=\"#{viewbox_size}\" id=\"#{@prefix}#{svg[:filename]}\">#{g.to_s}</symbol>"
+  end
+end

data/middleman-scavenger.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "middleman-scavenger"
+  s.version     = "1.0.0"
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Johan Halse"]
+  s.email       = ["johan.halse@varvet.com"]
+  s.license     = "MIT"
+  s.homepage    = "https://github.com/varvet/middleman-scavenger"
+  s.summary     = %q{A middleman extension for automatically creating SVG sprite sheets}
+  s.description = %q{Discovers and compiles SVG files into a sprite sheet that can be used for icons and such.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # The version of middleman-core your extension depends on
+  s.add_runtime_dependency("middleman-core", [">= 3.3.12"])
+
+  # Additional dependencies
+  s.add_runtime_dependency("nokogiri", "~> 1.6")
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: middleman-scavenger
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Johan Halse
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: middleman-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.12
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.12
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: Discovers and compiles SVG files into a sprite sheet that can be used
+  for icons and such.
+email:
+- johan.halse@varvet.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- Rakefile
+- assets/javascripts/middleman-scavenger.js.erb
+- features/support/env.rb
+- lib/middleman-scavenger.rb
+- lib/middleman_extension.rb
+- lib/svg_processor.rb
+- middleman-scavenger.gemspec
+homepage: https://github.com/varvet/middleman-scavenger
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: A middleman extension for automatically creating SVG sprite sheets
+test_files:
+- features/support/env.rb
+has_rdoc: