compass-svg-templates 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ce22fbc07b592fdd745dc5fdbf2db4d4e249fa29
+  data.tar.gz: d0adbbf48a527b538c6f0d4f892d49bb94c0a72b
+SHA512:
+  metadata.gz: 81e5c0197fd8cdbdc3e4d7658951316c16c1f139d80d51e3a4843d5a04c7097ad820685922b8cac96f67ede856f0c7b2c2ed3f2e1facd2d379c85f7edcb62646
+  data.tar.gz: 177acc31283a6454762fa5bbb6b9708ac5ddf2f706b0f447d87765e276d13fe2981d774caef289da59721a2a4d48e5d28e862fd5177f49a9a1b5764910eb67d8

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Thomas Bachem
+
+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,125 @@
+Compass SVG Templates
+===========================================================================================
+
+Use variables in SVGs to modify images on-the-fly
+-------------------------------------------------------------------------------------------
+
+This [Compass](http://compass-style.org) extension can read SVG files, replace variables
+in these images (e.g. to manipulate colors) and optionally also render them as PNG images
+e.g. for Internet Explorer <= 8.
+
+### Installation
+
+```sh
+sudo gem install compass-svg-templates
+```
+
+If you want to make use of the PNG rendering functionality as well, you need to have
+librsvg, ImageMagick and RMagick installed. You can install those on OS X using
+[Homebrew](http://brew.sh) like this:
+```sh
+brew install librsvg
+brew install imagemagick --with-librsvg
+sudo ARCHFLAGS="-arch x86_64" gem install rmagick
+```
+
+### Usage
+
+To use the extension in your existing Compass project, add the following to your *config.rb* file:
+```ruby
+require 'svg-templates'
+```
+
+To make use of the shipped mixins in addition to the functions, add this to your SCSS file:
+```scss
+@import 'svg-templates'
+```
+
+### Example
+
+SVG template (*img/circle.svg*):
+```svg
+<?xml version="1.0" encoding="utf-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 50 50">
+	<circle stroke="#{$stroke||black}" fill="#{$fill||white}" cx="50" cy="50" r="40" stroke-width="3" />
+</svg>
+```
+
+SCSS (*scss/styles.scss*):
+```scss
+.myselector {
+  background-image: svg-template('circle.svg', $stroke: red);
+}
+```
+
+Compiled CSS (*css/styles.css*):
+```css
+.myselector {
+  background-image: url('styles-circle.12345.svg?12345');
+}
+```
+
+Generated SVG (*css/styles-circle.12345.svg*):
+```svg
+<?xml version="1.0" encoding="utf-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 50 50">
+	<circle stroke="red" fill="white" cx="50" cy="50" r="40" stroke-width="3" />
+</svg>
+```
+
+### Functions
+
+#### `svg-template($path, $variables...)`
+
+Reads the SVG file from `$path` (relative to Compass' image path), optionally replaces
+variables within the SVG, puts the resulting SVG file in the CSS directory and returns
+a `url(...)` statement that points there.
+  
+#### `svg-template-inline($path, $variables...)`
+
+Like `svg-template` but returns the generated SVG inlined as `url('data:...')`.
+
+#### `svg-template-png($path, $variables...)`
+
+Generates the SVG like `svg-template` but uses RMagick/ImageMagick to render it into
+a PNG file and returns the `url(...)` statement pointing to that PNG file.
+
+#### `svg-template-png-inline($path, $variables...)`
+
+Like `svg-template-png` but returns the generated PNG inlined as `url('data:...')`.
+
+### Mixins
+
+The shipped mixins do automatically include a PNG fallback.
+
+#### `svg-template-background($path, $variables...)`
+
+```scss
+@mixin svg-template-background($path, $variables...) {
+  background-image: svg-template-png($path, keywords($variables));
+  background-image: svg-template($path, keywords($variables));
+}
+```
+
+#### `svg-template-background-inline($path, $variables...)`
+
+```scss
+@mixin svg-template-background-inline($path, $variables...) {
+  background-image: svg-template-png-inline($path, keywords($variables));
+  background-image: svg-template-inline($path, keywords($variables));
+}
+```
+
+### Configuration Settings
+
+#### `$svg-templates-cache-buster` (default: `auto`)
+
+Set this variable to `null` or an empty string to prevent the extension from
+appending a cache buster to the query string or provide a static cache buster
+value to be used. The default `auto` tells the extension to use the file's
+shortened MD5 hash as the cache buster.
+
+#### `$svg-templates-minify` (default: `1`)
+
+Set this variable to `0` to disable automatic SVG minification (stripping of
+XML prolog, doctype, comments and redundant whitespace).

data/lib/svg-templates.rb

@@ -0,0 +1,4 @@
+require 'svg-templates/sass_extensions'
+
+extension_path = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+Compass::Frameworks.register('svg-templates', :path => extension_path)

data/lib/svg-templates/sass_extensions.rb

@@ -0,0 +1,159 @@
+module Sass::Script::Functions
+
+  # Allow to supply variables as keywords or as a map
+  declare :svg_template,            [:path], :var_kwargs => true
+  declare :svg_template,            [:path, :variables]
+
+  declare :svg_template_inline,     [:path], :var_kwargs => true
+  declare :svg_template_inline,     [:path, :variables]
+  
+  declare :svg_template_png,        [:path], :var_kwargs => true
+  declare :svg_template_png,        [:path, :variables]
+
+  declare :svg_template_png_inline, [:path], :var_kwargs => true
+  declare :svg_template_png_inline, [:path, :variables]
+
+  def svg_template(path, variables = {})
+    real_path = File.join(Compass.configuration.images_path, path.value)
+
+    # Process SVG
+    data = read_svg_file(real_path)
+    data = replace_svg_variables(data, variables)
+
+    # Generate filename
+    css_basepath = Pathname.new(options[:css_filename].to_s).dirname.sub_ext('').to_s
+    css_filename = Pathname.new(options[:css_filename].to_s).basename.sub_ext('').to_s
+    svg_filename = Pathname.new(real_path).basename.sub_ext('').to_s
+    hash         = Digest::MD5.hexdigest(data)[0, 5]
+    svg_basename = "#{css_filename}-#{svg_filename}.#{hash}.svg"
+
+    # Write SVG image file
+    File.write(css_basepath + '/' + svg_basename, minify_svg_data(data))
+
+    url = handle_cache_buster(svg_basename, hash)
+    unquoted_string("url('#{url}')")
+  end
+
+  def svg_template_inline(path, variables = {})
+    real_path = File.join(Compass.configuration.images_path, path.value)
+
+    # Process SVG
+    data = read_svg_file(real_path)
+    data = replace_svg_variables(data, variables)
+    data = minify_svg_data(data)
+
+    # Inline SVG image
+    data = [data].flatten.pack('m').gsub("\n", '')
+    url = "data:image/svg+xml;base64,#{data}"
+    unquoted_string("url('#{url}')")
+  end
+
+  def svg_template_png(path, variables = {})
+    real_path = File.join(Compass.configuration.images_path, path.value)
+
+    # Process SVG
+    data = read_svg_file(real_path)
+    data = replace_svg_variables(data, variables)
+
+    # Generate filename
+    css_basepath = Pathname.new(options[:css_filename].to_s).dirname.sub_ext('').to_s
+    css_filename = Pathname.new(options[:css_filename].to_s).basename.sub_ext('').to_s
+    svg_filename = Pathname.new(real_path).basename.sub_ext('').to_s
+    hash         = Digest::MD5.hexdigest(data)[0, 5]
+    png_basename = "#{css_filename}-#{svg_filename}.#{hash}.png"
+
+    # Render SVG as PNG image file using ImageMagick
+    img = load_svg_image_data(data)
+    img.write(css_basepath + '/' + png_basename)
+    
+    url = handle_cache_buster(png_basename, hash)
+    unquoted_string("url('#{url}')")
+  end
+
+  def svg_template_png_inline(path, variables = {})
+    real_path = File.join(Compass.configuration.images_path, path.value)
+
+    # Process SVG
+    data = read_svg_file(real_path)
+    data = replace_svg_variables(data, variables)
+
+    # Render SVG as PNG image file using ImageMagick
+    img = load_svg_image_data(data)
+    data = img.to_blob()
+
+    # Inline SVG image
+    data = [data].flatten.pack('m').gsub("\n", '')
+    url = "data:image/svg+xml;base64,#{data}"
+    unquoted_string("url('#{url}')")
+  end
+
+private
+
+  def get_config_setting(name, default = nil)
+    # Read config setting from a scoped or global variable
+    setting = environment.caller.var(name)
+    if setting.nil?
+      default
+    else
+      setting.value
+    end
+  end
+  
+  def read_svg_file(real_path)
+    if File.readable?(real_path)
+      File.open(real_path, "rb") {|io| io.read}
+    else
+      raise Compass::Error, "File not found or cannot be read: #{real_path}"
+    end
+  end
+
+  def replace_svg_variables(data, variables)
+    # Cast Sass map to hash
+    if variables.respond_to?(:to_h)
+      variables = variables.to_h
+    end
+
+    # Replace variables
+    variables.each do |key, value|
+      data = data.gsub('#{$' + key.to_s + '}', value.to_s)
+    end
+
+    # Replace undefined variables by their defaults or strip them entirely
+    data.gsub(/#\{\$[a-z_][a-zA-Z0-9_]*(?:\|\|(.+?))?\}/, '\1')
+  end
+
+  def minify_svg_data(data)
+    if get_config_setting('svg-templates-minify', 1) == 1
+      # Strip XML prolog, as browsers don't need it when a MIME type is specified
+      data = data.gsub(/^<\?xml\s.+?\?>/, '')
+      # Strip doctype
+      data = data.gsub(/^<!DOCTYPE\s.+?>/, '')
+      # Strip comments
+      data = data.gsub(/<!--.*?-->/, '')
+      # Compress consecutive whitespace
+      data = data.gsub(/[\s\r\n]+/, ' ')
+    else
+      data
+    end
+  end
+
+  def load_svg_image_data(data)
+    begin
+      require 'RMagick'
+    rescue LoadError
+      raise Compass::Error, "Please install RMagick to make use of the PNG rendering functionality."
+    end
+    begin
+      Magick::Image.from_blob(data).first
+    rescue
+      raise Compass::Error, "SVG file #{real_path} cannot be processed – probably invalid?"
+    end
+  end
+
+  def handle_cache_buster(url, hash)
+    cache_buster = get_config_setting('svg-templates-cache-buster', 'auto')
+    cache_buster = hash if cache_buster == 'auto'
+    cache_buster.to_s.length > 0 ? url + '?' + cache_buster.to_s : url
+  end
+
+end

data/stylesheets/_svg-templates.scss

@@ -0,0 +1,14 @@
+$svg-templates-cache-buster: auto !default;
+$svg-templates-minify:       1    !default;
+
+@mixin svg-template-background($path, $variables...) {
+  background-image: svg-template-png($path, keywords($variables));
+  // Use a second background-image so IE <= 8 won't parse this property
+  background-image: svg-template($path, keywords($variables)), none;
+}
+
+@mixin svg-template-background-inline($path, $variables...) {
+  background-image: svg-template-png-inline($path, keywords($variables));
+  // Use a second background-image so IE <= 8 won't parse this property
+  background-image: svg-template-inline($path, keywords($variables)), none;
+}

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: compass-svg-templates
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Thomas Bachem
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sass
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: compass
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This Compass extension can read SVG files, replace variables in these
+  images (e.g. to manipulate colors) and optionally render them as PNG images.
+email:
+- mail@thomasbachem.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/svg-templates.rb
+- lib/svg-templates/sass_extensions.rb
+- stylesheets/_svg-templates.scss
+homepage: http://github.com/thomasbachem/compass-svg-templates
+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.2.0
+signing_key: 
+specification_version: 4
+summary: Use variables in SVG files to modify CSS images on-the-fly
+test_files: []