JsonML
======

http://jsonml.org

The utilities here represent a variety of JsonML-related tools for **losslessly** converting between XML/HTML and JSON.
These are intended for use within a browser context for working with DOM representations of XML / HTML in JavaScript.
A proof of concept XSLT is also included for converting from XML to JsonML.

Mixed-mode XML
--------------

**A common misconception is that JsonML is intended to replace a natural JSON data representation. *This is not the case!* **

JsonML-encoding is intended for situations of mixed-mode XML/HTML, i.e., where text nodes sit as siblings to element nodes.
There isn't a natural JSON encoding for mixed-mode documents, and at worst the representation degrades to modeling DOM nodes themselves.
JsonML is a more compact representation of mixed-mode XML/HTML which does not lose the structure of the original markup.

JSON Data
---------

While mixed-mode is very common in markup scenarios (X/HTML) it is actually quite rare in data documents.
In data scenarios, a ["natural" JSON encoding](http://wiki.open311.org/index.php?title=JSON_and_XML_Conversion), such as Badgerfish or Parker Conventions, is
generally more efficient and intuitive to work with in JavaScript.

That being said, some have found JsonML to be a useful intermediate encoding of XML for manipulation within JavaScript. Your mileage may vary.

Utilities
---------

Here are the various modules available in this repository:

### jsonml-html.js *(formerly `jsonml2.js`)*

Methods for converting from JsonML to HTML:

- `Element JsonML.toHTML(string|array jml, function filter)`
	Converts a JsonML structure to HTML DOM nodes
- `string JsonML.toHTMLText(string|array jml, function filter)`
	Converts a JsonML structure to HTML text

### jsonml-dom.js

Methods for converting from HTML to JsonML:

- `string|array JsonML.fromHTML(Element node, function filter)`
	Converts HTML DOM nodes to a JsonML structure

- `string|array JsonML.fromHTMLText(string xmlText, function filter)`
	Converts HTML text to a JsonML structure

### jsonml-xml.js

Methods for converting between JsonML and XML:

- `Element JsonML.toXML(string|array jml, function filter)`
	Converts a JsonML structure to XML DOM nodes

- `string JsonML.toXMLText(string|array jml, function filter)`
	Converts a JsonML structure to XML text

- `string|array JsonML.fromXML(Element node, function filter)`
	Converts XML DOM nodes to a JsonML structure

- `string|array JsonML.fromXMLText(string xmlText, function filter)`
	Converts XML text to a JsonML structure

### jsonml-utils.js

Utility methods for manipulating JsonML structures:

- `boolean JsonML.isElement(string|array jml)`
	Tests if a given object is a valid JsonML element

- `string JsonML.getTagName(string|array jml)`
	Gets the name of a JsonML element

- `boolean JsonML.isAttributes(string|array jml)`
	Tests if a given object is a JsonML attributes collection

- `boolean JsonML.hasAttributes(string|array jml)`
	Tests if a JsonML element has a JsonML attributes collection

- `object JsonML.getAttributes(string|array jml)`
	Gets the attributes collection for a JsonML element

- `void JsonML.addAttributes(string|array jml, object attr)`
	Sets multiple attributes for a JsonML element

- `object JsonML.getAttribute(string|array jml, string key)`
	Gets a single attribute for a JsonML element

- `void JsonML.setAttribute(string|array jml, string key, string|int|boolean value)`
	Sets a single attribute for a JsonML element

- `void JsonML.appendChild(parent, child)`
	Appends a JsonML child node to a parent JsonML element

- `array JsonML.getChildren(string|array jml)`
	Gets an array of the child nodes of a JsonML element

### jsonml-jbst.js

Client-side templating library which executes [JsonML Browser-Side Templates (JBST)](http://www.jsonml.org/bst/).
This is the native runtime format generated by [JsonFx-UI](http://docs.jsonfx.net/jbst).

	// JBST + JSON => DOM
	var dom = JsonML.BST(jbst).bind(data);

	// JBST + JSON => JsonML
	var jsonml = JsonML.BST(jbst).dataBind(data);

**NOTE:** JBST has been rebuilt from the ground up as [DUEL](http://duelengine.org), a dual-side template library (client-side & server-side).

### jsonml.xslt

Proof-of-concept XSL transformation from XML directly to JsonML.

### jsonml2.js *(deprecated)*

NOTE: If you want the same functionality of `jsonml2.js`, use `jsonml-html.js` and `jsonml-utils.js` if you used the extra helper methods.
