domoperations v0.0.1

domoperations

A library of helper methods for working with the DOM.

Installation

Simply do: npm install domoperations.

What is it?

It's simply a collection of helper methods for working with the DOM such as create, remove and assignAttributes.

Example

import {create, add, remove} from "domoperations";

let button = create("button", {disabled: true});
add(button);
remove(button);

Changelog:

v0.01:

• First release!

Usage

Import it in your project like this:

import {create, ...} from "domoperations";                  // (standard) Transpiled to ES5, inlined dependencies.;
// or

import {create, ...} from "domoperations/external";        // Transpiled to ES5, external dependencies.
// or

import {create, ...} from "domoperations/native";          // Transpiled to ES5, native ES-modules, inlined dependencies.
// or

import {create, ...} from "domoperations/native-external"; // Transpiled to ES5, native ES-modules external dependencies.
// or

import {create, ...} from "domoperations/typed";           // Flow typings, ES-modules, external dependencies.

Documentation

Types

interface PropertyObject {
	[key: string]: any;
}

#nodeNameFromPrototype()

Extracts the node name for a prototype. For instance, calling the method with HTMLButtonElement will return 'button'.

Signature:

nodeNameFromPrototype (prototype: Class<HTMLElement>): string

Arguments:

• prototype: Class<HTMLElement> - The prototype to extract the name from.

Returns:

string - The element name.

Throws:

• TypeError - If the prototype is 'HTMLElement'.

• TypeError - If the prototype is 'HTMLUnknownElement'.

• TypeError - If the name couldn't be decoded for some reason.

Example

nodeNameFromPrototype(HTMLButtonElement); // returns "button";
nodeNameFromPrototype(MyCustomElement);   // returns 'my-custom-element' (or whatever the node name is).

#nodeNameFromInstance()

Extracts the node name for a instance of HTMLElement. For instance, an instance of HTMLButtonElement will return 'button'.

Signature:

nodeNameFromInstance (instance: HTMLElement): string

Arguments:

• instance: HTMLElement - The node instance to extract the name from.

Returns:

string - The node name of the instance.

Throws:

• TypeError - If the given instance isn't of type 'HTMLElement'.

Example

nodeNameFromInstance(document.createElement("p")); // returns "p";
nodeNameFromInstance(document.createElement("my-custom-element")); // returns 'my-custom-element'.

#remove()

Removes an element from the DOM.

Signature:

remove (element: HTMLElement): void

Arguments:

• element: HTMLElement - The element that should be removed.

Returns:

boolean - Whether or not the removal were successful.

Throws:

• TypeError - If the given element isn't of type 'HTMLElement'.

Example

let paragraph = document.createElement("p");
document.appendChild(button);
remove(paragraph); // returns true
remove(document.createElement("p")); // returns false - element not in the DOM.

#getFromTag()

Gets the element that matches the given tag name.

Signature:

getFromTag (tagName: string, all: boolean = false, root: Document|HTMLElement = document): HTMLCollection<*> | ?HTMLElement

Arguments:

• tagName: string - The tag name to find a matching element for.

• all: boolean - If true, all matches will be returned. default: false

• root: Document|HTMLElement - The root element of the query. default: document

Returns:

HTMLCollection<*>|?HTMLElement - A HTMLCollection of matches if 'all' is true, otherwise the matched element, if any.

Throws:

• TypeError - If the first argument is not of type 'string'.

• TypeError - If the second argument is not of type 'boolean'.

• TypeError - If the third argument is not of type 'Document' or 'HTMLElement'

Example

getFromTag("head"); // Returns the 'head' element.
getFromTag("p", true);    // Returns a HTMLCollection of all 'p' elements.

#getFromClassName()

Gets the element that matches the given CSS class name.

Signature:

getFromClassName (className: string, all: boolean = false, root: Document|HTMLElement = document): HTMLCollection<*> | ?HTMLElement

Arguments:

• className: string - The CSS class name to find a matching element for.

• all: boolean - If true, all matches will be returned. default: false

• root: Document|HTMLElement - The root element of the query. default: document

Returns:

HTMLCollection<*>|?HTMLElement - A HTMLCollection of matches if 'all' is true, otherwise the matched element, if any.

Throws:

• TypeError - If the first argument is not of type 'string'.

• TypeError - If the second argument is not of type 'boolean'.

• TypeError - If the third argument is not of type 'Document' or 'HTMLElement'

Example

getFromClassName("active");       // Returns the first element with a CSS class of "active".
getFromClassName("active", true); // Returns a HTMLCollection of all elements with a CSS class of "active".

#getFromId()

Gets the element that matches the given id.

Signature:

getFromId (id: string): ?HTMLElement

Arguments:

• id: string - The id to find a matching element for.

Returns:

?HTMLElement - The matched element, if any.

Throws:

• TypeError - If the first argument is not of type 'string'.

Example

getFromId("container"); // Returns the element with an id of 'container', if any.

#addTo()

Adds the given element to another elements local DOM. If 'unique' is true, the element will only be added if no direct child exists with the same node name.

Signature:

addTo (to: HTMLElement, toAdd: HTMLElement, unique: boolean = false): Node

Arguments:

• to: HTMLElement - The element to add the element to.

• toAdd: HTMLElement - The element that should be added.

• unique: boolean - If true, the element will be added only if no direct child exists with the same node name. default: false

Returns:

HTMLElement - The added element. If 'unique' is true and another element with the same node name exists already, that one will be returned.

Throws:

• TypeError - If the first argument isn't of type 'HTMLElement'.

• TypeError - If the second argument isn't of type 'HTMLElement'.

Example

addTo(document.body, document.createElement("p")); // Adds the new "p" element to the body.
addTo(document.body, document.createElement("p"), true); // Does NOT add the new "p" element because it already exists as a direct child. Instead the existing one is returned.

#assignAttributes()

Sets the given attributes on the given element. Will automatically dash properties and handle booleans.

Signature:

assignAttributes (element: HTMLElement, attributes: PropertyObject): void

Arguments:

• element: HTMLElement - The element that should get the attributes.

• attributes: PropertyObject - The PropertyObject containing the attributes that should be set on the element.

Returns:

void

Throws:

• TypeError - If the first argument isn't of type 'HTMLElement'.

Example

let button = document.createElement("button");
let customElement = dcoument.createElement("my-custom-element");
assignAttributes(button, {disabled: true}); // Sets the 'disabled' attribute on the button element.
assignAttributes(button, {disabled: false}); // Removes the 'disabled' attribute from the button element.
assignAttributes(customElement, {myCustomProp: "a string", anotherProp: 12}) // Sets the 'my-custom-prop="a string"' and 'another-prop="12"' attributes on the custom element instance.

#create()

Creates a new HTMLElement.

Signature:

create (elementName: string, properties?: PropertyObject, asAttributes: boolean = false): HTMLElement

Arguments:

• elementName: string - The name of the element to create.
• properties?: PropertyObject - Any properties to set on the element upon creation.
• asAttributes: boolean - if true, the properties will be set as attributes instead of as properties. default: false

Returns:

HTMLElement - The created element .

Throws:

• TypeError - If the first argument isn't of type 'string'.
• TypeError - If the third argument isn't of type 'boolean'.

Example

create("p");                                  // Creates a 'p' element.
create("button", {disabled: true}, true);     // Creates a 'button' element and sets the 'disabled' property as an attribute.
create("img", {src: "images/funnycatz.png"}); // Creates a 'img' element and sets the 'src' property.