export default function (scrawl, el, args = {}) {Scrawl-canvas DOM element snippets
Related files:
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
Example of how a Javascript module can import and use a snippet definition:
import scrawl from '../relative/or/absolute/path/to/scrawl.js';
import { mySnippet } from './relative/or/absolute/path/to/snippet/definition/file.js';
let myElements = document.querySelectorAll('.some-class');
myElements.forEach(el => mySnippet(el));
Snippet definition functions can be written in any way the developer sees fit - a developer could write a snippet definition so that it:
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:
For the sake of fellow developers, each snippet definition function should come with some documentation to explain:
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 import statement in that file
Purpose: 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.
Function input:
Function output: a Javascript object will be returned, containing the following attributes
{
element // the Scrawl-canvas wrapper for the DOM element supplied to the function
canvas // the Scrawl-canvas wrapper for the snippet's canvas
animation // the Scrawl-canvas animation object
demolish // remove the snippet from the Scrawl-canvas library
}
import spotlightText from './relative/or/absolute/path/to/this/file.js';
let myElements = document.querySelectorAll('.some-class');
myElements.forEach(el => spotlightText(scrawl, el));
Effects on the element:
export default function (scrawl, el, args = {}) {The snippet will accept an optional key:value Object as the second argument
whitelightgray const spotlightColor = args.spotlightColor || 'white',
backgroundColor = args.backgroundColor || 'lightgray';Apply the snippet to the DOM element
const snippet = scrawl.makeSnippet({(required) The DOM element we are about to snippetize
domElement: el,(optional) An array of animation hook functions with the following attributes
commence - for an preparatory work required before the display cycle kicks offafterClear - runs between the ‘clear’ and ‘compile’ stages of the display cycleafterCompile - runs between the ‘compile’ and ‘show’ stages of the display cycleafterShow - for any cleanup work required after the display cycle completeserror - a function to run when an error in the display cycle occursFor this snippet, we’ll define and add an animation hook function after the animation object has been created
animationHooks: {},(optional) Options we can supply for the IntersectionObserver. Defaults are usually good enough; changing the ‘threshold’ value is probably the most useful option to play with
observerSpecs: {},(optional - default: true) Scrawl-canvas snippets don’t have to include a canvas!
includeCanvas: true,(optional, and only useful if we are including a canvas) - canvas-specific options. The most useful attribute is (probably) fit, whose value can be one of: contain, cover, fill, or none (the default value)
canvasSpecs: {},
});NOTE: makeSnippet() defines its own afterClear animation hook
Once the snippet is built, we can supply values to our previously defined variables
if (snippet) {Set some convenience variables
const canvas = snippet.canvas,
animation = snippet.animation,
wrapper = snippet.element,
name = wrapper.name;
canvas.setAsCurrentCanvas();Define the gradient
const spotlightGradient = scrawl.makeRadialGradient({
name: `${name}-gradient`,
startX: '50%',
startY: '50%',
endX: '50%',
endY: '50%',
endRadius: '20%',
})
.updateColor(0, spotlightColor)
.updateColor(999, backgroundColor);This animation hook uses the variables and gradient we defined above
animation.commence = function () {
let active = false;
return function () {
if (canvas.here.active !== active) {
active = canvas.here.active;The block entity swaps between the gradient and a color fill, dependent on user interaction
block.set({
lockTo: (active) ? 'mouse' : 'start',
fillStyle: (active) ? spotlightGradient : backgroundColor,
});
}
};
}();Define the block which will (sometimes) display our spotlingt gradient
const block = scrawl.makeBlock({
name: `${name}-spotlight`,
width: '200%',
height: '200%',
startX: "50%",
startY: "50%",
handleX: "50%",
handleY: "50%",
fillStyle: backgroundColor,
lockFillStyleToEntity: true,
method: 'fill',
});
}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
return snippet;
}