crs-factory v0.0.2

CRS Factory

Introduction

This is a library that helps you create UI parts as registered on a UI store.

Currently under construction

Initializing

1. Load the library
2. Register items with the factory you can call on later to produce for you.

Async

Before we proceed, it is important to note that all public functions on the factory are async.

Register and unregister basics.

You can register a new item with the factory using the "register" function.
You can unregister a item using the key used in the register process. Do this by calling the "unregister" function.

Getting instances

There are two ways of getting a new instance of a factory registered item. Use the "get" or "getCollection" functions to get a new instance of the template. Get returns a instance where getCollection will return a document fragment. See below for more details.

Registering elements

Here is a comprehensive example of the parameters that you can register for creating an element; Parameters are optional and do not have to be provided.

await crs.factory.register("div", crs.factory.types.element, {
    tag: "div",         // node name to use when creating the item
    innerText: null,    // what innerText do you want to add by default
    innerHTML: null,    // what innerHTML do you want to add by default
    attributes: {       // what attribuutes should be set and what are the values 
        disabled: "disabled",
        "data-readonly": true
    },
    styles: {           // what style properties do you want to set
        background: "#ffbb00"
    },
    classes: ["disabled", "gray"]
});

A simple example could look like

await crs.factory.register("div", crs.factory.types.element);
await crs.factory.register("menu-item", crs.factory.types.element, {tag: "li"});

Note that if you do not provide a tag property it will use the key (first parameter of register function) as the nodeName;

Register template

In some cases you want to use a HTML template as the base to create UI from. You can use the register function as with elements but this time the type is template. Instead of sending a object definition you will pass in the actual template.

<template id="tpl">
    <div>Template Item</div>
</template>

await crs.factory.register("my-template", crs.factory.types.template, document.querySelector("#tpl"));

Create a element instance

To get a new copy of registered item you use the factory's get function.

document.querySelector("main").appendChild(await crs.factory.get("div"));

Creating a copy of a existing element

If you have a element already on your UI and you just want to make a copy of that element, you can register it with the factory as a clone.

<button id="clonable" click.call="cloneClick">Clone</button>

await crs.factory.register("clone", crs.factory.types.clone, document.querySelector("#clonable"));

Note that this just does a deep clone of the node but that does not include events. If you want events attached to the item you will need to manage that after getting the item.

Create a collection of elements

For this we are going to use the getCollection function.

const elements = await crs.factory.getCollection("menu-item", ["Item 1", "Item 2", "Item 3"], async (element, obj) => element.innerText = obj);
document.querySelector("main").appendChild(elements);

This is a bit more complicated so let's look at the parameters. 1. The key used to register the item 1. The array you want to process during the creation process. 1. A callback function used on each item in the collection where you can set values as you require. The callback has two parameters. The element created and the collection item being processed.

Please note that the result of getCollection is a documentFragment.

Working with svg

If you want to create a new copy of a svg object the best way to deal with that is either with clone or template. In this example I am just using template.

Set up template

<template id="image">
    <svg width="100" height="100">
        <circle cx="50" cy="50" r="40" stroke="green" stroke-width="4" fill="yellow" />
    </svg>
</template>

Register

await crs.factory.register("circle", crs.factory.types.template, document.querySelector("#image"));

Get instance

document.querySelector("main").appendChild(await crs.factory.get("circle"));

The factory does have a type for svg. This type helps you work wit svg symbols.
This is a better way of working with svg in projects as it allows you styling abilities.

Defining svg symbols on the page

<svg style="display: none;">
    <symbol id="menu" viewBox="0 0 24 24">
        <path d="M4 19h18v-2H4v2zm0-5h18v-2H4v2zm0-7v2h18V7H4z" />
    </symbol>
</svg>

Simple registration

await crs.factory.register("menu", crs.factory.types.svg)

This example registers the symbol with id "menu" so that when you get it, it will give you the svg to represent that image. Since you can also do styling, you can also define attributes, classes and styles properties.

await crs.factory.register("menu", crs.factory.types.svg, {
    attributes: {
        width: "2rem", 
        height: "2rem"
    }, 
    styles: {
        fill: "blue"
    }
})

Custom factory function

You can't cater for every scenario. For this reason you can register a custom function with the factory. In this function you are responsible for creating the appropriate object and returning it.

await crs.factory.register("my-custom", crs.factory.types.custom, async () => {
    const result = document.createElement("h2");
    result.innerHTML = "Hello World";
    return result;
})

Getting an instance is the same as every other case.

document.querySelector("main").appendChild(await crs.factory.get("my-custom"));