rnh v0.2.0

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.

Additional arguments:

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().

c (str)

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

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.

addchd (el, children, detach)

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

remchd (el, children, detach)

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

clrchd (el, detach)

Removes all child nodes from given node. Returns el.

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().

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)

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.

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

remcls(el, cls)

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

togcls(el, cls)

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.

byid (i)

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

bycls (c, l)

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

bytag (t, l)

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

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.).

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.