Component definitions

Component 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 component definition:

import scrawl from '../relative/or/absolute/path/to/scrawl.js';
import { myScrawlComponent } from './relative/or/absolute/path/to/component/definition/file.js';

let myElements = document.querySelectorAll('.some-class');
myElements.forEach(el => myScrawlComponent(el));

Component definition functions can be written in any way the developer sees fit - a developer could write a component definition so that it:

• can accept additional data to help further personalize how the component gets built
• visits remote APIs to gather additional data as part of the component build
• holds local state for the component
• 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 component)
• etc…

At a minimum, a component 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 component:

• 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 stick to its element in the final display
• it will also be given a unique Scrawl-canvas identifier in a new data-scrawl-name attribute on the element
• the new <canvas> element will be added to the element as its first child; the canvas will be absolutely positioned within the element
• Scrawl-canvas will also add a hidden text-hold <div> element immediately after the canvas element - this is where Scrawl-canvas keeps dynamic text (for assistive technology)
• 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)
• the new canvas’s dimensions will include the element’s padding and border as well as its content

For the sake of fellow developers, each component definition function should come with some documentation to explain:

• the purpose and usage of the component that the definition function will deliver/render
• any effects (beyond those explained above) that componentization will have on the DOM element and any child elements it may contain
• what input the function requires, and in what format and argument order
• what - if anything - the definition function will return

Each of the following component definition functions could live in its own file; we can also bundle components together so that related components can be imported into another Javascript module using a single import statement in that file

BOILERPLATE: import the Scrawl-canvas object - the path to the file will vary according to where in a particular site’s server’s directory structure the Scrawl-canvas files have been placed

‘Spotlight text’ component

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: the DOM element, or a handle to it, as the only argument.

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 component's canvas
    animation   // the Scrawl-canvas animation object
    demolish    // remove the component from the Scrawl-canvas library
}

Usage example:

import scrawl from '../relative/or/absolute/path/to/scrawl.js';
import { spotlightText } from './relative/or/absolute/path/to/this/file.js';

let myElements = document.querySelectorAll('.some-class');
myElements.forEach(el => spotlightText(el));

Effects on the element: no additional effects.

Define some variables and functions we’ll be using as part of the component build

Define the gradient

This animation hook uses the variables and gradient we defined above

• not defining them first leads to the animation functionality failing

The block entity swaps between the gradient and a color fill, dependent on user interaction

Generate the component for the DOM element

(required) The DOM element we are about to componentize

(optional) An array of animation hook functions with the following attributes commence - for an preparatory work required before the display cycle kicks off afterClear - runs between the ‘clear’ and ‘compile’ stages of the display cycle afterCompile - runs between the ‘compile’ and ‘show’ stages of the display cycle afterShow - for any cleanup work required after the display cycle completes error - a function to run when an error in the display cycle occurs

(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

(optional - default: true) Scrawl-canvas components don’t have to include a canvas!

(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)

NOTE: makeComponent() defines its own afterClear animation hook

• the functionality is to keep the canvas properly aligned and sized with its DOM element
• overwriting this hook here will lose that functionality!
• instead, use the commence animation hook for all display cycle preparations

Once the component is built, we can supply values to our previously defined variables

Set the canvas as the current canvas - not required, it just makes things simpler for building artefacts etc

Define the block which will (sometimes) display our spotlingt gradient

Return the component, so coders can access the component’s parts - in case they need to tweak the output to meet the web page’s specific requirements

‘Jazzy button’ component

Purpose: display the number of times a user has clicked on a button element; animate the text and its line when the user clicks on the button. Function input: a <button> element, or any other block-displayed DOM element containing no child elements.

Function output:

{
    element           // wrapper
    canvas            // wrapper
    animation         // object
    demolish          // function

    artefacts {
        trackLine     // Shape entity
        label         // Phrase entity
    }

    assets {
        lineGradient  // Gradient wrapper
    }

    functions {
        setClickText  // increase the number of clicks recorded on the button
        textTween     // Tween animation function
        gradientTween // Tween animation function
    }
}

Usage example:

import scrawl from '../relative/or/absolute/path/to/scrawl.js';
import { jazzyButton } from './relative/or/absolute/path/to/this/file.js';

let myElements = document.querySelectorAll('.some-class');
myElements.forEach(el => jazzyButton(el));

Effects on the element: no additional effects.

define the text we’ll be displaying in the button

A path for the text to animate along, together with a gradient for its strokeStyle

The phrase entity that will display the text

Animate the phrase entity along the line when button element is clicked

Animate the gradient for the Line the text moves along

Increase the local counter; update the Phrase entity with new text

Both tweens need to halt and restart if user clicks on them while they are running

‘Page performance’ reporter

Purpose: (roughly) measure and display the time taken between calls to RequestAnimationFrame, and the resultant animated frames-per-second performance of the web page.

Function input: an empty <div> element.

Function output: true if component builds; false otherwise

Usage example:

import scrawl from '../relative/or/absolute/path/to/scrawl.js';
import { pagePerformance } from './relative/or/absolute/path/to/this/file.js';

let myElements = document.querySelectorAll('.some-class');
myElements.forEach(el => pagePerformance(el));

Effects on the element: updates the <div> element’s innerHTML data, which will replace any child elements or text placed between the element’s opening and closing tags.

Exports