html-script

Create DOMs (real or virtual) using a concise API, similar to
hyperscript.

This is a general purpose utility that uses adapters to generate the backing
structure, if you specifically want to work with the real browser DOM using the
same API syntax, see dom-script.

Example

``javascript
'use strict'

const H = require( 'html-script' )

const {
document, documentType, text, comment, documentFragment, element,
html, head, body, meta, title, div, p, strong, input
} = H

const dom =
document(
documentType('html'),
html(
head(
meta({charset:'utf-8'}),
title('Hello World!')
),
body(
comment('Whose line is it anyway?'),
div({id:'main'},
p('The quick brown fox jumps over the ',strong('lazy dog')),
input({type:'text',name:'firstName',placeholder:'Alex'})
),
comment('Fragment not (usually) necessary but make sure it works'),
documentFragment(
comment('Text not necessary but etc.'),
p(text('lol '),'wut')
),
comment('But what if it is not in the spec?'),
element('customtag',{class:'kk'},
p('OK that works for me')
)
)
)
)
`

`html

The quick brown fox jumps over the lazy dog

lol wut

OK that works for me

`

Default adapter

Because it is a general purpose utility, html-script ships only with a very
simple adapter over a virtual DOM that follows the same structure as
JsonML:

`javascript
const myDiv =
div( { id: 'myDiv' },
p( 'Hello world!' )
)

console.log( JSON.stringify( myDiv ) )
`

`json
["div",{"id":"myDiv"},["p","Hello world!"]]
`

Other implementations include
dom-script, which generates real DOM
nodes in the browser, and mojule-h, which
generates nodes for the mojule-dom
virtual DOM.

Installation and usage

npm install html-script

`javascript
const H = require( 'html-script' )

// now destructure out the functions you want - alternatively, use H.div etc.
const { div, p, comment, element } = H

// any objects passed will be treated as attributes
//

const main = div( { id: 'main' } )

// any strings passed will be treated as text nodes
//

Hello world!

const hello = p( 'Hello world!' )

// non-element nodes also supported
//
const helloComment = comment( 'Hello world!' )

// any nodes passed will be appended to the parent
//

Hello

World

const nested =
div(
p( 'Hello' ),
p( 'World' )
)

// if html-script doesn't have the element you want
// Hello world!
const custom =
element( 'custom', { id: 'myCustom' },
'Hello world!'
)
`

Attributes

An object passed to an html-script function is treated as though it were an
attribute map for the node. For the most part, it is expected to be a simple map
of attribute name to attribute value, and the value is expected to be a string,
with some exceptions listed below.

`javascript
const nameField =
div(
label( { for: 'firstName' }, 'First Name' ),
input( { type: 'text', name: 'firstName' } )
)
`

`html

First Name

`

$3

To make working with boolean attributes easier, any attribute that has a boolean
value will be treated as though the boolean attribute is present on the node if
the value is true, and absent if the value is false:

`javascript
div(
input( { type: 'radio', checked: true } ),
input( { type: 'radio', checked: false } )
)
`

`html

`

$3

Either a string, or an object of name value pairs:

`javascript
div(
p( { style: 'font-family: sans-serif' }, 'Hello' ),
p( { style: { 'font-family': 'sans-serif', 'font-size': '1rem' }, 'World' )
)
`

`html

Hello

World

`

$3

An attribute named data with an object value will be treated similarly to the
dataSet
property on DOM nodes, that is, the object keys will be converted from camelCase
to dash-style with a data- prefix. This makes it easy to use your existing
models to set data attributes without having to first mangle the names:

`javascript
div( { data: { firstName: 'Nik', lastName: 'Coughlin' } } )
`

`html

`

$3

If an attribute value is a function and the name starts with 'on', it's
considered to be an event handler. Note that the default adapter is a JsonML
implementation which contains data only, so events don't make sense and they'll
just be removed, but other adapters can handle these as they see fit, see
dom-script for an example.

`javascript
div( { onclick: e => window.alert( 'Clicked!' ) }
p( 'Hello world!' )
)
`

$3

All other values are converted to a string via String( value )

Adapters

You can get an instance of html-script that uses your custom adapter by
calling it as a function with your adapter as the parameter:

`javascript
const H = require( 'html-script' )
const adapter = require( './path/to/your/adapter' )

const Mine = H( adapter )

const {
document, documentType, text, comment, documentFragment, element,
html, head, body, meta, title, div, p, strong, input
} = Mine

const dom =
document(
documentType('html')
// etc.
)
`

An adapter is an object containing the following functions (where Node is your
custom backing type). Type notation below should be self explanatory, it's
similar to rtype /
typescript et al.

`javascript
{
isNode: ( node:Node ) => Boolean,
createElement: ( tagName:String ) => elementNode:Node,
createText: ( value:String ) => textNode:Node,
appendChild: ( node:Node, child:Node ) => Void,
addAttributes: ( node:Node, attributes:Object ) => Void,
createDocument: () => documentNode:Node,
createDocumentType: ( name:String, publicId:String?, systemId:String? ) => documentTypeNode:Node,
createComment: ( value:String ) => commentNode:Node,
createDocumentFragment: () => documentFragmentNode:Node,
addEventListener: ( node:Node, name:String, listener:( e:Event? ) => result:Boolean ) => Void
}
`

See the built in JsonML adapter for an example of
how adapters work.

addEventListener is optional and only needs to be implemented by adapters for
which is makes sense, eg an adapter over the real DOM, and doesn't need to be
implemented in for example adapters that just back a data-only structure.

html-script expects createDocument to return a document node with no
children! Note that the default DOM implementation takes a title and adds
various children like an html tag element etc. - if you are backing this with
the real DOM, you will have to clear out all the children before returning the
node.

Using JsonML with other adapters

Because JsonML is a convenient format for transportation and persistence, a
helper method is provided to populate your custom backing adapter from JsonML
data:

`javascript
const H = require( 'html-script' )
const adapter = require( './path/to/your/adapter' )
const jsonML = require( './path/to/some/data.json' )

const Mine = H( adapter )

const dom = Mine.fromJsonML( jsonML )
``