As of jQuery 1.3.2, adding multiple HTML classes to an element using jQuery’s addClass method will add them one at a time, modifying the className property of an element for each class.

$('#myElement').addClass('myFirstClass mySecondClass');

Here’s the original code inside of jQuery 1.3.2. Note how the classNames string is split, and elem.className is changed for each split entry.

add: function( elem, classNames ) {
    jQuery.each((classNames || "").split(/\s+/), function(i, className){
        if ( elem.nodeType == 1 && !jQuery.className.has( elem.className, className ) )
            elem.className += (elem.className ? " " : "") + className;
        });
    },
// ...

This may cause longer than needed delays, as reflow may occur after every class is added individually. If absolutely necessary, you can always fall back to modifying the className yourself, like so:

$('#myElement').each(function()
{
   this.className += ' myFirstClass mySecondClass';
});

Most likely, this isn’t a tip that will be needed, but it is useful to be aware of.

When developing on the front end, it’s easy to prioritize correctness over performance. Performance is the step child that gets lost while you’re pulling your hair out worrying about cross browser compatibility. It’s very important to regularly benchmark your JavaScript code, using a profiler or some form of benchmarking code paired with a cross browser logging utility (see Firebug Lite, YUI Logger, or log4javascript).

Event delegation is a great way to program for performance. The live jQuery method was a great addition to the jQuery core, it makes event delegation really easy (see also the closest method). Unfortunately, it isn’t quite what I expected.

For example, say you have a page containing approximately 500 custom tooltip components on it (not typical, but stick with me, this is to prove a point). How might one go about adding a simple live event to activate each tooltip when the user hovers over it?

$('span.myTooltip').live('mouseover', function(event) {
    // activate tooltip
});

See the problem? jQuery will actually run the selector on the document, resulting in unnecessary overhead. jQuery is only assigning a single event handler to top level of the document, why does it need to know what nodes it will be binding to before assigning the callback?

What can we do? Let’s create a jQuery function, instead of a method, so it won’t query the document. Try this on for size:

$.live = function(selector, type, fn)
{
    var r = $([]);
    r.selector = selector;
    if(type && fn) {
        r.live(type, fn);
    }
    return r;
};

Usage

// Single event type
$.live('span.myTooltip', 'mouseover', function(event) {
    // activate tooltip
});
 
// Multiple event types (you can call the jQuery live method on the return value from the function)
$.live('span.myTooltip')
    .live('mouseover', function(event) {
        // activate tooltip
    })
    .live('mouseout', function(event) {
        // deactivate tooltip
    });

Also, as a side note, keep in mind that jQuery live doesn’t support space separated events, like bind does.

// Will not work.
$('span.myTooltip').live('mouseover mouseout', function() {});

Have fun!

Download the Source Code

Here’s a use case. An unregistered visitor visits your blog, and decides that your content is so good that it merits a comment! Congratulations, you’ve fooled them! Now you can twply their account details for $1200 on Sitepoint! Just kidding. But generally, when you visit a blog’s commenting section (such as the Tournology Blog shown above), you’ll see a simple form to authenticate you’re not a spammer, generally including (among other things) an e-mail address field.

Well, since they’re typing their e-mail address, wouldn’t it be cool if we could show them their gravatar right there, inline with the blog comment form? Well, that’s now possible with my new JavaScript Gravatar Plugin! It doesn’t have any server side language dependencies.

Hell, gravatar.com could even use this to improve the user experience of registering your e-mail account. Right now it does a full page refresh and doesn’t even show you a preview!

See the Demo

Download the Source Code

Licensing

Licensed under the WTFPL, as highly recommended by Isaac Schleuter (see discussion).

JavaScript Dependencies:

• Requires jQuery (Feel free to port and post a link!)
• Requires md5.js

Example Usage:

Easiest form, onblur of email text input field:

$('#emailTextField').blur(function(event)
{
    $(this).after($.gravatar($(this).val()));
});

Showing all options, again onblur of email text input field.

$('#email').blur(function(event)
{
    $('body').append($.gravatar($(this).val(), {
        // integer size: between 1 and 512, default 80 (in pixels)
        size: 200,
        // maximum rating (in order of raunchiness, least to most): g (default), pg, r, x
        rating: 'pg',
        // url to define a default image (can also be one of: identicon, monsterid, wavatar)
        image: 'identicon'
    }));
});

Super Fast Beginner’s Primer

• Case 1: Node (or un-namespaced node, null-namespaced node): a node without a prefix, such as child here:
  <child/>
• Case 2: Default namespaced node: a node without a prefix, but a parent node (or itself) has a xmlns attribute, like both root and child here:
  <root xmlns="http://example.com/"><child/></root>
• Case 3: Namespaced node: a node with a prefix, and a parent node (or itself) declaring a xmlns with that prefix attached, like both child and root here:
  <prefix:root prefix:xmlns="http://example.com/"><prefix:child/></root>

/End Primer

Parsing XML in the browser can be a tricky beast. There are many different wrong ways to do it, which can leave you cold and naked in a snowstorm if you’re not careful. So, let’s put on the metaphorical electric one-sie of standards based code and let the power of Edison heat our JavaScript code like the innards of a tauntaun.

If there is one thing you can take away from this article, its that the problems with XML in JavaScript have already been solved, and there is library code out there to do the job for you. But libraries aren’t a substitute for knowledge (abstraction is a dangerous thing during education), so let’s learn why these problems are occurring so we can wrinkle our gray matter and increase our productivity at the same time.

Use Cases

These are the main use cases that takes place when selecting a node inside of an XML document:

1. Case 1: Selecting un-namespaced nodes (or nodes in the null namespace):

   <root><child/></root>

   This one is easy. If you can guarantee that your XML will never have any namespaces, you’re home free. Take your get out of jail free card and run for the hills. Using this assumption, you can query nodes inside of your XML Document object using nothing other than getElementsByTagName(). Lucky bastard.

   // assume oDocEl is the documentElement inside of an XML Document 
   var correctForCase1 = oDocEl.getElementsByTagName('child');

2. Case 2: Selecting default namespaced nodes:

   <root xmlns="http://example.com/"><child/></root>

   Tread lightly, this is about to get serious. In most cases, historically I had thought that using the solution described for Case 1 would be sufficient in this case. I had learned awhile back that Internet Explorer treats node names (including namespace prefix and local name together) as one string. So, the method for Case 1 should work for Internet Explorer, especially in the case of node sans prefix. In Firefox, you’d have to use getElementsByTagNS(), but that would be just a simple wrapper.

   Then I met an Internet Explorer exception. The only unique thing about this installation of Internet Explorer 7 was that it had MSXML 6 installed, when all the other computers I had tested on were using MSXML 3. The obvious conclusion here is that MSXML 6 won’t select child nodes for Case 2.

   var incorrectForCase2 = oDocEl.getElementsByTagName('child');

   Here’s the right way to select nodes for Case 2. Fair warning, to keep the code examples here simple, this solution requires Sarissa (sarissa.js and sarissa_ieemu_xpath.js) to be included on the page prior to usage.

   // assume oDoc is an XML Document object.
   oDoc.setProperty("SelectionNamespaces", "xmlns:whatever='http://example.com/'");
   var oDocEl = oDoc.documentElement;
   var correctForCase2A = oDocEl.selectNodes('whatever:child');
   var correctForCase2B = oDocEl.selectSingleNode('whatever:child');

   Note how we’ve mapped what was the default namespace (without a prefix) to be a namespace WITH a prefix during the node selection.

   It should be noted that when the resultant XML has a namespace attached (Case 2 and 3), Firefox works fine using getElementsByTagNameNS. IE doesn’t include support for that method, however, so we’re forced to find a more complete solution.

3. Case 3: Select a non-default namespaced node:

   <root prefix:xmlns="http://example.com/"><prefix:child/></root>

   As I mentioned in Case 2, normally (pre-MSXML 6), you’d be able to perform a getElementsByTagName('prefix:child') in IE and use getElementsByTagNameNS in Firefox as usual. But that has changed now. We need to set up the SelectionNamespaces property for IE, and we’ll use Sarissa to take it cross-browser for us.

   // assume oDoc is an XML Document object.
   oDoc.setProperty("SelectionNamespaces", "xmlns:whatever='http://example.com/'");
   var oDocEl = oDoc.documentElement;
   var correctForCase3A = oDocEl.selectNodes('whatever:child');
   var correctForCase3B = oDocEl.selectSingleNode('whatever:child');
   // Note, this is the same code as Case 2 (which is a good thing)

   Note that we did not have to use the same prefix that was defined by the result XML. We can map it to whatever we want (literally).

Why is this important?

Because most libraries don’t handle Case 2 and Case 3, which are important parts of XML. Here’s some code straight from YUI 2.5.1 (DataSource component):

// Line 1394
var xmlNode = result.getElementsByTagName(key);
if(xmlNode && xmlNode.item(0) && xmlNode.item(0).firstChild) {
    data = xmlNode.item(0).firstChild.nodeValue;
}
else {
       data = "";
}

Notice how they just do getElementsByTagName. For shame :( jQuery doesn’t handle Case 2 or Case 3 either. (Proof is an exercise to the reader :P) So, if you have XML data sources with namespaces, it would do you well to use the solution presented in this article, or you’re going to have headaches later.

Springer’s Final Word

Don’t use getElementsByTagName. If you do, PLEASE include a note saying that your code isn’t going to support namespaced XML. Branch your selection code to check if Sarissa has been included on the page, and use Sarissa for namespaced XML if it’s there. It’s not fun to be pidgin-holed into the simplest case of XML.

Evolution of your engineering skill is also a vital trait in this world, which means that as a developer increases his knowledge of good practices and proper methods, sometimes he must shirk his previous assertions about the world as he previously knew it. And today I’m shirking a staple of the front end as all web users know it: The Grid (DataTable) Component.

Of course, I’ve written a few articles in the past about the YUI DataTable, during my long love affair with Yahoo’s User Interface library. Another popular one is jQuery’s TableSorter. Then there’s the Dojo Grid, a component inherited from TurboAjax. ExtJS has a variety of nice examples as well for their Ext 2.0 Grid.

And after using these Grids and DataTables, I certainly respect the programming that went into developing these components. But let’s take a step back for a second. Why do the users need the bells and whistles in these components? Are they worth the extra load time and complexity they add to the interface?

All we’re doing here is putting a nice coat of paint on a <table> tag. Sure, it might have some nice ancillary features like Ajax Data Loading, but those don’t really matter – they are things that can be easily performed with some good Ajax and DOM insert utility functions. In fact, most of the core features included in these components could be described as feature creep, and not beneficial to the end user at all. Feature creep contributes to code bloat, which means the user is downloading bytes to their web browser that they don’t need, which can hamper performance. Libraries usually have online examples of their components, and the include sizes are seen below. (Gzip compression not considered)

The JavaScript include sizes listed above are directly proportional to the feature set that the components provide, and should give you an idea of the overhead involved with using them. Do we need 545.5 KB of features coming down the pipe to give our users an extra bell, or an extra whistle? Let’s analyze the features to rationalize their usage, and remove items from the feature set.

• Sorting
• Modifying column order and display
• Resizing columns
• Editing of row data directly on the grid itself
• Scrolling
• Pagination

Sorting

Data should be used in the context of its usefulness. You have a list of messages in your e-mail inbox. What’s the most useful context for this list? In order of date received. The default sort order provided by the application, to facilitate proper use of the application. Is comparing the rows in the grid by any other method as useful? Does the user need to see the list of messages ordered alphabetically by subject? In these cases where the user is in need of a specific message, searching and filtering is more useful than sorting. The default sort is useful, but allowing the user to resort on the client, in most cases, is not as useful as other methods of finding a row.

Modifying column order and display

The same argument can be made for any of the other methods of customization provided to the end user. Does the user need to reorder or hide columns? The context provided by the application should be sufficient to use the applications data in the way it was intended. Don’t overcomplicate your user interface with needless features or a deluge of useless data. Provide succinct, appropriate data, and the user needn’t reorder or change the interface.

Resizing columns

The default HTML <table> tag expands to fit the data inside of its cells. Even when you set the width of the table explicitly, the cells adjust themselves accordingly to fit the data. This should be the behavior of your table. You needn’t monkey around with widths, the browser is smart enough to do it for you. You can even customize a cell to wrap its text to multiple lines with CSS, if need be.

Editing of row data directly on the grid itself

If you’re providing an Excel spreadsheet interface for the end user to customize your data, you haven’t designed your interface correctly. Rethink how the user needs to interact with the data you’ve provided, and give them a better, simpler way to edit the data.

Scrolling

Everyone knows that internal scrollbars on a page are evil. I don’t even like scrollbars on textareas, to be honest. Previously, I had worked and reworked the YUI DataTable to handle horizontal scrolling. Looking back on this, it was a mistake. There are better ways to handle lots of data in a table, without the heavy mouse interaction and scanning that scrolling require. Which brings me to my next point.

Pagination

This is the one exception to the feature set cutting board. This is the one feature that’s is a requirement, when the data set has too many records to fit on a single page.

Keep these in mind, and look at the feature set provided by a few sites using tabular data centric interfaces that know a thing or two about interface design:

So, what should we include?

A simple CSS class to style your table is sufficient, with links to paginate the table (properly) and/or a hover for row selection if needed. You’re looking at 10-20 lines of jQuery code, maximum, and a few CSS declarations. In lieu of sorting, of course, you’ll need to program in a mechanism for searching and filtering as well. But really, the difficulty with programming this component is knowing what to leave out.

Update: added Metric and Unit Circle time formats.

I know, some of you are reading this and thinking to yourself — genital herpes is more appealing than yet another online alarm clock. But to that I say, congratulations, that’s one of the new features in ALARMd 2!

Why did I make another online alarm clock? Mostly due to missing features and limitations in the old version, but also because it’s a good exercise in JavaScript programming and User Interface design. Everyone likes to hone their skills, and this is my publicly viewable work desk. But the real reason I went back to rewrite the old version is that I’m hooked on jQuery. I can’t get enough of that sweet, sweet, source code, and couldn’t stand to see my old, crusty, handwritten DOM manipulations polluting web browsers across the world. Users of the Yahoo User Interface Library (what I used for the original version of ALARMd) would do well to consider jQuery a nice plugin to be used alongside YUI. It will clean up your code MAX_INT-fold.

Here are a few new features and addressed limitations in ALARMd 2.

• Easy Alarm Mode: No more fumbling around when you just want one simple easy-to-add alarm.
• Google Calendar Alarm Mode: Customize your alarm schedule to your heart’s content, it will load your alarms straight from a publicly available Google Calendar. There are some great features with this:
  • Load only the first calendar event of every day
  • Day Limiter (Example: Only load calendar events within the next 3 days)
  • Minute Adjuster (Example: Alarm me 90 minutes before work without adding a separate event)
  • Google does a nice job of normalizing dates as well, so you don’t have to worry about calendar time syncing. If it says 8AM on your calendar, it’s going to alarm you at 8AM on your computer’s local time.
• New Clock Formats:
  • Human Readable Clock Format: Think “Half Past Two”, or “Quarter Til Twelve”. This idea is from Laurence Willmott’s Project “It’s about Time”. I took some liberties with his labeling scheme, I hope he doesn’t mind too much.
  • Metric Time Format: Shows the measurement Centi-days in Local Metric Time. Basically, it’s a percentage of much of the day has passed. If it’s 80.000, 80 percent of the day has passed, which coincides with 7:12 PM.
  • Unit Circle Time Format: Displays the time in radians that would be shown if a clock were pasted on top of a unit circle. If it’s 12 o’clock, it will read π/2. After programming this one, it’s starting to seem normal in my brain. Oh, it’s 3π/2? Time to eat dinner. How the hell did it get 2π/3??
• Human Readable Alarm Dates: Think “29 Minutes”, “1 Hour”, “2 Days Ago”.
• Much cleaner interface, using a jQuery accordion to display the options.
• The old ALARMd required an internet connection for all sources, and provided no safeguard if your internet went down whilst you were sleeping. ALARMd 2 preloads all Youtube videos in the background when the page loads using the new Youtube JavaScript API. A nice benefit of this is that the browser window no longer requires focus to play the YouTube video.
• Less clunky interface for adding new alarm sources.
• Repeat option for YouTube videos and MP3′s. Turn infinite loop on or off. Careful with this one. Don’t leave ALARMd going if you’re not going to be home when it goes off.
• CSS Skins, Use the really simple ones I’ve included for Red, Green, or Blue, or include your own URL to your own hosted CSS file. Have a good skin? I’ll include it in the select list and give you some props here, just link to it in the comments below. Use some CSS class hooks to spice up your skins (they are mutually exclusive). These are CSS classes that are added to the body tag to allow you to style the alarm differently depending on the alarm clock’s current state. Future enhancements might include more than just alarm-based hooks: Year, day of the year, and hour of the day might be useful, that way you could style the clock to show a lighter background during the day and a darker background at night.
  • .alarmWithin30Minutes
  • .alarmWithin15Minutes
  • .alarmWithin5Minutes
  • .alarmWithin1Minute
  • .alarmActive (Alarm is being played)
• Still has all the old favorites:
  • Test Button to make sure the video or source is working and to check your volume.
  • Count Down mode to show the time between now and the first alarm.
  • Store your own list of alarm sources, using YouTube, MP3, Last.FM, or any URL (Pandora is included).
  • Military time (24 hour clock) and seconds toggle.
  • Naked mode (get rid of the extras)

Finished reading? I’m surprised you didn’t click the link at the top: ALARMd 2 Beta

Remember, this is BETA. That means it’s new. I’ve done my best to test and code out all the kinks, but there may be a few that slipped through. Try it out and please report any bugs. And once again, this code is released under the BSD license.

I’ll probably move this to the main ALARMd.com domain shortly.

Alarmd has been personally tested with Firefox 2, Firefox 3, Internet Explorer 7, Safari 3.1, and Opera 9.27, all on Windows. Google GDATA reports an unsupported browser error on Safari and Opera, which you can hide using custom CSS.

Required and Optional Arguments

There are generally two styles used when programming a new function in JavaScript. The first, most obvious, and least extensible method is putting each argument as its own argument in the function definition, as so:

// For our purposes, assume arg1 is required, and arg2 and arg3 are optional.
function myFunction(arg1, arg2, arg3) {
   arg2 = arg2 || 'defaultValue';
   arg3 = arg3 || 'defaultValue';
}

One obvious downside to this method is that it requires a line of code for each optional argument to define a default value. What if you want to pass in an arg3, but not an arg2? Your call could end up like: myFunction('myArg1', null, 'myArg3');. This might work in the beginning, but what about when you have more than 3 arguments defined? That’s going to get messier than a Dick Cheney hunting party.

The next method people generally move to when they have a lot of optional arguments in their function definition is to put all the arguments into a single object argument, like the following:

// taken from jQuery
 $.ajax({
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){}
 });

The benefit to this method is that you can populate all the defaults easily by using jQuery.extend, like so:

// simulated code, not from jQuery
$.ajax = function(args)
{
    var defaultArgs = {
        type: 'GET',
        data: '',
        dataType: 'text'
    };
    // overwrites defaultArgs with args values, stores result into args.
    args = jQuery.extend({}, defaultArgs, args);
    if(!args['url']) {
          return;
    }
};

The args object would end up with the following value:

{
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){},
   dataType: 'text'
}

This method can be easily seen as extensible. You could put a metric shit ton of optional arguments in your function (the option is there, I won’t judge you), and you could define them in any order inside of the object without having to put in null spacers like the previous method.

But what about required arguments? The Ajax method above requires a URL, and the script can’t guess a default for that variable. But it isn’t immediately obvious to the end-user that URL is always required. And what’s more, you’ll have to put specific code inside your function to check that the required arguments were sent in the object. (Think if(!args['url']) { return; } as shown two code blocks up.)

Which leads me to my favorite way to define functions: a combination of the two methods. Declare your required arguments as explicit arguments, and pile the rest into an optional arguments object. Here I’ll show you how I would define the Ajax function using this method:

// jQuery doesn't use this argument structure, so don't copy and paste this.
 $.ajax('some.php', {
   type: "POST",
   data: "name=John&location=Boston",
   success: function(msg){}
 });

This way, it is immediately obvious which is a required argument and which is optional, and your required arguments will never be accidentally assigned a default value in your code. If the end-user doesn’t send in all of the required arguments, the resulting error message will be obvious and easily fixed, without a ton of code inside of your function to check that the end-user obeyed the function defintion.

Setting Default Values for Optional Arguments

When developing code, sometimes it is obvious that the method described above for optional arguments may be overkill for a tiny little utility method. Sometimes you just want a boolean flag, or a single optional argument. When that occassion arrives, it’s time to put on your robe and coding hat, because we’re going to town.

In the beginning of JavaScript maturity, my <body> was going through a lot of changes. I was confused about a lot of things, and you’d see a lot of lines of code like this (embarrassingly enough):

function myFunction(runDoSomething)
{
     if(runDoSomething == null) {
          runDoSomething = true; // never make your default true, as I'll show you below
     }
     if(runDoSomething) {
          doSomething();
     }
}

Ugh, checking against null? Janet Reno looked better in the morning. But now that I’m a full grown man that can open his own pickle jars, I’ve got some guidelines:

1. When the argument is optional and might be left out, define it in your code in such a way that if it does have a value, it will not evaluate to boolean false (0, false, undefined, null, ”, NaN). In other words, don’t make the value the user passes in for this argument be false. False is the value it should have when it’s empty. See the example below:

   // runDoSomething is still optional
   function myFunction(runDoSomething)
   {
        if(runDoSomething) {
             doSomething();
        }
   }

   We didn’t have to assign a default value to arg1, because if it’s null, then doSomething() won’t execute. Don’t ever use arg1 in a way that would have you passing in false, because false and null are the same in a boolean comparison.

2. When using non-boolean optional arguments, another way to avoid assigning a default value to an optional argument is to use the OR operator to give you a default value where you’re using it. This is really only useful when you use the argument in one single place inside of your function. If you’re using it more than once, it’s best to define the default value at the top of the function.

   function myFunction(arg1)
   {
        // arg1 is used only once
        jQuery('#myId').html(arg1 || 'myDefaultValue');
   }
   function myFunction(arg1)
   {
        arg1 = arg1 || 'myDefaultValue;
        // arg1 is used multiple times
        jQuery('#myId').html(arg1);
        jQuery('#myOtherId').html(arg1);
   }

Hopefully you’ve learned something from this post. It is the byproduct of many mistakes and overcomplicated functions that I’ve refactored to end up with this result.

Like any well intentioned programmer, you’re writing reusable code in JavaScript. Maybe it’s a simple widget, maybe it’s a higher level plug-in for your favorite JavaScript library. But now you want to provide a mechanism for your friendly neighborhood developer to extend your code by hooking into it with a little bit of code of their own. How do you accomplish this?

Generally, it can be done one of two ways:

• A callback function
• A custom event

A callback function is a function passed into your code as an argument that will be executed at the time the library code specifies. For instance, callback functions are usually supplied for for Ajax XmlHttpRequest’s to execute, one callback if the Ajax Request is successful, and another on failure. See the following code as an example:

End-Developer’s Code:

 $.ajax({
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){
     alert( "Data Saved: " + msg );
   }
 });

Library Code (from jQuery):

// taken out of context, just know that s stands for the options object passed into $.ajax() above.
if ( s.success )
	s.success( data, status );

In the above code example taken straight from the jQuery documentation, the success key of the object being passed into the ajax() function is a callback function. It will be executed after the Ajax request has successfully completed.

The other mechanism you can use for controlling dependent function execution is a custom event. Custom events provide more flexability because they use the publish/subscribe mechanism. That means, instead of the library author deciding how many callbacks he or she is going to allow you to pass into their method as arguments, he or she will just trigger a custom event, which will fire all functions the end-developer has said they want to subscribe to that event. See the following example from the jQuery documentation.

End-Developer’s Code:

$(document).bind("myCustomEvent", function(e, msg){
   alert( "Data Saved: " + msg );
});
$(document).bind("myCustomEvent", function(e, msg){
   alert( "More Data Saved: " + msg );
});
// We can subscribe as many functions as we want to myCustomEvent.

Library Code:

// again, no context here
$(document).trigger("myCustomEvent", [ "My Message" ]);

As you can see above, custom events are much more extensible and customizable to your needs. Want to attach 10 functions to myCustomEvent? Sure, go right ahead. Want to try to attach 10 callbacks to the ajax success method above, that’s going to be a bit more work. The benefit to using callbacks lies in their disposability and isolation. Perhaps you don’t want to publish to the world when your Ajax Request completes — maybe you just want to handle the completion and be done with it.

Let’s Review.

Callback Functions: + Private + Disposable – Limited by Design of Parent Code (Number of callbacks)
Custom Events: +Extensible (Any number of functions attached) – Public – Not Disposable (Functions stay attached after execution, and continue to fire when triggered)

The more I used Dean Landolt’s script, the more problems I began to see with his implementation. It was a good start, but definitely had bugs. His assumptions translating from integer second differences to human readable labels stretched too far at times (there is an error in logic to say anything between 24 hours and 48 hours from now can be labeled “Tomorrow”), and he was a bit loose with his difference categories (assumed average month length was 28 days, and always used Math.floor instead of rounding — 47 hours from now would be labeled “1 Day”). It was great code otherwise, and I definitely liked the way he used the while loop to run through the comparisons.

So, I’ve cleaned up his great start, and am releasing it to the world in the spirit of cooperation and open sauce. You just read that typo out loud didn’t you?

Download: Yet Another Pretty Date Implementation (2 KB)

Update: Dates for this script must have a specific ISO8601 format: YYYY-MM-DDTHH:MM:SSZ (in UTC) where T and Z are literals.

I’ll be honest, using the YAHOO namespace to store my own code makes my bunghole tighten just a little bit. What if I had written code stored under YAHOO.tool, which was unused prior to YUI 2.3.0? What would I do now? I’d have to rewrite my code, or never include any of the wonderful YAHOO.tool.TestCase, put together by Nicholas Zakas. As is traditional with most of my weblog posts, I try not to just complain about a problem without giving you a solution (but let’s be honest, only if it doesn’t take too much work).

Let’s rewrite the YAHOO.namespace function to work outside of the YAHOO Namespace, so we can do things like this:

namespace( 'zachsWorld.partyTime' );
zachsWorld.partyTime = function() {
	alert( 'Excellent.' );
}
zachsWorld.partyTime(); // obviously would alert: Excellent.

Here’s some code:

function namespace() {
    var a=arguments, o=null, i, j, d;
    for (i=0; i<a.length; i=i+1) {
        d=a[i].split(".");
        o=window;
        for (j=0; j<d.length; j=j+1) {
            o[d[j]]=o[d[j]] || {};
            o=o[d[j]];
        }
    }
    return o;
};

Obviously this is just a modification of the YAHOO.namespace function. I’d recommend putting this under your own namespace (I’m trying to put most of the code I write on this website under the Y2 namespace, but everyone should have their own parent namespace), like so (any namespaces you create using this function won’t use the parent namespace assigned here by default):

if (typeof Y2 == "undefined") {
    var Y2 = {};
}
Y2.namespace = function() { /* copy function contents from above. */ };

But you can do whatever you want. This is one of the functions that I think separates YUI from the other frameworks out there, giving an easy utility to organize your code. This is something I think jQuery seriously lacks, noting from the code inside the many jQuery plugins contributed by end users. Many jQuery contributors do not organize their code, putting multiple unnecessary top level functions into jQuery.fn as methods, or into the jQuery object itself as functions. People whine about polluting the global namespace… I suppose it might be considered nitpickey to whine about the jQuery namespace. Okay you whiney bastard, let’s help out and put this into jQuery!

// include jQuery first.
jQuery.namespace = function() {
    var a=arguments, o=null, i, j, d;
    for (i=0; i<a.length; i=i+1) {
        d=a[i].split(".");
        o=window;
        for (j=0; j<d.length; j=j+1) {
            o[d[j]]=o[d[j]] || {};
            o=o[d[j]];
        }
    }
    return o;
};

Please note, this method does NOT work using jQuery methods with an element context, such as jQuery(‘div’).myNamespace.myMethod(). Your element context won’t be carried through to myMethod().

However, you can use it for jQuery functions, such as this:

// definition
jQuery.namespace( 'jQuery.debug' );
jQuery.debug.test1 = function()
{
    alert( 'test1 function' );
};
jQuery.debug.test2 = function()
{
    alert( 'test2 function' );
};
// usage
jQuery.debug.test1();
jQuery.debug.test2();

For more information, you can read Global Domination, an article written by Douglas Crockford, or Best Practices for Writing jQuery plugins.

Updated: fixed some weird source parsing errors introduced by the code formatting plugin.

So, let’s plug one of them into YUI! Let’s get some of that power under the hood. And let’s make it work identically to how we write our code for YUI currently, instead of changing the coding style (a la Dustin Diaz’s great extension to YUI called DED|Chain).

How are we going to do this? Let’s dive into the shallow end of the pool.

The include order of our javascript files is going to be important. So, first we’ll do the YUI library core file (either yahoo-dom-event.js or utilities.js depending on your need for animation). Next, we need to include a CSS Selector DOM Querying class. For this proof of concept, I’ve provided examples for my two favorites, the jQuery engine and Jack Slocum’s DomQuery. These files are released under the MIT license, so make sure that complies with your project. It’s pretty liberal, so you shouldn’t have any problems. If you find these querying libraries useful, please donate to these projects!

For code simplicity, I’ve added a one liner to Jack’s DomQuery to make it work as a standalone file.

if( typeof Ext == 'undefined' ) var Ext = function(){};

If you want to read more about DomQuery, you can go to Jack’s site all about syntax and benchmarks.

Download: Jack Slocum’s DomQuery Standalone File (24 KB) 1.0 Alpha 3 – Rev 4
Download: Jack Slocum’s DomQuery Standalone File Packed (7 KB) 1.0 Alpha 3 – Rev 4

If you want to use jQuery’s selector engine, I’ve stripped out the functions unnecessary to the selector engine in the 1.1.3.1 release and packaged it up as jDomQuery. There are differences between these two package’s syntax, so make sure you keep that in mind, especially when looking at the pseudos, like :gt() and :lt() for example.

Download: jDomQuery Standalone File (23 KB) 1.1.3.1
Download: jDomQuery Standalone File Packed (10 KB) 1.1.3.1

If you want to read about jQuery syntax, go over to their documentation. My current preference is the jQuery syntax, given that it works with poorly implemented JSF ID attributes. But that’s a different argument.

If you want to use the full jQuery library, that should work too, but if you want to do that, you might just want to switch to using jQuery at that point (dare I say it).

Next, we’ll extend the YAHOO.util.Dom class into a new Y2 namespace. This will map all of the functions from YAHOO.util.Dom into a new CSS Selector extension.

Download: Y2.util.Dom (2 KB)

(pack at your own leisure, you can do it online at Dean Edward’s Packer)

Putting It All Together

<html>
	<body>
		<div>
			<div class="first">
				<span></span>
			</div>
			<div class="second">
				<b></b>
			</div>
		</div>
		<script type="text/javascript" src="/Lib/yui/build/yahoo-dom-event/yahoo-dom-event.js"></script>
		<script type="text/javascript" src="jdomquery-1.1.3.1-packer.js"></script>
		<!-- <script type="text/javascript" src="DomQuery-packer.js"> -->
		<script type="text/javascript" src="Dom.js"></script>
		<script type="text/javascript">
		Y2.util.Dom.addClass( 'div div:last', 'myClass' )
		Y2.util.Dom.hasClass( 'div div:last', 'myClass' ); // returns true
		var b = Y2.util.Dom.get( 'div div:last b' );
		Y2.util.Dom.addClass( b, 'myOtherClass' );
		</script>
	</body>
</html>

One important thing to note is that when using the CSS Selector syntax, when only one node is selected, functions will return a scalar instead of an array. So if you’re expecting to select multiple nodes in your selector query and only one node results, make sure your code handling the result is prepared for such an instance.

Have fun!

or maybe the same thing using Facelets:

<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core">
<body>
<f:view>
<form jsfc="h:form" id="myForm">
<input type="text" jsfc="h:inputText" id="myText"/>
</form>
</f:view>
</body>
</html>


These will both output the following result:

<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:ui="http://java.sun.com/jsf/facelets">
<body>
<form id="myForm">
<input type="text" id="myForm:myText"/>
</form>
</body>
</html>


Notice how the resulting text field has an ID attribute with the parent id prepended on. Now the real question is, how do we select this result node using the various JavaScript frameworks that are available to us?

Works, but we don’t care: Raw JavaScript or any GetById Function

Obviously using document.getElementById( 'myForm:myText' ); will function correctly. As will any framework that has a similar “GetById” function (YAHOO.util.Dom.get, or $ in Prototype, etc) What is more interesting to us is the behavior using the various CSS selector packages included with each JavaScript library.

Does not work: DomQuery in Ext 1.1 Beta 2

Ext.query( '#myForm:myText' );
Ext.query( '#myForm\:myText' );

These two tests will throw the error Ext.DomQuery.pseudos[name] is not a function, which obviously means that myText is not a pseudo class like :first or :last.

Ext.query( '#myForm\\:myText' );

Throws the error: Error parsing selector, parsing failed at "\:myText"

Works: jQuery 1.1.3

jQuery( '#myForm\\:myText' );

As of version 1.1.3 (the latest of this writing), they have added support for the colon in ID selection when escaped with a double backslash. Versions older than 1.1.3 will not function properly. This is not yet in the documentation but can be viewed in the Escape selectors section of a blog post.

Does not Work: Prototype 1.5.1.1

$$( '#myForm:myText' );
$$( '#myForm\:myText' );

Returns the form instead of the input element and treats myText as a pseudo class.

$$( '#myForm\\:myText' );

Interprets as XPATH selectors (\\ means anywhere in the document), using myText as a pseudo selector now, so it returns ALL nodes in the document.

Does not Work: Dojo query 0.9.0 Beta

dojo.query( '#myForm:myText' );
dojo.query( '#myForm\:myText' );
dojo.query( '#myForm\\:myText' );

It’s becoming mind numbingly obvious that if the framework doesn’t specifically say that you can escape selectors, it’s not going to let you do so. In the first two tests, Dojo performs the same as Prototype. In the double backslash test however, Dojo returns no result nodes.

Does not Work: Mootools 1.11

$$( '#myForm:myText' );
$$( '#myForm\:myText' );
$$( '#myForm\\:myText' );

All throw the error The expression is not a legal expression." code: "51.

There you have it folks. jQuery is the JavaScript library of choice for the discerning JSF applications developer. Kudos to you if you’re already using it.