2 | 
3 |
4 |
20 |
21 | This module provides an Apostrophe piece type that manages and renders SVG sprites. Sprites can be imported from files in a website codebase or an external source via a URL.
22 |
23 | SVG sprites must be generated by a separate process. The module does not provide functionality to build the sprite files. [See below](#sprite-file-markup) for sprite markup requirements.
24 |
25 | ## Installation
26 |
27 | To install the module, use the command line to run this command in an Apostrophe project's root directory:
28 |
29 | ```
30 | npm install @apostrophecms/svg-sprite
31 | ```
32 |
33 | ## Usage
34 |
35 | Configure the SVG Sprite module in the `app.js` file:
36 |
37 | ```javascript
38 | require('apostrophe')({
39 | shortName: 'my-project',
40 | modules: {
41 | '@apostrophecms/svg-sprite': {}
42 | }
43 | });
44 | ```
45 |
46 | The SVG Sprites module should then be configured in its own `index.js` file with information about the sprite maps. Sprite files should be registered in the `maps` option, set to an array of configuration objects.
47 |
48 | ```javascript
49 | // modules/@apostrophecms/svg-sprite/index.js
50 | module.exports = {
51 | options: {
52 | maps: [
53 | {
54 | label: 'Places Icons',
55 | name: 'places',
56 | file: 'svg/places.svg'
57 | },
58 | {
59 | label: 'Service Icons',
60 | name: 'services',
61 | file: 'svg/services.svg'
62 | }
63 | ]
64 | }
65 | }
66 | ```
67 |
68 | The configuration objects include:
69 |
70 | - `label`: A clear label for the group of sprites.
71 | - `name`: A string with no whitespace that is unique within the project.
72 | - `file`: The location of the file. This may be a local file or a URL, as discussed below.
73 |
74 | The sprites can be imported into Apostrophe as pieces by running the module's `import` task. This task will look for each registered sprite file and generate pieces (Apostrophe content) for each SVG. On the command line this task could be started from the project root with the following command:
75 |
76 | ```bash
77 | node app @apostrophecms/svg-sprite:import
78 | ```
79 |
80 | ### Sprite file location options
81 |
82 | There are three options for registering SVG file locations:
83 |
84 | 1. Use a partial file path to a specific file, e.g., `'svg/places.svg'`.
85 | 2. Use a partial file path with wild card symbols, e.g., `'svg/*-icons.svg'`. See the [Glob package documentation](https://www.npmjs.com/package/glob#glob-primer) for acceptable patterns.
86 | 3. Use a URL for an externally hosted file, e.g., `'http://myfiles.net/svg/icons.svg'`.
87 |
88 | When using the partial file path options, the module will look for those files in its own `public` directory: `modules/@apostrophecms/svg-sprite/public/`. For example, `'svg/places.svg'` would reference a file at `modules/@apostrophecms/svg-sprite/public/svg/places.svg` in the code base.
89 |
90 | ### Sprite file markup
91 |
92 | Sprite files use the [SVG `symbol` element](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/symbol) to include multiple SVG images within a single `svg` tag. See the [CSS-Tricks](https://css-tricks.com/svg-symbol-good-choice-icons/) guide for more information about how to construct and use these sprite files.
93 |
94 | **Requirements for this module include:**
95 | - Sprite maps must be formatted so that all `
3 |
4 | SVG Sprites for ApostropheCMS
5 |
6 |
7 | 
8 |
9 |
10 | 
