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
npm install svg-icon-toolbox --save-dev
Make sure Inkscape is installed and in your PATH
.
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);
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');
};
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.
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)
- .task
- callback
callback
- node style callback gets the Loaded object.
Returns: void
Params
- error
any
- loaded
Loaded
the loaded file represented as a cheerio object
the name of the loaded file
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 thatincludePaths
defaults to the respective directory of each file if omitted
- .src
- callback
callback
- node style callback gets the Loaded object.
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 thatincludePaths
defaults to the respective directory of each file if omitted
- .src
- callback
callback
- node style callback gets the Loaded object.
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.
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 followinginkscape --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.
- [.ids]
- callback
callback
- node style callback gets the Loaded object.