NOTE: This project's API is not yet 100% stable.
If you are seeking an even lighter version (e.g., for inclusion in a stand-alone library) while still getting some benefits of the syntax-highlighter-friendly pure JS approach for DOM construction, see Jamilih Lite.
The following functions are available:
jml()- For building DOM objects (and optionally appending into an existing DOM node). Arguments demoed and explained below.
configis an object and which supports a
stringOutputproperty which can be set to
truein order to JSON-stringify the converted Jamilih JSON object. Note that element results will be in array form.
jml.toJMLString(objOrString, config)- Works like
jml.toJMLbut stringifies the resulting Jamilih object.
jml.toHTML()- Works like jml() except that the resulting DOM object is converted into an HTML string.
jml.toXML()- Works like jml() except that the resulting DOM object is converted into an XML-serialized string.
jml.toDOM()- An alias for jml().
jml.toDOMString()- An alias for
jml.toHTML()(for parity with
jml.toXMLDOMString()- An alias for
jml.toXML()(for parity with
var input = jml'input';
Simple element with attributes...
var input = jml'input' type:'password' id:'my_pass';
Simple element with just child elements...
var div = jml'div''p' 'no attributes on the div';
Simple element with attributes and child elements...
var div = jml'div' 'class': 'myClass''p' 'Some inner text''p' 'another child paragraph';
Simple element with attributes, child elements, and text nodes...
var div = jml'div' 'class': 'myClass''text1''p' 'Some inner text''text3';
var simpleAttachToParent = jml'hr' documentbody;
Returning first element among siblings when appending them to a DOM element (API unstable)...
var firstTr = jml'tr''td' 'row 1 cell 1''td' 'row 1 cell 2''tr' className: 'anotherRowSibling''td' 'row 2 cell 1''td' 'row 2 cell 2'table;
Returning element siblings as an array (API unstable)...
var trsFragment = jml'tr''td' 'row 1 cell 1''td' 'row 1 cell 2''tr' className: 'anotherRowSibling''td' 'row 2 cell 1''td' 'row 2 cell 2'null;
Inclusion of regular DOM elements...
var div = jml'div'$'#DOMChildrenMustBeInArray'0$'#anotherElementToAddToParent'0$'#yetAnotherSiblingToAddToParent'0parent;
Document fragments addable anywhere within child elements...
jml'div''text0''#': 'text1' 'span' 'inner text' 'text2''text3'
var input = jml'input'// Contains events to be added via addEventListener or// attachEvent where available$on:click:alert'worked1';true // Capturing;
var input2 = jml'input'style: 'position:absolute; left: -1000px;'$on:alert'worked2';focus:alert'worked3';truedocumentbody;
Comments, processing instructions, entities, decimal and hexadecimal character references, CDATA sections...
var div = jml'div''!' 'a comment''?' 'customPI' 'a processing instruction''&' 'copy''#' '1234''#x' 'ab3''![' '&test <CDATA> content';
Namespace definitions (default or prefixed)...
jml'abc' xmlns: 'prefix1': 'def' 'prefix2': 'ghi'
jml'abc' xmlns: 'prefix1': 'def' 'prefix2': 'ghi' '': 'newdefault'
jml()must be either:
nullas the last argument.)
!followed by a string to create a comment
&followed by an HTML entity reference (e.g.,
#followed by a decimal character reference as a string or number, e.g.,
#xfollowed by a hexadecimal character reference as a string, e.g.,
?followed by a processing instruction target string and string value (XML)
'![followed by CDATA content as a string (XML), e.g.,
&test <CDATA> content
#indicating a document fragment; see array children below for allowable contents of this array.
$textset to a string to create a bare text node (this is only necessary if one wishes jml() to return a sole text node; otherwise, text nodes are created with simple strings belonging to an element's children array).
$aset to an array of attribute name-value arrays (this is only necessary if one requires and the environment allows a fixed attribute order but may not support first-declared-first-iterated for-in object iteration).
$documentset to an object with properties
childNodesand, where present, a child object
standAlone. In place of
childNodes, one may instead add to any of the array properties,
body. One may also add a string
titleproperty in which case, a
<head>will be automatically created, with a
<meta charset="utf-8"/>element (as expected by HTML5) and a
<title>element, and any additionally supplied
headarray items appended to that
titleare supplied, an empty "html" DOCTYPE will be auto-created (as expected by HTML5) as well as an
<html>element with the XHTML namespace. If
headis supplied, a
<meta charset="utf-8">will also be added as the first child of
$DOCTYPEobject with properties
name, and, where present,
internalSubsetis not currently supported in
$attributeset to an array of a namespace, name, and value (for a namespaced attribute node) or a two-item name-value array for a non-namespaced attribute node.
$NOTATIONset to an object with properties
$ENTITYset to an object with the properties
encodingfor an external parsed entity with a declaration present) and
$onexpects a subject of event types mapped to a function or to an array with the first element as a function and the second element as a boolean indicating whether to capture or not.
htmlForare also provided to avoid the need for quoting the reserved keywords
onfollowed by any string will be set as a property (for events).
xmlnsfor namespace declarations (not needed in HTML)
datasetis an object whose keys are hyphenated or camel-cased properties used to set the dataset property (note that no polyfill for older browsers is provided out of the box)
#with an array of children (following these same rules) as its value to represent a fragment. (Useful if embedding the return result of a function amidst other children.)
nullis currently undefined behavior and should not be used; these may be allowed for some other purpose in the future, however.
jml()is usually the parent node to which to append the contents, with the following exceptions:
null(at the end) will cause an element or fragment to be returned
nullis the last argument, in which case, it returns a fragment of all added elements or, if only one element was present, the element itself.
The only work which comes close to meeting these goals as far as I have been able to find is JsonML. JsonML even does a better job of goal #1 in terms of succinctness than my proposal for Jamilih (except that Jamilih can represent empty elements more succinctly). However, for goal #3, I believe Jamilih is slightly more flexible for regular usage in templates, and to my personal sensibilities, more clear in goal #8 (and with a plan for goal #5 and #7?).