chalker / jsml

Javascript object to DOM translator

JSML

What is JSML?

JSML is a compact representation of HTML using Javascript arrays and objects. JSML is also a small jQuery plug-in that allows you to construct DOM elements from these structured Javascript objects. Here’s a quick example:

$("#my-element").jsml(["a", { href: "http://example.com" }, "This is a <link>" ])

That finds the div identified by "my-element" and replaces its contents with:

<a href="http://example.com">This is a &lt;link&gt;</a>

…​except that there’s never an actual HTML string created. JSML uses document.createElement(), document.createTextNode() and document.appendChild() to build up the DOM representation directly which means that you never have to worry about quoting HTML entities which helps prevent XSS (cross site scripting) attacks by being secure by default.

Here’s a slightly more complicated example:

$("#my-element").jsml(["ul",
                       ["li", { style: { backgroundColor: "red" } }, "First item"],
                       ["li",
                        ["img", { src: "myimage.png", title: "A title"},
                                { alt: "Some Alt-text" }], "Second item"],
                       $("<li>raw html item</li>")])

Additional things to notice:

• The basic idea is that new arrays signal new elements. The first item in an array defines what type of element. The rest of the items in an array are either attributes or child elements.

• Objects (enclosed in "{}") let you define an element’s attributes. You can have multiple objects in the array—​they simply accumulate. If you have duplicate keys in the objects then the last one in the array wins.

• As a special case you can drill down into the style with a nested object (though it’s not necessarily the best thing to do).

• Style and attribute names are the standard Javascript equivalents ("border-top" is "borderTop", "class" is "className").

• You can use jQuery to drop in unquoted HTML strings if you absolutely need to.

Advanced Usage

JSML has special support for map functions (Underscore’s is shown here):

$("#my-element").jsml(["ul", _.map([1,2,3], function(num) { return ["li", "Item "+num] })]);

If you’re paying attention you’ll notice that the structure passed to the jsml() function looks like this:

["ul", [["li", "Item 1"],
        ["li", "Item 2"],
        ["li", "Item 3"]]]

…​which has extra array around the list items unlike the standard syntax:

["ul", ["li", "Item 1"],
       ["li", "Item 2"],
       ["li", "Item 3"]]

JSML automatically flattens this extra level of arrays to make using map() convenient. This is also useful for passing in an array of uniform items in a JSML structure (which means there’s usually no need to use concat()).

var a = [];
a.push(["li", "Item 1"],
       ["li", "Item 2"]);
$("#my-element").jsml(["ul", a]);

You can also pass DOM element objects and jQuery objects and those will be appended:

var li = document.createElement("li");
li.appendChild(document.createTextNode("Standard DOM element"));
$("#my-element").jsml(["ul", li, $("<li>jQuery element</li>")]);

If you wish to create detached DOM elements you can call either $.fn.jsml.make() which returns a jQuery wrapped object, or, $.fn.jsml.dom() which returns a standard DOM element object.

How Should I Pronounce This?

There are 3 ways to pronounce it, depending on what you think of the project. If you think it’s cool you can call it "Jay-Smile", since its compact representation and XSS resistance makes you happy. If you are neutral, you can just call it "Jay Ess Emm Ell". If you hate it, feel free to call it "Jay-Smell" (and make sure to really sneer when you say it).

Author, Copyright, and License

Copyright © 2009-2012 by David Caldwell <[email protected]> and Jim Radford <[email protected]>

The JSML source code is licensed under the Mozilla Public License. It is available here: http://mozilla.org/MPL/2.0/