Inline SVG

Styling a SVG document with CSS for use on the web is most reliably achieved by adding classes to the document and embedding it inline in the HTML.

This gem adds a Rails helper method (inline_svg) that reads an SVG document (via Sprockets, so works with the Rails Asset Pipeline), applies a CSS class attribute to the root of the document and then embeds it into a view.

Inline SVG supports Rails 3 (from v0.12.0), Rails 4 and Rails 5 (from v0.10.0).

Changelog

This project adheres to Semantic Versioning. All notable changes are documented in the CHANGELOG.

Installation

Add this line to your application’s Gemfile:

gem 'inline_svg'

And then execute:

$ bundle

Or install it yourself as:

$ gem install inline_svg

Usage

inline_svg(file_name, options={})

The file_name can be a full path to a file, the file’s basename or an IO object. The actual path of the file on disk is resolved using Sprockets (when available), a naive file finder (/public/assets/...) or in the case of IO objects the SVG data is read from the object. This means you can pre-process and fingerprint your SVG files like other Rails assets, or choose to find SVG data yourself.

Here’s an example of embedding an SVG document and applying a ‘class’ attribute:

```erb

This is my SVG. There are many like it. You get the picture </svg> ``` ***Note:*** The title and desc `id` attributes generated for, and referenced by, `aria-labelled-by` are one-way digests based on the value of the title and desc elements and an optional "salt" value using the SHA1 algorithm. This reduces the chance of `inline_svg` embedding elements inside the SVG with `id` attributes that clash with other elements elsewhere on the page. ## Custom Transformations The transformation behavior of `inline_svg` can be customized by creating custom transformation classes. For example, inherit from `InlineSvg::CustomTransformation` and implement the `#transform` method: ```ruby # Sets the `custom` attribute on the root SVG element to supplied value # Remember to return a document, as this will be passed along the transformation chain class MyCustomTransform < InlineSvg::CustomTransformation def transform(doc) with_svg(doc) do |svg| svg["custom"] = value end end end ``` Add the custom configuration in an initializer (E.g. `./config/initializers/inline_svg.rb`): ```ruby # Note that the named `attribute` will be used to pass a value to your custom transform InlineSvg.configure do |config| config.add_custom_transformation(attribute: :my_custom_attribute, transform: MyCustomTransform) end ``` The custom transformation can then be called like so: ```haml %div = inline_svg "some-document.svg", my_custom_attribute: 'some value' ``` In this example, the following transformation would be applied to a SVG document: ```xml ``` You can also provide a default_value to the custom transformation, so even if you don't pass a value it will be triggered ```ruby # Note that the named `attribute` will be used to pass a value to your custom transform InlineSvg.configure do |config| config.add_custom_transformation(attribute: :my_custom_attribute, transform: MyCustomTransform, default_value: 'default value') end ``` The custom transformation will be triggered even if you don't pass any attribute value ```haml %div = inline_svg "some-document.svg" = inline_svg "some-document.svg", my_custom_attribute: 'some value' ``` In this example, the following transformation would be applied to a SVG document: ```xml ``` And ```xml ``` Passing a `priority` option with your custom transformation allows you to control the order that transformations are applied to the SVG document: ```ruby InlineSvg.configure do |config| config.add_custom_transformation(attribute: :custom_one, transform: MyCustomTransform, priority: 1) config.add_custom_transformation(attribute: :custom_two, transform: MyOtherCustomTransform, priority: 2) end ``` Transforms are applied in ascending order (lowest number first). ***Note***: Custom transformations are always applied *after* all built-in transformations, regardless of priority. ## Custom asset file loader An asset file loader returns a `String` representing a SVG document given a filename. Custom asset loaders should be a Ruby object that responds to a method called `named`, that takes one argument (a string representing the filename of the SVG document). A simple example might look like this: ```ruby class MyAssetFileLoader def self.named(filename) # ... load SVG document however you like return "" end end ``` Configure your custom asset file loader in an initializer like so: ```ruby InlineSvg.configure do |config| config.asset_file = MyAssetFileLoader end ``` ## Caching all assets at boot time When your deployment strategy prevents dynamic asset file loading from disk it can be helpful to cache all possible SVG assets in memory at application boot time. In this case, you can configure the `InlineSvg::CachedAssetFile` to scan any number of paths on disks and load all the assets it finds into memory. For example, in this configuration we load every `*.svg` file found beneath the configured paths into memory: ```ruby InlineSvg.configure do |config| config.asset_file = InlineSvg::CachedAssetFile.new( paths: [ "#Rails.root/public/path/to/assets", "#Rails.root/public/other/path/to/assets" ], filters: /\.svg/ ) end ``` **Note:** Paths are read recursively, so think about keeping your SVG assets restricted to as few paths as possible, and using the filter option to further restrict assets to only those likely to be used by `inline_svg`. ## Missing SVG Files If the specified SVG file cannot be found a helpful, empty SVG document is embedded into the page instead. The embedded document contains a single comment displaying the filename of the SVG image the helper tried to render: ```html ``` You may apply a class to this empty SVG document by specifying the following configuration: ```rb InlineSvg.configure do |config| config.svg_not_found_css_class = 'svg-not-found' end ``` Which would instead render: ```html ``` ## Contributing 1. Fork it ( [http://github.com/jamesmartin/inline_svg/fork](http://github.com/jamesmartin/inline_svg/fork) ) 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create new Pull Request Please write tests for anything you change, add or fix. There is a [basic Rails app](http://github.com/jamesmartin/inline_svg_test_app) that demonstrates the gem's functionality in use.