svg_sprite 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 034825d7337c6cb0e9d1c159d2f90a2754278fc8
-  data.tar.gz: 33c7621c2d8940ccb14d0b507f62e4a217759bc4
+  metadata.gz: ece2edc0ee57a16a3be26fbee5c14a7dfec7543f
+  data.tar.gz: e8768667775ac396d65847de4501fb2ff9521b8b
 SHA512:
-  metadata.gz: 3a64803c8c087f1f67a5109ec30144f1634b894317a5d0343d3b6b62f5ea1810a81207e0f606e067fab2a1838c5ae3c463fb727e7aa39402b5d806ee27b3c3c1
-  data.tar.gz: a03e9f43ec6eb363fbbf5978951199fef18d0726b58263ef48f45da137789841706b23658f74a4ced563bc54608c883c0a2cac683eb1c3025dc683198e56ed62
+  metadata.gz: 666f6801f1b8af0020631934647a1d509fc53a4a4d5875076569229d18878f0f735ff3d676fa98b544ae08124d4751ee5eeceba256fd133b2c1ae56f37cbd0f5
+  data.tar.gz: 14922c07b23583d3e1c5306fdd217002498ffa4c41f9493c78d37cac4d7c2194a8632557c05791be3b65980ef018a764251b2cbe91a0b13876b8d95054e4ddd0

data/README.md

@@ -1,6 +1,6 @@
 # SvgSprite
 
-Create SVG sprites by embedding images into CSS using data URIs.
+Create SVG sprites by embedding images into CSS using data URIs. The SVGs are optimized using [svg_optimizer](https://github.com/fnando/svg_optimizer).
 
 ## Installation
 
@@ -63,6 +63,63 @@ Let's say the `images/icons` directory has a file called `user.svg`. The command
 .icons-user-after
 ```
 
+### Programming API
+
+To generate the sprite without saving the file:
+
+```ruby
+require "svg_sprite"
+rendered_css = SvgSprite.create({
+  source: "./images/icons",
+  format: "scss",
+  name: "icons"
+}).render
+```
+
+To save the sprite content to a file:
+
+```ruby
+require "svg_sprite"
+rendered_css = SvgSprite.export({
+  source: "./images/icons",
+  output: "./styles/_icons.scss",
+  format: "scss",
+  name: "icons"
+})
+```
+
+#### Adding new formats
+
+First, register your template renderer. The assigned object should respond to `call(source, options)`.
+
+```ruby
+# `source` is SvgSprite::Source, which wraps all SVG files.
+# Each item returned by `source` is a SvgSprite::SVG instance.
+SvgSprite::TEMPLATES["custom"] = proc do |source, options|
+  content = source.to_a.map(&:name).join("\n")
+  "/*\nImage names:\n#{content}\n*/"
+end
+```
+
+Then you can generate the sprite like the following:
+
+```ruby
+rendered_css = SvgSprite.create({
+  source: "./examples",
+  format: "custom",
+  name: "icons"
+}).render
+#=> /*
+#=> Image names:
+#=> blue-square
+#=> orange-square
+#=> green-square
+#=> yellow-square
+#=> */
+```
+
+See what's available in [SvgSprite::SVG](https://github.com/fnando/svg_sprite/blob/master/lib/svg_sprite/svg.rb) class.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -71,7 +128,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/svg_sprite. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/fnando/svg_sprite. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 
 ## License

data/lib/svg_sprite.rb

@@ -1,22 +1,18 @@
 module SvgSprite
-  require "erb"
   require "base64"
+  require "cgi"
+  require "erb"
   require "svg_optimizer"
   require "thor"
 
-  OUTPUT_FORMATS = %w[scss css].freeze
-  require "svg_sprite/cli"
   require "svg_sprite/version"
   require "svg_sprite/template/scss"
   require "svg_sprite/template/css"
+  require "svg_sprite/template"
   require "svg_sprite/sprite"
   require "svg_sprite/source"
   require "svg_sprite/svg"
-
-  TEMPLATES = {
-    "scss" => Template::SCSS.new,
-    "css"  => Template::CSS.new
-  }
+  require "svg_sprite/cli"
 
   def self.create(options)
     Sprite.new(

data/lib/svg_sprite/cli.rb

@@ -6,6 +6,10 @@ module SvgSprite
       true
     end
 
+    def self.formats
+      TEMPLATES.keys
+    end
+
     desc "version", "Display svg_sprite version"
     map %w[-v --version] => :version
 
@@ -15,11 +19,12 @@ module SvgSprite
 
     desc "generate", "Generate the SVG sprite by embedding the images as data URIs."
     option :source, aliases: %w[-s], required: true, desc: "The source directory. Will match SOURCE/**/*.svg."
-    option :output, aliases: %w[-o], required: true, desc: "The output file. Must be a file with a known format extension (#{OUTPUT_FORMATS.join(", ")})"
+    option :output, aliases: %w[-o], required: true, desc: "The output file."
     option :name, aliases: %w[-n], default: "sprite", desc: "The sprite name. This will be used as the variable for dynamic files."
+    option :format, aliases: %w[-f], desc: "The output format. When not provided, will be inferred from output file's extension. Can be any of #{formats.join("|")}."
     def generate
-      format = File.extname(options["output"])[1..-1]
-      fail Error, "ERROR: invalid output extension. Must be one of #{OUTPUT_FORMATS.join("|")}." unless valid_format?(format)
+      format = options["format"] || File.extname(options["output"])[1..-1]
+      fail Error, "ERROR: invalid output format. Must be one of #{formats.join("|")}." unless valid_format?(format)
 
       SvgSprite.export(
         source: File.expand_path(options["source"]),
@@ -32,7 +37,11 @@ module SvgSprite
     private
 
     def valid_format?(format)
-      OUTPUT_FORMATS.include?(format)
+      formats.include?(format)
+    end
+
+    def formats
+      self.class.formats
     end
   end
 end

data/lib/svg_sprite/svg.rb

@@ -6,40 +6,69 @@ module SvgSprite
       @path = path
     end
 
+    # Return the image file name without the extension.
+    def name
+      File.basename(path, ".*")
+    end
+
+    # Detect if SVG has all dimensions defined.
     def has_dimensions?
       width && height
     end
 
+    # Return a Nokogiri representation of the <svg> element.
     def svg
-      @svg ||= xml.css("svg").first
+      @svg ||= Nokogiri::XML(contents).css("svg").first
     end
 
+    # Return the <svg>'s width.
     def width
       svg["width"]
     end
 
+    # Return the <svg>'s height.
     def height
       svg["height"]
     end
 
-    def xml
-      @xml ||= Nokogiri::XML(contents)
-    end
-
+    # Return the raw content. This content is not optimized by svg_optimizer.
     def contents
       @contents ||= File.read(path)
     end
 
+    # Return the optimized content.
     def optimized
       @optimized ||= SvgOptimizer.optimize(contents)
     end
 
+    # Return the URL-encoded version of the content.
+    def encoded
+      CGI.escape(contents)
+    end
+
+    # Return the Base64-encoded version of the content.
     def base64
       Base64.strict_encode64(optimized)
     end
 
-    def name
-      File.basename(path, ".*")
+    # Return the smaller data URI.
+    def data_uri
+      [base64_data_uri, urlencoded_data_uri].sort_by(&:bytesize).first
+    end
+
+    # Return the Base64 version of the data URI.
+    def base64_data_uri
+      %[data:image/svg+xml;base64,#{base64}]
+    end
+
+    # Return the URL-encoded version of the data URI.
+    def urlencoded_data_uri
+      %[data:image/svg+xml;charset=#{encoding},#{encoded}]
+    end
+
+    # The output encoding based on the global configuration.
+    def encoding
+      Encoding.default_external.name
     end
   end
 end

data/lib/svg_sprite/template.rb

@@ -0,0 +1,6 @@
+module SvgSprite
+  TEMPLATES = {
+    "scss" => Template::SCSS.new,
+    "css"  => Template::CSS.new
+  }
+end

data/lib/svg_sprite/template/css.erb

@@ -3,7 +3,7 @@
 .<%= options[:name] %>-<%= svg.name %>,
 .<%= options[:name] %>-<%= svg.name %>-before:before,
 .<%= options[:name] %>-<%= svg.name %>-after:after {
-  background-image: url(data:image/svg+xml;base64,<%= svg.base64 %>);
+  background-image: url(<%= svg.data_uri %>);
   <%- if svg.has_dimensions? -%>
   width: <%= svg.width %>;
   height: <%= svg.height %>;

data/lib/svg_sprite/template/scss.erb

@@ -15,7 +15,7 @@ $<%= options[:name] %>-names: (<%= names(source) %>);
 
 <% for svg in source %>
 %<%= options[:name] %>-<%= svg.name %> {
-  background-image: url(data:image/svg+xml;base64,<%= svg.base64 %>);
+  background-image: url(<%= svg.data_uri %>);
   <%- if svg.has_dimensions? -%>
   width: <%= svg.width %>;
   height: <%= svg.height %>;

data/lib/svg_sprite/version.rb

@@ -1,3 +1,3 @@
 module SvgSprite
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: svg_sprite
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Nando Vieira
@@ -152,6 +152,7 @@ files:
 - lib/svg_sprite/source.rb
 - lib/svg_sprite/sprite.rb
 - lib/svg_sprite/svg.rb
+- lib/svg_sprite/template.rb
 - lib/svg_sprite/template/css.erb
 - lib/svg_sprite/template/css.rb
 - lib/svg_sprite/template/scss.erb