Update the docs

ddamato · Jun 16, 2020 · ae139ff · ae139ff
1 parent f9a1e8e
commit ae139ff
Show file tree

Hide file tree

Showing 6 changed files with 68 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -129,6 +129,24 @@ const { injectionFn } = require('savager');
 
 ---
 
+### `getAssets(assetNames, options)`
+
+This is a slimmer version of the `prepareAssets()` method on the `Savager` instance. It can be helpful when you've prepared your reference sheet in one part of the app lifecycle but need to generate the assets at another time without needing to import the `symbols` and instanciate another instance.
+
+This function will not provide a reference sheet, only the `assets` and `inject` (if requested).
+
+The `consolidate` and `autoAppend` options do nothing here as there is no reference sheet to work with.
+
+```js
+const { getAssets } = require('savager');
+
+const { assets } = getAssets(['balloon', 'paperclip'], { externalPath: 'path/to/assets' });
+console.log(assets.balloon); // <svg><use href="path/to/assets/balloon.svg#balloon"></svg>
+console.log(assets.paperclip); // <svg><use href="path/to/assets/paperclip.svg#paperclip"></svg>
+```
+
+---
+
 ### `createSymbols(pathOrObject)`
 
 This method takes a single argument, either a path to SVG files or an object where the keys are asset names (used for look up) and the value is a SVG XML string (`<svg></svg>`). When using the directory path, the file name will become the asset name.

diff --git a/docs/index.html b/docs/index.html
@@ -1,4 +1,4 @@
-<!doctype html><html lang="en"><head><title>Savager Example Page</title><meta http-equiv="content-type" content="text/html; charset=utf-8"><meta content="chrome=1" http-equiv="X-UA-Compatible"><meta content="width=device-width,initial-scale=1" name="viewport"><meta name="description" content="Savager Example Page"><link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;700&display=swap" rel="stylesheet"><link href="styles.css" rel="stylesheet"></head><body><nav class="navigation"><svg exposure="internal" xmlns="http://www.w3.org/2000/svg" class="savager-logo"><use href="#savager-logo"></use></svg><ul class="none"><li><a class="neom-concave" href="#getting-started">Getting Started</a></li><li><a class="neom-concave" href="#external-assets">External Assets</a></li><li><a class="neom-concave" href="#internal-assets">Internal Assets</a></li><li><a class="neom-concave" href="#contingencies">Contingencies</a></li><li><a class="neom-concave" href="#examples">Examples</a></li></ul></nav><main class="content"><h1 id="savager">Savager</h1><h2 id="getting-started">Getting Started</h2><p>Install the package into your project</p><pre class="language-bash"><code class="language-bash"><span class="token function">npm</span> i savager
+<!doctype html><html lang="en"><head><title>Savager Example Page</title><meta http-equiv="content-type" content="text/html; charset=utf-8"><meta content="chrome=1" http-equiv="X-UA-Compatible"><meta content="width=device-width,initial-scale=1" name="viewport"><meta name="description" content="Savager Example Page"><link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;700&display=swap" rel="stylesheet"><link href="styles.css" rel="stylesheet"></head><body><nav class="navigation"><svg exposure="internal" xmlns="http://www.w3.org/2000/svg" class="savager-logo"><use href="#savager-logo"></use></svg><ul class="none"><li><a class="neom-concave" href="#getting-started">Getting Started</a></li><li><a class="neom-concave" href="#external-assets">External Assets</a></li><li><a class="neom-concave" href="#internal-assets">Internal Assets</a></li><li><a class="neom-concave" href="#contingencies">Contingencies</a></li><li><a class="neom-concave" href="#organization">Organization</a></li><li><a class="neom-concave" href="#examples">Examples</a></li></ul></nav><main class="content"><h1 id="savager">Savager</h1><h2 id="getting-started">Getting Started</h2><p>Install the package into your project</p><pre class="language-bash"><code class="language-bash"><span class="token function">npm</span> i savager
 </code></pre><p>Run the <code>create-symbols</code> script against your SVG files.</p><pre class="language-bash"><code class="language-bash">create-symbols -i svg -o assets -t esm
 </code></pre><p>Then import <code>Savager</code> and the symbols into your build script. The <code>assets</code> output will contain your new SVG markup!</p><pre class="language-js"><code class="language-js"><span class="token keyword">import</span> Savager <span class="token keyword">from</span> <span class="token string">'savager'</span><span class="token punctuation">;</span>
 <span class="token keyword">import</span> symbols <span class="token keyword">from</span> <span class="token string">'./manifest.js'</span><span class="token punctuation">;</span>
@@ -30,7 +30,19 @@
 <span class="token keyword">const</span> savager <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">Savager</span><span class="token punctuation">(</span>symbols<span class="token punctuation">,</span> <span class="token punctuation">{</span> attemptInject<span class="token operator">:</span> <span class="token boolean">true</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
 <span class="token keyword">const</span> <span class="token punctuation">{</span> assets<span class="token punctuation">,</span> inject <span class="token punctuation">}</span> <span class="token operator">=</span> savager<span class="token punctuation">.</span><span class="token function">prepareAssets</span><span class="token punctuation">(</span><span class="token string">'balloon'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
 </code></pre><p>If you need the <code>inject</code> function in a different context from where you prepare assets, you can export it directly from the package. Be sure that when preparing assets, that <code>attemptInject</code> option was set to <code>true</code>. Otherwise, executing the function will do nothing.</p><pre class="language-js"><code class="language-js"><span class="token keyword">import</span> <span class="token punctuation">{</span> injectionFn <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'savager'</span><span class="token punctuation">;</span>
-</code></pre><h2 id="examples">Examples</h2><p>Each one of the examples shows the code after initializing an instance of Savager as well as the output to this page with an SVG.</p><p>Reference sheets are automatically consolidated under the <code>savager-primarysheet</code> Element by default using <code>consolidate</code> option. This consolidates multiple reference sheets found on the page into a single sheet. For the purposes of example, this option has been set to <code>false</code> so sheets can be inspected within the page. Consolidation is normally an important step to ensure no <code>id</code> is duplicated.</p><hr><h3 id="assets-as-innerhtml">Assets as innerHTML</h3><p>Creating these assets will return strings. You can export the strings to a render function for templating or just write them as HTML. Remember to add the sheet to the page if the assets are not hosted.</p><pre class="language-js"><code class="language-js"><span class="token keyword">const</span> <span class="token punctuation">{</span> assets<span class="token punctuation">,</span> sheet <span class="token punctuation">}</span> <span class="token operator">=</span> savager<span class="token punctuation">.</span><span class="token function">prepareAssets</span><span class="token punctuation">(</span><span class="token string">'bang-triangle'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
+</code></pre><h2 id="organization">Organization</h2><p>One method of organizing is to create a <code>savager.config.js</code> which you may maintain as your source of truth for SVG assets.</p><pre class="language-js"><code class="language-js"><span class="token comment">// savager.config.js</span>
+<span class="token keyword">import</span> Savager <span class="token keyword">from</span> <span class="token string">'savager'</span><span class="token punctuation">;</span>
+<span class="token keyword">import</span> symbols <span class="token keyword">from</span> <span class="token string">'./manifest.js'</span><span class="token punctuation">;</span>
+
+<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">new</span> <span class="token class-name">Savager</span><span class="token punctuation">(</span>symbols<span class="token punctuation">)</span><span class="token punctuation">;</span>
+</code></pre><p>Then you can prepare assets as needed.</p><pre class="language-js"><code class="language-js"><span class="token keyword">import</span> <span class="token punctuation">{</span> prepareAssets <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'./savager.config.js'</span><span class="token punctuation">;</span>
+
+<span class="token keyword">const</span> <span class="token punctuation">{</span> assets<span class="token punctuation">,</span> sheet <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">prepareAssets</span><span class="token punctuation">(</span><span class="token string">'balloon'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
+</code></pre><p>You may also apply the reference sheet earlier and use the <code>getAssets</code> export from the package to render your assets. This function is independent from the <code>symbols</code> entered into a <code>Savager</code> instance; it just assumes these assets are included in the correct location given the options you provide.</p><pre class="language-js"><code class="language-js"><span class="token comment">// Assume the reference sheet is on the page</span>
+<span class="token keyword">import</span> <span class="token punctuation">{</span> getAssets <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'savager'</span><span class="token punctuation">;</span>
+
+<span class="token keyword">const</span> <span class="token punctuation">{</span> assets <span class="token punctuation">}</span> <span class="token operator">=</span> <span class="token function">getAssets</span><span class="token punctuation">(</span><span class="token string">'balloon'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
+</code></pre><p>Options related to reference sheet management (<code>consolidate</code>, <code>autoAppend</code>) do not affect these assets.</p><h2 id="examples">Examples</h2><p>Each one of the examples shows the code after initializing an instance of Savager as well as the output to this page with an SVG.</p><p>Reference sheets are automatically consolidated under the <code>savager-primarysheet</code> Element by default using <code>consolidate</code> option. This consolidates multiple reference sheets found on the page into a single sheet. For the purposes of example, this option has been set to <code>false</code> so sheets can be inspected within the page. Consolidation is normally an important step to ensure no <code>id</code> is duplicated.</p><hr><h3 id="assets-as-innerhtml">Assets as innerHTML</h3><p>Creating these assets will return strings. You can export the strings to a render function for templating or just write them as HTML. Remember to add the sheet to the page if the assets are not hosted.</p><pre class="language-js"><code class="language-js"><span class="token keyword">const</span> <span class="token punctuation">{</span> assets<span class="token punctuation">,</span> sheet <span class="token punctuation">}</span> <span class="token operator">=</span> savager<span class="token punctuation">.</span><span class="token function">prepareAssets</span><span class="token punctuation">(</span><span class="token string">'bang-triangle'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
 
 <span class="token comment">/* Add the reference sheet to the page */</span>
 <span class="token keyword">const</span> sheetContainer <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">'div'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

diff --git a/docs/index.md b/docs/index.md
@@ -88,6 +88,34 @@ If you need the `inject` function in a different context from where you prepare
 import { injectionFn } from 'savager';
 ```
 
+## Organization
+One method of organizing is to create a `savager.config.js` which you may maintain as your source of truth for SVG assets.
+
+```js
+// savager.config.js
+import Savager from 'savager';
+import symbols from './manifest.js';
+
+export default new Savager(symbols);
+```
+
+Then you can prepare assets as needed.
+
+```js
+import { prepareAssets } from './savager.config.js';
+
+const { assets, sheet } = prepareAssets('balloon');
+```
+
+You may also apply the reference sheet earlier and use the `getAssets` export from the package to render your assets. This function is independent from the `symbols` entered into a `Savager` instance; it just assumes these assets are included in the correct location given the options you provide.
+
+```js
+// Assume the reference sheet is on the page
+import { getAssets } from 'savager';
+
+const { assets } = getAssets('balloon');
+```
+Options related to reference sheet management (`consolidate`, `autoAppend`) do not affect these assets.
 
 ## Examples