inline_svg 0.11.0 → 1.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +5 -5
- data/.github/workflows/integration_test.yml +58 -0
- data/.github/workflows/ruby.yml +20 -0
- data/.rubocop.yml +1 -0
- data/.rubocop_todo.yml +421 -0
- data/CHANGELOG.md +144 -2
- data/README.md +148 -34
- data/Rakefile +7 -0
- data/inline_svg.gemspec +4 -4
- data/lib/inline_svg.rb +41 -9
- data/lib/inline_svg/action_view/helpers.rb +72 -7
- data/lib/inline_svg/cached_asset_file.rb +71 -0
- data/lib/inline_svg/finds_asset_paths.rb +1 -1
- data/lib/inline_svg/id_generator.rb +12 -3
- data/lib/inline_svg/io_resource.rb +4 -3
- data/lib/inline_svg/railtie.rb +8 -3
- data/lib/inline_svg/static_asset_finder.rb +4 -2
- data/lib/inline_svg/transform_pipeline.rb +0 -1
- data/lib/inline_svg/transform_pipeline/transformations.rb +8 -1
- data/lib/inline_svg/transform_pipeline/transformations/aria_attributes.rb +17 -20
- data/lib/inline_svg/transform_pipeline/transformations/aria_hidden.rb +9 -0
- data/lib/inline_svg/transform_pipeline/transformations/aria_hidden_attribute.rb +9 -0
- data/lib/inline_svg/transform_pipeline/transformations/class_attribute.rb +5 -6
- data/lib/inline_svg/transform_pipeline/transformations/data_attributes.rb +10 -5
- data/lib/inline_svg/transform_pipeline/transformations/description.rb +7 -6
- data/lib/inline_svg/transform_pipeline/transformations/height.rb +3 -4
- data/lib/inline_svg/transform_pipeline/transformations/id_attribute.rb +3 -4
- data/lib/inline_svg/transform_pipeline/transformations/no_comment.rb +5 -2
- data/lib/inline_svg/transform_pipeline/transformations/preserve_aspect_ratio.rb +3 -4
- data/lib/inline_svg/transform_pipeline/transformations/size.rb +4 -5
- data/lib/inline_svg/transform_pipeline/transformations/style_attribute.rb +11 -0
- data/lib/inline_svg/transform_pipeline/transformations/title.rb +7 -6
- data/lib/inline_svg/transform_pipeline/transformations/transformation.rb +13 -0
- data/lib/inline_svg/transform_pipeline/transformations/width.rb +3 -4
- data/lib/inline_svg/version.rb +1 -1
- data/lib/inline_svg/webpack_asset_finder.rb +50 -0
- data/spec/cached_asset_file_spec.rb +73 -0
- data/spec/files/static_assets/assets0/known-document-two.svg +1 -0
- data/spec/files/static_assets/assets0/known-document.svg +1 -0
- data/spec/files/static_assets/assets0/some-document.svg +1 -0
- data/spec/files/static_assets/assets1/known-document.svg +1 -0
- data/spec/files/static_assets/assets1/other-document.svg +3 -0
- data/spec/files/static_assets/assets1/some-file.txt +1 -0
- data/spec/helpers/inline_svg_spec.rb +104 -21
- data/spec/id_generator_spec.rb +5 -3
- data/spec/inline_svg_spec.rb +48 -0
- data/spec/transformation_pipeline/transformations/aria_attributes_spec.rb +16 -16
- data/spec/transformation_pipeline/transformations/aria_hidden_attribute_spec.rb +12 -0
- data/spec/transformation_pipeline/transformations/data_attributes_spec.rb +18 -0
- data/spec/transformation_pipeline/transformations/height_spec.rb +9 -0
- data/spec/transformation_pipeline/transformations/style_attribute_spec.rb +26 -0
- data/spec/transformation_pipeline/transformations/title_spec.rb +9 -0
- data/spec/transformation_pipeline/transformations/transformation_spec.rb +39 -0
- data/spec/transformation_pipeline/transformations_spec.rb +5 -1
- metadata +49 -22
- data/circle.yml +0 -3
data/CHANGELOG.md
CHANGED
@@ -3,8 +3,130 @@ All notable changes to this project will be documented in this file.
|
|
3
3
|
This project adheres to [Semantic Versioning](http://semver.org/).
|
4
4
|
|
5
5
|
## [Unreleased][unreleased]
|
6
|
+
|
6
7
|
- Nothing
|
7
8
|
|
9
|
+
## [1.7.2] - 2020-12-07
|
10
|
+
### Fixed
|
11
|
+
- Improve performance of `CachedAssetFile`. [#118](https://github.com/jamesmartin/inline_svg/pull/118). Thanks [@stevendaniels](https://github.com/stevendaniels)
|
12
|
+
- Avoid XSS by preventing malicious input of filenames. [#117](https://github.com/jamesmartin/inline_svg/pull/117). Thanks [@pbyrne](https://github.com/pbyrne).
|
13
|
+
|
14
|
+
## [1.7.1] - 2020-03-17
|
15
|
+
### Fixed
|
16
|
+
- Static Asset Finder uses pathname for compatibility with Sprockets 4+. [#106](https://github.com/jamesmartin/inline_svg/pull/106). Thanks [@subdigital](https://github.com/subdigital)
|
17
|
+
|
18
|
+
## [1.7.0] - 2020-02-13
|
19
|
+
### Added
|
20
|
+
- WebpackAssetFinder serves files from dev server if one is running. [#111](https://github.com/jamesmartin/inline_svg/pull/111). Thanks, [@connorshea](https://github.com/connorshea)
|
21
|
+
|
22
|
+
### Fixed
|
23
|
+
- Using Webpacker and Asset Pipeline in a single App could result in SVGs not being found because the wrong `AssetFinder` was used. [#114](https://github.com/jamesmartin/inline_svg/pull/114). Thanks, [@kylefox](https://github.com/kylefox)
|
24
|
+
- Prevent "EOFError error" when using webpack dev server over HTTPS [#113](https://github.com/jamesmartin/inline_svg/pull/113). Thanks, [@kylefox](https://github.com/kylefox)
|
25
|
+
|
26
|
+
|
27
|
+
## [1.6.0] - 2019-11-13
|
28
|
+
### Added
|
29
|
+
- Support Webpack via the new `inline_svg_pack_tag` helper and deprecate `inline_svg` helper in preparation for v2.0.
|
30
|
+
[#103](https://github.com/jamesmartin/inline_svg/pull/103)
|
31
|
+
Thanks, [@kylefox](https://github.com/kylefox)
|
32
|
+
|
33
|
+
## [1.5.2] - 2019-06-20
|
34
|
+
### Fixed
|
35
|
+
- Revert automatic Webpack asset finder behavior. Make Webpack "opt-in".
|
36
|
+
[#98](https://github.com/jamesmartin/inline_svg/issues/98)
|
37
|
+
|
38
|
+
## [1.5.1] - 2019-06-18
|
39
|
+
### Fixed
|
40
|
+
- Prevent nil asset finder when neither Sprockets or Webpacker are available
|
41
|
+
[#97](https://github.com/jamesmartin/inline_svg/issues/97)
|
42
|
+
|
43
|
+
## [1.5.0] - 2019-06-17
|
44
|
+
### Added
|
45
|
+
- Support for finding assets bundled by Webpacker
|
46
|
+
[#96](https://github.com/jamesmartin/inline_svg/pull/96)
|
47
|
+
|
48
|
+
## [1.4.0] - 2019-04-19
|
49
|
+
### Fixed
|
50
|
+
- Prevent invalid XML names being generated via IdGenerator
|
51
|
+
[#87](https://github.com/jamesmartin/inline_svg/issues/87)
|
52
|
+
Thanks, [@endorfin](https://github.com/endorfin)
|
53
|
+
|
54
|
+
### Added
|
55
|
+
- Raise error on file not found (if configured)
|
56
|
+
[#93](https://github.com/jamesmartin/inline_svg/issues/93)
|
57
|
+
|
58
|
+
## [1.3.1] - 2017-12-14
|
59
|
+
### Fixed
|
60
|
+
- Allow Ruby < 2.1 to work with `CachedAssetFile`
|
61
|
+
[#80](https://github.com/jamesmartin/inline_svg/pull/80)
|
62
|
+
|
63
|
+
## [1.3.0] - 2017-10-30
|
64
|
+
### Added
|
65
|
+
- Aria hidden attribute
|
66
|
+
[#78](https://github.com/jamesmartin/inline_svg/pull/78)
|
67
|
+
and [#79](https://github.com/jamesmartin/inline_svg/pull/79)
|
68
|
+
- In-line CSS style attribute
|
69
|
+
[#71](https://github.com/jamesmartin/inline_svg/pull/71)
|
70
|
+
|
71
|
+
### Fixed
|
72
|
+
- Make aria ID attributes unique
|
73
|
+
[#77](https://github.com/jamesmartin/inline_svg/pull/77)
|
74
|
+
|
75
|
+
## [1.2.3] - 2017-08-17
|
76
|
+
### Fixed
|
77
|
+
- Handle UTF-8 characters in SVG documents
|
78
|
+
[#60](https://github.com/jamesmartin/inline_svg/pull/69)
|
79
|
+
|
80
|
+
## [1.2.2] - 2017-07-06
|
81
|
+
### Fixed
|
82
|
+
- Handle malformed documents that don't contain a root SVG element
|
83
|
+
[#60](https://github.com/jamesmartin/inline_svg/pull/65)
|
84
|
+
### Added
|
85
|
+
- Add configurable CSS class to empty SVG document
|
86
|
+
[#67](https://github.com/jamesmartin/inline_svg/pull/67)
|
87
|
+
|
88
|
+
## [1.2.1] - 2017-05-02
|
89
|
+
### Fixed
|
90
|
+
- Select most exactly matching cached asset file when multiple files match
|
91
|
+
given asset name [#64](https://github.com/jamesmartin/inline_svg/pull/64)
|
92
|
+
|
93
|
+
## [1.2.0] - 2017-04-20
|
94
|
+
### Added
|
95
|
+
- Cached asset file (load assets into memory at boot time)
|
96
|
+
[#62](https://github.com/jamesmartin/inline_svg/pull/62)
|
97
|
+
|
98
|
+
## [1.1.0] - 2017-04-12
|
99
|
+
### Added
|
100
|
+
- Allow configurable asset file implementations
|
101
|
+
[#61](https://github.com/jamesmartin/inline_svg/pull/61)
|
102
|
+
|
103
|
+
## [1.0.1] - 2017-04-10
|
104
|
+
### Fixed
|
105
|
+
- Don't override custom asset finders in Railtie
|
106
|
+
|
107
|
+
## [1.0.0] - 2017-04-7
|
108
|
+
### Added
|
109
|
+
- Remove dependency on `Loofah` while maintaining basic `nocomment` transform
|
110
|
+
|
111
|
+
## [0.12.1] - 2017-03-24
|
112
|
+
### Added
|
113
|
+
- Relax dependency on `Nokogiri` to allow users to upgrade to v1.7x, preventing
|
114
|
+
exposure to
|
115
|
+
[CVE-2016-4658](https://github.com/sparklemotion/nokogiri/issues/1615):
|
116
|
+
[#59](https://github.com/jamesmartin/inline_svg/issues/59)
|
117
|
+
|
118
|
+
## [0.12.0] - 2017-03-16
|
119
|
+
### Added
|
120
|
+
- Relax dependency on `ActiveSupport` to allow Rails 3 applications to use the
|
121
|
+
gem: [#54](https://github.com/jamesmartin/inline_svg/issues/54)
|
122
|
+
|
123
|
+
## [0.11.1] - 2016-11-22
|
124
|
+
### Fixed
|
125
|
+
- Dasherize data attribute names:
|
126
|
+
[#51](https://github.com/jamesmartin/inline_svg/issues/51)
|
127
|
+
- Prevent ID collisions between `desc` and `title` attrs:
|
128
|
+
[#52](https://github.com/jamesmartin/inline_svg/pull/52)
|
129
|
+
|
8
130
|
## [0.11.0] - 2016-07-24
|
9
131
|
### Added
|
10
132
|
- Priority ordering for transformations
|
@@ -76,7 +198,7 @@ transformations](https://github.com/jamesmartin/inline_svg/blob/master/README.md
|
|
76
198
|
|
77
199
|
## [0.5.1] - 2015-03-30
|
78
200
|
### Warning
|
79
|
-
|
201
|
+
** This version is NOT comaptible with Sprockets >= 3. **
|
80
202
|
|
81
203
|
### Fixed
|
82
204
|
- Support for ActiveSupport (and hence, Rails) 4.2.x. Thanks, @jmarceli.
|
@@ -117,7 +239,27 @@ transformations](https://github.com/jamesmartin/inline_svg/blob/master/README.md
|
|
117
239
|
### Added
|
118
240
|
- Basic Railtie and view helper to inline SVG documents to Rails views.
|
119
241
|
|
120
|
-
[unreleased]: https://github.com/jamesmartin/inline_svg/compare/
|
242
|
+
[unreleased]: https://github.com/jamesmartin/inline_svg/compare/v1.7.2...HEAD
|
243
|
+
[1.7.2]: https://github.com/jamesmartin/inline_svg/compare/v1.7.1...v1.7.2
|
244
|
+
[1.7.1]: https://github.com/jamesmartin/inline_svg/compare/v1.7.0...v1.7.1
|
245
|
+
[1.7.0]: https://github.com/jamesmartin/inline_svg/compare/v1.6.0...v1.7.0
|
246
|
+
[1.6.0]: https://github.com/jamesmartin/inline_svg/compare/v1.5.2...v1.6.0
|
247
|
+
[1.5.2]: https://github.com/jamesmartin/inline_svg/compare/v1.5.1...v1.5.2
|
248
|
+
[1.5.1]: https://github.com/jamesmartin/inline_svg/compare/v1.5.0...v1.5.1
|
249
|
+
[1.5.0]: https://github.com/jamesmartin/inline_svg/compare/v1.4.0...v1.5.0
|
250
|
+
[1.4.0]: https://github.com/jamesmartin/inline_svg/compare/v1.3.1...v1.4.0
|
251
|
+
[1.3.1]: https://github.com/jamesmartin/inline_svg/compare/v1.3.0...v1.3.1
|
252
|
+
[1.3.0]: https://github.com/jamesmartin/inline_svg/compare/v1.2.3...v1.3.0
|
253
|
+
[1.2.3]: https://github.com/jamesmartin/inline_svg/compare/v1.2.2...v1.2.3
|
254
|
+
[1.2.2]: https://github.com/jamesmartin/inline_svg/compare/v1.2.1...v1.2.2
|
255
|
+
[1.2.1]: https://github.com/jamesmartin/inline_svg/compare/v1.2.0...v1.2.1
|
256
|
+
[1.2.0]: https://github.com/jamesmartin/inline_svg/compare/v1.1.0...v1.2.0
|
257
|
+
[1.1.0]: https://github.com/jamesmartin/inline_svg/compare/v1.0.1...v1.1.0
|
258
|
+
[1.0.1]: https://github.com/jamesmartin/inline_svg/compare/v1.0.0...v1.0.1
|
259
|
+
[1.0.0]: https://github.com/jamesmartin/inline_svg/compare/v0.12.1...v1.0.0
|
260
|
+
[0.12.1]: https://github.com/jamesmartin/inline_svg/compare/v0.12.0...v0.12.1
|
261
|
+
[0.12.0]: https://github.com/jamesmartin/inline_svg/compare/v0.11.1...v0.12.0
|
262
|
+
[0.11.1]: https://github.com/jamesmartin/inline_svg/compare/v0.11.0...v0.11.1
|
121
263
|
[0.11.0]: https://github.com/jamesmartin/inline_svg/compare/v0.10.0...v0.11.0
|
122
264
|
[0.10.0]: https://github.com/jamesmartin/inline_svg/compare/v0.9.1...v0.10.0
|
123
265
|
[0.9.1]: https://github.com/jamesmartin/inline_svg/compare/v0.9.0...v0.9.1
|
data/README.md
CHANGED
@@ -1,19 +1,25 @@
|
|
1
1
|
# Inline SVG
|
2
2
|
|
3
|
+

|
4
|
+

|
5
|
+
|
3
6
|
Styling a SVG document with CSS for use on the web is most reliably achieved by
|
4
7
|
[adding classes to the document and
|
5
8
|
embedding](http://css-tricks.com/using-svg/) it inline in the HTML.
|
6
9
|
|
7
|
-
This gem
|
10
|
+
This gem adds Rails helper methods (`inline_svg_tag` and `inline_svg_pack_tag`) that read an SVG document (via Sprockets or Webpacker, so works with the Rails Asset Pipeline), applies a CSS class attribute to the root of the document and
|
8
11
|
then embeds it into a view.
|
9
12
|
|
10
|
-
Inline SVG
|
13
|
+
Inline SVG supports:
|
11
14
|
|
12
|
-
|
15
|
+
- [Rails 3](http://weblog.rubyonrails.org/2010/8/29/rails-3-0-it-s-done/) (from [v0.12.0](https://github.com/jamesmartin/inline_svg/releases/tag/v0.12.0))
|
16
|
+
- [Rails 4](http://weblog.rubyonrails.org/2013/6/25/Rails-4-0-final/)
|
17
|
+
- [Rails 5](http://weblog.rubyonrails.org/2016/6/30/Rails-5-0-final/) (from [v0.10.0](https://github.com/jamesmartin/inline_svg/releases/tag/v0.10.0))
|
18
|
+
- [Rails 6](https://weblog.rubyonrails.org/2019/4/24/Rails-6-0-rc1-released/) with Sprockets or Webpacker (from [v1.5.2](https://github.com/jamesmartin/inline_svg/releases/tag/v1.5.2)).
|
13
19
|
|
14
20
|
## Changelog
|
15
21
|
|
16
|
-
This project adheres to [Semantic Versioning](http://
|
22
|
+
This project adheres to [Semantic Versioning](http://semver.org). All notable changes are documented in the
|
17
23
|
[CHANGELOG](https://github.com/jamesmartin/inline_svg/blob/master/CHANGELOG.md).
|
18
24
|
|
19
25
|
## Installation
|
@@ -32,9 +38,15 @@ Or install it yourself as:
|
|
32
38
|
|
33
39
|
## Usage
|
34
40
|
|
41
|
+
```ruby
|
42
|
+
# Sprockets
|
43
|
+
inline_svg_tag(file_name, options={})
|
44
|
+
|
45
|
+
# Webpacker
|
46
|
+
inline_svg_pack_tag(file_name, options={})
|
35
47
|
```
|
36
|
-
|
37
|
-
|
48
|
+
|
49
|
+
_**Note:** The remainder of this README uses `inline_svg_tag` for examples, but the exact same principles work for `inline_svg_pack_tag`._
|
38
50
|
|
39
51
|
The `file_name` can be a full path to a file, the file's basename or an `IO`
|
40
52
|
object. The
|
@@ -42,18 +54,20 @@ actual path of the file on disk is resolved using
|
|
42
54
|
[Sprockets](://github.com/sstephenson/sprockets) (when available), a naive file finder (`/public/assets/...`) or in the case of `IO` objects the SVG data is read from the object.
|
43
55
|
This means you can pre-process and fingerprint your SVG files like other Rails assets, or choose to find SVG data yourself.
|
44
56
|
|
45
|
-
Here's an example of embedding an SVG document and applying a 'class' attribute
|
46
|
-
HAML:
|
57
|
+
Here's an example of embedding an SVG document and applying a 'class' attribute:
|
47
58
|
|
48
|
-
```
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
59
|
+
```erb
|
60
|
+
<html>
|
61
|
+
<head>
|
62
|
+
<title>Embedded SVG Documents<title>
|
63
|
+
</head>
|
64
|
+
<body>
|
65
|
+
<h1>Embedded SVG Documents</h1>
|
66
|
+
<div>
|
67
|
+
<%= inline_svg_tag "some-document.svg", class: 'some-class' %>
|
68
|
+
</div>
|
69
|
+
</body>
|
70
|
+
</html>
|
57
71
|
```
|
58
72
|
|
59
73
|
Here's some CSS to target the SVG, resize it and turn it an attractive shade of
|
@@ -69,30 +83,45 @@ blue:
|
|
69
83
|
}
|
70
84
|
```
|
71
85
|
|
72
|
-
## Options
|
86
|
+
## Options
|
73
87
|
|
74
88
|
key | description
|
75
|
-
:---------------------- | :----------
|
89
|
+
:---------------------- | :----------
|
76
90
|
`id` | set a ID attribute on the SVG
|
77
91
|
`class` | set a CSS class attribute on the SVG
|
92
|
+
`style` | set a CSS style attribute on the SVG
|
78
93
|
`data` | add data attributes to the SVG (supply as a hash)
|
79
|
-
`size` | set width and height attributes on the SVG <br/> Can also be set using `height` and/or `width` attributes, which take precedence over `size` <br/> Supplied as "{Width} * {Height}" or "{Number}", so "30px
|
94
|
+
`size` | set width and height attributes on the SVG <br/> Can also be set using `height` and/or `width` attributes, which take precedence over `size` <br/> Supplied as "{Width} * {Height}" or "{Number}", so "30px\*45px" becomes `width="30px"` and `height="45px"`, and "50%" becomes `width="50%"` and `height="50%"`
|
80
95
|
`title` | add a \<title\> node inside the top level of the SVG document
|
81
96
|
`desc` | add a \<desc\> node inside the top level of the SVG document
|
82
|
-
`nocomment` | remove comment tags
|
97
|
+
`nocomment` | remove comment tags from the SVG document
|
83
98
|
`preserve_aspect_ratio` | adds a `preserveAspectRatio` attribute to the SVG
|
84
99
|
`aria` | adds common accessibility attributes to the SVG (see [PR #34](https://github.com/jamesmartin/inline_svg/pull/34#issue-152062674) for details)
|
100
|
+
`aria_hidden` | adds the `aria-hidden=true` attribute to the SVG
|
101
|
+
`fallback` | set fallback SVG document
|
85
102
|
|
86
103
|
Example:
|
87
104
|
|
88
105
|
```ruby
|
89
|
-
|
90
|
-
|
106
|
+
inline_svg_tag(
|
107
|
+
"some-document.svg",
|
108
|
+
id: 'some-id',
|
109
|
+
class: 'some-class',
|
110
|
+
data: {some: "value"},
|
111
|
+
size: '30% * 20%',
|
112
|
+
title: 'Some Title',
|
113
|
+
desc: 'Some description',
|
114
|
+
nocomment: true,
|
115
|
+
preserve_aspect_ratio: 'xMaxYMax meet',
|
116
|
+
aria: true,
|
117
|
+
aria_hidden: true,
|
118
|
+
fallback: 'fallback-document.svg'
|
119
|
+
)
|
91
120
|
```
|
92
121
|
|
93
122
|
## Accessibility
|
94
123
|
|
95
|
-
Use the `aria: true` option to make `
|
124
|
+
Use the `aria: true` option to make `inline_svg_tag` add the following
|
96
125
|
accessibility (a11y) attributes to your embedded SVG:
|
97
126
|
|
98
127
|
* Adds a `role="img"` attribute to the root SVG element
|
@@ -103,7 +132,7 @@ Here's an example:
|
|
103
132
|
|
104
133
|
```erb
|
105
134
|
<%=
|
106
|
-
|
135
|
+
inline_svg_tag('iconmonstr-glasses-12-icon.svg',
|
107
136
|
aria: true, title: 'An SVG',
|
108
137
|
desc: 'This is my SVG. There are many like it. You get the picture')
|
109
138
|
%>
|
@@ -117,11 +146,11 @@ Here's an example:
|
|
117
146
|
</svg>
|
118
147
|
```
|
119
148
|
|
120
|
-
***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 `
|
149
|
+
***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_tag` embedding elements inside the SVG with `id` attributes that clash with other elements elsewhere on the page.
|
121
150
|
|
122
151
|
## Custom Transformations
|
123
152
|
|
124
|
-
The transformation behavior of `
|
153
|
+
The transformation behavior of `inline_svg_tag` can be customized by creating custom transformation classes.
|
125
154
|
|
126
155
|
For example, inherit from `InlineSvg::CustomTransformation` and implement the `#transform` method:
|
127
156
|
|
@@ -131,10 +160,9 @@ For example, inherit from `InlineSvg::CustomTransformation` and implement the `#
|
|
131
160
|
|
132
161
|
class MyCustomTransform < InlineSvg::CustomTransformation
|
133
162
|
def transform(doc)
|
134
|
-
doc
|
135
|
-
|
136
|
-
|
137
|
-
doc
|
163
|
+
with_svg(doc) do |svg|
|
164
|
+
svg["custom"] = value
|
165
|
+
end
|
138
166
|
end
|
139
167
|
end
|
140
168
|
```
|
@@ -151,7 +179,7 @@ end
|
|
151
179
|
The custom transformation can then be called like so:
|
152
180
|
```haml
|
153
181
|
%div
|
154
|
-
=
|
182
|
+
= inline_svg_tag "some-document.svg", my_custom_attribute: 'some value'
|
155
183
|
```
|
156
184
|
|
157
185
|
In this example, the following transformation would be applied to a SVG document:
|
@@ -172,8 +200,8 @@ end
|
|
172
200
|
The custom transformation will be triggered even if you don't pass any attribute value
|
173
201
|
```haml
|
174
202
|
%div
|
175
|
-
=
|
176
|
-
=
|
203
|
+
= inline_svg_tag "some-document.svg"
|
204
|
+
= inline_svg_tag "some-document.svg", my_custom_attribute: 'some value'
|
177
205
|
```
|
178
206
|
|
179
207
|
In this example, the following transformation would be applied to a SVG document:
|
@@ -203,6 +231,92 @@ Transforms are applied in ascending order (lowest number first).
|
|
203
231
|
***Note***: Custom transformations are always applied *after* all built-in
|
204
232
|
transformations, regardless of priority.
|
205
233
|
|
234
|
+
## Custom asset file loader
|
235
|
+
|
236
|
+
An asset file loader returns a `String` representing a SVG document given a
|
237
|
+
filename. Custom asset loaders should be a Ruby object that responds to a
|
238
|
+
method called `named`, that takes one argument (a string representing the
|
239
|
+
filename of the SVG document).
|
240
|
+
|
241
|
+
A simple example might look like this:
|
242
|
+
|
243
|
+
```ruby
|
244
|
+
class MyAssetFileLoader
|
245
|
+
def self.named(filename)
|
246
|
+
# ... load SVG document however you like
|
247
|
+
return "<svg>some document</svg>"
|
248
|
+
end
|
249
|
+
end
|
250
|
+
```
|
251
|
+
|
252
|
+
Configure your custom asset file loader in an initializer like so:
|
253
|
+
|
254
|
+
```ruby
|
255
|
+
InlineSvg.configure do |config|
|
256
|
+
config.asset_file = MyAssetFileLoader
|
257
|
+
end
|
258
|
+
```
|
259
|
+
|
260
|
+
## Caching all assets at boot time
|
261
|
+
|
262
|
+
When your deployment strategy prevents dynamic asset file loading from disk it
|
263
|
+
can be helpful to cache all possible SVG assets in memory at application boot
|
264
|
+
time. In this case, you can configure the `InlineSvg::CachedAssetFile` to scan
|
265
|
+
any number of paths on disks and load all the assets it finds into memory.
|
266
|
+
|
267
|
+
For example, in this configuration we load every `*.svg` file found beneath the
|
268
|
+
configured paths into memory:
|
269
|
+
|
270
|
+
```ruby
|
271
|
+
InlineSvg.configure do |config|
|
272
|
+
config.asset_file = InlineSvg::CachedAssetFile.new(
|
273
|
+
paths: [
|
274
|
+
"#{Rails.root}/public/path/to/assets",
|
275
|
+
"#{Rails.root}/public/other/path/to/assets"
|
276
|
+
],
|
277
|
+
filters: /\.svg/
|
278
|
+
)
|
279
|
+
end
|
280
|
+
```
|
281
|
+
|
282
|
+
**Note:** Paths are read recursively, so think about keeping your SVG assets
|
283
|
+
restricted to as few paths as possible, and using the filter option to further
|
284
|
+
restrict assets to only those likely to be used by `inline_svg_tag`.
|
285
|
+
|
286
|
+
## Missing SVG Files
|
287
|
+
|
288
|
+
If the specified SVG file cannot be found a helpful, empty SVG document is
|
289
|
+
embedded into the page instead. The embedded document contains a single comment
|
290
|
+
displaying the filename of the SVG image the helper tried to render:
|
291
|
+
|
292
|
+
```html
|
293
|
+
<svg><!-- SVG file not found: 'some-missing-file.svg' --></svg>
|
294
|
+
```
|
295
|
+
|
296
|
+
You may apply a class to this empty SVG document by specifying the following
|
297
|
+
configuration:
|
298
|
+
|
299
|
+
```rb
|
300
|
+
InlineSvg.configure do |config|
|
301
|
+
config.svg_not_found_css_class = 'svg-not-found'
|
302
|
+
end
|
303
|
+
```
|
304
|
+
|
305
|
+
Which would instead render:
|
306
|
+
|
307
|
+
```html
|
308
|
+
<svg class='svg-not-found'><!-- SVG file not found: 'some-missing-file.svg' --></svg>
|
309
|
+
```
|
310
|
+
|
311
|
+
Alternatively, `inline_svg_tag` can be configured to raise an exception when a file
|
312
|
+
is not found:
|
313
|
+
|
314
|
+
```ruby
|
315
|
+
InlineSvg.configure do |config|
|
316
|
+
config.raise_on_file_not_found = true
|
317
|
+
end
|
318
|
+
```
|
319
|
+
|
206
320
|
## Contributing
|
207
321
|
|
208
322
|
1. Fork it ( [http://github.com/jamesmartin/inline_svg/fork](http://github.com/jamesmartin/inline_svg/fork) )
|