# apostrophe-svg-sprites
`apostrophe-images` for SVGs in external sprite maps!
This bundle provides a piece subclass that manages and renders SVG sprites referenced from external maps and an accompanying widget for display.
This bundle assumes you are compiling/managing the SVG maps on your own (Gulp, Webpack, manual).
The bundle also assumes *either* that you're shipping the files in the project level folder `lib/modules/apostrophe-svg-sprites/public` or that you'r referencing the files on a public webserver (`http://mysite.websites/svg/icons.svg`)
This module is *not* an interface for uploading SVG files or pasting SVG markup.
Bundle consists of
* `apostrophe-svg-sprites` as a piece subclass for managing SVGs, similar to `apostrophe-images`
* `apostrophe-svg-sprites-widgets` as a way to render the SVG on a page
`apostrophe-svg-sprites` supports multiple source maps for multiple sets of SVGs.
## Example configuration
```javascript
modules: {
'apostrophe-svg-sprites': {
maps: [
{
label: 'Social Media Icons',
name: 'social',
file: 'svg/social.svg' // Would be found in /public/svg/social.svg
},
{
label: 'Places Icons',
name: 'places',
file: 'svg/places-*.svg' // filename uses a wildcard because it is part of a continuous build process
},
{
label: 'Interface Icons',
name: 'interface',
file: 'http://mysite.websites/svg/icons.svg' // externally requested resource
}
]
},
'apostrophe-svg-sprites-widgets': {},
}
```
## Example markup output
```HTML
```
## Example spritemap format
Important, all `` elements need to be peers of one another at the same node depth.
In `lib/modules/apostrophe-svg-sprites/public/svg/places.svg`
```XML
```
## Importing sprites as pieces
To make getting started easier this module provides a command line task for parsing your sprite maps and automatically creating pieces for them.
## Requirements for import
- Sprite maps must be formatted so that all `...` elements are on the same node level.
- The import uses the `maps` array from 'apostrophe-svg-sprites' configuration, so that must be set beforehand.
- `` tags must have an id attribute `....`
- `` tags can optionally have a title attribute that will be used as the piece's title field `....`
```bash
node app.js apostrophe-svg-sprites:import
```
## Automating running import
Your SVG map might be being built by Gulp.js or Webpack constantly, which means your Apostrophe pieces have to stay in sync with changes. The `import` task automatically updates existing sprites's details on run, so you might want to run the task as part of your build process or before each deploy.
### To run on each deploy
Just add the task to the `/deployment/migrate` file using the existing example.
## Why use external SVG maps?
SVGs
- Resolution independent
- Small footprint
- Can be manipulated via CSS and JS
`