scrawl-canvas
Version:
Version 8.9.4 - 19 Nov 2022
587 lines (401 loc) • 27.4 kB
HTML
<html>
<head>
<title>Demo Snippets 001</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
<link rel="stylesheet" media="all" href="../../docco.css" />
</head>
<body>
<div id="container">
<div id="background"></div>
<ul id="jump_to">
<li>
<a class="large" href="javascript:void(0);">Jump To …</a>
<a class="small" href="javascript:void(0);">+</a>
<div id="jump_wrapper">
<div id="jump_page_wrapper">
<div id="jump_page">
<a class="source" href="../modules/canvas-minimap.html">
./demo/modules/canvas-minimap.js
</a>
<a class="source" href="../modules/canvas-scene-editor.html">
./demo/modules/canvas-scene-editor.js
</a>
<a class="source" href="../modules/dom-entity-editor.html">
./demo/modules/dom-entity-editor.js
</a>
<a class="source" href="../modules/entity-copy-paste.html">
./demo/modules/entity-copy-paste.js
</a>
<a class="source" href="../modules/entity-manipulation-gui.html">
./demo/modules/entity-manipulation-gui.js
</a>
<a class="source" href="../modules/entity-navigation.html">
./demo/modules/entity-navigation.js
</a>
<a class="source" href="../modules/entity-ring-builder.html">
./demo/modules/entity-ring-builder.js
</a>
<a class="source" href="../modules/london-crime-graphic.html">
./demo/modules/london-crime-graphic.js
</a>
<a class="source" href="../modules/london-crime-lines.html">
./demo/modules/london-crime-lines.js
</a>
<a class="source" href="../modules/london-crime-stacked-bars.html">
./demo/modules/london-crime-stacked-bars.js
</a>
<a class="source" href="../modules/lottie-loader.html">
./demo/modules/lottie-loader.js
</a>
<a class="source" href="../modules/simple-chart-frame-tests.html">
./demo/modules/simple-chart-frame-tests.js
</a>
<a class="source" href="../modules/simple-chart-frame.html">
./demo/modules/simple-chart-frame.js
</a>
<a class="source" href="../modules/simple-graph-lines.html">
./demo/modules/simple-graph-lines.js
</a>
<a class="source" href="../modules/simple-graph-stacked-bars.html">
./demo/modules/simple-graph-stacked-bars.js
</a>
<a class="source" href="../modules/wikipedia-views-spiral-chart.html">
./demo/modules/wikipedia-views-spiral-chart.js
</a>
<a class="source" href="animated-highlight-gradient-text-snippet.html">
./demo/snippets/animated-highlight-gradient-text-snippet.js
</a>
<a class="source" href="animated-hover-gradient-snippet.html">
./demo/snippets/animated-hover-gradient-snippet.js
</a>
<a class="source" href="animated-word-gradient-snippet.html">
./demo/snippets/animated-word-gradient-snippet.js
</a>
<a class="source" href="before-after-slider-infographic.html">
./demo/snippets/before-after-slider-infographic.js
</a>
<a class="source" href="bubbles-text-snippet.html">
./demo/snippets/bubbles-text-snippet.js
</a>
<a class="source" href="green-box-snippet.html">
./demo/snippets/green-box-snippet.js
</a>
<a class="source" href="jazzy-button-snippet.html">
./demo/snippets/jazzy-button-snippet.js
</a>
<a class="source" href="page-performance-snippet-test.html">
./demo/snippets/page-performance-snippet-test.js
</a>
<a class="source" href="page-performance-snippet.html">
./demo/snippets/page-performance-snippet.js
</a>
<a class="source" href="pan-image-snippet.html">
./demo/snippets/pan-image-snippet.js
</a>
<a class="source" href="placeholder-effect-snippet.html">
./demo/snippets/placeholder-effect-snippet.js
</a>
<a class="source" href="ripple-effect-snippet.html">
./demo/snippets/ripple-effect-snippet.js
</a>
<a class="source" href="risograph-text-gradient-snippet.html">
./demo/snippets/risograph-text-gradient-snippet.js
</a>
<a class="source" href="spotlight-text-snippet-test.html">
./demo/snippets/spotlight-text-snippet-test.js
</a>
<a class="source" href="spotlight-text-snippet.html">
./demo/snippets/spotlight-text-snippet.js
</a>
<a class="source" href="swirling-stripes-text-snippet.html">
./demo/snippets/swirling-stripes-text-snippet.js
</a>
<a class="source" href="text-snippet-helper.html">
./demo/snippets/text-snippet-helper.js
</a>
<a class="source" href="word-highlighter-snippet.html">
./demo/snippets/word-highlighter-snippet.js
</a>
<a class="source" href="worley-text-gradient-snippet.html">
./demo/snippets/worley-text-gradient-snippet.js
</a>
</div>
</div>
</li>
</ul>
<ul class="sections">
<li id="section-1">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-1">§</a>
</div>
<h1 id="demo-snippets-001">Demo Snippets 001</h1>
<p>Scrawl-canvas DOM element snippets</p>
<p>Related files:</p>
<ul>
<li><a href="../snippets-001.html">DOM element snippets - main module</a></li>
<li><a href="./spotlight-text-snippet.html">Spotlight text snippet</a></li>
<li><a href="./jazzy-button-snippet.html">Jazzy button snippet</a></li>
<li><a href="./page-performance-snippet.html">Page performance snippet</a></li>
</ul>
<h3 id="snippet-definitions">Snippet definitions</h3>
<p>Snippet definitions are functions that take a DOM element and manipulate it to supply it with additional functionality, including the ability to add Scrawl-canvas displays and animations to the DOM element</p>
<p>Example of how a Javascript module can import and use a snippet definition:</p>
<pre><code><span class="hljs-keyword">import</span> scrawl <span class="hljs-keyword">from</span> <span class="hljs-string">'../relative/or/absolute/path/to/scrawl.js'</span>;
<span class="hljs-keyword">import</span> { mySnippet } <span class="hljs-keyword">from</span> <span class="hljs-string">'./relative/or/absolute/path/to/snippet/definition/file.js'</span>;
<span class="hljs-keyword">let</span> myElements = <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">querySelectorAll</span>(<span class="hljs-string">'.some-class'</span>);
myElements.<span class="hljs-title function_">forEach</span>(<span class="hljs-function"><span class="hljs-params">el</span> =></span> <span class="hljs-title function_">mySnippet</span>(el));
</code></pre>
<p>Snippet definition functions can be written in any way the developer sees fit - a developer could write a snippet definition so that it:</p>
<ul>
<li>can accept additional data to help further personalize how the snippet gets built</li>
<li>visits remote APIs to gather additional data as part of the snippet build</li>
<li>holds local state for the snippet</li>
<li>supplies a return object, class instance or function containing handles to the objects built by the definition, or functions for manipulating the Scrawl-canvas assets, artefacts, styles, animation(s) and/or canvas built by the definition (a ‘mini-API’ for each snippet)</li>
<li>etc…</li>
</ul>
<p>At a minimum, a snippet definition function will need to take a DOM element (or a pointer to it) as an argument. Note that Scrawl-canvas will manipulate the element in the following ways to make it work as a snippet:</p>
<ul>
<li>the element’s CSS ‘position’ value, if set to ‘static’ (the default value), will change to either ‘relative’ or ‘absolute’ - this is required to get any added canvas to <em>stick to</em> its element in the final display</li>
<li>it will also be given a unique Scrawl-canvas identifier in a new <strong>data-scrawl-name</strong> attribute on the element</li>
<li>the new <canvas> element will be added to the element as its <em>first child</em>; the canvas will be absolutely positioned within the element</li>
<li>Scrawl-canvas will also add a hidden <em>text-hold</em> <div> element immediately after the canvas element - this is where Scrawl-canvas keeps dynamic text (for assistive technology)</li>
<li>by default, the canvas is built so that it displays beneath the element, using a lower z-index CSS property on the canvas element (compared to the host’s z-index value)</li>
<li>the new canvas’s dimensions will include the element’s padding and border as well as its content</li>
</ul>
<p>For the sake of fellow developers, each snippet definition function should come with some documentation to explain:</p>
<ul>
<li>the purpose and usage of the snippet that the definition function will deliver/render</li>
<li>any effects (beyond those explained above) that snippetization will have on the DOM element and any child elements it may contain</li>
<li>what input the function requires, and in what format and argument order</li>
<li>what - if anything - the definition function will return</li>
</ul>
<p>Each of the following snippet definition functions could live in its own file; we can also bundle snippets together so that related snippets can be imported into another Javascript module using a single <strong>import</strong> statement in that file</p>
<p>Import the Scrawl-canvas object </p>
<ul>
<li>there’s various ways to do this. See <a href="../dom-001.html">Demo DOM-001</a> for more details</li>
</ul>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-keyword">import</span> * <span class="hljs-keyword">as</span> scrawl <span class="hljs-keyword">from</span> <span class="hljs-string">'../../source/scrawl.js'</span>;</pre></div></div>
</li>
<li id="section-2">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-2">§</a>
</div>
<h3 id="spotlight-text-snippet">‘Spotlight text’ snippet</h3>
<p><strong>Purpose:</strong> adds a spotlight effect to an element. When the user hovers the mouse over the element, a ‘spotlight’ gradient will track the mouse’s movements.</p>
<p><strong>Function input:</strong> </p>
<ul>
<li>the DOM element, or a handle to it, as the first argument.</li>
<li>an optional key:value Object as the second argument</li>
</ul>
<p><strong>Function output:</strong> a Javascript object will be returned, containing the following attributes</p>
<pre><code>{
element <span class="hljs-comment">// the Scrawl-canvas wrapper for the DOM element supplied to the function</span>
canvas <span class="hljs-comment">// the Scrawl-canvas wrapper for the snippet's canvas</span>
animation <span class="hljs-comment">// the Scrawl-canvas animation object</span>
demolish <span class="hljs-comment">// remove the snippet from the Scrawl-canvas library</span>
}
</code></pre>
<h5 id="usage-example">Usage example:</h5>
<pre><code><span class="hljs-keyword">import</span> spotlightText <span class="hljs-keyword">from</span> <span class="hljs-string">'./relative/or/absolute/path/to/this/file.js'</span>;
<span class="hljs-keyword">let</span> myElements = <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">querySelectorAll</span>(<span class="hljs-string">'.some-class'</span>);
myElements.<span class="hljs-title function_">forEach</span>(<span class="hljs-function"><span class="hljs-params">el</span> =></span> <span class="hljs-title function_">spotlightText</span>(el));
</code></pre>
<p><strong>Effects on the element:</strong> </p>
<ul>
<li>no additional effects on the DOM element</li>
<li>setting any background fill on the DOM element will hide the snippet canvas, unless it is deliberately brought forward</li>
</ul>
</div>
<div class="content"><div class='highlight'><pre><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">function</span> (<span class="hljs-params">el, args = {}</span>) {</pre></div></div>
</li>
<li id="section-3">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-3">§</a>
</div>
<p>The snippet will accept an optional key:value Object as the second argument</p>
<ul>
<li><strong>spotlightColor</strong> - default: <code>white</code></li>
<li><strong>backgroundColor</strong> - default: <code>lightgray</code></li>
</ul>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">let</span> spotlightColor = args.<span class="hljs-property">spotlightColor</span> || <span class="hljs-string">'white'</span>,
backgroundColor = args.<span class="hljs-property">backgroundColor</span> || <span class="hljs-string">'lightgray'</span>;</pre></div></div>
</li>
<li id="section-4">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-4">§</a>
</div>
<p>Apply the snippet to the DOM element</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">let</span> snippet = scrawl.<span class="hljs-title function_">makeSnippet</span>({</pre></div></div>
</li>
<li id="section-5">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-5">§</a>
</div>
<p>(<strong>required</strong>) The DOM element we are about to snippetize</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-attr">domElement</span>: el,</pre></div></div>
</li>
<li id="section-6">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-6">§</a>
</div>
<p>(<strong>optional</strong>) An array of animation hook functions with the following attributes</p>
<ul>
<li><code>commence</code> - for an preparatory work required before the display cycle kicks off</li>
<li><code>afterClear</code> - runs between the ‘clear’ and ‘compile’ stages of the display cycle</li>
<li><code>afterCompile</code> - runs between the ‘compile’ and ‘show’ stages of the display cycle</li>
<li><code>afterShow</code> - for any cleanup work required after the display cycle completes</li>
<li><code>error</code> - a function to run when an error in the display cycle occurs</li>
</ul>
<p>For this snippet, we’ll define and add an animation hook function after the animation object has been created</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-attr">animationHooks</span>: {},</pre></div></div>
</li>
<li id="section-7">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-7">§</a>
</div>
<p>(<strong>optional</strong>) Options we can supply for the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API">IntersectionObserver</a>. Defaults are usually good enough; changing the ‘threshold’ value is probably the most useful option to play with</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-attr">observerSpecs</span>: {},</pre></div></div>
</li>
<li id="section-8">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-8">§</a>
</div>
<p>(<strong>optional</strong> - default: true) Scrawl-canvas snippets don’t have to include a canvas!</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-attr">includeCanvas</span>: <span class="hljs-literal">true</span>,</pre></div></div>
</li>
<li id="section-9">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-9">§</a>
</div>
<p>(<strong>optional</strong>, and only useful if we are including a canvas) - canvas-specific options. The most useful attribute is (probably) <strong>fit</strong>, whose value can be one of: <code>contain</code>, <code>cover</code>, <code>fill</code>, or <code>none</code> (the default value)</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-attr">canvasSpecs</span>: {},
});</pre></div></div>
</li>
<li id="section-10">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-10">§</a>
</div>
<p>NOTE: makeSnippet() defines its own <strong>afterClear</strong> animation hook</p>
<ul>
<li>the functionality is to keep the canvas properly aligned and sized with its DOM element</li>
<li>overwriting this hook here will lose that functionality!</li>
<li>instead, use the <strong>commence</strong> animation hook for all display cycle preparations</li>
</ul>
<p>Once the snippet is built, we can supply values to our previously defined variables</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">if</span> (snippet) {</pre></div></div>
</li>
<li id="section-11">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-11">§</a>
</div>
<p>Set some convenience variables</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">let</span> canvas = snippet.<span class="hljs-property">canvas</span>,
animation = snippet.<span class="hljs-property">animation</span>,
wrapper = snippet.<span class="hljs-property">element</span>,
name = wrapper.<span class="hljs-property">name</span>;
canvas.<span class="hljs-title function_">setAsCurrentCanvas</span>();</pre></div></div>
</li>
<li id="section-12">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-12">§</a>
</div>
<p>Define the gradient</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">let</span> spotlightGradient = scrawl.<span class="hljs-title function_">makeRadialGradient</span>({
<span class="hljs-attr">name</span>: <span class="hljs-string">`<span class="hljs-subst">${name}</span>-gradient`</span>,
<span class="hljs-attr">startX</span>: <span class="hljs-string">'50%'</span>,
<span class="hljs-attr">startY</span>: <span class="hljs-string">'50%'</span>,
<span class="hljs-attr">endX</span>: <span class="hljs-string">'50%'</span>,
<span class="hljs-attr">endY</span>: <span class="hljs-string">'50%'</span>,
<span class="hljs-attr">endRadius</span>: <span class="hljs-string">'20%'</span>,
})
.<span class="hljs-title function_">updateColor</span>(<span class="hljs-number">0</span>, spotlightColor)
.<span class="hljs-title function_">updateColor</span>(<span class="hljs-number">999</span>, backgroundColor);</pre></div></div>
</li>
<li id="section-13">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-13">§</a>
</div>
<p>This animation hook uses the variables and gradient we defined above</p>
</div>
<div class="content"><div class='highlight'><pre> animation.<span class="hljs-property">commence</span> = <span class="hljs-keyword">function</span> (<span class="hljs-params"></span>) {
<span class="hljs-keyword">let</span> active = <span class="hljs-literal">false</span>;
<span class="hljs-keyword">return</span> <span class="hljs-keyword">function</span> (<span class="hljs-params"></span>) {
<span class="hljs-keyword">if</span> (canvas.<span class="hljs-property">here</span>.<span class="hljs-property">active</span> !== active) {
active = canvas.<span class="hljs-property">here</span>.<span class="hljs-property">active</span>;</pre></div></div>
</li>
<li id="section-14">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-14">§</a>
</div>
<p>The block entity swaps between the gradient and a color fill, dependent on user interaction</p>
</div>
<div class="content"><div class='highlight'><pre> block.<span class="hljs-title function_">set</span>({
<span class="hljs-attr">lockTo</span>: (active) ? <span class="hljs-string">'mouse'</span> : <span class="hljs-string">'start'</span>,
<span class="hljs-attr">fillStyle</span>: (active) ? spotlightGradient : backgroundColor,
});
}
};
}();</pre></div></div>
</li>
<li id="section-15">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-15">§</a>
</div>
<p>Define the block which will (sometimes) display our spotlingt gradient</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">let</span> block = scrawl.<span class="hljs-title function_">makeBlock</span>({
<span class="hljs-attr">name</span>: <span class="hljs-string">`<span class="hljs-subst">${name}</span>-spotlight`</span>,
<span class="hljs-attr">width</span>: <span class="hljs-string">'200%'</span>,
<span class="hljs-attr">height</span>: <span class="hljs-string">'200%'</span>,
<span class="hljs-attr">startX</span>: <span class="hljs-string">"50%"</span>,
<span class="hljs-attr">startY</span>: <span class="hljs-string">"50%"</span>,
<span class="hljs-attr">handleX</span>: <span class="hljs-string">"50%"</span>,
<span class="hljs-attr">handleY</span>: <span class="hljs-string">"50%"</span>,
<span class="hljs-attr">fillStyle</span>: backgroundColor,
<span class="hljs-attr">lockFillStyleToEntity</span>: <span class="hljs-literal">true</span>,
<span class="hljs-attr">method</span>: <span class="hljs-string">'fill'</span>,
});
}</pre></div></div>
</li>
<li id="section-16">
<div class="annotation">
<div class="sswrap ">
<a class="ss" href="#section-16">§</a>
</div>
<p>Return the snippet, so coders can access the snippet’s parts - in case they need to tweak the output to meet the web page’s specific requirements</p>
</div>
<div class="content"><div class='highlight'><pre> <span class="hljs-keyword">return</span> snippet;
};</pre></div></div>
</li>
</ul>
</div>
</body>
</html>