svg-icon-toolbox

A toolbox for svg icon and style assets workflows for node.js.

The use of stylesheets with standalone SVG files is not ubiquitious. Browsers understand them, some renderers (like librsvg) do not. Workflow in editors mostly do not support their usage, or are at least not helpfull, even if they understand them.

This module aims to bridge that state of affairs by offering a workflow that

• inserts stylesheets into SVG files, optionally compiling them from Sass
• inlines stylesheets by distributing all styles into element style attributes

Secondly, it exports single objects from such a file to PNG or SVG (icon) files. This part of the workflow depends on the command line features of Inkscape for

• identifying the bounding box of objects: a major undertaking not easily done, so the module takes advantage of the existing solution
• PNG export: to ensure the correct interpretation of stylesheets

Installation

npm install svg-icon-toolbox --save-dev

Make sure Inkscape is installed and in your PATH.

Usage

var toolbox = require('svg-icon-toolbox');

var list = ['icon-default', 'icon-active', 'icon-insensitive'];

toolbox.batch('src/assets.svg', [
    { task: 'stylize', arg: {src: 'src/sass/assets.scss'} },
    { task: 'write', arg: 'dist/assets.svg' },
    { task: 'export', arg: {
        ids: list,
        format: 'png',
        dir: 'dist/assets/'
        exportOptions: { dpi: 180 }
    } }
], callback);

As a Grunt task

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, do not forget to install grunt:

npm install grunt --save-dev

Then configure:

module.exports = function(grunt) {

  grunt.initConfig({
    svg_icon_toolbox: {
      src: 'src/assets.svg',
      options: {
        tasks: [
          { task: 'stylize', arg: {src: 'src/sass/assets.scss'} },
          { task: 'write', arg: 'dist/assets.svg' },
          { task: 'export', arg: {
              idFile: 'src/iconlist.txt',
              format: 'png',
              dir: 'dist/assets/'
              exportOptions: { dpi: 180 }
          } }
        ]
      }
    }
  });

  grunt.task.loadNpmTasks('svg-icon-toolbox');
};

API

toolbox

toolbox.load(sourceFn, callback) ⇒

Load a svg file for editing and/or exporting from.

Returns: void
Params

• sourceFn string - qualified file name
• callback callback - node style callback gets the Loaded object.

toolbox.batch(sourceFn, tasks, callback) ⇒

Load and batch process a svg file.

Returns: void
Params

• sourceFn string - qualified file name
• tasks Array.<Object> - a series of tasks to perform in the loaded file
  • .task string - name of a Loaded method
  • .arg string | Object - the first argument for that method (either a file name or an options object)
• callback callback - node style callback gets the Loaded object.

toolbox~callback(error, loaded) ⇒

Returns: void
Params

• error any
• loaded Loaded

Loaded

loaded.$ : Cheerio

the loaded file represented as a cheerio object

loaded.sourceFn : string

the name of the loaded file

loaded.stylize(opt, callback) ⇒

Write stylesheets into the loaded file; all pre-existing style sheets are removed.

Returns: void
Params

• opt Object
  • .src string | Array.<string> - single .css or .scss file name or Array of file names
  • [.sassOptions] Object - node-sass compiler options, excluding file, data and sourceMap. Note that includePaths defaults to the respective directory of each file if omitted
• callback callback - node style callback gets the Loaded object.

loaded.inline(opt, callback) ⇒

Distribute all styles from the style sheets of the loaded file to inline style attributes. Note that @-rules are ignored; the <style> elements are subsequently removed.

Returns: void
Params

• opt Object
  • .src string | Array.<string> - single .css or .scss file name or Array of file names of extra stylesheet(s) to apply before each internal stylesheet
  • [.sassOptions] Object - node-sass compiler options, excluding file, data and sourceMap. Note that includePaths defaults to the respective directory of each file if omitted
• callback callback - node style callback gets the Loaded object.

loaded.write([targetFn], callback) ⇒

Write the loaded file to a target file.

Returns: void
Params

• [targetFn] string - qualified file name. Defaults to overwriting the source of the loaded file.
• callback callback - node style callback gets the Loaded object.

loaded.export(opt, callback) ⇒

Export a list of objects from the loaded file to separate icon files, either in PNG or SVG format.

The command needs a list of object IDs from the loaded file to export. The exported files will be nemed from these IDs. The list can be in the form of an Array included as opt.ids or imported from an external file named as opt.idFile. Such a file must consist only of the object ids, each on its own line. A file superceeds the ID Array, if both exist.

For SVG, if the Loaded object contains stylesheets, the exported files will have all styles distributed to inline style attributes. Despite this, the Loaded object returned by the callback is guaranteed to be unaltered.

Returns: void
Params

• opt Object
  • [.ids] Array.<string> - list of object ids to export. If missing, opt.idFile must be given.
  • [.idFile] Array.<string> - name of file containing object ids to export. If missing, opt.ids must be given.
  • .format string - png or svg
  • [.dir] string = "." - directory to write to
  • [.suffix] string - name exported files in the form ${id}${suffix}.${format}
  • [.postProcess] string | function - executed on the exported file. If a string, as a CLI command, if a function, directly. Both get the qualified file name as argument. A function should have the form (fileName, callback) => void and execute the callback with (err).
  • [.exportOptions] Object -
    for PNG, the following inkscape --export-${cmd} command line options are permissible: background, background-opacity, use-hints, dpi, text-to-path, ignore-filters, width and height.
    for SVG, width, height and preserveAspectRatio can be set as attributes of the root svg element. The viewBox attribute will be set to the bounding box of the exported object.
• callback callback - node style callback gets the Loaded object.