Anchor factory

In Scrawl-canvas, an Anchor object holds all the data and functionality required to turn an artefact into a link. That functionality gets defined in this file.

Scrawl-canvas uses the Anchor mixin to add anchor functionality to artefacts - in particular canvas entitys.

This gives us a interactive canvas containing dynamic, clickable regions.

Note that while anchors are primarily for generating URL links to (external site) web pages, they can also be used to trigger any other desired action. This can be achieved by setting the anchor object’s clickAction attribute to a function. For instance:

• We can define a clickAction which emits a Google Analytics tracker message before performing the URL navigation (see demo Canvas-009)
• We can suppress the click action (via ‘preventDefault’) and instead action code supplied by a third party library - though there’s usually better ways to achieve this via other Scrawl-canvas functionalities, for instance by using Scrawl-canvas enhanced event listeners or artefact functions (onEnter, onLeave, onDown, onUp).

NOTE - generating an anchor will have an impact on the DOM document code, as an (off-viewport) <a> element will be added to it.

The makeAnchor function is not exposed to the ‘scrawl’ object, thus objects can only be created indirectly. Anchors can be saved, cloned and killed as part of wider save/kill/clone functionality.

Demos:

• Canvas-009 - Pattern styles; Entity web link anchors; Dynamic accessibility
• Component-003 - Save and load Scrawl-canvas entity using text packets

Imports

Anchor constructor

Anchor prototype

Mixins

Anchor attributes

• Attributes defined in the base mixin: name.

host - Every anchor will belong to exactly one Artefact.

description - The text that Scrawl-canvas will include between the anchor tags, when building the anchor. Always include a description for accessibility.

The following attributes are detailed in MDN’s <a> reference page

• They are (most of) the DOM element’s attributes: download, href, hreflang, ping, referrerpolicy, rel, target, anchorType.
• The HTML Anchor element type attribute is stored in the Scrawl-canvas Anchor object using the key anchorType.
• Scrawl-canvas will build a link element and add it to the DOM, then invoke a click event on it when required to do so.

The clickAction attribute is a function which returns a string command which in turn gets attached to the anchor DOM element’s onclick attribute. Invoking the result is handled entirely by the browser (as is normal).

Example usage

This doesn’t work! The browser will generate an error, rather than output an update to the console, when the user clicks on the canvas entity associated with the anchor (although navigation will still occur - the wikipedia page will open in a new browser tab):

anchor: {
    name: 'wikipedia-box-link',
    href: 'https://en.wikipedia.org/wiki/Box',
    description: 'Link to the Wikipedia article on boxes (opens in new tab)',

    clickAction: function () { console.log('box clicked') },
}

This works as expected - the function returns a string which can then be attached to the <a> DOM element’s onclick attribute:

anchor: {
    name: 'wikipedia-box-link',
    href: 'https://en.wikipedia.org/wiki/Box',
    description: 'Link to the Wikipedia article on boxes (opens in new tab)',

    clickAction: function () { return `console.log('box clicked')` },
},

We can instruct the anchor to add event listeners for focus and blur events using the focusAction and blurAction Boolean flags. When set to true, the focus event listener will invoke the host entity’s onEnter function; the blur event listener invokes the onLeave function. Default is to ignore these events

Packet management

Clone management

No additional clone functionality required

Kill management

Get, Set, deltaSet

Value should be the artefact object, or its name-String

Used internally - do not set directly! A reference to the hidden DOM hold <div> elemenbt where the anchors <a> element is kept.

While the Scrawl-canvas anchor object keeps copies of all of its <a> DOM element’s attributes locally, they also need to be updated on that element. Most of the setter functions manage this using the anchor.update() helper function.

The artefact with which an anchor object is associated maps these attributes to itself as follows:

anchor.description     ~~> artefact.anchorDescription
anchor.type            ~~> artefact.anchorType
anchor.target          ~~> artefact.anchorTarget
anchor.rel             ~~> artefact.anchorRel
anchor.referrerPolicy  ~~> artefact.anchorReferrerPolicy
anchor.ping            ~~> artefact.anchorPing
anchor.hreflang        ~~> artefact.anchorHreflang
anchor.href            ~~> artefact.anchorHref
anchor.download        ~~> artefact.anchorDownload

One or more of these attributes can also be set (in the artefact factory argument, or when invoking artefact.set) using an ‘anchor’ attribute:

artefact.set({

    anchor: {
        description: 'value',
        type: 'value',
        target: 'value',
        rel: 'value',
        referrerPolicy: 'value',
        ping: 'value',
        hreflang: 'value',
        href: 'value',
        download: 'value',
    },
});

These last setters do not follow previous behaviour because Scrawl-canvas anchor objects save the values for each under a different attribute key, compared to the DOM element’s attribute key:

• anchor.description -> a.textContent - this is the text between the <a> element’s opening and closing tags
• anchor.clickAction -> a.onclick - a function that returns an string which is added to the DOM element’s ‘onclick’ attribute

Prototype functions

The build function builds the <a> element and adds it to the DOM

Scrawl-canvas generated anchor links are kept in hidden <nav> elements - either the Canvas object’s nav, or the Scrawl-canvas default nav (referenced by scrawlNavigationHold) which Scrawl-canvas automatically generates and adds to the top of the DOM <body> element when it first runs.

This is done to give screen readers access to link URLs and descriptions associated with Canvas graphical entitys (which visually impaired users may not be able to see). It also allows links to be tabbed through and invoked in the normal way (which may vary dependent on how browsers implement tab focus functionality)

Internal function - update the DOM element attribute

To action a user click on an artifact with an associated anchor object, we generate a DOM MouseEvent originating from the anchor element which the browser can act on in the usual manner (browser/device dependent)

This choke mechanism is intended to prevent “Maximum call stack size exceeded” errors occurring

• Was causing an issue in Demo Canvas-027, where two entitys share the same anchor

Factory

To create an anchor, include an anchor definition object in any artefact object’s factory argument:

// get a handle on the canvas where the block/link will be defined 
// (in this case a canvas with id="mycanvas")
let canvas = scrawl.library.artefact.mycanvas;
canvas.setAsCurrentCanvas();

// Define a block entity
scrawl.makeBlock({

    name: 'demo-anchor-block',

    width: '40%',
    height: '40%',

    startX: '25%',
    startY: '25%',

    // Define the anchor object's attributes
    anchor: {
        name: 'wikipedia-water-link',
        href: 'https://en.wikipedia.org/wiki/Water',
        description: 'Link to the Wikipedia article on water (opens in new tab)',
    },

    // Add an action to take when user clicks on the block entity
    onUp: this.clickAnchor,
});

// Add a listener to propagate DOM-detected click events on our canvas 
// back into the Scrawl-canvas event system
scrawl.addListener('up', () => canvas.cascadeEventAction('up'), canvas.domElement);

Exports