svg-icon-toolbox v0.2.4
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
andpreserveAspectRatio
can be set as attributes of the root svg element. TheviewBox
attribute will be set to the bounding box of the exported object.
- callback callback - node style callback gets the Loaded object.