https://github.com/bitstarr/grav-plugin-svg-extension
Inline SVG in Twig Templates
https://github.com/bitstarr/grav-plugin-svg-extension
Last synced: 17 days ago
JSON representation
Inline SVG in Twig Templates
- Host: GitHub
- URL: https://github.com/bitstarr/grav-plugin-svg-extension
- Owner: bitstarr
- License: mit
- Created: 2020-03-13T10:31:56.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-08-01T21:42:25.000Z (almost 2 years ago)
- Last Synced: 2025-03-28T23:43:50.204Z (about 1 month ago)
- Language: PHP
- Size: 27.3 KB
- Stars: 5
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# SVG Extension Plugin
The **SVG Extension** Plugin is an extension for [Grav CMS](http://github.com/getgrav/grav). It provides a way to inline SVG files in your Twig templates so you can style them with CSS. In 1.1.0 a way to create [sprites](#sprites) was added.
> Remember Minifying: To keep the amount of markup low, consider an automated workflow (involving gulp/grunt and svgo for example) to minimize the filesize of the SVG files by optimizing them. Here we are assume that you have an ``assets/svg`` folder with the source files and ``dist/svg`` with the optimized copies. Only the latter will be transfered to the production enviroment in this scenario.
## Usage
You can access your SVG files in two ways.
### Access by filename
First you can set a base path in the plugin config and access them by filename:
````twig
{{ svg( 'search' )|raw }}
````
This will lookup ``search.svg`` in the icons folder. The default icon folder is ``theme://dist/icons/`` and can be set in the [configuration](#configuration).
### Access with absolute path
The second way is to use a somehow absolute path:
````twig
{{ svg('theme://optimized/icons/search.svg', 'icon')|raw }}
````
### Parameters
First parameter is the path or filname (as mentioned above). The second is the place for CSS classes. The third is an object/associative array. This array accepts up to three items at the moment:
* An ``id`` as the id attribute for the svg element embedded in the markup.
* A ``title`` for better accessability
* ``preserveAspectRatio`` for orientation, defaults to ``xMinYMin``
````twig
{{ svg('logo', 'icon logo__img', { 'id': 'logo-icon', 'title': 'Brand name' })|raw }}
````
> About Accessibility: Without a title, the SVG will be placed as pesentational image. Take a look in the expamples tfor more details.
There is a [configuration](#configuration) option to set the default CSS classes, so you can use a very short call for simple, presentational icons:
````twig
{{ svg('info')|raw }}
````
### Example
````css
.icon {
fill: currentColor;
height: 1em;
width: 1em;
overflow: hidden;
vertical-align: -.125em;
}
.meta__item .icon {
color: rebeccapurple;
}
````
````twig
````
Will render to this:
````html
````
## Sprites
To create a sprite you take a similiar approach as for inlining SVGs dirctly. The difference is, that you provide an array of icons needed and you will refer them elsewhere.
````twig
{{ svgSprite( [ 'search', 'phone', 'mail' ] )|raw }}
````
The example above will place something like the following in your markup;
````html
````
To make use of this hidden bunch of icons use the following, where you like to have the icon.
````twig
{{ sprite('mail', 'icon')|raw }}
````
Which will output:
```html
```
If you want your content to be more accessable, use this:
```twig
{{ sprite('mail', null, 'E-Mail')|raw }}
```
````html
E-Mail
````
### Parameters
**svgSprite**
* The first parameter is an array of IDs/names
* The second is an object that can only hold ``preserveAspectRatio`` for orientation, defaults to ``xMinYMin``
````twig
{{ svgSprite( [ 'search', 'phone', 'mail' ], { preserveAspectRatio: 'xMinYMin' } )|raw }}
````
**sprite**
* First parameter is the ID/Name
* Second is the custom class names, default is `icon`
* Third is the title for better accessability, default is no title
````twig
{{ sprite('mail', 'icon', 'E-Mail')|raw }}
````
## Installation
Installing the SVG Extension plugin can be done in one of three ways: The GPM (Grav Package Manager) installation method lets you quickly install the plugin with a simple terminal command, the manual method lets you do so via a zip file, and the admin method lets you do so via the Admin Plugin.
### GPM Installation (Preferred)
To install the plugin via the [GPM](http://learn.getgrav.org/advanced/grav-gpm), through your system's terminal (also called the command line), navigate to the root of your Grav-installation, and enter:
bin/gpm install svg-extension
This will install the SVG Extension plugin into your `/user/plugins`-directory within Grav. Its files can be found under `/your/site/grav/user/plugins/svg-extension`.
### Manual Installation
To install the plugin manually, download the zip-version of this repository and unzip it under `/your/site/grav/user/plugins`. Then rename the folder to `svg-extension`. You can find these files on [GitHub](https://github.com//grav-plugin-svg-extension) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
You should now have all the plugin files under
/your/site/grav/user/plugins/svg-extension
### Admin Plugin
If you use the Admin Plugin, you can install the plugin directly by browsing the `Plugins`-menu and clicking on the `Add` button.
## Configuration
Before configuring this plugin, you should copy the `user/plugins/svg-extension/svg-extension.yaml` to `user/config/plugins/svg-extension.yaml` and only edit that copy.
Here is the default configuration and an explanation of available options:
```yaml
enabled: true
path: 'theme://dist/icons/' # Where are your SVG files stored?
defaultClass: 'icon' # What's the default CSS classes?
```
Note that if you use the Admin Plugin, a file with your configuration named svg-extension.yaml will be saved in the `user/config/plugins/`-folder once the configuration is saved in the Admin.