inline_svg 1.0.0 → 1.10.0

data/CHANGELOG.md

@@ -3,7 +3,129 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][unreleased]
-- Nothing
+
+Nothing.
+
+## [1.10.0] - 2024-09-03
+### Added
+- Support for Shakapacker.  [#158](https://github.com/jamesmartin/inline_svg/pull/158). Thanks, [@tagliala](https://github.com/tagliala)
+
+### Fixed
+- Fixed documentation typos.  [#157](https://github.com/jamesmartin/inline_svg/pull/157). Thanks, [@tagliala](https://github.com/tagliala)
+- Fixed missing ActiveSupport require.  [#152](https://github.com/jamesmartin/inline_svg/pull/152). Thanks, [@xymbol](https://github.com/xymbol)
+- Remove wrapping whitespace from SVG tags.  [#150](https://github.com/jamesmartin/inline_svg/pull/150). Thanks, [@fredboyle](https://github.com/fredboyle)
+
+## [1.9.0] - 2023-03-29
+### Added
+- A new option: `view_box` adds a `viewBox` attribute to the SVG. [#142](https://github.com/jamesmartin/inline_svg/pull/142). Thanks [@sunny](https://github.com/sunny)
+
+### Fixed
+- Allow Propshaft assets to use fallbacks. [#140](https://github.com/jamesmartin/inline_svg/pull/140). Thanks, [@ohrite](https://github.com/ohrite)
+- Handling missing file when using static assets. [#141](https://github.com/jamesmartin/inline_svg/pull/141). Thanks, [@leighhalliday](https://github.com/leighhalliday)
+- Handle missing file when using Webpacker assets.
+
+## [1.8.0] - 2022-01-09
+### Added
+- Remove deprecation warning for `inline_svg`, as we intend to keep it in 2.0. [#131](https://github.com/jamesmartin/inline_svg/pull/131). Thanks [@DanielJackson-Oslo](https://github.com/DanielJackson-Oslo)
+- Add support for Webpacker 6 beta. [#129](https://github.com/jamesmartin/inline_svg/pull/129). Thanks [@Intrepidd](https://github.com/Intrepidd) and [@tessi](https://github.com/tessi)
+- Add support for Propshaft assets in Rails 7. [#134](https://github.com/jamesmartin/inline_svg/pull/134). Thanks, [@martinzamuner](https://github.com/martinzamuner)
+
+## [1.7.2] - 2020-12-07
+### Fixed
+- Improve performance of `CachedAssetFile`. [#118](https://github.com/jamesmartin/inline_svg/pull/118). Thanks [@stevendaniels](https://github.com/stevendaniels)
+- Avoid XSS by preventing malicious input of filenames. [#117](https://github.com/jamesmartin/inline_svg/pull/117). Thanks [@pbyrne](https://github.com/pbyrne).
+
+## [1.7.1] - 2020-03-17
+### Fixed
+- 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)
+
+## [1.7.0] - 2020-02-13
+### Added
+- 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)
+
+### Fixed
+- 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)
+- 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)
+
+## [1.6.0] - 2019-11-13
+### Added
+- Support Webpack via the new `inline_svg_pack_tag` helper and deprecate `inline_svg` helper in preparation for v2.0.
+[#103](https://github.com/jamesmartin/inline_svg/pull/103)
+Thanks, [@kylefox](https://github.com/kylefox)
+
+## [1.5.2] - 2019-06-20
+### Fixed
+- Revert automatic Webpack asset finder behavior. Make Webpack "opt-in".
+  [#98](https://github.com/jamesmartin/inline_svg/issues/98)
+
+## [1.5.1] - 2019-06-18
+### Fixed
+- Prevent nil asset finder when neither Sprockets or Webpacker are available
+  [#97](https://github.com/jamesmartin/inline_svg/issues/97)
+
+## [1.5.0] - 2019-06-17
+### Added
+- Support for finding assets bundled by Webpacker
+  [#96](https://github.com/jamesmartin/inline_svg/pull/96)
+
+## [1.4.0] - 2019-04-19
+### Fixed
+- Prevent invalid XML names being generated via IdGenerator
+  [#87](https://github.com/jamesmartin/inline_svg/issues/87)
+  Thanks, [@endorfin](https://github.com/endorfin)
+
+### Added
+- Raise error on file not found (if configured)
+  [#93](https://github.com/jamesmartin/inline_svg/issues/93)
+
+## [1.3.1] - 2017-12-14
+### Fixed
+- Allow Ruby < 2.1 to work with `CachedAssetFile`
+  [#80](https://github.com/jamesmartin/inline_svg/pull/80)
+
+## [1.3.0] - 2017-10-30
+### Added
+- Aria hidden attribute
+  [#78](https://github.com/jamesmartin/inline_svg/pull/78)
+  and [#79](https://github.com/jamesmartin/inline_svg/pull/79)
+- In-line CSS style attribute
+  [#71](https://github.com/jamesmartin/inline_svg/pull/71)
+
+### Fixed
+- Make aria ID attributes unique
+  [#77](https://github.com/jamesmartin/inline_svg/pull/77)
+
+## [1.2.3] - 2017-08-17
+### Fixed
+- Handle UTF-8 characters in SVG documents
+  [#60](https://github.com/jamesmartin/inline_svg/pull/69)
+
+## [1.2.2] - 2017-07-06
+### Fixed
+- Handle malformed documents that don't contain a root SVG element
+  [#60](https://github.com/jamesmartin/inline_svg/pull/65)
+### Added
+- Add configurable CSS class to empty SVG document
+  [#67](https://github.com/jamesmartin/inline_svg/pull/67)
+
+## [1.2.1] - 2017-05-02
+### Fixed
+- Select most exactly matching cached asset file when multiple files match
+  given asset name [#64](https://github.com/jamesmartin/inline_svg/pull/64)
+
+## [1.2.0] - 2017-04-20
+### Added
+- Cached asset file (load assets into memory at boot time)
+  [#62](https://github.com/jamesmartin/inline_svg/pull/62)
+
+## [1.1.0] - 2017-04-12
+### Added
+- Allow configurable asset file implementations
+  [#61](https://github.com/jamesmartin/inline_svg/pull/61)
+
+## [1.0.1] - 2017-04-10
+### Fixed
+- Don't override custom asset finders in Railtie
 
 ## [1.0.0] - 2017-04-7
 ### Added
@@ -99,7 +221,7 @@ transformations](https://github.com/jamesmartin/inline_svg/blob/master/README.md
 
 ## [0.5.1] - 2015-03-30
 ### Warning
-** This version is NOT comaptible with Sprockets >= 3. **
+** This version is NOT compatible with Sprockets >= 3. **
 
 ### Fixed
 - Support for ActiveSupport (and hence, Rails) 4.2.x. Thanks, @jmarceli.
@@ -140,7 +262,25 @@ transformations](https://github.com/jamesmartin/inline_svg/blob/master/README.md
 ### Added
 - Basic Railtie and view helper to inline SVG documents to Rails views.
 
-[unreleased]: https://github.com/jamesmartin/inline_svg/compare/v1.0.0...HEAD
+[unreleased]: https://github.com/jamesmartin/inline_svg/compare/v1.9.0...HEAD
+[1.9.0]: https://github.com/jamesmartin/inline_svg/compare/v1.8.0...v1.9.0
+[1.8.0]: https://github.com/jamesmartin/inline_svg/compare/v1.7.2...v1.8.0
+[1.7.2]: https://github.com/jamesmartin/inline_svg/compare/v1.7.1...v1.7.2
+[1.7.1]: https://github.com/jamesmartin/inline_svg/compare/v1.7.0...v1.7.1
+[1.7.0]: https://github.com/jamesmartin/inline_svg/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/jamesmartin/inline_svg/compare/v1.5.2...v1.6.0
+[1.5.2]: https://github.com/jamesmartin/inline_svg/compare/v1.5.1...v1.5.2
+[1.5.1]: https://github.com/jamesmartin/inline_svg/compare/v1.5.0...v1.5.1
+[1.5.0]: https://github.com/jamesmartin/inline_svg/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/jamesmartin/inline_svg/compare/v1.3.1...v1.4.0
+[1.3.1]: https://github.com/jamesmartin/inline_svg/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/jamesmartin/inline_svg/compare/v1.2.3...v1.3.0
+[1.2.3]: https://github.com/jamesmartin/inline_svg/compare/v1.2.2...v1.2.3
+[1.2.2]: https://github.com/jamesmartin/inline_svg/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/jamesmartin/inline_svg/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/jamesmartin/inline_svg/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/jamesmartin/inline_svg/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/jamesmartin/inline_svg/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/jamesmartin/inline_svg/compare/v0.12.1...v1.0.0
 [0.12.1]: https://github.com/jamesmartin/inline_svg/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/jamesmartin/inline_svg/compare/v0.11.1...v0.12.0

data/README.md

@@ -1,13 +1,22 @@
 # Inline SVG
 
+![Unit tests](https://github.com/jamesmartin/inline_svg/workflows/Ruby/badge.svg)
+![Integration Tests](https://github.com/jamesmartin/inline_svg/workflows/Integration%20Tests/badge.svg)
+
 Styling a SVG document with CSS for use on the web is most reliably achieved by
 [adding classes to the document and
 embedding](http://css-tricks.com/using-svg/) 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
+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
 then embeds it into a view.
 
-Inline SVG supports [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)), [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/) (from [v0.10.0](https://github.com/jamesmartin/inline_svg/releases/tag/v0.10.0)).
+Inline SVG supports:
+
+- [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))
+- [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)).
+- [Rails 7](https://weblog.rubyonrails.org/2021/12/6/Rails-7-0-rc-1-released/)
+
+Inline SVG no longer officially supports Rails 3 or Rails 4 (although they may still work). In order to reduce the maintenance cost of this project we now follow the [Rails Maintenance Policy](https://guides.rubyonrails.org/maintenance_policy.html).
 
 ## Changelog
 
@@ -30,9 +39,15 @@ Or install it yourself as:
 
 ## Usage
 
+```ruby
+# Sprockets
+inline_svg_tag(file_name, options={})
+
+# Webpacker
+inline_svg_pack_tag(file_name, options={})
 ```
-inline_svg(file_name, options={})
-```
+
+_**Note:** The remainder of this README uses `inline_svg_tag` for examples, but the exact same principles work for `inline_svg_pack_tag`._
 
 The `file_name` can be a full path to a file, the file's basename or an `IO`
 object. The
@@ -40,18 +55,20 @@ actual path of the file on disk is resolved using
 [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.
 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 in
-HAML:
+Here's an example of embedding an SVG document and applying a 'class' attribute:
 
-```haml
- !!! 5 
-  %html
-    %head
-      %title Embedded SVG Documents
-    %body
-      %h1 Embedded SVG Documents
-      %div
-        = inline_svg "some-document.svg", class: 'some-class'
+```erb
+<html>
+  <head>
+    <title>Embedded SVG Documents<title>
+  </head>
+  <body>
+    <h1>Embedded SVG Documents</h1>
+    <div>
+      <%= inline_svg_tag "some-document.svg", class: 'some-class' %>
+    </div>
+  </body>
+</html>
 ```
 
 Here's some CSS to target the SVG, resize it and turn it an attractive shade of
@@ -67,30 +84,47 @@ blue:
 }
 ```
 
-## Options 
+## Options
 
 key                     | description
-:---------------------- | :---------- 
+:---------------------- | :----------
 `id`                    | set a ID attribute on the SVG
 `class`                 | set a CSS class attribute on the SVG
+`style`                 | set a CSS style attribute on the SVG
 `data`                  | add data attributes to the SVG (supply as a hash)
 `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%"`
 `title`                 | add a \<title\> node inside the top level of the SVG document
 `desc`                  | add a \<desc\> node inside the top level of the SVG document
 `nocomment`             | remove comment tags from the SVG document
 `preserve_aspect_ratio` | adds a `preserveAspectRatio` attribute to the SVG
+`view_box`              | adds a `viewBox` attribute to the SVG
 `aria`                  | adds common accessibility attributes to the SVG (see [PR #34](https://github.com/jamesmartin/inline_svg/pull/34#issue-152062674) for details)
+`aria_hidden`           | adds the `aria-hidden=true` attribute to the SVG
+`fallback`              | set fallback SVG document
 
 Example:
 
 ```ruby
-inline_svg("some-document.svg", id: 'some-id', class: 'some-class', data: {some: "value"}, size: '30% * 20%', title: 'Some Title', desc:
-'Some description', nocomment: true, preserve_aspect_ratio: 'xMaxYMax meet', aria: true)
+inline_svg_tag(
+  "some-document.svg",
+  id: 'some-id',
+  class: 'some-class',
+  data: {some: "value"},
+  size: '30% * 20%',
+  title: 'Some Title',
+  desc: 'Some description',
+  nocomment: true,
+  preserve_aspect_ratio: 'xMaxYMax meet',
+  view_box: '0 0 100 100',
+  aria: true,
+  aria_hidden: true,
+  fallback: 'fallback-document.svg'
+)
 ```
 
 ## Accessibility
 
-Use the `aria: true` option to make `inline_svg` add the following
+Use the `aria: true` option to make `inline_svg_tag` add the following
 accessibility (a11y) attributes to your embedded SVG:
 
 * Adds a `role="img"` attribute to the root SVG element
@@ -101,7 +135,7 @@ Here's an example:
 
 ```erb
 <%=
-  inline_svg('iconmonstr-glasses-12-icon.svg',
+  inline_svg_tag('iconmonstr-glasses-12-icon.svg',
     aria: true, title: 'An SVG',
     desc: 'This is my SVG. There are many like it. You get the picture')
 %>
@@ -115,11 +149,11 @@ Here's an example:
 </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.
+***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.
 
 ## Custom Transformations
 
-The transformation behavior of `inline_svg` can be customized by creating custom transformation classes.
+The transformation behavior of `inline_svg_tag` can be customized by creating custom transformation classes.
 
 For example, inherit from `InlineSvg::CustomTransformation` and implement the `#transform` method:
 
@@ -129,10 +163,9 @@ For example, inherit from `InlineSvg::CustomTransformation` and implement the `#
 
 class MyCustomTransform < InlineSvg::CustomTransformation
   def transform(doc)
-    doc = Nokogiri::XML::Document.parse(doc.to_html)
-    svg = doc.at_css 'svg'
-    svg['custom'] = value
-    doc
+    with_svg(doc) do |svg|
+      svg["custom"] = value
+    end
   end
 end
 ```
@@ -149,7 +182,7 @@ end
 The custom transformation can then be called like so:
 ```haml
 %div
-  = inline_svg "some-document.svg", my_custom_attribute: 'some value'
+  = inline_svg_tag "some-document.svg", my_custom_attribute: 'some value'
 ```
 
 In this example, the following transformation would be applied to a SVG document:
@@ -170,8 +203,8 @@ 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'
+  = inline_svg_tag "some-document.svg"
+  = inline_svg_tag "some-document.svg", my_custom_attribute: 'some value'
 ```
 
 In this example, the following transformation would be applied to a SVG document:
@@ -201,6 +234,92 @@ 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 "<svg>some document</svg>"
+  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_tag`.
+
+## 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
+<svg><!-- SVG file not found: 'some-missing-file.svg' --></svg>
+```
+
+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
+<svg class='svg-not-found'><!-- SVG file not found: 'some-missing-file.svg' --></svg>
+```
+
+Alternatively, `inline_svg_tag` can be configured to raise an exception when a file
+is not found:
+
+```ruby
+InlineSvg.configure do |config|
+  config.raise_on_file_not_found = true
+end
+```
+
 ## Contributing
 
 1. Fork it ( [http://github.com/jamesmartin/inline_svg/fork](http://github.com/jamesmartin/inline_svg/fork) )

data/Rakefile

@@ -1 +1,8 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = Dir.glob("spec/**/*_spec.rb")
+  #t.rspec_opts = "--format documentation"
+end
+task :default => :spec

data/inline_svg.gemspec

@@ -18,11 +18,12 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 3.2"
   spec.add_development_dependency "rspec_junit_formatter", "0.2.2"
   spec.add_development_dependency "pry"
+  spec.add_development_dependency "rubocop"
 
   spec.add_runtime_dependency "activesupport", ">= 3.0"
   spec.add_runtime_dependency "nokogiri", ">= 1.6"

data/lib/inline_svg/action_view/helpers.rb

@@ -4,21 +4,82 @@ require 'action_view/context' if defined?(Rails)
 module InlineSvg
   module ActionView
     module Helpers
+      def inline_svg_tag(filename, transform_params={})
+        with_asset_finder(InlineSvg.configuration.asset_finder) do
+          render_inline_svg(filename, transform_params)
+        end
+      end
+
+      def inline_svg_pack_tag(filename, transform_params={})
+        with_asset_finder(InlineSvg::WebpackAssetFinder) do
+          render_inline_svg(filename, transform_params)
+        end
+      end
+
       def inline_svg(filename, transform_params={})
+        render_inline_svg(filename, transform_params)
+      end
+
+      private
+
+      def backwards_compatible_html_escape(filename)
+        # html_escape_once was introduced in newer versions of Rails.
+        if ERB::Util.respond_to?(:html_escape_once)
+          ERB::Util.html_escape_once(filename)
+        else
+          ERB::Util.html_escape(filename)
+        end
+      end
+
+      def render_inline_svg(filename, transform_params={})
         begin
-          svg_file = if InlineSvg::IOResource === filename
-            InlineSvg::IOResource.read filename
-          else
-            InlineSvg::AssetFile.named filename
+          svg_file = read_svg(filename)
+        rescue InlineSvg::AssetFile::FileNotFound => error
+          raise error if InlineSvg.configuration.raise_on_file_not_found?
+          return placeholder(filename) unless transform_params[:fallback].present?
+
+          if transform_params[:fallback].present?
+            begin
+              svg_file = read_svg(transform_params[:fallback])
+            rescue InlineSvg::AssetFile::FileNotFound
+              placeholder(filename)
+            end
           end
-        rescue InlineSvg::AssetFile::FileNotFound
-          return "<svg><!-- SVG file not found: '#{filename}' #{extension_hint(filename)}--></svg>".html_safe
         end
 
         InlineSvg::TransformPipeline.generate_html_from(svg_file, transform_params).html_safe
       end
 
-      private
+      def read_svg(filename)
+        if InlineSvg::IOResource === filename
+          InlineSvg::IOResource.read filename
+        else
+          configured_asset_file.named filename
+        end
+      end
+
+      def placeholder(filename)
+        css_class = InlineSvg.configuration.svg_not_found_css_class
+        not_found_message = "'#{backwards_compatible_html_escape(filename)}' #{extension_hint(filename)}"
+
+        if css_class.nil?
+          return "<svg><!-- SVG file not found: #{not_found_message}--></svg>".html_safe
+        else
+          return "<svg class='#{css_class}'><!-- SVG file not found: #{not_found_message}--></svg>".html_safe
+        end
+      end
+
+      def configured_asset_file
+        InlineSvg.configuration.asset_file
+      end
+
+      def with_asset_finder(asset_finder)
+        Thread.current[:inline_svg_asset_finder] = asset_finder
+        output = yield
+        Thread.current[:inline_svg_asset_finder] = nil
+
+        output
+      end
 
       def extension_hint(filename)
         filename.ends_with?(".svg") ? "" : "(Try adding .svg to your filename) "

data/lib/inline_svg/cached_asset_file.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module InlineSvg
+  class CachedAssetFile
+    attr_reader :assets, :filters, :paths
+
+    # For each of the given paths, recursively reads each asset and stores its
+    # contents alongside the full path to the asset.
+    #
+    # paths   - One or more String representing directories on disk to search
+    #           for asset files. Note: paths are searched recursively.
+    # filters - One or more Strings/Regexps to match assets against. Only
+    #           assets matching all filters will be cached and available to load.
+    #           Note: Specifying no filters will cache every file found in
+    #           paths.
+    #
+    def initialize(paths: [], filters: [])
+      @paths = Array(paths).compact.map { |p| Pathname.new(p) }
+      @filters = Array(filters).map { |f| Regexp.new(f) }
+      @assets = @paths.reduce({}) { |assets, p| assets.merge(read_assets(assets, p)) }
+      @sorted_asset_keys = assets.keys.sort { |a, b| a.size <=> b.size }
+    end
+
+    # Public: Finds the named asset and returns the contents as a string.
+    #
+    # asset_name  - A string representing the name of the asset to load
+    #
+    # Returns: A String or raises InlineSvg::AssetFile::FileNotFound error
+    def named(asset_name)
+      assets[key_for_asset(asset_name)] or
+        raise InlineSvg::AssetFile::FileNotFound.new("Asset not found: #{asset_name}")
+    end
+
+    private
+    # Internal: Finds the key for a given asset name (using a Regex). In the
+    # event of an ambiguous asset_name matching multiple assets, this method
+    # ranks the matches by their full file path, choosing the shortest (most
+    # exact) match over all others.
+    #
+    # Returns a String representing the key for the named asset or nil if there
+    # is no match.
+    def key_for_asset(asset_name)
+      @sorted_asset_keys.find { |k| k.include?(asset_name) }
+    end
+
+    # Internal: Recursively descends through current_paths reading each file it
+    # finds and adding them to the accumulator if the fullpath of the file
+    # matches all configured filters.
+    #
+    # acc     - Hash representing the accumulated assets keyed by full path
+    # paths   - Pathname representing the current node in the directory
+    #           structure to consider
+    #
+    # Returns a Hash containing the contents of each asset, keyed by fullpath
+    # to the asset.
+    def read_assets(acc, paths)
+      paths.each_child do |child|
+        if child.directory?
+          read_assets(acc, child)
+        elsif child.readable_real?
+          acc[child.to_s] = File.read(child) if matches_all_filters?(child)
+        end
+      end
+      acc
+    end
+
+    def matches_all_filters?(path)
+      filters.all? { |f| f.match(path.to_s) }
+    end
+  end
+end

data/lib/inline_svg/finds_asset_paths.rb

@@ -6,7 +6,7 @@ module InlineSvg
     end
 
     def self.configured_asset_finder
-      InlineSvg.configuration.asset_finder
+      Thread.current[:inline_svg_asset_finder] || InlineSvg.configuration.asset_finder
     end
   end
 end

data/lib/inline_svg/id_generator.rb

@@ -1,8 +1,17 @@
+require 'digest'
+
 module InlineSvg
   class IdGenerator
-    def self.generate(base, salt)
-      bytes = Digest::SHA1.digest("#{base}-#{salt}")
-      Digest.hexencode(bytes).to_i(16).to_s(36)
+    class Randomness
+      require "securerandom"
+      def self.call
+        SecureRandom.hex(10)
+      end
+    end
+
+    def self.generate(base, salt, randomness: Randomness)
+      bytes = Digest::SHA1.digest("#{base}-#{salt}-#{randomness.call}")
+      'a' + Digest.hexencode(bytes).to_i(16).to_s(36)
     end
   end
 end