the soopergeek of svidgen: building custom tags in html5 and javascript, part 1

Tuesday, October 16, 2012

building custom tags in html5 and javascript, part 1

If you've had the chance to work with Facebook's Social Plugins, you've likely come across the option to embed their widgets using XFBML. They offer a similar "HTML5 compatible" option, but I tend to think the custom, name-spaced tags option is neat. So, let's explore one way to do that.

As an example of the usefulness, I'll use my recently completed book of small potatoes (wisdom of the ancients) from thepointless.com. With each wise guy quote, we see markup in the following format, which renders a voting widget, with the help of some fancy JavaScript:


<tpdc:voter method='/ajax/pointlisting_vote' record_id='37' vote='1'

 fb_like_url='http://www.thepointless.com/pointlistings?id=37'>

  <tpdc:vote>vote<tpdc:vote>

  <tpdc:unvote>unvote<tpdc:unvote>

  +<tpdc:count>1<tpdc:count>

<tpdc:voter>

(Rather the post the full script that does the magic here, I'll be using some trivial simplified JavaScript here for conciseness. You can take a peek at it in action if you're interested.)

To prevent Internet Explorers 7 and 8 from giving us the silent treatment come script-time, our custom tags need to live in a namespace. (Other browsers, as far as I know, ignore the namespace altogether.) And the namespace must be defined in the opening html tag:

<html xmlns:tpdc="http://www.thepointless.com/ns/tpdc">

Now, as you might imagine, a little JavaScript magic is needed to work with these nodes gracefully. And although a touch hacking, it may not be as hackish as you'd expect! As seen on the thepointless.com, here is the function we use to grab these nodes and "import" their attributes correctly:

var getNodes = function(n, q) {

    try {

        // i think "r" stands for "return" here.

// in any event, our first step is to try to find the nodes

        // by their full names -- that is, with the namespace.

        var r = n['getElementsByTagName'](q);

        if (r.length < 1) {

// ... and if we don't find anything, omit the namespace,

            // if present.

            var p = q.split(":");

            if (p.length == 2) {

                r = n['getElementsByTagName'](p[1]);

            }

        }



        // import attributes, for each node

        for (var i = 0; i < r.length; i++) {



            // for each attribute in r[i]

            // first, make sure we're not attempting to RE-import attributes.

            var ri = r[i];


            if (!ri.__attributes_imported) {

// so, we basically iterate through each attribute and
// "re-attach" it to the node directly. seems silly, but
// it allows our scripts to operate on these attributes

                // later much more naturally.

                for (var ai = 0; ai < ri.attributes.length; ai++) {

                    var att = ri.attributes[ai];

                    if (!ri[att.name]) {

                        ri[att.name] = att.value;

                    }

                }

                ri.__attributes_imported = true;

            }

        }



        // and finally, give that list of nodes back.

        return r;

    } catch (e) {

        return [];

    }

} // getNodes()

This getNodes() implementation works in recent versions of Chrome, Firefox, Safari, and IE7+ (not tested in IE6). One-off use of the function works similarly to (but not exactly like) the normal getElementByTagName() function. So, if we want to work with all the tpdc:voter nodes, we could do this:

// get an array of tpdc:voter nodes.

var voterNodes = getNodes(document, "tpcd:voter");



// for each one, let's add an onclick event that simply displays

// the method attribute.

for (var i = 0; i < voterNodes.length; i++) {

  // to be clear, the "this" here is the node itself

  voterNodes[i].onclick = function() { alert(this.method); }

}

Pretty simple. And working with child nodes is just as easy. Suppose we want to loop through all the tpdc:voter nodes and make each tpdc:count node with a value of 10 or more bold. Now, with this trivial example, we could do this globally, like so:

// get all the tpdc:count nodes.

var countNodes = getNodes(document, "tpdc:count");



// make each one with an innerHTML value >= 10 bold

for (var i = 0; i < countNodes.length; i++) {

  if (parseInt(countNodes[i].innerHTML) >= 10) {

    countNodes[i].style.fontWeight = 'bold';

  }

}

Or, we can work within the context of a single tpdc:voter node, as we might in a voter node's class method. A trivial example again, but this works as expected:

// assume we already have a tpdc:voter node, voterNode
var countChildren = getNodes(voterNode, 'tpdc:count');

// act on all tpdc:count nodes found.
for (var ci = 0; ci < countChildren.length; ci++) {
  if (parseInt(countChildren[ci].innerHTML) >= 10) {
    countChildren[ci].style.fontWeight = 'bold';
  }
}

Neat.

But, we're not done yet. What we really want is the ability to treat these custom tags like instances of a real class. And we can! We can define a namespace (empty object) with some classes (functions) and bind them semi-automagically to the DOM nodes.

Let's consider a TPDC namespace with two very simple classes:

// the namespace

var TPDC = {};

// class Simple

TPDC.Simple = function() {

  // we can do things at object "instantiation" time

  this.innerHTML = "Simple";

} // class TPDC.Simple()

// class LessSimple

TPDC.LessSimple = function() {

// we can also define object methods
this.makeSimple = function() {
this.innerHTML = "Simple";
} // TPDC.LessSimple.makeSimple()



  this.onClick = function() {
    this.makeSimple();

  } // TPDC.LessSimple.onClick()

  this.innerHTML = "Less Simple";

} // class TPDC.LessSimple()

Simple. And so is binding our whole TPDC "namespace" to the appropriate document nodes:

for (var k in TPDC) {
  var tpdc_nodes = getNodes(document, 'tpdc:' + k);
  for (var i = 0; i < tpdc_nodes.length; i++) {
    TPDC[k].apply(tpdc_nodes[i]);
  }

}

And, if we want to stuff our getNodes() function stuffed neatly away in a shared library, we can also add a convenient little binder method:

var BindNS = function(ns_name, parent) {

  // "find" the namespace within its parent, given its name

  var p = parent || this;

  var ns = p[ns_name];

  // apply the class constructors to the document nodes

  for (var k in ns) {

    var ns_nodes = getNodes(document, ns_name.toLowerCase() + ":" + k.toLowerCase());

    for (var i = 0; i < ns_nodes.length; i++) {

      ns[k].apply(ns_nodes[i]);

    }

  }

} // BindNS()

And then bind our simple TPDC class with one line:

BindNS('TPDC');

And at this point, any tags in our document that look like these will operate as though they're instances of our Simple and LessSimple classes:

<tpdc:simple>weeeeee...</tpdc:simple>

<tpdc:lesssimple>...eeeeee!</tpdc:lesssimple>

They also operate as generic DOM nodes too, of course. Your JavaScript classes are, in many respects, subclasses of the Node class.

Two things to remember though:

1. Most browsers ignore the namespace. So, this approach doesn't grant you an ability, so far as I know, to create namespaces with identical class names. You can work around this by including the namespace again as a prefix in your class names if you need to.

and

2. It's invalid markup! It's served up with a text/html content type and an HTML5 doctype, which explicitly forbids tag namespaces. So, you might even call it grossly invalid! That said, of all the custom tag variations I tested, this syntax actually provided the most consistent behavior.

In any event, I like the way this works. I can simplify and minimize both my markup and my script using this approach. And I definitely plan on playing with it more. One thing I'm pondering is an elegant way to automagically attach custom child tags to custom-tag parents in a helpful and meaningful way.

So, if anyone has any thoughts on that (or any of this), I'd be interested in your feedback.

And of course, I encourage you to check out the working examples of this concept at thepointless.com, starting with the book of small potatoes!

Wee!

UPDATE: There's now a building custom tags in html5 and javascript, part 2!