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.
Files changed (56) hide show
  1. checksums.yaml +5 -5
  2. data/.github/workflows/integration_test.yml +58 -0
  3. data/.github/workflows/ruby.yml +20 -0
  4. data/.rubocop.yml +1 -0
  5. data/.rubocop_todo.yml +421 -0
  6. data/CHANGELOG.md +144 -2
  7. data/README.md +148 -34
  8. data/Rakefile +7 -0
  9. data/inline_svg.gemspec +4 -4
  10. data/lib/inline_svg.rb +41 -9
  11. data/lib/inline_svg/action_view/helpers.rb +72 -7
  12. data/lib/inline_svg/cached_asset_file.rb +71 -0
  13. data/lib/inline_svg/finds_asset_paths.rb +1 -1
  14. data/lib/inline_svg/id_generator.rb +12 -3
  15. data/lib/inline_svg/io_resource.rb +4 -3
  16. data/lib/inline_svg/railtie.rb +8 -3
  17. data/lib/inline_svg/static_asset_finder.rb +4 -2
  18. data/lib/inline_svg/transform_pipeline.rb +0 -1
  19. data/lib/inline_svg/transform_pipeline/transformations.rb +8 -1
  20. data/lib/inline_svg/transform_pipeline/transformations/aria_attributes.rb +17 -20
  21. data/lib/inline_svg/transform_pipeline/transformations/aria_hidden.rb +9 -0
  22. data/lib/inline_svg/transform_pipeline/transformations/aria_hidden_attribute.rb +9 -0
  23. data/lib/inline_svg/transform_pipeline/transformations/class_attribute.rb +5 -6
  24. data/lib/inline_svg/transform_pipeline/transformations/data_attributes.rb +10 -5
  25. data/lib/inline_svg/transform_pipeline/transformations/description.rb +7 -6
  26. data/lib/inline_svg/transform_pipeline/transformations/height.rb +3 -4
  27. data/lib/inline_svg/transform_pipeline/transformations/id_attribute.rb +3 -4
  28. data/lib/inline_svg/transform_pipeline/transformations/no_comment.rb +5 -2
  29. data/lib/inline_svg/transform_pipeline/transformations/preserve_aspect_ratio.rb +3 -4
  30. data/lib/inline_svg/transform_pipeline/transformations/size.rb +4 -5
  31. data/lib/inline_svg/transform_pipeline/transformations/style_attribute.rb +11 -0
  32. data/lib/inline_svg/transform_pipeline/transformations/title.rb +7 -6
  33. data/lib/inline_svg/transform_pipeline/transformations/transformation.rb +13 -0
  34. data/lib/inline_svg/transform_pipeline/transformations/width.rb +3 -4
  35. data/lib/inline_svg/version.rb +1 -1
  36. data/lib/inline_svg/webpack_asset_finder.rb +50 -0
  37. data/spec/cached_asset_file_spec.rb +73 -0
  38. data/spec/files/static_assets/assets0/known-document-two.svg +1 -0
  39. data/spec/files/static_assets/assets0/known-document.svg +1 -0
  40. data/spec/files/static_assets/assets0/some-document.svg +1 -0
  41. data/spec/files/static_assets/assets1/known-document.svg +1 -0
  42. data/spec/files/static_assets/assets1/other-document.svg +3 -0
  43. data/spec/files/static_assets/assets1/some-file.txt +1 -0
  44. data/spec/helpers/inline_svg_spec.rb +104 -21
  45. data/spec/id_generator_spec.rb +5 -3
  46. data/spec/inline_svg_spec.rb +48 -0
  47. data/spec/transformation_pipeline/transformations/aria_attributes_spec.rb +16 -16
  48. data/spec/transformation_pipeline/transformations/aria_hidden_attribute_spec.rb +12 -0
  49. data/spec/transformation_pipeline/transformations/data_attributes_spec.rb +18 -0
  50. data/spec/transformation_pipeline/transformations/height_spec.rb +9 -0
  51. data/spec/transformation_pipeline/transformations/style_attribute_spec.rb +26 -0
  52. data/spec/transformation_pipeline/transformations/title_spec.rb +9 -0
  53. data/spec/transformation_pipeline/transformations/transformation_spec.rb +39 -0
  54. data/spec/transformation_pipeline/transformations_spec.rb +5 -1
  55. metadata +49 -22
  56. data/circle.yml +0 -3
@@ -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
- *** This version is NOT comaptible with Sprockets >= 3.***
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/v0.11.0...HEAD
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
+ ![Unit tests](https://github.com/jamesmartin/inline_svg/workflows/Ruby/badge.svg)
4
+ ![Integration Tests](https://github.com/jamesmartin/inline_svg/workflows/Integration%20Tests/badge.svg)
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 is a little 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
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 (from [v0.10.0](https://github.com/jamesmartin/inline_svg/releases/tag/v0.10.0)) supports both [Rails 4](http://weblog.rubyonrails.org/2013/6/25/Rails-4-0-final/) and [Rails 5](http://weblog.rubyonrails.org/2016/6/30/Rails-5-0-final/).
13
+ Inline SVG supports:
11
14
 
12
- Want to embed SVGs with Javascript? You might like [RemoteSvg](https://github.com/jamesmartin/remote-svg), which features similar transforms but can also load SVGs from remote URLs (like S3 etc.).
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://sermver.org). All notable changes are documented in the
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
- inline_svg(file_name, options={})
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 in
46
- HAML:
57
+ Here's an example of embedding an SVG document and applying a 'class' attribute:
47
58
 
48
- ```haml
49
- !!! 5
50
- %html
51
- %head
52
- %title Embedded SVG Documents
53
- %body
54
- %h1 Embedded SVG Documents
55
- %div
56
- = inline_svg "some-document.svg", class: 'some-class'
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*45px" becomes `width="30px"` and `height="45px"`, and "50%" becomes `width="50%"` and `height="50%"`
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 (and other unsafe/unknown tags) from svg (uses the [Loofah](https://github.com/flavorjones/loofah) gem)
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
- inline_svg("some-document.svg", id: 'some-id', class: 'some-class', data: {some: "value"}, size: '30% * 20%', title: 'Some Title', desc:
90
- 'Some description', nocomment: true, preserve_aspect_ratio: 'xMaxYMax meet', aria: true)
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 `inline_svg` add the following
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
- inline_svg('iconmonstr-glasses-12-icon.svg',
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 `inline_svg` embedding elements inside the SVG with `id` attributes that clash with other elements elsewhere on the page.
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 `inline_svg` can be customized by creating custom transformation classes.
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 = Nokogiri::XML::Document.parse(doc.to_html)
135
- svg = doc.at_css 'svg'
136
- svg['custom'] = value
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
- = inline_svg "some-document.svg", my_custom_attribute: 'some value'
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
- = inline_svg "some-document.svg"
176
- = inline_svg "some-document.svg", my_custom_attribute: 'some value'
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) )
data/Rakefile CHANGED
@@ -1 +1,8 @@
1
1
  require "bundler/gem_tasks"
2
+ require "rspec/core/rake_task"
3
+
4
+ RSpec::Core::RakeTask.new(:spec) do |t|
5
+ t.pattern = Dir.glob("spec/**/*_spec.rb")
6
+ #t.rspec_opts = "--format documentation"
7
+ end
8
+ task :default => :spec