zoll
A lightweight custom-element-like hook for use with existing frameworks.
zoll strives to be spec compatible where possible. For the implementation details please refer to custom elements spec
Installation
# NPM npm install zoll # Bower bower install zoll
You can also include it directly on the webpage
Usage
Creating a custom element with lifecycle callbacks
Let's assume we want to create a custom element . The end goal is to use them directly on the page like this
To do this, we need to define the element
// since `custom-element-hook` doesn't actually alter any prototypes it's // necessary to specify utility functions as free-standing and pass the node // to them { nodestylecssText = `background: url(); width: 200px; height: 200px;`;} // Defining the element in the custom element registryzoll; // creating and adding it to the DOMconst pic = zoll;zoll;zoll; zoll;//output - disconnected
Creating custom element using extends
Lets create a custom button element <custom-button>
by extending it from default <button>
.
Click Me!
zoll; const btn = zoll;zoll;
Upgrade
This allows progressive enhancement of the content in the custom element.
index.html
main.js
zoll;// upgrade all the elementszoll;
once the main.js loads, it will define the <profile-picture>
element and the existing <profile-picture>
element will be upgraded, applying the custom element's definition (which will set the background image in our case).
Note: The upgrade only apply to the elements in the document tree.
API
The library exposes a Zoll class where the below methods are defined.
define(tagName, options)
Defines a new custom element with the specified tag name and options.
Options
extends
extending a built in element or other custom Element.observedAttributes
array of attributes that triggers the attributeChangedCallback on modifications.attributeChangedCallback(attrName, oldValue, newValue)
gets called for all theobservedAttributes
of an element.connectedCallback
gets called when the element is inserted in to the document.disconnectedCallback
gets called when the element is removed from the document.
create(tagName, attributes)
Simple wrapper around document.createElement, that can also set attributes in a batch without notifying the possible observers.
connect(root)
Simulates the connect process for custom elements in the given subtree calling defined lifecycle callbacks.
forceConnectNode(element)
Allows to manually notify when the element is inserted in document.
forceConnectChildren(element)
Allows to manually notify when the element's children is inserted in document.
forceDisconnectNode(element)
Allows to manually notify when the element is removed in document.
forceDisconnectChildren(element)
Allows to manually notify when the element's children is inserted in document.
forceNotifyAttributeChange(descriptor, el, attributeName, oldValue, attributeValue)
Allows to manually notify an element about the attribute change.
This is useful for some libraries that manipulate DOM under you, like React.
getDescriptor(node)
Retrives the element from the CustomElementRegistry if defined.
setAttribute(node, attributeName, attributeValue)
A proxy for native setAttribute
that takes care of the observed attribute notifications.
removeAttribute(node, attributeName)
A proxy for native removeAttribute
that takes care of the observed attribute notifications.
hasAttribute(node, attributeName)
A proxy for native hasAttribute
.
getAttribute(node, attributeName)
A proxy for native getAttribute
.
appendChild(parent, child)
A proxy for native appendChild
that will notify about nodes connected to the document.
insertBefore(parent, child, reference)
A proxy for native insertBefore
that will notify about nodes connected to the document.
remove(element)
Removes the node from it's parent if one exists.