How Prototype extends the DOM

Prototype’s DOM extensions set it apart from other JavaScript libraries. Prototype adds many convenience methods to elements returned by the $() function: for instance, you can write $('comments').addClassName('active').show() to get the element with the ID ‘comments’, add a class name to it and show it (if it was previously hidden). The ‘comments’ element didn’t have those methods in native JavaScript; how is this possible? This document reveals some clever hacks found in Prototype.

The Element.extend method

Most of the DOM methods are encapsulated by the Element.Methods object and then copied over to the Element object (for convenience). They all receive the element to operate with as the first parameter:

Element.hide('comments');
var div_height = Element.getHeight(my_div);
Element.addClassName('contactform', 'pending');

These examples are concise and readable, but we can do better. If you have an element to work with, you can pass it through Element.extend() and it will copy all those methods directly to the element. Example, to create an element and manipulate it:

var my_div = document.createElement('div');

Element.extend(my_div);
my_div.addClassName('pending').hide();

// insert it in the document
document.body.appendChild(my_div);

Our method calls just got shorter and more intuitive! As mentioned before, Element.extend() copies all the methods from Element.Methods to our element which automatically becomes the first argument for all those functions. The extend() method is smart enough not to try to operate twice on the same element. What’s even better, the dollar function $() extends every element passed through it with this mechanism.

In addition, Element.extend() also applies Form.Methods to FORM elements and Form.Element.Methods to INPUT, TEXTAREA and SELECT elements:

var contact_data = $('contactform').serialize();
var search_terms = $('search_input').getValue();

Note that not only the dollar function automatically extends elements! Element.extend() is also called in document.getElementsByClassName, Form.getElements, on elements returned from the $$() function (elements matching a CSS selector) and other places - in the end, chances are you will rarely need to explicitly call Element.extend() at all.

Adding your own methods with Element.addMethods

If you have some DOM methods of your own that you’d like to add to those of Prototype, no problem! Prototype provides a mechanism for this, too. Suppose you have a bunch of functions encapsulated in an object, just pass the object over to Element.addMethods():

var MyUtils = {
  truncate: function(element, length){
    element = $(element);
    return element.update(element.innerHTML.truncate(length));
  },
  updateAndMark: function(element, html){
    return $(element).update(html).addClassName('updated');
  }
};
    	
Element.addMethods(MyUtils);
    	
// now you can:
$('explanation').truncate(100);

The only thing to watch out here is to make sure the first argument of these methods is the element itself. In your methods, you can also return the element in the end to allow for chainability (or, as practiced in the example, any method which itself returns the element).

Native extensions

There is a secret behind all this.

In browsers that support adding methods to prototype of native objects such as HTMLElement all DOM extensions on the element are available by default without ever having to call Element.extend(), dollar function or anything! This will then work in those browsers:

var my_div = document.createElement('div');
my_div.addClassName('pending').hide();
document.body.appendChild(my_div);

Because the prototype of the native browser object is extended, all DOM elements have Prototype extension methods built-in. This, however, isn’t true for IE which doesn’t let anyone touch HTMLElement.prototype. To make the previous example work in IE you would have to extend the element with Element.extend(). Don’t worry, the method is smart enough not to extend an element more than once.

Because of browsers that don’t support this you must take care to use DOM extensions only on elements that have been extended. For instance, the example above works in Firefox and Opera, but add Element.extend(my_div) after creating the element to make the script really solid. You can use the dollar function as a shortcut like in the following example:

// this will error out in IE: 
$('someElement').parentNode.hide();
// to make it cross-browser:
$($('someElement').parentNode).hide();

Don’t forget about this! Always test in all the browsers you plan to support.