A teeny tiny helper library for working with the DOM
DUM.js helps you work with the DOM a lot easier by providing a concise API for common tasks that would normally be much more verbose.
DUM.js isn't designed for AJAX or animations or anything else already covered by dedicated libraries.
*Please note: This is a work in progress, ideas and assistance most welcome!! I'm specifically looking for help bundling the library for different importers. *
DUM.js adds an object to the global scope with the following identifiers: $d or DUM That object contains the following signatures.
Kind: global class
- DUM
- .ready(context) ⇒
Promise - .id(id) ⇒
HTMLElement|null - .query(expression, context) ⇒
HTMLElement|null - .queryAll(expression, contexts) ⇒
Array.<HTMLElement> - .prev(element, expression) ⇒
HTMLElement|null - .next(element, expression) ⇒
HTMLElement|null - .children(elements, expression) ⇒
Array.<HTMLElement> - .create(type) ⇒
HTMLElement - .prepend(elements, children)
- .append(elements, children)
- .detach(element) ⇒
HTMLElement - .hasClass(element, name) ⇒
boolean - .addClass(elements, names)
- .removeClass(elements, names)
- .toggleClass(elements, names)
- .getAttr(element, name) ⇒
HTMLElement|null - .setAttr(elements, values)
- .removeAttr(elements, names)
- .setStyle(elements, values)
- .empty(elements)
- .on(element, events, selector, handler)
- .one(element, events, selector, handler)
- .off(element, events)
- .trigger(elements, event, detail) ⇒
boolean
- .ready(context) ⇒
Specifies a function to execute when the element of DOM is fully loaded.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| context | HTMLElement | HTMLDocument |
The context to monitor the state of; defaults to document if not set |
$d.ready().then(() => {
// Do your thing
});Returns a reference to the first object with the specified value of the id or name attribute.
Kind: instance method of DUM
| Param | Type |
|---|---|
| id | string |
let mainForm = $d.id("mainForm");Returns the first element that is a descendant of the element on which it is invoked that matches the specified group of selectors.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| expression | string |
The selector expression; this must be valid CSS syntax |
| context | HTMLElement | HTMLDocument |
The context to search within; defaults to document if not set |
let mainForm = $d.query(".form");Returns a list of the elements within the element or collection of elements (using depth-first pre-order traversal of the elements nodes)
that match the specified group of selectors. The object returned is different from querySelectorAll in that it is a true array.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| expression | string |
The selector expression; this must be valid CSS syntax |
| contexts | HTMLElement | Array.<HTMLElement> | HTMLDocument |
The element or collection of elements to search within; defaults to document if not set |
let inputs = $d.queryAll("input[type=text]");Returns the element matching the optional expression immediately prior to the specified one in its parent's children list, or null if the specified element is the first one in the list.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| element | HTMLElement |
The element to search from |
| expression | string |
The optional selector expression; this must be valid CSS syntax |
let previous = $d.prev($d.query("td"), "[scope=row]");Returns the element matching the optional expression immediately following to the specified one in its parent's children, or null if the specified element is the last one in the list
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| element | HTMLElement |
The element to search from |
| expression | string |
The optional selector expression; this must be valid CSS syntax |
let next = $d.next($d.query("td"), "[scope=row]");Returns an ordered collection of DOM elements that are children of the given element or element collection. If there are no element children, then children contains no elements and has a length of 0.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements to search within |
| expression | string |
The optional selector expression; this must be valid CSS syntax |
let children = $d.children($d.query("tr"), "td");Creates an instance of an element for the specified tag
Kind: instance method of DUM
| Param | Type |
|---|---|
| type | string |
let para = $d.create($d.query("p"));Prepends the child or collection of child elements to the element or collection of elements. The child collection is reversed before prepending to ensure order is correct. If prepending to multiple elements the nodes are deep cloned for successive elements.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements to prepend within |
| children | HTMLElement | Array.<HTMLElement> |
The child or collection of child elements |
$d.prepend($d.query("p"), $d.create("span"));Appends the child or collection of child elements to the element or collection of elements If appending to multiple elements the nodes are deep cloned for successive elements.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements to prepend within |
| children | HTMLElement | Array.<HTMLElement> |
The child or collection of child elements |
$d.append($d.query("p"), $d.create("span"));Detaches an element from the DOM returning the result. Any event handlers bound to the element are still present.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| element | HTMLElement |
The element to detach |
let detached = $d.detach($d.id("detach"));Returns a value indicating whether the specified class value exists in class attribute of the element.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| element | HTMLElement |
The element to search within |
| name | string |
The class name |
const hasClass = $d.hasClass($d.query("input[type=text]"), "fancy");Add the specified class, space-separated class values or class array to the given element or collection of elements. If these classes already exist in attribute of the element, then they are ignored.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| names | string | Array.<string> |
$d.addClass($d.queryAll("input[type=text]"), "fancy");
$d.addClass($d.queryAll("input[type=text]"), "fancy fancier");
$d.addClass($d.queryAll("input[type=text]"), ["fancy","fancier","fanciest"]);Removes the specified class, space-separated class values or class array from the given element or collection of element. If these classes already exist in attribute of the element, then they are ignored.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| names | string | Array.<string> |
$d.removeClass($d.queryAll("input[type=text]"), "fancy");
$d.removeClass($d.queryAll("input[type=text]"), "fancy fancier");
$d.removeClass($d.queryAll("input[type=text]"), ["fancy","fancier","fanciest"]);Toggles the specified class, space-separated class values or class array to or from the given element or collection of elements. If these classes already exist in attribute of the element, then they are ignored.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| names | string | Array.<string> |
$d.toggleClass($d.queryAll("input[type=text]"), "fancy");
$d.toggleClass($d.queryAll("input[type=text]"), "fancy fancier");
$d.toggleClass($d.queryAll("input[type=text]"), ["fancy","fancier","fanciest"]);Returns the value of a specified attribute on the element. If the given attribute does not exists the value
returned will be null.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| element | HTMLElement |
The element |
| name | string |
The string specifying the attribute whose value to return |
const attr = $d.getAttr($d.queryAll("input[type=text]"), "name");Sets the collection of attribute values on the element or collection of elements
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| values | object |
The object contining the collection of key-value attribute pairs to set |
$d.setAttr($d.queryAll("input[type=text]"), {"name":"firstname", "placeholder":"first name"});Removes specified attribute, space-separated attribute names or attribute array from the element or collection of elements
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| names | string | Array.<string> |
The name or array of names to remove |
$d.removeAttr($d.queryAll("input[type=text]"), "placeholder");
$d.removeAttr($d.queryAll("input[type=text]"), ["name", "placeholder"]);Sets the collection of style values on the element or collection of elements.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| values | object |
The object contining the collection of key-value attribute pairs to set |
$d.setStyle($d.queryAll("input[type=text]"), {"height":"16px", "display":"block"});Empties the contents of the given element or collection of elements. Any event handlers bound to the element contents are automatically removed.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
$d.empty($d.query("#to-empty"));
$d.empty($d.queryAll(".to-empty"));Adds an event listener to the given element or collection of elements. Events can be delegated to a parent by passing an optional CSS selector.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| events | string | Array.<string> |
The event or collection of event names |
| selector | string | undefined |
The selector expression; this must be valid CSS syntax or undefined |
| handler | function |
The function to call when the event is triggered |
$d.on($d.query("ul"), "click", e => {
$d.addClass(e.target, "foo");
});
$d.on($d.query("ul"), "click", ".highlight", e => {
$d.addClass(e.target, "bar");
});
// Namespaces are supported
$d.on($d.query("ul"), "click.baz", ".highlight", e => {
$d.addClass(e.target, "bar");
});Adds an event listener to the given element or collection of elements that is immediately unbound when the event is triggered. Events can be delegated to a parent by passing a CSS selector.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| events | string | Array.<string> |
The event or collection of event names |
| selector | string | undefined |
The selector expression; this must be valid CSS syntax or undefined |
| handler | function |
The function to call when the event is triggered |
$d.one($d.query("ul"), "click", e => {
$d.addClass(e.target, "foo");
});
$d.one($d.query("ul"), "click", ".highlight", e => {
$d.addClass(e.target, "bar");
});
// Namespaces are supported
$d.one($d.query("ul"), "click.baz", ".highlight", e => {
$d.addClass(e.target, "bar");
});Removes any event listener matching the given event name or names.
Kind: instance method of DUM
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| events | string | Array.<string> |
The event name or names, previously bound using on. |
$d.off(element, "click");
$d.off(element, ["click", "keydown"]);
// Namespaces are supported
$d.off(element, "click.baz");Triggers an event returning a value indicating whether the event has been cancelled. By default the event bubbles and is cancelable.
Kind: instance method of DUM
Returns: boolean - A value indicating whether at least one of the bound event handlers called Event.preventDefault()
| Param | Type | Description |
|---|---|---|
| elements | HTMLElement | Array.<HTMLElement> |
The element or collection of elements |
| event | string |
The name of the event to trigger |
| detail | object |
Optional and defaulting to null this contains any event dependant value associated with the event |
if(!$d.trigger($d.queryAll("li"), "customevent")){
return;
}
// Namespaces are supported and can be accessed via `event.detail.namespace` in the handling function.
if!($d.trigger($d.queryAll("li"), "click.foo")){
return;
}We live in the future. Support covers evergreen browers supporting ECMAScript 6