<commit_before># Scavenger

This project rocks and uses MIT-LICENSE.<commit_msg>Adds documentation<commit_after># Scavenger

A Rails plugin for turning a directory of svg images into a sprite sheet, for frontend performance and reusability.


## Getting started

Put the gem in your `Gemfile` and run `bundle install`:
`gem "scavenger"`

Create a folder called `app/assets/svg` and put your svg images there, then in `views/layouts/application.html.erb`:
`<%= svg_sprite_sheet %>`

Now you can refer to your svg images by their name, so if you have `hejsna.svg` sitting in your svg directory, you can get a reference to it by writing `<%= svg "hejsna" %>`.


## The `svg` helper

Scavenger works by inserting svg tags with a reference in them. There is nothing inherently special about these svg tags, so if you want to add classes or attributes to it, you can: `<%= svg "hejsna", class: "foo", style: "width:100px" %>`.


## Loading the sprite sheet asynchronously

Scavenger comes with a dependency-free javascript for fetching and injecting the sprite sheet into the DOM. This is a pretty good idea since the sprite sheet can be served from your reverse proxy and be cached by the browser. Extra nice if you have a lot of symbols and don't want to bloat every page, but the downside is that users may experience a brief flash of missing icons. To use this javascript, remove the `<%= svg_sprite_sheet %>` helper from your layout and instead include the javascript in your `application.js` like so:
`//= require scavenger`


## Configuration

You can configure Scavenger to do your bidding. Create a file called `config/initializers/scavenger.rb` and put your configuration there.


### Use another directory

Default is `app/assets/svg` but it can be changed with the following directive:
`Scavenger::Config.svg_directory = Rails.root.join("app", "assets", "my_directory")`


### Put the compiled sprite sheet somewhere else

Default is `app/assets/images/sprite.svg` but it can be changed with the following directive:
`Scavenger::Config.sprite_path = Rails.root.join("app", "assets", "my_directory", "my_file.svg")`


### Set a default prefix on your svg classes

The svg references will get their name as the default classname, so `hejsna.svg` will be inserted like this: `<svg class="hejsna">`. If you want a prefix, for instance `icon-`, put `Scavenger::Config.class_prefix = "icon-"` in your configuration file and the svg will look like this instead: `<svg class="icon-hejsna">`.


## Caveats

Scavenger uses a basic built-in compressor. It will remove comments, non-significant whitespace, and ids from your files. Since every svg lives as a `symbol` within the sprite sheet, all `<defs>` tags and everything in them will be removed. Some tools (like [Sketch](https://www.sketchapp.com)) will export your files with references inside `<defs>` and use really generic ids in there, like `path-1`. That poses a problem for us since there's only one global `<defs>` tag within an svg, and ids are global to the html document. We've experimented with some workarounds but nothing satisfactory, so the solution for now is to manually fix any svgs that use `<defs>` tags in this way. Ideas welcome!
{'fraction_non_alphanumeric': 0.08338538413491568, 'fraction_numerical': 0.0012492192379762648, 'mean_word_length': 4.699288256227758, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 1, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3449975', 'n_tokens_mistral': 926, 'n_tokens_neox': 866, 'n_words': 456}