zoll
v0.1.1
Published
A lightweight custom-element-like hook for use with existing frameworks
Downloads
4
Readme
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 zollYou can also include it directly on the webpage
<script type="text/javascript" src="./dist/zoll.min.js"></script>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
<profile-picture url="./image.png"> </profile-picture>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
function updateBg(node, url) {
node.style.cssText = `background: url(${zoll.getAttribute(node, 'url')}); width: 200px; height: 200px;`;
}
// Defining the element in the custom element registry
zoll.define('profile-picture', {
observedAttributes: ['url'],
connectedCallback: function() {
if (this.hasAttribute('url')) {
updateBg(this, this.getAttribute('url'));
}
},
disconnectedCallback: function() {
console.log('disconnected');
},
attributeChangedCallback: function(attrName, oldValue, newValue) {
if (attrName === 'url') {
updateBg(this, newValue);
}
}
});
// creating and adding it to the DOM
const pic = zoll.create('profile-picture', {
url: 'image.png'
});
zoll.appendChild(document.body, pic);
zoll.setAttribute(pic, 'url', 'image2.png');
zoll.remove(pic);
//output - disconnectedCreating custom element using extends
Lets create a custom button element <custom-button> by extending it from default <button>.
<custom-button>Click Me!</custom-button>zoll.define('custom-button', {
extends: 'button',
connectedCallback: function() {
this.onclick = function(){
console.log('Button Clicked');
};
},
disconnectedCallback: function() {
console.log('Button Removed');
}
});
const btn = zoll.create('button', {
is : 'custom-button',
value: 'Click Me'
});
zoll.appendChild(document.body, btn);Upgrade
This allows progressive enhancement of the content in the custom element.
index.html
<!DOCTYPE html>
<html lang="en">
<script type="text/javascript" src="dist/zoll.min.js"></script>
<body>
<profile-picture url="image.png"></profile-picture>
<script src= "main.js"></script>
</body>main.js
zoll.define('profile-picture', {
// same as first example
});
// upgrade all the elements
zoll.connect(document.body);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
extendsextending a built in element or other custom Element.observedAttributesarray of attributes that triggers the attributeChangedCallback on modifications.attributeChangedCallback(attrName, oldValue, newValue)gets called for all theobservedAttributesof an element.connectedCallbackgets called when the element is inserted in to the document.disconnectedCallbackgets 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.