scavenger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: db7f56756253d3ff4ceb216b29d346b13807552d
+  data.tar.gz: 22e76b9d3d3b99e907e646871ed4d0bcad20d4bc
+SHA512:
+  metadata.gz: aa46f8f30d9a03b59f647fcf3b1c0120df8706693f893decde17752d71843c4cf34acf2411e35ddc21817d911254d9cf7c88bd30e6585700d53bb0e6602d5448
+  data.tar.gz: 2557e3fdf001e3239d1303e7b8cc870deb3b0988eccd4738debba85011c1dce98700f07b9fe230ae3f6b963e8401e3a346e633f7907dbbb5af112157cf982cf6

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Johan Halse
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+# Scavenger
+
+![Version](https://img.shields.io/gem/v/scavenger.svg)
+![Build status](https://img.shields.io/travis/johanhalse/scavenger.svg)
+
+A Rails plugin for turning a directory of svg images into a bunch of `<symbol>` tags in a sprite sheet and using them by reference. The main advantage of using `<symbol>` is that you can define a viewBox for each element, which means it's possible to reuse and resize them and still make them occupy the space you'd expect them to. A common use case would be icons.
+
+
+## Getting started
+
+Put the gem in your `Gemfile` and run `bundle install`:
+```ruby
+gem "scavenger"
+```
+
+Create a folder called `app/assets/svg` and put your svg images there.
+
+Add the following to `views/layouts/application.html.erb`:
+```ruby
+<%= svg_sprite_sheet %>
+```
+
+Now you can refer to your svg images by their name, so if you have `hejsna.svg` sitting in your svg directory, you can make it show up by writing `<%= svg "hejsna" %>`.
+
+
+## The `svg` helper
+
+Scavenger works by inserting svg tags with references to ids defined in the sprite sheet. There is nothing inherently special about these svg tags, so if you want to add classes or attributes to them in the usual Rails fashion, you can: `<%= svg "hejsna", class: "foo", style: "width:100px" %>`.
+
+
+## Loading the sprite sheet asynchronously
+
+Scavenger comes with a dependency-free javascript for fetching and injecting the sprite sheet into the DOM. This is a  good idea since the sprite sheet can be served from your reverse proxy and cached by the browser. Extra useful if you have a lot of symbols and don't want to bloat every page, but the downside is that users may experience a brief flash of missing icons. To use this javascript, remove the `<%= svg_sprite_sheet %>` helper from your layout and instead include the javascript in your `application.js` like so:
+```javascript
+//= require scavenger
+```
+
+
+## Configuration
+
+You can configure Scavenger to do your bidding. Create a file called `config/initializers/scavenger.rb` and put your configuration there.
+
+
+### Use another directory
+
+Default is `app/assets/svg` but it can be changed with the following directive:
+```ruby
+Scavenger::Config.svg_directory = Rails.root.join("app", "assets", "my_directory")
+```
+
+
+### Put the compiled sprite sheet somewhere else
+
+Default is `app/assets/images/sprite.svg` but it can be changed with the following directive:
+```ruby
+Scavenger::Config.sprite_path = Rails.root.join("app", "assets", "my_directory", "my_file.svg")
+```
+
+
+### Set a default prefix on your svg classes
+
+The svg references will get their name as the default classname, so `hejsna.svg` will be inserted like this: `<svg class="hejsna">`. If you want a prefix, for instance `icon-`, put `Scavenger::Config.class_prefix = "icon-"` in your configuration file and the svg will look like this instead: `<svg class="icon-hejsna">`.
+
+
+### Change how aspect ratio is preserved
+
+Default is `"xMinYMin meet"` but it can be changed with the following directive:
+```ruby
+Scavenger::Config.aspect_ratio = "xMaxYMax meet"
+```
+
+A full list of options for this directive can be found [here](https://developer.mozilla.org/en/docs/Web/SVG/Attribute/preserveAspectRatio).
+
+
+## Caveats
+
+Scavenger uses a basic built-in compressor. It will remove comments, non-significant whitespace, and ids from your files. Since every svg lives as a `symbol` within the sprite sheet, all `<defs>` tags and everything in them will be removed. Tools (like [Sketch](https://www.sketchapp.com)) will sometimes export your files with references inside a `<defs>` tag, and use really generic ids like `path-1`. That poses a problem for us since there's only one global `<defs>` tag within an svg, and ids are global to the html document. We've experimented with some workarounds but nothing satisfactory, so the solution for now is to manually fix any svgs that use `<defs>` tags in this way before placing them in the svg directory.
+
+
+## Author
+
+I'm [Johan Halse](https://twitter.com/hejsna) and I work for illustrious Swedish developers [Varvet](https://www.varvet.com). You should hire us if you need well-made, quality software!

data/Rakefile

@@ -0,0 +1,28 @@
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "Scavenger"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+Bundler::GemHelper.install_tasks
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/lib/scavenger.rb

@@ -0,0 +1,15 @@
+require "scavenger/config"
+require "scavenger/view_helpers"
+require "scavenger/compressor"
+
+module Scavenger
+  module Rails
+    class Engine < ::Rails::Engine
+      def initialize
+        super
+        Config.svg_directory = ::Rails.root.join("app", "assets", "svg")
+        Config.sprite_path = ::Rails.root.join("app", "assets", "images", "sprite.svg")
+      end
+    end
+  end
+end

data/lib/scavenger/compressor.rb

@@ -0,0 +1,70 @@
+module Scavenger
+  class Compressor
+    def initialize(path)
+      @path = path
+    end
+
+    def allowed_tags
+      @allowed_tags ||=
+        %w(a altGlyph altGlyphDef altGlyphItem animate animateColor
+           animateMotion animateTransform audio canvas circle clipPath
+           color-profile cursor discard ellipse feBlend feColorMatrix
+           feComponentTransfer feComposite feConvolveMatrix feDiffuseLighting
+           feDisplacementMap feDistantLight feDropShadow feFlood feFuncA
+           feFuncB feFuncG feFuncR feGaussianBlur feImage feMerge feMergeNode
+           feMorphology feOffset fePointLight feSpecularLighting feSpotLight
+           feTile feTurbulence filter font font-face font-face-format
+           font-face-name font-face-src font-face-uri foreignObject g glyph
+           glyphRef hatch hatchpath hkern iframe image line linearGradient
+           marker mask mesh meshgradient meshpatch meshrow metadata
+           missing-glyph mpath path pattern polygon polyline radialGradient
+           rect script set solidcolor stop style svg switch symbol text
+           textPath tref tspan unknown use video view vkern)
+    end
+
+    def compress_dir
+      sheet = Dir.entries(@path)
+                 .select { |f| !File.directory? f }
+                 .map { |f| compress_file(File.join(@path, f), f) }
+                 .join("")
+
+      File.write(Scavenger::Config.sprite_path, "<svg>#{sheet}</svg>") unless Scavenger::Config.sprite_path.nil?
+      sheet
+    end
+
+    def compress_file(filename, id)
+      doc = Nokogiri::XML(File.open(filename), &:noblanks)
+      doc = doc.remove_namespaces!.root
+      remove_comments(doc)
+      remove_tags(doc)
+      remove_ids(doc)
+      symbolize(doc, id)
+      doc.to_html
+    end
+
+    private
+
+    def remove_comments(doc)
+      doc.xpath("//comment()").remove
+    end
+
+    def remove_tags(doc)
+      doc.xpath("//*").each do |node|
+        node.remove unless allowed_tags.include?(node.name)
+      end
+    end
+
+    def remove_ids(doc)
+      doc.xpath("//@id").remove
+    end
+
+    def symbolize(doc, id)
+      doc.xpath("@*").each do |attribute|
+        attribute.remove unless attribute.name == "viewBox"
+      end
+      doc.name = "symbol"
+      doc["id"] = id.chomp(".svg")
+      doc["preserveAspectRatio"] = Scavenger::Config.aspect_ratio
+    end
+  end
+end

data/lib/scavenger/config.rb

@@ -0,0 +1,12 @@
+module Scavenger
+  module Config
+    class << self
+      attr_accessor :svg_directory
+      attr_accessor :sprite_path
+      attr_accessor :class_prefix
+      attr_accessor :aspect_ratio
+    end
+
+    self.aspect_ratio = "xMinYMin meet"
+  end
+end

data/lib/scavenger/version.rb

@@ -0,0 +1,3 @@
+module Scavenger
+  VERSION = "0.1.0"
+end

data/lib/scavenger/view_helpers.rb

@@ -0,0 +1,22 @@
+module Scavenger
+  module ViewHelpers
+    def compressor
+      @compressor ||= Scavenger::Compressor.new(Scavenger::Config.svg_directory)
+    end
+
+    def svg_sprite_sheet
+      content_tag :svg, compressor.compress_dir.html_safe, style: "display:none;"
+    end
+
+    def svg(ref, options = {})
+      options[:class] = "#{Scavenger::Config.class_prefix}#{ref}" if options[:class].nil?
+      content_tag :svg, "<use xlink:href=\"##{ref}\"/>".html_safe, options
+    end
+
+    def scavenger_sprite_path
+      asset_path File.basename(Scavenger::Config.sprite_path)
+    end
+  end
+end
+
+ActiveSupport.on_load(:action_view) { include Scavenger::ViewHelpers }

data/lib/tasks/scavenger_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :scavenger do
+#   # Task goes here
+# end

data/test/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.

data/test/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Rails.application.load_tasks

data/test/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or any plugin's vendor/assets/javascripts directory can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/rails/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/test/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any styles
+ * defined in the other CSS/SCSS files in this directory. It is generally better to create a new
+ * file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/test/dummy/app/assets/svg/hejsna.svg

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="173px" height="173px" viewBox="0 0 173 173" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <!-- Generator: Sketch 40.1 (33804) - http://www.bohemiancoding.com/sketch -->
+    <title>hejsna</title>
+    <desc>Created with Sketch.</desc>
+    <defs></defs>
+    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="hejsna" transform="translate(1.000000, 1.000000)">
+            <circle id="Oval" stroke="#979797" fill="#D8D8D8" cx="85.5" cy="85.5" r="85.5"></circle>
+            <path d="M83.5,117.5 L83.5,51.5" id="Line" stroke="#A80C0C" stroke-linecap="square" fill="#A80C0C"></path>
+            <path id="Line-decoration-1" d="M83.5,51.5 L80.5,62.3 L86.5,62.3 L83.5,51.5 Z" stroke="#A80C0C" stroke-linecap="square" fill="#A80C0C"></path>
+            <polygon id="Star" stroke="#979797" fill="#D8D8D8" points="39 92 20.1908719 101.888544 23.7830957 80.9442719 8.56619148 66.1114562 29.595436 63.0557281 39 44 48.404564 63.0557281 69.4338085 66.1114562 54.2169043 80.9442719 57.8091281 101.888544"></polygon>
+            <polygon id="Triangle" fill="#EB8D8D" points="125 56 154 114 96 114"></polygon>
+        </g>
+    </g>
+</svg>

data/test/dummy/app/assets/svg/thing.svg

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="185px" height="69px" viewBox="0 0 185 69" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <!-- Generator: Sketch 40.3 (33839) - http://www.bohemiancoding.com/sketch -->
+    <title>thing</title>
+    <desc>Created with Sketch.</desc>
+    <defs>
+        <rect id="path-1" x="0" y="1" width="185" height="68" rx="8"></rect>
+        <mask id="mask-2" maskContentUnits="userSpaceOnUse" maskUnits="objectBoundingBox" x="0" y="0" width="185" height="68" fill="white">
+            <use xlink:href="#path-1"></use>
+        </mask>
+        <text id="text-3" font-family="Oxygen-Regular, Oxygen" font-size="20" font-weight="normal" fill="#FFFFFF">
+            <tspan x="24.5898438" y="37">LOL</tspan>
+        </text>
+        <filter x="-50%" y="-50%" width="200%" height="200%" filterUnits="objectBoundingBox" id="filter-4">
+            <feOffset dx="0" dy="2" in="SourceAlpha" result="shadowOffsetOuter1"></feOffset>
+            <feGaussianBlur stdDeviation="2" in="shadowOffsetOuter1" result="shadowBlurOuter1"></feGaussianBlur>
+            <feColorMatrix values="0 0 0 0 0   0 0 0 0 0   0 0 0 0 0  0 0 0 0.5 0" type="matrix" in="shadowBlurOuter1"></feColorMatrix>
+        </filter>
+    </defs>
+    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="thing">
+            <use id="Rectangle" stroke="#979797" mask="url(#mask-2)" stroke-width="2" fill="#D8D8D8" xlink:href="#path-1"></use>
+            <path d="M1.5,0.5 L179.5,64.5" id="Line" stroke="#979797" stroke-linecap="square"></path>
+            <path d="M180.5,4.5 L8.5,64.5" id="Line" stroke="#979797" stroke-linecap="square"></path>
+            <g id="LOL" fill-opacity="1" fill="#FFFFFF">
+                <use filter="url(#filter-4)" xlink:href="#text-3"></use>
+                <use xlink:href="#text-3"></use>
+            </g>
+        </g>
+    </g>
+</svg>

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,5 @@
+class ApplicationController < ActionController::Base
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
+end

data/test/dummy/app/controllers/welcome_controller.rb

@@ -0,0 +1,3 @@
+class WelcomeController < ApplicationController
+  def index; end
+end

data/test/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/test/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Dummy</title>
+  <%= stylesheet_link_tag    'application', media: 'all', 'data-turbolinks-track' => true %>
+  <%= javascript_include_tag 'application', 'data-turbolinks-track' => true %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= svg_sprite_sheet %>
+
+<%= yield %>
+
+</body>
+</html>

data/test/dummy/app/views/welcome/index.html.erb

@@ -0,0 +1,3 @@
+<h1>Test</h1>
+<%= svg "hejsna" %>
+<%= svg "thing" %>

data/test/dummy/bin/bundle

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
+load Gem.bin_path('bundler', 'bundle')