Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/apostrophecms/svg-sprite
https://github.com/apostrophecms/svg-sprite
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/apostrophecms/svg-sprite
- Owner: apostrophecms
- License: mit
- Created: 2021-12-13T15:48:57.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-31T13:37:14.000Z (2 months ago)
- Last Synced: 2024-11-04T09:00:50.701Z (2 months ago)
- Language: JavaScript
- Size: 37.1 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
SVG Sprites for ApostropheCMS
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.
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.
## Installation
To install the module, use the command line to run this command in an Apostrophe project's root directory:
```
npm install @apostrophecms/svg-sprite
```
## Usage
Configure the SVG Sprite module in the `app.js` file:
```javascript
require('apostrophe')({
shortName: 'my-project',
modules: {
'@apostrophecms/svg-sprite': {}
}
});
```
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.
```javascript
// modules/@apostrophecms/svg-sprite/index.js
module.exports = {
options: {
maps: [
{
label: 'Places Icons',
name: 'places',
file: 'svg/places.svg'
},
{
label: 'Service Icons',
name: 'services',
file: 'svg/services.svg'
}
]
}
}
```
The configuration objects include:
- `label`: A clear label for the group of sprites.
- `name`: A string with no whitespace that is unique within the project.
- `file`: The location of the file. This may be a local file or a URL, as discussed below.
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:
```bash
node app @apostrophecms/svg-sprite:import
```
### Sprite file location options
There are three options for registering SVG file locations:
1. Use a partial file path to a specific file, e.g., `'svg/places.svg'`.
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.
3. Use a URL for an externally hosted file, e.g., `'http://myfiles.net/svg/icons.svg'`.
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.
### Sprite file markup
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.
**Requirements for this module include:**
- Sprite maps must be formatted so that all `...` elements are on the same node level. This simply means that `symbol` tags should not be nested within other `symbol` tags.
- `symbol` tags must have an `id` attribute, e.g., `...`.
- `symbol` tags can *optionally* have a `title` attribute that will be used as the imported piece's title field, e.g., `...`
Here is an example of sprite file markup (with the `path` values abbeviated):
```html
```
### Using SVG sprite pieces
The primary properties we use to reference individual SVG symbols are:
- `file`: The file path or URL to the full sprite map. This file still includes all symbols that were part of that original map file.
- `svgId`: The `id` property of the individual SVG symbol. We have to use this in combination with the file path to get a specific symbol.
- `map`: The `map` name property can be used to quickly find one of the sprite maps that were configured in the module's `maps` array.
HTML markup using an individual SVG symbol might look like the example below. The example uses `svgSprite` as a reference to the individual piece content. A project might reference sprite pieces using a relationship field, for example.
```django
```