JavaScript Library Design

This final tutorial explains the XML generator JavaScript library. Whether you like angle bracket tax or not, XML is used in web development for XHTML pages, RSS feeds, and AJAX, to name but a few.

This library is designed to produce XML (it has nothing to do with parsing XML). It was inspired by Sean M. Burke's digression in his article “Higher-Order JavaScript”, and by JSON, the JavaScript Object Notation.

The Problem

Personally, I am very tired of reading, let alone writing code like this:

<div id="sidebar">
  <h3>Action</h3>
  <ul>
    <li><a href="<%=newItem%>">New</a></li>
    <li><a href="<%=tagCloud%>">Tag cloud</a></li>
  </ul>
  <h3>Navigation</h3>
  <ul>
    <li><a href="<%=cJU%>">Detail</a></li>
    <li><a href="<%=AppPath + "List.asp"%>">All</a></li>
  </ul>
</div>

Or even this:

var x = document.createElement("div");
x.setAttribute("class", "foo");
document.body.appendChild(x);
var y = document.createElement("div");
y.setAttribute("class", "bar");
x.appendChild(y);
y.appendChild(document.createTextNode("Baz"));

The first is, of course, classic ASP. The problem is that you have to escape code snippets using <% and %>, or <%= and %>. Highlighting helps a little, but it is still all too easy to make a mistake with those escapes. It can also be extremely frustrating to debug.

The second is standard DOM notation. As you can see, it is extremely verbose, and quite difficult to understand what it is doing. Want to know? It is simply producing this:

<div class="foo">
  <div class="bar">
    Baz
  </div>
</div>

I don't want to do that, either. What I want is some terse format, in JavaScript, which will produce XML using less text than the XML itself. Here's an mock-up, to produce the first example:

["div#sidebar",
  ["h3", "Action"],
  ["ul",
    ["li", ["a", { "href" : newItem }, "New"]],
    ["li", ["a", { "href" : tagCloud }, "Tag Cloud"]]
  ],
  ["h3", "Navigation"],
  ["ul",
    ["li", ["a", { "href" : cJU }, "Detail"]],
    ["li", ["a", { "href" : AppPath + "List.asp" }, "All"]]
  ]
]

And the second example would look like:

['div.foo',
  ['div.bar',
    "Baz!"
  ]
]

I hope you agree with me that these last two examples look easier than the first two. Both of the examples are valid JavaScript, though the resulting array is not stored anywhere. Being JavaScript, we can modify the array contents programmatically, before converting to XML. As long as the variables in the first example return strings, then this is also valid JSON. The second example is certainly valid JSON.

The Specifications

An element is defined by an array. The array contains the name of the element, followed by optional attributes (specified as a collection), followed by any number of text or elements (including zero).

For example:

["img", { "src" : "..." }]

Or:

["a", { "href" : "..." }, ["img", { "src" : "..." }]]

Or:

["pre", "Text"]

Or:

["br"]

The name of the element can be 'decorated' with a single identifier, using the '#' character, and/or by a single class name, using the '.' character. When used together, the '#' character must appear first.

For example:

["p.normal", "Text"]

which is identical to:

["p", { "class" : "normal" }, "Text"]

Or:

["p#id123", "Text"]

which is identical to:

["p", { "id" : "id123" }, "Text"]

Or:

["p#id123.normal", "Text"]

which is identical to:

["p", { "id" : "id123", "class" : "normal" }, "Text"]

Caveats

It is impossible to specify a text node, on its own, with this syntax. At best the text would have to be wrapped in an element, such as span:

["span", "Text"]

Element names, attribute names, and text must be of type string. Attribute values can be either of type string or number. Obviously, they can also be substituted by method calls, though these must return the required type.

No effort has been made to encapsulate more exotic node types, such as document type, comments, CData, or processing instructions.

The converter always encloses attribute values in single quotes ('). This means that font names in CSS style attributes can use double quotes ("), without having to escape the string.

The converter makes no attempt to encode illegal characters (<, >, &, ", and ') in attributes or text. Rather, it assumes that the programmer has taken care of this detail beforehand. The library does provide helper functions, however.

The next part of this tutorial describes the library code.

All the scripts in these tutorials are available for download as two compressed archives; Scripts.zip and AspScripts.zip, both distributed under the GNU Lesser General Public License.