dom-factory
The DOM factory provides a convenient API (inspired by Polymer) to enhance HTML elements with custom behavior, using plain JavaScript objects with advanced features like property change observers, property reflection to attributes on HTML elements and simplify mundane tasks like adding and removing event listeners.
Compatibility
Supports the last two versions of every major browser.
- Chrome
- Safari
- Firefox
- IE 11/Edge
- Opera
- Mobile Safari
- Chrome on Android
Installation
npm install dom-factory
Usage
The DOM factory library exports to AMD, CommonJS and global.
Global
CommonJS
var handler = handler
ES6
Components
The following ES6 example, illustrates a component definition for an enhanced button using properties as a public API, property reflection to attributes, property change observers and event listeners.
Component definition
A component definition is nothing more than a simple object factory (a function that creates an object) which accepts a HTMLElement
node as it's argument.
/** * A component definition * @return */const buttonComponent = /** * Properties part of the component's public API. * @type */ properties: /** * Maps to [data-a-property="value"] attribute * Also sets a default property value * and updates the attribute on the HTMLElement * @type */ aProperty: reflectToAttribute: true value: 'value for aProperty' /** * Maps to [data-b-property] attribute * It removes the attribute when the property value is `false` * @type */ bProperty: reflectToAttribute: true type: Boolean /** * Maps to [data-c-property] attribute * It casts the value to a Number * Sets the initial value to 0 * @type */ cProperty: reflectToAttribute: true type: Number value: 0 /** * Property change observers. * @type */ observers: '_onPropertyChanged(aProperty, bProperty)' /** * Event listeners. * @type */ listeners: '_onClick(click)' /** * Property change observer handler * @param * @param * @param */ { // access from context, with the new values console } /** * Click event listener * @param */ { event console }
Register the component
handler
Initializing
When calling the autoInit()
method, the component handler attempts to self-initialize all registered components which match the component CSS class. The CSS class is computed automatically from the component ID which was provided at registration, prefixed with js-
.
In this example, since we registered the buttonComponent
with a component ID of my-button
, the handler will try to initialize all the HTML elements which have the js-my-button
CSS class.
Press me
// Initialize all components on window.DOMContentLoaded and window.load events.handler
You can also initialize components manually.
// Initialize all components immediately.handler // Initialize all components on a single element.var myButtonNode = documenthandler // Initialize a single component on a single element.handler // Upgrade all elements matching a registered component ID.handler
Downgrade
Sometimes we need component lifecycle control when integrating with other libraries (Vue.js, Angular, etc).
var myButtonNode = documenthandler
Interact with the component API
When the handler initializes a component on a HTML element, a reference to the created component is stored as a property on the HTML element, matching the camelCase
version of the component ID.
var buttonNode = documentvar button = buttonNodemyButton
We can use this reference to interact with the component's API.
console// => 'value for aProperty'
Property reflection to attribute
buttonaProperty = 'something else'buttonbProperty = truebuttoncProperty = 5
When using the reflectToAttribute: true
property option, the property reflects a string representation of it's value to the corresponding data-*
attribute on the HTML element using the dataset
API, which means you can use the HTML element attribute to configure the property value.
Casting values
Because component properties using reflectToAttribute: true
are using the dataset API, all values are strings by default, but you can cast them to Boolean
or Number
.
Boolean
When using a Boolean
property type and assigning a property value of true
, the attribute will be created on the HTML element with an empty value and when assigning a property value of false
, the attribute will be removed from the DOM.
For example, an attribute with an empty value called [data-my-boolean-attribute]
will map to button.myBooleanAttribute
.
Press me
`console.log(button.myBooleanAttribute) // => true`
Number
Cast the component property value to a Number
by adding type: Number
to the property definition. It returns NaN
when the value is not a valid number.
buttoncProperty = '50'console // => 50 buttoncProperty = 'abc'console // => NaN
Press me
console // => 'something else'console // => trueconsole // => 13
Destroy
Calling the destroy
method on the component reference, removes observers and event listeners. Useful before removing the HTML element from the DOM, for example when using libraries like Vue.js or Angular2 where you need to hook into the application lifecycle.
button