rnh.js

A library for HTML creation and manipulation in Javascript (ES6)

Please note: This project is a work in progress. The base API should remain stable as additional features are added, but it's not guaranteed.

Overview

rnh.js is a library for creating, selecting, and manipulating HTML elements, written using ES6 standards. It is loosely based on Hyperscript, with some additional convenience functions for selecting elements using browser-native interfaces, and adding/removing DOM nodes.

Requirements

rnh.js requires Node 6.0 or higher to build, and uses rollup.js for bundling. Usage in ES5 environments requires transpliation with Babel or equivalent.

Installation

The easiest method is simply npm install rnh. Manual installation is possible through git clone https://github.com/rneilson/rnh.js.git; however, creating the bundled library (in the /dist directory) requires Node to be installed, and can be built with npm run build.

Importing

ES6 syntax:

import * as rnh from 'rnh';

Node/CommonJS syntax:

var rnh = require('rnh');

Three library versions are available depending on use:

• /dist/rnh.js ES6 native export format (recommended for use with rollup.js)
• /dist/rnh.cjs.js CommonJS module format (for use with Node/npm)
• /dist/rnh.iife.js Immediately-invoked function expression (for direct use in the browser)

Element/node creation

h (tag, ...args)

Creates an HTMLElement node.

| Param | Type | Desc | | ----- | ---- | ---- | | tag | string | Element tag to create (default 'div') | | args | * | Processed by type |

Additional arguments:

| Type | Desc | | ---- | ---- | | string | Class or class list to set on element (multiple args will be concantenated) | | object | Properties/attributes to set on element; argument(s) passed to setprops() | | array, element | Child nodes to insert; argument(s) passed to addchd() |

Example:

import * from 'rnh';

var ex = h('div', {id: 'main', class: 'main'},
	h('p', 'big',
		[ h('span', {style: {color: 'red'}}, t('This')), 'is the first line.', br(), 'This is the second.' ]),
	h('p', 'small',
		[ 'Also, strings within an array', br(), 'are converted to text nodes.' ])
);

Output (ex.outerHTML, indentation added for clarity):

<div id="main" class="main">
	<p class="big">
		<span style="color: red;">This</span>is the first line.<br>
		This is the second.
	</p>
	<p class="small">
		Also, strings within an array<br>
		are converted to text nodes.
	</p>
</div>

t (str)

Creates text node. null and undefined will be converted into the empty string. Other non-string types will be cast using String().

| Param | Type | Desc | | ----- | ---- | ---- | | str | stringlike | Content of text node to create |

c (str)

Creates comment node. null and undefined will be converted into the empty string. Other non-string types will be cast using String().

| Param | Type | Desc | | ----- | ---- | ---- | | str | stringlike | Content of comment node to create |

br ()

Creates <br> element.

a (...args)

Equivalent to h('a', ...args).

p (...args)

Equivalent to h('p', ...args).

div (...args)

Equivalent to h('div', ...args).

span (...args)

Equivalent to h('span', ...args).

ul (...args)

Equivalent to h('ul', ...args).

li (...args)

Equivalent to h('li', ...args).

em (...args)

Equivalent to h('em', ...args).

strong (...args)

Equivalent to h('strong', ...args).

img (...args)

Equivalent to h('img', ...args).

pre (...args)

Equivalent to h('pre', ...args).

input (...args)

Equivalent to h('input', ...args).

select (...args)

Equivalent to h('select', ...args).

textarea (...args)

Equivalent to h('textarea', ...args).

Element/node child manipulation

replace (el, newel)

Replaces one node with another. Returns el.

| Param | Type | Desc | | ----- | ---- | ---- | | el | Node | Node to replace | | newel | Node | Node to replace with |

addchd (el, children, detach)

Appends one or more child nodes to given node. Returns el.

| Param | Type | Desc | | ----- | ---- | ---- | | el | Node | Node to append child(ren) to | | children | array, stringlike, Node | Child(ren) to append; stringlike (see strLike()) will be added as text nodes | | detach | boolean | Detach node from DOM before appending child(ren) |

remchd (el, children, detach)

Removes one or more child nodes from given node. Returns el.

| Param | Type | Desc | | ----- | ---- | ---- | | el | Node | Node to remove child(ren) from | | children | array, stringlike, Node | Child(ren) to remove; stringlike will be selected by id | | detach | boolean | Detach node from DOM before removing child(ren) |

clrchd (el, detach)

Removes all child nodes from given node. Returns el.

| Param | Type | Desc | | ----- | ---- | ---- | | el | Node | Node to remove child(ren) from | | detach | boolean | Detach node from DOM before removing children |

Text to node conversion

brklns (str)

Splits string on newlines, converts to text nodes, and inserts <br> elements in place of '\n'; returns array of nodes. null and undefined will be converted into the empty string. Other non-string types will be cast using String().

| Param | Type | Desc | | ----- | ---- | ---- | | str | string | String to parse |

txt (strings, ...inserts)

Converts/splits template string into array of elements/nodes, including converting \n to <br> where applicable. Inserted expressions will be called if a function, inserted directly if a node, or converted to text otherwise. Please note that this function is for use with template strings instead of direct calls.

var str = 'string';
var arr = rnh.txt`This is a ${str}, which will be converted\nto an array of DOM nodes.`;
// Result:		[ text, text, text, br, text ]
// Contents:	[ 'This is a ', 'string', ', which will be converted', <br>, 'to an array of DOM nodes.' ]
// (Please note the strings above represent text nodes, not strings.)

html (strings, ...inserts)

Converts/splits template string into array of elements/nodes, including converting HTML where applicable. Inserted expressions will be called if a function, inserted according to outerHTML property if a node, or converted to text otherwise. Please note that this function is for use with template strings instead of direct calls. Existing nodelike objects given in the template string using ${insert} syntax will be placed directly into the final DOM without further conversion. Also, please note that whitespace within strings is not converted using brklns(), and thus newlines, tabs, and multiple spaces will be output as-is.

var str = 'string';
var span = rnh.span({id: 'test'}, ['DOM nodes']);
var arr = rnh.html`This is a <span>${str}</span>, which will be converted<br>to an array of ${span}.`;
// Result:		[ text, span, text, br, text, span, text ]
// Contents:	[ "This is a ", <span>string</span>, ", which will be converted", <br>, "to an array of ", <span id="test">DOM nodes.</span>, "." ]
// (Please note the strings above represent elements or text nodes, not Javascript strings.)

Element property/attribute manipulation

setprops (el, props)

| Param | Type | Desc | | ----- | ---- | ---- | | el | Element | Target element | | props | object | Properties or attributes to set |

Some properties have special processing:

• class: value will be passed to addcls()
• style: a string value will set el.style.cssText to given value; an object value will set each property using setProperty()
• any property with a function as its value will be added as an event listener, with the key as the event
• any property beginning with 'data-' will be added as an attribute of the element instead of a property

addcls(el, cls)

Adds given class(es) to element.

| Param | Type | Desc | | ----- | ---- | ---- | | el | Element | Target element | | cls | array, string | Class(es) to add |

Multiple classes in single string (eg 'green big') will be split on spaces when adding to the element's classList.

remcls(el, cls)

| Param | Type | Desc | | ----- | ---- | ---- | | el | Element | Target element | | cls | array, string | Class(es) to remove |

Multiple classes in single string (eg 'green big') will be split on spaces when removing from the element's classList.

togcls(el, cls)

| Param | Type | Desc | | ----- | ---- | ---- | | el | Element | Target element | | cls | array, string | Class(es) to toggle |

Multiple classes in single string (eg 'green big') will be split on spaces when toggling on the element's classList.

Element selection

sel (s, l)

Selects elements using browser-native querySelectorAll(). Returns array of results.

| Param | Type | Desc | | ----- | ---- | ---- | | s | string | Selector string | | l | Element | Root element to search (optional) |

byid (i)

Selects elements using browser-native getElementById(). Returns array of results.

| Param | Type | Desc | | ----- | ---- | ---- | | i | string | Element id |

bycls (c, l)

Selects elements using browser-native getElementsByClassName(). Returns array of results.

| Param | Type | Desc | | ----- | ---- | ---- | | c | string | Class name | | l | Element | Root element to search (optional) |

bytag (t, l)

Selects elements using browser-native getElementsByTagName(). Returns array of results.

| Param | Type | Desc | | ----- | ---- | ---- | | t | string | Tag name | | l | Element | Root element to search (optional) |

Miscellaneous utilities

has (obj, prop)

Returns true if obj has own property or path of own properties prop. prop may be a string, a number, a symbol, or an array or '.'-delimited string of valid property names (eg a.b, 0.1, 0.length, [0, 1], [0, 'length'], etc.).

| Param | Type | Desc | | ----- | ---- | ---- | | obj | any | value to check | | prop | array, string, number | property to check |

makestr (s)

Returns empty string if s is null or undefined, otherwise converts s to string.

strlike (s)

Returns true if s is a string, number, boolean, Date, or RegExp.

nodelike (n)

Returns true if n is not falsy, and has non-falsy properties nodeName and nodeType.