scrawl-canvas/source/asset-management/image-asset.js

Responsive, interactive and more accessible HTML5 canvas elements. Scrawl-canvas is a JavaScript library designed to make using the HTML5 canvas element easier, and more fun

// # ImageAsset factory
// The factory generates wrapper Objects around <img> elements which can either be pulled from the current document (DOM-based assets), or fetched from the server using an URL address.


// #### Imports
import { artefact, canvas, cell, constructors, group } from '../core/library.js';

import { doCreate, isa_obj, mergeOver, λnull, λcloneError, Ωempty, generateUniqueString } from '../helper/utilities.js';

import baseMix from '../mixin/base.js';
import assetMix from '../mixin/asset.js';

// Shared constants
import { _parse, ANONYMOUS, ASSET, ASSET_IMPORT_REGEX, BLOCK, ELEMENT, IMG, NONE, T_CANVAS, T_CELL, T_GROUP, T_IMAGE, ZERO_STR } from '../helper/shared-vars.js';

// Local constants
const IMAGE_ELEMENTS = ['IMG', 'PICTURE'],
    INTRINSIC = 'intrinsic',
    SLASH = '/',
    ZERO = 'zero';


// #### ImageAsset constructor
const ImageAsset = function (items = Ωempty) {

    return this.assetConstructor(items);
};


// #### ImageAsset prototype
const P = ImageAsset.prototype = doCreate();
P.type = T_IMAGE;
P.lib = ASSET;
P.isArtefact = false;
P.isAsset = true;


// #### Mixins
baseMix(P);
assetMix(P);


// #### ImageAsset attributes
const defaultAttributes = {

// __intrinsicDimensions__ - Javascript object which defines the intrinsic dimensions of each image contributing to an <img> element's `srcset` attribute. Can also be set in Javascript code:
// ```
// filename-String: [width-Number, height-Number]
// {
//     'river-300.jpg': [300, 225],
//     'river-600.jpg': [600, 450],
//     'river-900.jpg': [900, 675]
// }
// ```
    intrinsicDimensions: null,
};
P.defs = mergeOver(P.defs, defaultAttributes);


// #### Packet management
// Assets do not take part in the packet or clone systems; they can, however, be used for importing and actioning packets as they retain those base functions
P.saveAsPacket = function () {

    return [this.name, this.type, this.lib, {}];
};
P.stringifyFunction = λnull;
P.processPacketOut = λnull;
P.finalizePacketOut = λnull;


// #### Clone management
P.clone = λcloneError;


// #### Kill management
// No additional kill functionality required


// #### Get, Set, deltaSet
const G = P.getters,
    S = P.setters;

// __source__
G.width = function () {

    return this.sourceNaturalWidth || this.source.naturalWidth || 0;
};
G.height = function () {

    return this.sourceNaturalHeight || this.source.naturalHeight || 0;
};

S.source = function (item) {

    if (item) {

        // ImageBitmap support (non-DOM path)
        if (item instanceof ImageBitmap) {

            this.source = item;
            this.sourceNaturalWidth = item.width;
            this.sourceNaturalHeight = item.height;
            this.sourceLoaded = true;

            this.notifySubscribers();
        }

        // For <img> and <picture> elements
        else if (item.tagName && IMAGE_ELEMENTS.includes(item.tagName.toUpperCase())) {

            this.source = item;
            this.sourceNaturalWidth = item.naturalWidth;
            this.sourceNaturalHeight = item.naturalHeight;
            this.sourceLoaded = item.complete;

            if (this.sourceLoaded) this.notifySubscribers();
        }
    }
};

// __currentSrc__ - this attribute is not part of the defs object
S.currentSrc = function (item) {

    this.currentSrc = item;
    this.currentFile = this.currentSrc.split(SLASH).pop();
};


// #### Prototype functions

// `checkSource`
P.checkSource = function (width, height) {

    const el = this.source;

    if (el instanceof ImageBitmap) return;

    let action = ELEMENT;

    if (this.sourceLoaded) {

        let iDims = this.intrinsicDimensions[this.currentFile];

        if (this.currentSrc !== el.currentSrc) {

            this.set({
                currentSrc: el.currentSrc
            });

            iDims = this.intrinsicDimensions[this.currentFile];

            if (iDims) action = INTRINSIC;
            else action = ZERO;
        }
        else if (iDims) action = INTRINSIC;

        switch (action) {

            case ZERO :

                this.sourceNaturalWidth = 0;
                this.sourceNaturalHeight = 0;
                this.notifySubscribers();
                break;

            case INTRINSIC :

                if (this.sourceNaturalWidth !== iDims[0] ||
                        this.sourceNaturalHeight !== iDims[1]) {

                    this.sourceNaturalWidth = iDims[0];
                    this.sourceNaturalHeight = iDims[1];

                    this.notifySubscribers();
                }
                break;

            default:

                if (this.sourceNaturalWidth !== el.naturalWidth ||
                        this.sourceNaturalHeight !== el.naturalHeight ||
                        this.sourceNaturalWidth !== width ||
                        this.sourceNaturalHeight !== height) {

                    this.sourceNaturalWidth = el.naturalWidth;
                    this.sourceNaturalHeight = el.naturalHeight;

                    this.notifySubscribers();
                }
        }
    }
};

// `gettableImageAssetAtributes`, `settableImageAssetAtributes` - exported Arrays.
export const gettableImageAssetAtributes = [];
export const settableImageAssetAtributes = [];


// #### Importing images into Scrawl-canvas

// `importImage` - load images from a remote server and create assets from them
//
// Arguments can be a comma-separated list of String urls. For example, for aimage file at server url `http://www.example.com/path/to/image/flower.jpg`:
// + Will attempt to give the new imageAsset object, and img element, a name/id value of eg 'flower' (but not guaranteed)
// + Will not add the new img element to the DOM
//
// Alternatively, the arguments can include an object with the following attributes:
// + __name__ string.
// + __src__ url string.
// + __parent__ CSS search string - if set, Scrawl-canvas will attempt to append the new img element to the corresponding DOM element.
// + __isVisible__ boolean - if true, and new img element has been added to DOM, make that image visible; default is false.
// + __className__ string - list of classes to be added to the new img element.
//
// Note: strings and object arguments can be mixed - Scrawl-canvas will interrrogate each argument in turn and take appropriate action to load the assets.
export const importImage = function (...args) {

    const results = [];

    args.forEach(item => {

        let name, url, className, visibility,
            parent = false;

        let flag = false;

        if (item.substring) {

            const match = ASSET_IMPORT_REGEX.exec(item);

            name = (match && match[1]) ? match[1] : ZERO_STR;
            url = item;
            className = ZERO_STR;
            visibility = false;

            flag = true;
        }
        else {

            item = (isa_obj(item)) ? item : false;

            if (item && item.src) {

                name = item.name || ZERO_STR;

                url = item.src;
                className = item.className || ZERO_STR;
                visibility = item.visibility || false;
                if (item.parent) parent = document.querySelector(item.parent);

                flag = true;
            }
        }

        if (flag) {

            const image = makeImageAsset({
                name: name,
                intrinsicDimensions: {},
            });

            const img = document.createElement(IMG);

            img.name = name;
            img.className = className;
            img.crossorigin = ANONYMOUS;

            img.style.display = (visibility) ? BLOCK : NONE;

            if (parent) parent.appendChild(img);

            img.onload = () => {

                image.set({
                    source: img,
                });
            };

            img.src = url;

            image.set({
                source: img,
            });

            results.push(name);
        }
        else results.push(false);
    });
    return results;
};

// `importDomImage` - import images defined in the web page HTML code
// + Required argument is a query string used to search the dom for matching elements
// + Scrawl-canvas does not remove <img> elements from the DOM (this is a breaking change from Scrawl-canvas v7.0).
// + If <img> elements should not appear, developers need to hide them in some way - for instance by positioning them (or their parent element) absolutely to the top or left of the display; or by giving their parent element zero width/height; or by setting their CSS: `display: none;`, `opacity: 0;`, etc.
export const importDomImage = function (query) {

    const items = document.querySelectorAll(query);

    items.forEach(item => {

        let name;

        if (IMAGE_ELEMENTS.includes(item.tagName.toUpperCase())) {

            if (item.id || item.name) name = item.id || item.name;
            else {

                const match = ASSET_IMPORT_REGEX.exec(item.src);
                name = (match && match[1]) ? match[1] : ZERO_STR;
            }

            let intrinsics = item.dataset.dimensions || {};
            if (intrinsics.substring) intrinsics = _parse(intrinsics);

            const image = makeImageAsset({
                name: name,
                source: item,
                intrinsicDimensions: intrinsics,
                currentSrc: item.currentSrc,
            });

            item.onload = () => {

                image.set({
                    source: item,
                });
            };
        }
    });
};

// `importImageBitmap` - import (non-DOM) [ImageBitmap images](https://developer.mozilla.org/en-US/docs/Web/API/ImageBitmap). The `items` suppled as arguments can either be:
// + An ImageBitmap object (in which case the asset's name will be auto-generated)
// + A JavaScript Object with two attributes - `{ name: String, src: ImageBitmap }`
export const importImageBitmap = function (...items) {

    const results = [];

    items.forEach(item => {

        let name, imageBitmap, flag = false;

        if (item instanceof ImageBitmap) {

            name = generateUniqueString();
            imageBitmap = item;
            flag = true;
        }
        else if (isa_obj(item) && item.src instanceof ImageBitmap) {

            name = item.name || generateUniqueString();
            imageBitmap = item.src;
            flag = true;
        }

        if (flag) {

            const image = makeImageAsset({
                name,
                intrinsicDimensions: {},
            });

            image.set({
                source: imageBitmap,
            });

            results.push(name);
        }
        else results.push(false);
    });

    return results;
};
// We can get cells, groups and entitys to save their output as imagedata, which we can then use to build an asset which in turn can be used by Picture entitys and pattern styles
// + If the `stashAsAsset` argument is `true`, the asset will be created using the Cell/Group/entity name with `-image` suffixed to it as its id/name value
// + If `stashAsAsset` argument is a String, the asset will be created using that String as its id/name attribute

// `createImageFromCell`
export const createImageFromCell = function (item, stashAsAsset = false) {

    let mycell = (item.substring) ? cell[item] || canvas[item] : item;

    if (mycell.type === T_CANVAS) mycell = mycell.base;

    if (mycell.type === T_CELL) {

        mycell.stashOutput = true;

        if (stashAsAsset) mycell.stashOutputAsAsset = stashAsAsset;
    }
};

// `createImageFromGroup`
export const createImageFromGroup = function (item, stashAsAsset = false) {

    let mygroup;

    if (item && !item.substring) {

        if (item.type === T_GROUP) mygroup = item;
        else if (item.type === T_CELL) mygroup = group[item.name];
        else if (item.type === T_CANVAS) mygroup = group[item.base.name];
    }
    else if (item && item.substring) mygroup = group[item];

    if (mygroup) {

        mygroup.stashOutput = true;

        if (stashAsAsset) mygroup.stashOutputAsAsset = stashAsAsset;
    }
};

// `createImageFromEntity`
export const createImageFromEntity = function (item, stashAsAsset = false) {

    const myentity = (item.substring) ? artefact[item] : item;

    if (myentity.isArtefact) {

        myentity.stashOutput = true;

        if (stashAsAsset) myentity.stashOutputAsAsset = stashAsAsset;
    }
};


// #### Factory (not exported)
const makeImageAsset = function (items) {

    if (!items) return false;
    return new ImageAsset(items);
};

constructors.ImageAsset = ImageAsset;