Commit 9fb2af97 authored by Stephanus Volke's avatar Stephanus Volke

add more documentation to api doc

parent 4a11d34f
Pipeline #709 failed with stage
in 10 seconds
......@@ -17,12 +17,13 @@ export class HTMLCustomElement extends HTMLElement {
}
/**
* equivalent of native getElementById, but works asynchroneous and
* returns a Promise which resolves when the requested element is
* aviable.
* In case you reference an element not yet loaded into the DOM this
* method will handle that case. It is an equivalent of native
* getElementById, but works asynchroneous and returns a Promise
* which resolves when the requested element is aviable.
*
* @param {string} id - id of DOM element waiting for
* @return {Promise<Node>} - A Promise to the requested Element
* @return {Promise<HTMLNode>} - A Promise to the requested Element
*/
waitForElementById(id) {
let prom = new Promise((resolve, reject) => {
......@@ -39,13 +40,44 @@ export class HTMLCustomElement extends HTMLElement {
}
/**
* Like an event listener but for attributes. It observes an
* Callback for attributListener executed every time an attribute of
* `node` has changed
*
* @callback HTMLCustomElement~AttributeListenerCB
* @param {HTMLNode} node - reference to the element under change
* @param {string} newVal - new value of the attribute
*/
/**
* For communication between different custom elements it is often
* required to observe the current attributes values. This can be
* done by using the `MutationObservers` interface, aviable in all
* modern browsers. Because handling is a little bit complicated
* `HTMLCustomElemen` provides an easy to use abstraction layer
* working like an event listener but for attributes. It observes an
* elements attribute for changes and invokes a pre defined callback
* function. For this native js MutationObservers are used.
* function.
*
* **Example**
*
* ``` javascript
* // somewhere inside your class
*
* _stateCB(node, newVal) {
* // do something with new val
* }
*
* // get Element from DOM
* let elem = getElementById('test');
*
* // invokes the CB immediately after registration
* // and every the class attribute of elem changes
* this.addAttributeListener(elem, 'class', this._stateCB.bind(this), true);
* ```
*
* @param {HTMLNode} Node - reference to the HTML Node
* @param {string} Attr - attribute name to observe
* @param {function} fn - callback function to execute on change
* @param {HTMLCustomElement~AttributeListenerCB} fn - callback function to execute on change
* @param {bool} IMT - if true, callback is executed immediately at registration
*/
addAttributeListener(Node, Attr, fn, IMT) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment