Matt Snider JavaScript Resource

Today’s post is going to introduce the file that provides the core functionality for my personal JavaScript Framework. I have already introduced several parts of the file, such as type detection and cookie management. You can view the code @ http://mattsnider.com/corejs.

The first thing you’ll probably notice is that I comment everything. This is the most important part of programming, and often overlooked in Web Applications. You almost can not have enough comments in any given file. In my case, I write so much code and work on so many different projects on a daily basis that without comments, I would be lost. But beyond that, if I wrote a file (of any reasonable length) 4 months ago and revisit it now, I am probably going to have to reacquaint myself with what it is doing (and most likely improve it a little). Figuring out what is going is exponentially faster when you comment your code. It’s best to comment: all functions, large blocks of code, anything that might be confusing, and all hacks.

Now, back to ‘Core.js’. What is does this all do? First, you will see a section that sets up some W3C standard constants, which should be attached to the ‘document’. These constants will be used anytime you want to compare the ‘nodeType’ of a DOMElement. Older browsers and IE do not define these by default, so this block of code fixes that. Note that I do not use browser detection to figure this out, but instead see if the variables are defined in the ‘document’ namespace. Always try not to use browser detection if you can.

/**
 *  W3C DOM Level 2 standard node types; for older browsers and IE
 */
if (null == document.ELEMENT_NODE) {
	document.ELEMENT_NODE                   = 1;
	document.ATTRIBUTE_NODE                 = 2;
	document.TEXT_NODE                      = 3;
	document.CDATA_SECTION_NODE             = 4;
	document.ENTITY_REFERENCE_NODE          = 5;
	document.ENTITY_NODE                    = 6;
	document.PROCESSING_INSTRUCTION_NODE    = 7;
	document.COMMENT_NODE                   = 8;
	document.DOCUMENT_NODE                  = 9;
	document.DOCUMENT_TYPE_NODE             = 10;
	document.DOCUMENT_FRAGMENT_NODE         = 11;
	document.NOTATION_NODE                  = 12;
}

An example of how you might use this is:

var isTextNode = function(node) {
	return document.TEXT_NODE == node.nodeType;
}

So, if you pass a DOMElement into the Function ‘isTextNode’, it will return ‘true’ if the node is a text node.

The next block of code defines the ‘Core’ Object and namespace. I say namespace, because the Core Object will be the global Object that the Framework will be attached to. I use the ‘module’ pattern as coined by Douglas Crockford to create my Core Object. This gives me the freedom to create ‘private’-like variables: ‘debugLevel’ and ‘clientInitFunc’. Debug level is a variable I use to differentiate between production and development messaging. ‘clientInitFunc’ also uses the ‘module’ pattern, creating the template that will evaluate the user’s browser and OS. This is also a logical place to attach cookie management Functions. Here are some references for these methods:

• Cookie Management Function
• Browser Detection, originally by Peter Paul Koch

Again, let me reiterate, “DO NOT USE BROWSER DETECTION, UNLESS ABSOLUTELY NECESSARY”. That said, the two browsers you might have to detect most often are IE and Opera, so I have two shortcut methods: ‘isIE’ and ‘isOpera’ that compares against the Core.browser variable.

The next statement returns the constants and methods attached directly to the Core namespace. These include additional namespace variables: Biz, Debug, Client, Widget, and Util. Each of these have been commented to explain what to use them for. I frequently use Core.Client and therefore have attached the Client Object created during the initialization of the Core Object to Core.Client for ease of access.

The next two Functions are helper methods that did not belong in the global namespace, nor any other namespace, so I have attached them to Core. ‘deepCopy’ copies an Object or Array and all of its member Objects and Arrays until all children have been copied. I need this from time-to-time to prevent Objects from being passed by reference, when I do not want a Function to modify the passed element. ‘getImage’ is a short-cut method to create an ‘Image’ instance and then attach the URI src to the image Object. This allows pre-caching of images and simplifies code.

‘getDebugLevel’ is used to retrieve the debugLevel variable. I have designed it this way, because I want to ensure that I (or a hacker) can never update the debug level directly once the script is loaded into the page. Lastly, the ‘init’ Function initializes some internal ‘Debug’ variables and initializes the Core.Client Object.

Now, the ‘emptyFunction’ Function and ‘Class’ Object are copies of similar elements in the ‘Prototype’ Framework. They probably should not be in the global namespace, but i have not had a good enough reason to move them yet. ‘emptyFunction’ is handy, because it allows you to supply a generic do-nothing method. The ‘Class’ Object, can be used to create ‘Prototype’ Objects, but is something I try to stay away from. I have only one instance in the Form Validator that benefited from this design pattern, and so it remains. Also, the amount of code is negligible and some people may prefer to build ‘Prototype’ Objects.

The file closes with all the type detection functions. These are described in detail for the Type Detection article.

Although, short and sweet, this file has some complex ideas and may take a little getting used to. Please let me know your thoughts and any possible improvements, especially with the ‘deepCopy’ method.

A List Apart Magazine recently posted an article on Frameworks. This mostly talks about CSS Frameworks, but does a great job describing Frameworks as a concept.

frameworksfordesigners

Probably the most commonly needed Function for a Web Application Developer (WAD), is document.getElementById. As you will most certainly need to retrieve HTMLElements from the DOM by the element’s ID. Using ‘getElementById’ is perfectly valid, but has potential drawbacks such as:

• ‘document.getElementById’ is verbose
• multiple elements cannot be retrieved with one simple call
• Some browsers, especially old browsers, do not support this call.
• The more IDs you use in your document, the longer the seek time of this method.

As the title says, I am in love with the ‘$’ (I am also in love with money, in case you were wondering). The ‘$’ function was first developed by Prototype (and IMHO is Prototype’s greatest contribution to the JavaScript community). My love for the ‘$’ function is two-fold:

• It is elegant, simple, and concise
• Using the $ symbol as a shortcut, should be safe and most people did not know this was possible (so it is cool)

But beyond those points, let us really consider what an element retrieval function should and should not do:

Dos

• Process lists of elements as well (both arguments list and arrays)
• Handle all x-browser issues and old browsers, or degrade nicely
• Caching. It is faster to maintain an array for all previously retrieved IDs, than to retrieve them each time
• Do nothing when passing an HTMLElement (it should be acceptable to use ‘foo= $(foo)’, just to ensure that is an HTMLElement

Do Nots

1. Attach a bunch of variables and/or functions to the HTMLElement*
2. DO NOT do item 1

* This is my single biggest gripe with pretty much all JavaScript Frameworks. Why do each of my HTMLElements need a slew of helper functions that are already available to me elsewhere? I am not that lazy and frankly it is expensive to add Function references to every HTMLElement that I retrieve. Plus: you increase your chances of circular references causing memory leaks, different Frameworks and Toolkits may conflict with each other, and some future version of JavaScript may define that same function.

That said, let us move on to comparing YUI ‘YAHOO.util.Dom.get’ vs. Prototype ‘$’. I have created an simple rating system that I will be using for this and future discussion. I will walk through each Function and rate them using a point system, where you get plus points for each ‘Dos’ (ex. +1) and minus points for each (ex. -3) ‘Do not’ used. Here is the newest prototype ‘$’ function from version 1.5.1:

Prototype ‘$’ Function

function $(element) {
if (arguments.length > 1) {
for (var i = 0, elements = [], length = arguments.length; i < length; i++)
{elements.push($(arguments[i]));}
return elements;
}
if (typeof element == 'string')
{element = document.getElementById(element);}
return Element.extend(element);
}

I am happy in this release that they allow you to pass a list of arguments and retrieve multiple HTMLElements at the same time (+1). I am going to give the Function (+1) for using the ‘$’ name. However, it does not allow you to pass in an array as an argument, which is important because sometimes you will have gotten your lists of IDs from a method that created an array of Strings (+0) and will be required to use a work around to pass these Strings into this Function. The Function does retrieve arguments that are Strings and returns the non-string Objects (hopefully HTMLElements) (+1). Unfortunately, the method attaches needless and dangerous methods to the HTMLElement that you pass or retrieve (-3). It does not work with old browsers or degrade well (+0) and has no built in caching system (+0). This gives Prototype an overall rating of (0), which is pretty poor.

YUI ‘YAHOO.util.Dom.get’ Function

get = function(el) {
if (!el) { return null; } // nothing to work with
//
if (typeof el != 'string' && !(el instanceof Array) ) { // assuming HTMLElement or HTMLCollection, so pass back as is
return el;
}
//
if (typeof el == 'string') { // ID
return document.getElementById(el);
}
else { // array of ID's and/or elements
var collection = [];
for (var i = 0, len = el.length; i < len; ++i) {
collection[collection.length] = Y.Dom.get(el[i]);
}
//
return collection;
}
//
return null; // safety, should never happen
}

As with Prototype you are allowed to pass multiple arguments at the same time (+1) and although you cannot pass in an array of arguments, you can pass an argument that is an array, which is more powerful (+1). There is no ‘$’ function short-cut (+0), but I always map this method to the ‘$’ symbol anyway, so it is really not a big deal. The function does retrieve arguments that are Strings and returns the non-string Objects (hopefully HTMLElements) (+1). It does not attach needless/dangerous methods to the HTMLElement (-0). Unfortunately, it does not work with old browsers (+0) (it does degrade well, by return ‘null for unexpected values) and has no built in caching system (+0). This gives YUI ‘get’ Function an overall rating of (+3), which is average, however, if you map the ‘$’ symbol to the ‘get’ Function, then it would bump the rating up one, making YUI ‘get’ Function slightly above average.

Therefore, using my metrics, YUI’s ‘get’ Function is better than Prototype’s ‘$’ Function. I recommend using the YUI one and mapping it to a function named ‘$’ in the global space, emulating Prototype. Not only will you be able to use the concise ‘$’ symbol to retrieve HTMLElements, but doing this will allow you to use YUI with some of Prototype-based Toolkits and Frameworks, without the down-side of using Prototype. Obviously, there is a little room for improvement, as there is no caching yet and there is not a work around for browsers that do not support the ‘document.getElementById’ method. However, 95%+ of internet users (with JavaScript enabled) will have a browser that supports ‘document.getElementById’ (and this number increases every year), and caching gives a marginal improvement only when repeatedly retrieving the same element using the ‘get’ Function (and may be detrimental to performance if you use your own caching system).

Lastly, I want to leave you with a slightly modified YUI ‘get’ function that I use. I use YUI’s namespace approach and attach everything to an Object named ‘Core’, which I later shortcut key methods (such as ‘get’) as part of my JavaScript build process. Here is my method (it will be made available as part of my Core.Util.Dom package after I have further discussed DOM manipulation:

Core.Util.Dom.get: function() {
var multiArgs = (1 < arguments.length); // arguments is not an Array
var elem = multiArgs? arguments: arguments[0];
//
// nothing to work with
if (! elem) {
return null;
}
//
// assume is a DOMElement, but could be any Object
if (! isString(elem) && ! isArray(elem) && ! multiArgs) {
return elem;
}
//
// ID
if (isString(elem)) {
return document.getElementById(elem);
}
// array of ID's and/or elements
else {
var collection = [];
for (var i = 0, j=elem.length; i collection[i] = Core.Util.Dom.get(elem[i]);
}
return collection;
}
}

I have been spending a lot of time improving my Form Utility Framework and wanted to share a little with you. First, we should address the reasons why we would want a Form Utility Framework. Here are some of my reasons:

• Serialization for ajax - converts forms into key/value pair string (ex. “&key1=value1&key2=value2…”), often used with AJAX requests
• Validation - rather than writing code to manually validate each form, i developed a system that allows you to add any number of validators for any number of fields in a form
• Abstracted Value Retrieval - a universal method used to always retrieve the value of an input whether it is an input, a select, or a textarea HTML tag, so you do not need to remember how or worry about x-browser issues
• Helper Methods - functions such as ones that: retrieve inputs by name, gets the first visible input of the form, disable/enable forms, etc.

Since every page will not always have a form and the Form Utility Framework will not always be used, try to keep it as lightweight as possible; it is easy to bloat your Utility with functions that you infrequently or never use.

If you find yourself using a Form Utility Framework, you might run into this problem that I had. I had not used the ‘reset’ HTMLInput type in a long time and found myself wanting to use it to clear the fields in a form. In the past that had always worked for me, but if you are using a server-side scripting language to set the values of the form fields when the page load, then you will find that reseting the form does not clear it. Instead, it reverts to the values that the form had when the page loaded. This is because in most modern browsers, when initializing a page that sets the form field value attribute, those values also are set the the fields defaultValue attribute. According to the W3C standards, the defaultValue attribute is what should be used for form reseting. Therefore, if the form fields had no values when the page load, then the reset function worked as I wanted, otherwise, it did not. To defeat this I created my own method ‘clear’ that iterates through the different form field elements and removes their values.

if (! Form) {Form = {};}
Form.clear = function(form, ingore) {
var inputs = form.getElementsByTagName('input');
// inputs
for (var i=0, input; input=inputs[i]; i++) {
if (-1 == ingore.indexOf(input.type.toLowerCase())) {
input.value = “”;
if (input.checked) {input.checked = false;}
}
}
// textareas
if (-1 == ingore.indexOf(’textarea’)) {
inputs = form.getElementsByTagName(’textarea’);
for (var i=0, input; input=inputs[i]; i++) {
input.value = “”;
}
}
// selects
if (-1 == ingore.indexOf(’select’)) {
inputs = form.getElementsByTagName(’select’);
for (var i=0, sel; sel=inputs[i]; i++) {
sel.selectedIndex = 0;
}
}
};

This method is pretty straight forward. Pass the method an HTMLFormElement Object and it will parse through the object’s child nodes by the tag names using the appropriate reset method. Lastly, I tossed in an array called ignore (array of string types that are not to be cleared), because I often don’t want to reset types such as “button”, “hidden”, “submit”, and “reset”. I was thinking, it might be helpful also to have a list of field names to ignore, but I did not have a need for it yet.

First, let’s make sure we are all using the same Frameworks, because these teams have been cranking out changes faster than you can keep up with them. This discussion will use the stable release of Prototype 1.5.1 and YUI 2.2.0. We will be analyzing the speed of creating small dummy objects to get an idea of which approach is better. Before, starting, I’d like to take a moment to thank the YUI guys for following rigorous coding standards and well documenting their code. I don’t know what high-horse the Prototype guys are riding, but there code is sloppy and it doesn’t compress well. Consequently, I have taken some time to clean up the prototype code (added semi colons, {} all statements, and ran jsmin): uncompressed and minified.

In the Prototype Framework you create Objects using the ‘Class.create()’ method. This basically attaches a function to your Object, that will execute the ‘initialize’ method you attach to the Object’s ‘prototype’ Object with all the variables you passed into the constructor. That’s a mouth full and a little hard to grasp textually, here is an example:

var PrototypeObject = Class.create();
PrototypeObject.prototype = {
initialize: function(v1, v2) {
// my initialization code
this.v1 = v1;
this.v2 = v2;
},
testFunction: function() {
alert(this.v1);
}
};
// to use
var someVariable = new PrototypeObject (v1, v2);
someVariable.testFunction();

The ’someVariable’ Object will contain all the functions and variables attached to ‘PrototypeObject.prototype’, including the initialize function. When I used this OOP Architecture, I often design the initialize function in such a way that it could be called again later to reset the object. This example illustrates how you can pass variables into the constructor and set them internally so that other function, like ‘testFunction’ can access the v1 variable, because it is attached to the ‘this’ keyword Object. You can extend these Object indefinitely, declare addition Objects inside, and do any number of customizations. However, I find that these Objects become larger than they need to be and are often difficult to follow.

In the YUI Framework you create Objects by executing a Function that contains ‘private’ like variables accessible only in the scope of the Function or through Closures in a returned Object. Again, difficult to describe textually; here is an example:

var YUIObject = function(v1, v2) {
var v1 = v1;
var v2 = v2;
return {
testFunction: function() {
alert(v1);
}
}
};
// to use
var someVariable = new YUIObject (v1, v2);
someVariable.testFunction();

So, this Object basically does the same thing as the PrototypeObject. The constructor call, instantiates the Function YUIObject, passing in two variables. Inside the scope of the Function those variables are redeclared to attach to the Function scope. Then the function returns an Object that ’someVariable’ will be set to. The ‘testFunction’ has access to v1 and v2 inside the Function scope because of Closures. For me this Architecture is easier to read and simpler to use, so I have built most of my Objects this way. The downside is that Closures leak memory like sieves in IE, if you are not careful.

To wrap up our discussion, I have created a page where you can compare the run times of the different instantiation. Unfortunately, JavaScript run-times aren’t very accurate and depend on the idle time of your computer. Having run it many times though in many browsers, I can summarize that on average the initialization of the YUI-type Objects is 35-45% faster than the Prototype Objects. Although, we’re talking about fractions of a millisecond, so you’re only going to notice this when you are creating thousands of Objects.

http://mattsnider.com/PrototypeVsYUITest.html

Jack Slocum, author of YAHOO.Ext, has recently launched http://extjs.com/. Initially, I thought the site was a remake of his personal site http://jackslocum.com/ with a greater focus on his YUI extension library. However, upon closer inspection, I realized the new website is dedicated also to framework interoperability. And since that is one of the main goals of this blog, I felt it worth mentioning. Anyway, Ext already works with jQuery, Prototype, and Scriptaculous.

Note: Ext is now also works standalone, without any other library. Although, I am impressed with the work this team has put into Ext, it is still to heavy for most websites. Using this Framework, it is very easy to create JavaScript libraries of 300k or more.

Wow, it’s May already. I’m really busy with my full-time work at Mint and my consulting, but will find the time to post some articles. I have been working on an article to compare different features from the different Frameworks, but while experimenting with JavaScript profilers and run-time analyzers, I have not found one that I like. If you have any ideas, please comment. For now, here is a simple article on how to architect your JavaScript.

Every Unobtrusive JavaScript driven Web Application should have 3 and a half tiers:

• 1. Framework tier
• 2. Toolkit/Utility tier
• 3. Business logic tier
• 3.5 Server-client variables

Framework tier
This tier will contain the objects, functions, and resources that will be used throughout your website. I suggest packaging everything into 1 file so that your client’s browser only needs to download and cache a single file (it is more efficient to download 1 large file, than several smaller files, unless the client has enabled special browser settings). At the bare minimum a framework tier should have your Dom and Event manipulation code. I also like to add String, Object, and Array manipulators and my AJAX system. Every page of your site using JavaScript should reference your Framework tier and it is safe to use these functions in your Toolkit and Business tiers.

I use one library.js file as my Framework tier; here is an where I take several files that make up my Framework and combine them into a library.js:

cat core.js dom.js form.js string.js array.js event.js > library.js

Toolkit tier
This tier contains JavaScript tools that you only use sometimes throughout your Web Application, such as Autocomplete or Animation. These files should be included as needed throughout your site. If you find yourself using these tools on every page, then go ahead and include it in your Framework file, as it will improve site performance. Also, you may find that certain tools, like a Dialog and Animation utility are always used together; you may improve performance by combining them into one file. Generally speaking, I recommend building a utility for any code that may be used on more than 2 pages. Some utilities examples:

Autcompleter, CustomCheckbox, Dialog, Logger, Math, Slider, Tooltip, etc

Business tier
This tier will contain all page specific code. I recommend you name the file directly after your view. So, if your page is called ‘login.html’, then your JavaScript business file should be entitled ‘login.js’ (any page specific stylesheet should be named ‘login.css’ as well). These pages should be included last and can reference any Objects or Functions from the Framework and Toolkit tiers. All your events should be attached to the DOM here and I often cache frequently used DOM Elements. It is good practice to put all your Business logic inside a namespace Object, such as ‘Login’ so as to not override any variables defined in the other Tiers. For example:

var Login = function() {
var dom = {collection of dom references};
Event.addListener(dom.someElement, someEvent, someFunction);
...
}

In-page tier
This tier should actually go before the Business tier, so that the Business tier can reference Objects passes from the server. You do not need this tier if you do not use any server-side scripting language. Whenever, your server-side scripting language generates the variables, such as JSON Objects, create a script tag just prior to the Business tier reference and set any variables that you need. For examples, suppose on the login page you want to retrieve a username and a JSON object representing the user’s messages in a PHP environment:

<script type='text/javascript'>
var username = "<?= $user->getUsername() ?&gt";
var messages = <?= $user->getMessages()->toJSON() ?>
</script>
<script type='text/javascript' src='login.js'></script>

Now the username and messages variables can be referenced by the Business logic code inside ‘login.js’.

To start this discuss, we must first decide what is a framework vs. a toolkit vs. any other name we might use. These words are often used interchangeably when discussing JavaScript libraries and can be confusing.

Framework: A fundamental structure, as for a written work.

Toolkit: A set of software applications that aid a task.

So for the sake of this blog, we will refer to any library that provides fundamental underlying architecture that will be used across the entire site as a ‘Framework’ and a small set of tools as a ‘Toolkit’, and any collection of code can/will also be referred to as a ‘Library’. Using these guidelines, ‘moo.fx’ would be considered a toolkit, as it is a compact set of tools that may be used to extend the prototype framework, and ‘Google Web Toolkit (GWT)’ will be called a ‘Framework’, as it is a complete architecture (even though it is misnamed). And both would be considered a ‘Library’.

With that out of the way, let’s dive into the meat of todays article, popular JavaScript frameworks and toolkits. There are enough JavaScript libraries to fill volumes of books, so we won’t be able to discuss all of them. This blog will consider the following list: prototype, script.aculo.us, rico, dojo, mochikit, gwt, yui, jquery, and moofx. If you know of another library that is widely used, please leave a comment and I will consider adding it to the discussion.

Today, we begin our library discussion by: looking at what libraries there are, where you can find them, and a little history about each. This will be a growing document and will always be available at the link below:

http://mattsnider.com/?page_id=9

Additionally, I here are some other articles I have written about Frameworks:

More on Frameworks