Build Your First JavaScript Library

Firstly, the DOM can be rather rough to wrangle for a beginner; its a pretty poor excuse for an API.

If building a library were just about writing the code, it wouldn’t be too difficult a job. But as I worked on this project, I found the tougher part was deciding how certain methods should work.

Soon, we’re going to build a text method that returns the text of our selected elements. If our Dome object wraps several DOM node (dome.get("li"), for example), what should this return? If you do something similar in jQuery ($("li").text()), you’ll get a single string with the text of all the elements concatenated together. Is this useful? I don’t think so, but I’m not sure what a better return value would be.

For this project, I’ll return the text of multiple elements as an array, unless there’s only one item in the array; then we’ll just return the text string, not an array with a single item. I think you’ll most often be getting the text of a single element, so we optimize for that case. However, if you’re getting the text of multiple elements, we’ll return something you can work with.

Back to Coding

So, the mapOne method will simply run map, and then either return the array, or the single item that was in the array. If you’re still not sure how this is useful, stick around: you’ll see!

Dome.prototype.mapOne = function (callback) {var m = this.map(callback);return m.length > 1 ? m : m[0];};

Step 5: Working with Text and HTML

Next, let’s add that text method. Just like jQuery, we can pass it a string and set the element’s text, or use no parameters to get the text back.

Dome.prototype.text = function (text) {if (typeof text !== "undefined") {return this.forEach(function (el) {el.innerText = text;});} else {return this.mapOne(function (el) {return el.innerText;});}};

As you might expect, we need to check for a value in text to see if we’re setting or getting. Note that just if (text) wouldn’t work, because an empty string is a false value.

If we’re setting, we’ll do a forEach over the elements and set their innerText property to the text. If we’re getting, we’ll return the elements’ innerText property. Note our use of the mapOne method: if we’re working with multiple elements, this will return an array; otherwise, it will be just the string.

The html method will do pretty much the same thing as text, except that it will use the innerHTML property, instead of innerText.

Dome.prototype.html = function (html) {if (typeof html !== "undefined") {this.forEach(function (el) {el.innerHTML = html;});return this;} else {return this.mapOne(function (el) {return el.innerHTML;});}};

Like I said: almost identical.

Step 6: Hacking Classes

Next up, we want to be able to add and remove classes; so let’s write the addClass and removeClass methods.

Our addClass method will take either a string or an array of class names. To make this work, we need to check the type of that parameter. If it’s an array, we’ll loop over it and create a string of class names. Otherwise, we’ll just add a single space to the front of the class name, so it doesn’t mess with the existing classes on the element. Then, we just loop over the elements and append the new classes to the className property.

Dome.prototype.addClass = function (classes) {var className = "";if (typeof classes !== "string") {for (var i = 0; i < classes.length; i++) {className += " " + classes[i];}} else {className = " " + classes;}return this.forEach(function (el) {el.className += className;});};

Pretty straightforward, eh?

Now, what about removing classes? To keep it simple, we’ll only allow removing one class at a time.

Dome.prototype.removeClass = function (clazz) {return this.forEach(function (el) {var cs = el.className.split(" "), i;while ( (i = cs.indexOf(clazz)) > -1) {cs = cs.slice(0, i).concat(cs.slice(++i));}el.className = cs.join(" ");});}; 

On every element, we’ll split the el.className into an array. Then, we use a while loop to slice out the offending class until cs.indexOf(clazz) returns -1. We do this to cover the edge case where the same classes has been added to an element more than once: we need to make sure it’s really gone. Once we’re sure we’ve cut out every instance of the class, we join the array with spaces and set it on el.className.

Step 7: Fixing an IE Bug

The worst browser we’re dealing is IE8. In our little library, there’s only one IE bug that we need to deal with; thankfully, it’s pretty simple. IE8 doesn’t support the Array method indexOf; we use it in removeClass, so let’s polyfill it:

if (typeof Array.prototype.indexOf !== "function") {Array.prototype.indexOf = function (item) {for(var i = 0; i < this.length; i++) {if (this[i] === item) {return i;}}return -1;};}

It’s pretty simple, and it’s not a full implementation (doesn’t support the second parameter), but it will work for our purposes.

Step 8: Adjusting Attributes

Now, we want an attr function. This’ll be easy, because it’s practically identical to our text or html methods. Like those methods, we’ll be able to both get and set attributes: we’ll take an attribute name and value to set, and just an attribute name to get.

Dome.prototype.attr = function (attr, val) {if (typeof val !== "undefined") {return this.forEach(function(el) {el.setAttribute(attr, val);});} else {return this.mapOne(function (el) {return el.getAttribute(attr);});}};

If the val has a value, we’ll loop through the elements and set the selected attribute with that value, using the element’s setAttribute method. Otherwise, we’ll use mapOne to return that attribute via the getAttribute method.

Step 9: Creating Elements

We should be able to create new elements, like any good library can. Of course, this would be no good as a method on a Dome instance, so let’s put it right on our dome object.

var dome = {// get method herecreate: function (tagName, attrs) {}};

As you can see, we’ll take two parameters: the name of the element, and an object of attributes. Most of the attributes be applied via our attr method, but two will get special treatment. We’ll use the addClass method for the className property, and the text method for the text property. Of course, we’ll need to create the element and the Dome object first. Here’s all that in action:

create: function (tagName, attrs) {var el = new Dome([document.createElement(tagName)]);if (attrs) {if (attrs.className) {el.addClass(attrs.className);delete attrs.className;}if (attrs.text) {el.text(attrs.text);delete attrs.text;}for (var key in attrs) {if (attrs.hasOwnProperty(key)) {el.attr(key, attrs[key]);}}}return el;}

As you can see, we create the element and send it right into a new Dome object. Then, we deal with the attributes. Notice that we have to delete the className and text attributes after working with them. This keeps them from being applied as attributes when we loop over the rest of the keys in attrs. Of course, we end by returning the new Dome object.

But now that we’re creating new elements, we’ll want to insert them into the DOM, right?

Step 10: Appending and Prepending Elements

Next up, we’ll write append and prepend methods, Now, these are actually a bit tricky functions to write, mainly because of the multiple use cases. Here’s what we want to be able to do:

dome1.append(dome2);dome1.prepend(dome2);

The worst browser were dealing is IE8.

The use cases are as these: we might want to append or prepend

• one new element to one or more existing elements.
• multiple new elements to one or more existing element.
• one existing element to one or more existing elements.
• multiple existing elements to one or more existing elements.

Note: I’m using “new” to mean elements not yet in the DOM; existing elements are already in the DOM.

Let’s step though it now:

Dome.prototype.append = function (els) {this.forEach(function (parEl, i) {els.forEach(function (childEl) {});});};

We expect that els parameter to be a Dome object. A complete DOM library would accept this as a node or nodelist, but we won’t do that. We have to loop over each of our elements, and then inside that, we loop over each of the elements we want to append.

If we’re appending the els to more than one element, we need to clone them. However, we don’t want to clone the nodes the first time they’re appended, only subsequent times. So we’ll do this:

if (i > 0) {childEl = childEl.cloneNode(true);}

That i comes from the outer forEach loop: it’s the index of the current parent element. If we aren’t appending to the first parent element, we’ll clone the node. This way, the actual node will go in the first parent node, and every other parent will get a copy. This works well, because the Dome object that was passed in as an argument will only have the original (uncloned) nodes. So, if we’re only appending a single element to a single element, all the nodes involved will be part of their respective Dome objects.

Finally, we’ll actually append the element:

parEl.appendChild(childEl);

So, altogether, this is what we have:

Dome.prototype.append = function (els) {return this.forEach(function (parEl, i) {els.forEach(function (childEl) {if (i > 0) {childEl = childEl.cloneNode(true);}parEl.appendChild(childEl);});});};

The prepend Method

We want to cover the same cases for the prepend method, so the method is pretty very similar:

Dome.prototype.prepend = function (els) {return this.forEach(function (parEl, i) {for (var j = els.length -1; j > -1; j--) {childEl = (i > 0) ? els[j].cloneNode(true) : els[j];parEl.insertBefore(childEl, parEl.firstChild);}});};

The different when prepending is that if you sequentially prepend a list of elements to another element, they’ll end up in reverse order. Since we can’t forEach backwards, I’m going through the loop backwards with a for loop. Again, we’ll clone the node if this isn’t the first parent we’re appending to.

---

Step 11: Removing Nodes

For our last node manipulation method, we want to be able to remove nodes from the DOM. Easy, really:

Dome.prototype.remove = function () {return this.forEach(function (el) {return el.parentNode.removeChild(el);});};

Just iterate through the nodes and call the removeChild method on each element’s parentNode. The beauty here (all thanks to the DOM) is that this Dome object will still work fine; we can use any method we want on it, including appending or prepending it back into the DOM. Nice, eh?

---

Step 12: Working with Events

Last, but certainly not least, we’re going to write a few functions for event handlers.

As you probably know, IE8 uses the old IE events, so we’ll have to check for that. Also, we’ll throw in the DOM 0 events, just ‘cause we can.

Check out the method, and then we’ll discuss it:

Dome.prototype.on = (function () {if (document.addEventListener) {return function (evt, fn) {return this.forEach(function (el) {el.addEventListener(evt, fn, false);});};} else if (document.attachEvent)  {return function (evt, fn) {return this.forEach(function (el) {el.attachEvent("on" + evt, fn);});};} else {return function (evt, fn) {return this.forEach(function (el) {el["on" + evt] = fn;});};}}());

Here, we have an IIFE, and inside it we’re doing feature checking. If document.addEventListener exists, we’ll use that; otherwise, we’ll check for document.attachEvent or fall back to DOM 0 events. Notice how we’re returning the final function from the IIFE: that’s what will end up being assigned to Dome.prototype.on. When doing feature detection, it’s really handy to be able to assign the appropriate function like this, instead of checking for the features each time the function is run.

The off function, which unhooks event handlers, is pretty much identical:

Dome.prototype.off = (function () {if (document.removeEventListener) {return function (evt, fn) {return this.forEach(function (el) {el.removeEventListener(evt, fn, false);});};} else if (document.detachEvent)  {return function (evt, fn) {return this.forEach(function (el) {el.detachEvent("on" + evt, fn);});};} else {return function (evt, fn) {return this.forEach(function (el) {el["on" + evt] = null;});};}}());

---

That’s It!

I hope you give our little library a try, and maybe even extend it a bit. Like I mentioned earlier, I have it up on Github, along with the Jasmine test suite for the code we’re written above. Feel free to fork it, play around, and send a pull request.

Let me clarify again: the point of this tutorial isn’t to suggest that you should always be writing your own libraries.

There are dedicated teams of people working together to make the big, established libraries as good as possible. The point here was to give a small peek into what might go on inside a library; I hope you’ve picked up a few tips here.

I really recommend you dig around inside a few of your favourite libraries. You’ll find that they aren’t so cryptic as you might have thought, and you’ll probably learn a lot. Here are a few great places to start:

• 10 Things I Learned from the jQuery Source (by Paul Irish)
• 11 More Things I Learned from the jQuery Source (also by Paul Irish)
• Under jQuery’s Bonnet (by James Padolsey)
• Backbone.js: Hacker’s Guide, part 1, part 2, part 3, part 4
• Know any other good library breakdowns? Let’s see ‘em in the comments!