Satyam (a.k.a Daniel Barreiro) is a long-time YUI contributor and one of the most prolific, generous experts in the YUI forums. He is also the author of a new book on YUI 2.8.0, YUI 2.8.0: Learning the Library. This article in the “Ask Satyam” series was suggested by JoeDev. While its focus (like the focus of the new book) is mostly on YUI 2, many of the practices described here are applicable to YUI 3 as well — and to frontend development in general, regardless of your library of choice.

Before posting a question in the YUI Library forums, there are plenty of things you can do by yourself and, if you have your tools handy, you may find your answer all by yourself in no time. Besides, clean code is robust code, much less likely to break when subjected to stress. Good practices not only avoid fatal errors (the kind that drive you to the IRC channel or forums in search of help), but they surface warnings about minor errors and help you stay away from the fatal edge.

In this article, I’m going to take a look at some of those best practices. Some of these are specific to developing with YUI, but the vast majority apply to frontend development regardless of your choice of Ajax library.

JSLint

A trip through JSLint is part of the build process for YUI. JSLint, itself fully written in JavaScript, is like a compiler but without code generation. It will, however, produce many of the useful error messages and warnings that a compiler would. A browser’s JavaScript interpreter forgives many errors and assumes defaults you might be unaware of; JSLint forgives little, and it points you to better choices in your program. JSLint is available in many formats; the YUI Builder tool uses it as a standalone command line application, but you can also integrate it into Eclipse or whatever IDE or more-or-less capable editor you use — there is even a Yahoo! Widget for JSLint.

If the zillion lines of code in the YUI library can go through JSLint with no errors and few warnings (it can’t avoid a few things), so should your code. I find JSLint very helpful when I’m tired. Bean counting in the late evening is a waste of time; you are likely to miss the most obvious errors. JSLint doesn’t care what time of the day it is and will point you straight to that mismatched curly bracket or misspelled variable that’s at the root of the problem.

JSLint is most helpful if you keep your code clean from the start. If you’ve never used JSLint before and try it out on an application that is already hundreds of lines long, it will flood you with so many warnings that it will feel that it hampers your job more than it helps. However, that only happens the first few times. Once you learn to stay away from bad coding practices, JSLint diagnostics will be few and straight to the point; your real error, the one that’s driving you nuts, will clearly stand out. In the meantime, JSLint will teach you to make your code safe and robust.

So, don’t wait for a tough error to show up. If you have never used JSLint, try it with what you believe to be good code, it might not be as good as you assumed. As Douglas Crockford (author of JSLint) says, “JSLint will hurt your feelings.” But that’s a small price to pay for better code.

Global and unused variables

One of the things JSLint will warn you about is the use of global variables. There should be no global variables except those you know about, such as the ones created automatically like window or document and those for the libraries you are using such as YAHOO (in YUI 2) or YUI (in YUI 3). You may also want to create a single global for your own namespace.

Global variables are dangerous, and there are usually more of them than you’d expect; moreover, “extras” such as mashups and banners might add more of them. Since the window HTML DOM namespace can be omitted from compound names, window.name, window.length and window.location become the global variables name, length and location. Have you never used such variable names in your code? I don’t mean in their HTML DOM sense but as everyday field names in a table — like the name of a person, the length of an object or the location of a book on the shelf. What if you use those variables without declaring them? You might assume that length is initially undefined but, in fact, if you don’t declare your own local copy of it (and initialize it), length will be a reference to window.length. And if you assign something to location, you might accidentally cause your user to navigate away from the current page. Here, I am just giving examples of possible collisions with the browser’s built-in variables, but if you start adding libraries from other sources, the chance for collisions increases. The JavaScript syntax highlighter used in YUI’s examples uses the global variable dp as its root and the number of global variables any Google script might add when you insert a map or other tool in your page is impolite, to say the least.

It’s not merely that you want to step lightly with respect to other people’s variables — by staying out of the global namespace, you reduce the risk that they will step on yours (or that you’ll step on your own). With asynchronous threads weaving themselves around each other, as is often the case in modern JavaScript applications, you can’t really be sure the order in which your various pieces of code will execute and what global variable will be left at what value by whom. The only sane approach is to avoid them whenever possible.

Global variables might also point to a typo. If you have a global variable you didn’t mean to have and you have an unused variable with a similar name, you might have misspelled one of them: that is, you may have declared it with one name and used it with another different spelling. It can also mean that you have declared it after you have used it, which means that at execution time you might find your variable not initialized as you would have expected.

Using this

Using this is often troublesome for beginners because it’s easy to lose track of where we are in the scope chain. Until we get some practice, keeping track of scope can be an issue. Also, developing a coding style and a structure for the application helps greatly; after all, it’s all about knowing where you place things. If you learn to organize your code consistently and store state in logical places (this points to one such place), information in your program will be easy find. Any debugger will show you what this points to at each step. It’s always a good thing to check first if this is referencing the object you expect. A lot of times when we have a bug, it’s be because this is pointing to window. There are several situations that can produce this result.

If we have a method with an inner function, when we call that inner function it won’t get the scope of the caller but rather that of window. This example shows that the inner function doesn’t share the scope of the method within which it is contained:

var someObject = {
    outerFunction: function () {
        console.log(‘outer’,this); // prints outer Object {}
        var innerFunction = function () {
            console.log(‘inner’,this);// prints inner Window
        };
        innerFunction();
    }
};
someObject.outerFunction();

There are a couple of ways to fix this. In this example, we ask JavaScript to correct the scope using call():

var someObject = {
    outerFunction: function () {
        console.log(‘outer’,this); // prints outer Object {}
        var innerFunction = function () {
            console.log(‘inner’,this); // prints inner Object {}
        };
        innerFunction.call(this);
    }
};
someObject.outerFunction();

In the next example, we take advantage of the ability for inner functions to share the variables of containing functions. We create a variable self which we initialize to the value of this in the outer function. We can then use self in the inner function to refer to the outer function:

var someObject = {
    outerFunction: function () {
        console.log(‘outer’,this); // prints outer Object {}
        var self = this;
        var innerFunction = function () {
            console.log(‘inner’,self); // prints inner Object {}
        };
        innerFunction();
    }
};
someObject.outerFunction();   

Finally, with events, the scope of the listener is that of the element to which the listener is attached:

var someObject = {
    outerFunction: function () {
        console.log(‘outer’,this); // prints outer Object {}
        YAHOO.util.Event.on(‘button’,'click’,function () {
            console.log(‘inner’,this); // prints inner <button id="button">
        });
    }
};
someObject.outerFunction();

Unless we adjust the scope of the listener when setting it up

var someObject = {
    outerFunction: function () {
        console.log(‘outer’,this); // prints outer Object {}
        YAHOO.util.Event.on(‘button’,'click’,function () {
            console.log(‘inner’,this); // prints inner Object {}
        },this,true);
    }
};
someObject.outerFunction();

This also applies to YUI components. If we listen to a click event on a DataTable cell, a TreeView node or a MenuItem, the scope of the listeners will be those of the YUI component instance that owns the event — unless it is explicitly set otherwise.

Sandboxes for applications

Another good way to keep your code clean is to start with a clean skeleton. The style of coding JavaScript applications has changed over time. Nowadays, most developers use two different styles: one for applications and one for library components. Most YUI 2 examples reflect the old style, where we used YAHOO.namespace to create a namespace for our own code.

Nowadays, for our applications, we mostly use a single sandbox declared within the scope of an anonymous function that executes onDOMReady:

YAHOO.util.Event.onDOMReady(function() {
    var Dom = YAHOO.util.Dom,
        Event = YAHOO.util.Event,
        Lang = YAHOO.lang;

    var yourVariable = initialValue,
        moreOfTheSame = otherInitialValue;

    var myFunction1 = function ( …) {
        // body of function;
    };
    var myFunction2 = function (… ) {
        // body of function;
    };
    …
});

This technique has several benefits.

1. We check for the readiness of the DOM right from the start, ensuring that all the pieces of HTML that we might want to manipulate are present and safe to use.
2. The function provided to onDOMReady is not wasted at all; it’s the container of the sandbox and, because it’s anonymous, it does not pollute the global namespace.
3. We immediately start defining our variables, including aliases or short names for our most often-used objects. This has several other advantages of its own:
   1. We save some typing
   2. The YUI Compressor can compress our short names, whereas it cannot compress a global name like YAHOO or its properties such as util or Menu no matter how deep they might be. If they are anchored in a global name such as YAHOO, the whole branch is untouchable. Thus our already short names Dom, Event and Lang might be further reduced to A, B and C when Compressor is run at build time.
   3. The interpreter does not need to resolve over and over again the long names. Each dot in a name such as YAHOO.util.Event.onDOMReady is time consumed in a symbol table look up.
   4. All variables will be available anywhere inside this anonymous function, even to functions defined within, unless a variable of the same name was defined in them. Basically, it is as if a sub-global environment has been defined within, and all variables there will be available anywhere just by name.
   5. For the variables in the sandbox we don’t need to use this, which gives us such headaches when using traditional OOP technique of making even the main function an object.

4. We define our functions. We can do this with the var statement, as I did above or the function statement; there is a subtle difference but it is mostly irrelevant. I use the var statement to highlight that they are just as accessible as the other variables: we can access them anywhere in the sandbox.

Of course this relies on the ability of JavaScript to allow us to define functions within functions and on the fact that the inner functions have access to all the variables defined in the outer function. Basically, each function you define creates a new local environment accessible to any further functions within.

Sandboxing is the standard way of doing things in YUI 3:

YUI().use(‘module1′, … , function (Y) {
    // This is the sandbox
});

Namespaces for libraries

While the sandboxing technique is great for final applications, it’s not good for libraries. What happens in the sandbox stays in the sandbox, completely invisible to the outside world. However, when you define a library utility or component of your own, you want to re-use it, so it needs to be globally accessible (which is not the same as being purely global). Anything you define under YAHOO.example — e.g., YAHOO.example.myUtility — is globally accessible. You can access it by its full name once it has been defined. myUtility, as a member of the global YAHOO, is not global but it is globally accessible.

When we build libraries, we usually use the sandbox for our code and namespacing for sharing, like this:

(function () {
    var MyClass = function () {
        // this would be the constructor
    };
    MyClass.prototype = {
        // properties and methods
    };
    YAHOO.namespace('MyLibrary');
    YAHOO.MyLibrary.MyClass = MyClass
})();

We create a sandbox by defining everything within an anonymous function, which we immediately execute (see all those parenthesis there?, they mean 'take the result of defining this function and execute it'). Here, we don't wait for the DOM to be ready; libraries seldom do, since the application that uses them is responsible to check that everything is in place. Within the sandbox, we have the same advantages as with the previous sandbox. We can define short names for anything we use often, even for the class we are defining: none of them will be visible outside. Then, to make it globally accessible, we create a namespace of our own and place our recently created class in it.

YUI Logger

Let's say we have our code nice and clean, with no JSLint errors or warnings, but we still have problems to debug. YUI can be helpful in telling us what's wrong. For production code, we will usually load the minified versions of the YUI components, but there are also two other versions. The -debug.js version is the one that can help us uncover problems. For example, we might be using Dom Collection's method setStyle to, lets say, change the color of a block of text. The change doesn't happen and we can't find what's wrong. The file dom-debug.js has this helpful line, which is deleted in the -min version:

YAHOO.log('element ' + el + ' is undefined', 'error', 'Dom');

This is executed when setStyle tries to locate the element to be styled and does not find it. The error message will probably show a misspelled element id or some such error that is so hard to pick after a long day of staring at the same code.

It's easy to get the logger up and running; you just need to include its files:

<link type="text/css" rel="stylesheet" href="http://yui.yahooapis.com/2.8.1/build/logger/assets/skins/sam/logger.css">
<script src="http://yui.yahooapis.com/2.8.1/build/yahoo-dom-event/yahoo-dom-event.js"></script>
<script src="http://yui.yahooapis.com/2.8.1/build/dragdrop/dragdrop-min.js"></script>
<script src="http://yui.yahooapis.com/2.8.1/build/logger/logger-min.js"></script>

The basic yahoo-dom-event aggregate is most likely to be there already while the Drag & Drop optional dependency is handy to move the logger window out of the way. Then, just add:

var myLogReader = new YAHOO.widget.LogReader();

Then, it's a matter of loading the -debug versions of the component files and all the messages they produce will be shown. The amount of information can be overwhelming so, it is wise not to load all -debug versions at once. The Logger can also filter the information it displays and you may uncheck the Info category of messages to concentrate on Warn and Fail. The filters do not affect what is logged, only what is shown; Logger logs all messages, regardless of whether the LogReader displays them or not. There is only one message queue per application and logging will start as soon as the Logger component file is loaded, it doesn't matter whether it is shown or not.

Another power-user strategy for YUI debugging with the Logger Control is to take advantage of Logger's ability to leverage the browser's console (in supported browsers):

YAHOO.widget.Logger.enableBrowserConsole();

With this line of code, you can pipe all Logger messages to the browser console, which is a natural part of your workflow in development in any case.

The only tedious thing about the Logger is remembering to change the component files from the minified, aggregates and combos to the -debug versions. In this, as always, the Dependency Configurator is a great help; click on the -debug button on the top left and it will produce the correct list of files.

And, now that I've mentioned it:

Check your dependencies

It's a good idea when you start with YUI to pick an example that closely resembles what you want to do and modify it. As you add more features, you take bits and pieces from other examples and incorporate them into your developing application. One frequent source of problems are the dependencies. Many people paste the dependency files of each and every example into their application, duplicating some of them over and over again. Missing, duplicate or out of order dependencies might produce unexpected errors. Not having the YAHOO Global Object loaded before anything else is most certainly going to be fatal. At any rate, loading something twice will certainly increase the time it takes your page to load.

Finally, if you are using your own servers to load the YUI library, you might have the base path for your copy of the library wrong. If you have Firebug, go to the Net tab and check that there are no lines in red. Those would mean that a requested resource could not be found.

Debugging

The Firebug add-on for Firefox is still the best debugger around, plus it is free. By default, when the debugger is activated the "Break on all errors" option is on, which means that Firebug will stop at the point where it finds an error and show the error message and source code. Some of those errors will be the same that JSLint would have diagnosed, so JSLint is still the first place to start — especially because Firebug can only signal one error on each run while JSLint can signal them all at once. Some errors will only show up at runtime, so the debugger is the only option. Whenever you get to such a break, the first thing to check is this, a four-letter word of the trickiest sort.

When using a sandbox, debuggers will usually show local variables and arguments, but they will not normally offer to show the variables in containing functions, such as those declared in the sandbox and used from within the inner functions. The debugger will be able to show their value if you explicitly ask for them by name, but it will not show them automatically. Another alternative is to make them globally accessible. For example, since YAHOO.example is always available (when YUI 2 is on the page), if you want to keep an eye on a certain component at all times you can simply copy it there:

var myTree = new YAHOO.widget.TreeView('tree-container');
YAHOO.example.myTree = myTree;

We add the last assignment while debugging so we can keep an eye on the TreeView instance while debugging since myTree would normally be within the sandbox and invisible elsewhere.

Don't use members starting with underscore

Many people use the debugger to look for the names of variables or properties holding the information they need. Sometimes that information is stored in properties starting with an underscore, like _nodes. By convention, those are private properties, not for general use. JavaScript enforces no true concept of private or protected members; thus the leading underscore is the conventional way to signal the intent of the class developer to keep that property private. These properties can present a temptation (after all, you can see them there in the debugger), but there are a couple of good reasons why it is not wise to use them in your programs.

First, only public interfaces are supported. Since you are not supposed to use a property starting with an underscore, the class developer is free to change it at any time. The developer should have provided some public mechanism to access this same value; for example, a _nodes private property might have a getNodes() method or a nodes configuration attribute. Either of these would be the public interface to that same value. The second reason not to use properties with leading underscores is that their accessors might need to produce a secondary effect which accessing the private property would completely bypass. The component would then be left in an inconsistent, fragile state.

So, if you are using the debugger to look for a value and you find it in a property starting with a leading underscore, don't use it. Go instead to the API docs and look in the Methods index for some getXxxx() method with a similar name or in the Configuration Attributes index. Avoid using private variables.

Stack Traces

The YUI library is robust and reliable. If the debugger breaks within the YUI library, it's more likely that it is because of an error induced by your code that by some failure in YUI itself. JavaScript was designed to carry on, always coping with errors as best as possible. The YUI library does likewise. The -debug versions will have extra checks and will emit diagnostic messages, but they are all stripped out in the minified versions. If you see an error in a YUI file it is likely that it got there out of pure stubbornness, but don't try to find the error there. When the debugger stops it is not because it has found the cause of the error but because the JavaScript interpreter can no longer carry on.

Breaks in minified files are not helpful, if you get a message such as...

F is not an object in line 7 of dom-min.js

...it is pointless to ask in the forum about it. First of all, F is an alias generated by YUI Compressor to replace a longer, descriptive variable name in the original uncompressed file; secondly, the first few lines of a component file are usually taken by the copyright notice, which the YUI Compressor always respects. And since the YUI Compressor also deletes all new-line characters, as it does with other white space, all the executable code in dom-min.js is in lines 7, 8 and 9 — so the line number doesn't say much either.

That is when the Stack Trace tab in the right sub-panel of the Script tab of Firebug (or wherever you can find the stack trace in your debugger) comes handy. It tells you how you got there. Here is a screen capture from Firebug:

The item on top of the right panel, createEvent(), is the name of the function where the current statement is; the one below is the place where createEvent() was called; the one below that the function that called the previous one; and so on. Most debuggers will let you select any of those trace points and see how you got to where you are. Firebug also lets you check the value of the variables at each of the trace points. We can see in the left subpanel the yellow arrow pointing to createEvent(). We got lucky this time, as it will always point to the line containing the offending code, but that code might be anywhere within that line; fortunately, createEvent()happens to be at the beginning of the line. See the variables and arguments? B, G, L...there is no guessing what the original names could have been, as this is the YUI Compressor at work. However, note that YAHOO is untouched and the copyright notices are preserved.

You might not recognize many of the names in the stack trace, as they might be functions within functions within the YUI library itself. Eventually, you might see function names you recognize. In this image, I know showAlbums, which calls the constructor for the REDT class (which is code I wrote). I don't have a clue about anything else. That's where I will go looking...to the ones I know.

If you are not sure, you can go through the full list. If you see compressed code (assuming you have not compressed your own yet), simply ignore it, or switch to the non-minified version of the YUI source files. But focus primarily on those names you recognize that belong to your own code. Note that Firebug uses (?)() for traces it cannot name. Usually, your code in the sandbox will be signaled that way since the sandbox is contained in an anonymous function. At any such point in your trace, check the values of the variables you provided as arguments; some of them might not be what you assumed. Check them against the API docs to see if it is a valid argument value.

If the argument and variable values you see are inconclusive, at least you can place a breakpoint right before your code calls the YUI component. You might then be able to see how you got into the mess.

Stack traces are often ignored by developers but with JavaScript's tendency to keep digging itself into an ever deeper hole as it tries to carry on, it is good to be able to come up to the surface to look around. As with all debugging techniques, it might not always work, but it is nice to know it is there. Let's be honest, if you have read this far, you know what desperation is.

Asynchronous calls

A lot of the interactivity that characterizes Web2.0 apps is based on the ability to handle asynchronous events. In contrast with the original style of web applications, where every interaction involved waiting for a new page to be delivered from the server, the modern interactive applications involve setting things up and listening for any of several possible events to happen...and then responding to those events. We set listeners for clicks or keystrokes and or other programmatic events; these are usually intuitive. Asynchronous calls and their callbacks, however, often are harder to understand.

The most common error I see in implementations on the forums is to place code right after an asynchronous call such as Connection Manager's asyncRequest()or DataSource's sendRequest() methods, assuming that such code will be executed when the operation is completed. When you call such a function, you are just priming the operation, not executing it in full. No data will be available after the call to the async method. Only the request for such data would have been produced so far. The server must receive it and process it, and the reply (if it ever comes) is still off in the future. That is why for such asynchronous operations we use callback functions.

A callback is like the function we assign as a listener for an event such as a click on a button in a form; when the user clicks, the listener gets called. The callback on a asynchronous event is very much like this; just as we send a form for a user to fill in, we send a request message to the server, and just as we wait for the filled-in form to be submitted back to our program, we wait for the reply sent by the server to come back to us. We cannot know when the user will submit the form or the server send the reply; that's why we set what for a user action we call an event listener and for an asynchronous event we call a callback function. It might seem the server reply is fast if not instantaneous, but it means ages in CPU time.

Debugging asynchronous calls

Sometimes there is no alternative but to single-step through the code. Be careful when you get to asynchronous calls such as Connection Manager's asyncRequest() method, DataSource's sendRequest() or DOM's window.setTimeout(). These start an asynchronous request for data against the server or delay some action a given time and their callbacks get called when the data has been received or the time has elapsed. There are two issues to consider; first, the debugger won't step into the callback automatically. If you want to catch up with the reply, you have to put a breakpoint inside the callback function. Lots of people reach the point of calling the asynchronous method and expect the single-stepping to resume within the callback when the async operation is finished. This will not happen; the thread of execution does not flow automatically into the callback, and the debugger cannot be expected to figure that one out.

Second, when you reach the line with the asynchronous call, put the breakpoint in the callback and then let the application run. Usually, whatever goes after the async call is not really important; in fact, the async call is normally at the end of a function, since there isn't much to do until the reply arrives. Don't single-step over the async call, because the debugger will keep the JavaScript interpreter on hold and, when the reply arrives or the time lapses, it will be missed since the interpreter was frozen and unable to handle it. So, if you were clicking on Step Over, when you get to the async call, make sure you have the breakpoint in the callback and then click Run so the JavaScript interpreter is active and able to handle the reply.

For repetitive events such as callbacks to window.setInterval() or other time-critical operations, it is better not to put breakpoints in them. While you are on hold, many events will be missed. It is usually better to use console.log or the YUI Logger to simply signal that the event is happening and show a few critical values. Don't use window.alert() for the same reason; it puts a hold on the browser and the events you care about will be missed.

Conclusion

There are many tools to help us find out what is happening in our programs. With the proper tools at hand, we can find an error in less time than what it takes us to write a question in the forums. The first step, however, is to write good and reliable code and make JSLint an integral part of your development process.

Douglas Crockford’s latest installment in the “Crockford on JavaScript” series, a talk in which he covers the role of event loops and the importance of server-side JavaScript, is now available on video. Flash video is embedded below, or you can download the HD video (480p ~370MB). Video from the first five lectures is available on the Crockford on JavaScript page.

• Download HD video (480p ~370MB)
• Download video (m4v)
• Download slides

Other Recent YUI Theater Videos:

• Nicholas Zakas and Victor Tsaran: Accessibility on the Yahoo Homepage — Nicholas Zakas, a principal developer of the Yahoo! homepage, and Victor Tsaran’s, Yahoo!’s senior accessibility manager, discuss the strategies and methods that made one of the most visited websites in the world fully accessible. The talk took place at the June 2010 BayJax meetup at Yahoo.
• Dennis Lembree: Making JavaScript Accessible — Dennis Lembree, an accessibility expert and the creator of AccessibleTwitter discusses the challenges of making JS-enabled sites accessible. The talk took place at the June 2010 BayJax meetup at Yahoo.
• Ryan Dahl: Introduction to NodeJS — Ryan Dahl, the creator of NodeJS, introduces the project and talks about performance improvements and new architecture. The talk took place at the May 2010 BayJax meetup at Yahoo.
• Elijah Insua: jsdom: a CommonJS Implementation of the DOM — Elijah Insua introduces a server-side implementation of the JavaScript DOM at the May 2010 BayJax meetup at Yahoo.
• Nicholas Zakas, Stoyan Stefanov, Ross Harmes, Julien Lecomte, Matt Sweeney: High Performance JavaScript — Five contributors to O’Reilly’s High Performance JavaScript discuss advanced JavaScript and DOM scripting optimizations at the April 2010 BayJax meetup at Yahoo.

Subscribing to YUI Theater:

• YUI Theater RSS feed
• YUI Theater on iTunes

Testing JavaScript is an important but often overlooked part of web development. One reason is because developing for the web means targeting more than one browser. YUI currently classifies 11 different environments that enjoy our highest support level. In addition, we also test YUI on emerging X-grade environments like mobile devices. When you have so many different environments to support, it’s tempting to just pick a couple important ones to develop with locally and hope for the best.

At YUI, we use Selenium and Hudson for running YUI Test-based unit tests on various browser and operating system configurations as part of our continuous integration strategy. This is great for catching problems that result from integrating your work with the rest of a complex software stack. It comes with a price: CI tools like these are complicated to setup and maintain. In any case, they don’t help you while you’re developing code and testing before you commit.

Today, I’m excited to release Yeti 0.1.0, an experimental command-line tool designed to make cross-browser testing easier before you commit a line of code.

Yeti automatically launches JavaScript unit tests in a browser and reports the results without leaving your terminal. It’s very simple to use: Just run yeti test.html to get the results of the YUI Test-based test in test.html. You can pass multiple HTML documents to test multiple components at once.

$ yeti dom/tests/dom.html attribute/tests/attribute.html json/tests/json.html
✔  DOM Tests from Safari (Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16)
  20 passed
  0 failed

✔  Y.JSON (JavaScript implementation) from Safari (Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16)
  68 passed
  0 failed

✔  Attribute Unit Tests from Safari (Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_4; en-us) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16)
  106 passed
  0 failed

194 tests passed! (3217ms)

The real power of Yeti is running tests in multiple browsers simultaneously. Although Yeti can open your tests one-by-one on your computer, Yeti allows you to run tests on any browser on any device—all at the same time.

If you run Yeti without arguments, it will start a web server that you can access at http://localhost:8000. You can then point browsers or devices on your network to that URL and every test you run from that point will be executed on all browsers visiting the test page.

When combined with the excellent localtunnel, firewalls between you and other computers are less painful. If you’re not working with sensitive information, it’s a simple way to make your Yeti available to the internet:

$ localtunnel 8000
   Port 8000 is now publicly accessible from http://example.localtunnel.com

You can then visit that URL to access Yeti and start running tests:

This is especially useful for cellular devices: You can use your carrier’s internet connection without needing to get your device on the same network as your development computer.

Yeti aims to make JavaScript testing easier; however, it’s far from being complete. (Don’t take the 0.1.0 version number lightly.) Yeti assumes you’re using YUI Test, has only been tested on Mac OS X, and may not work with some kinds of testing scenarios. Despite these shortcomings, Yeti has been so useful internally that we didn’t want to wait any longer to share it with the YUI community.

Getting the code

Yeti is available on GitHub and offered under YUI’s BSD license.

Installing

Yeti is written entirely in JavaScript and runs on top of NodeJS. If you’re already a NodeJS and npm user, installing is very simple:

$ npm install yeti@stable

If you haven’t installed NodeJS and npm and you’re on a recent Mac, you can still install Yeti with a convenient installer.

Download the Yeti 0.1.0 Installer 2.7 MB Requires Mac OS X 10.6 and a Intel Core 2 processor or better

If your computer doesn’t meet the installer’s requirements, you can still use Yeti if you’re able to install npm. More installation and usage instructions are available in Yeti’s README.

Your participation is welcome

Yeti is the first project we’ve launched in YUI Labs, an umbrella category where our new ideas and initiatives will take shape. As such, Yeti is offered without the same level of support as our other projects. We still encourage you to ask questions and give feedback in Yeti’s forums and hope Yeti makes testing easy and fun. If it doesn’t, please tell us, file a bug or consider contributing to Yeti.

Happy testing!

About the Author: Reid Burke (@reid) is the newest member of the YUI team. He loves abominable snow monsters and JavaScript.

In a hurry? Skip to the demo page.

Many ecommerce sites, social networking services, and online communities include rating or assessment features. Soliciting people’s opinion has even become a business model; there are now sites dedicated to rating products, services, businesses, and more.

The most common interface used to display votes is the “star rating system,” in which a particular number of points (often expressed as stars) is assigned to an item by each reviewer. We find this model on many sites, from Amazon to Yelp.

Figure A. Star rating examples from Amazon and Yelp.

As Figure A shows, both visual interfaces are similar, but what makes these two solutions interesting is their markup base. One relies on <map>, the other on <img>.

You might think that most rating systems would be based on some markup proven to be semantic and "operational" across many User Agents — that is, that rating systems would be based on a specific set of HTML elements and attributes to which one applies behavior and style via JS and CSS. That would make sense, but it is far from the truth. When it comes to markup, authors try just about everything:

• <a>,
• <img>,
• <span>,
• <li>,
• <map>,
• <div>,
• <input>,
• and more…

The case of Microformats

Before presenting a few image-based techniques to mark up ratings, I think it is worth mentioning a basic and straightforward approach (from Microformats) that uses characters:

<abbr class="rating" title="3 stars">***</abbr>

Pros

It is straightforward and semantic.

The markup is minimal.

The method is not reliant on CSS.

The method is not reliant on images.

There is no HTTP request.

Cons

It is impossible to represent half values (i.e. 3.5 stars)

It "works" only with asterisks ("star rating").

Screen-readers, by default, do not expand abbreviations (which may not be a big deal in this case).

Note: I use "*" rather than ★ (★) because screen-readers (at least JAWS and NVDA) seem to ignore html entities.

Markup to display image-based ratings

When it comes to display images, authors have many options.

One image per rating

Using a single image:

<img src="4stars.png" alt="4 out of five">

One star

Two stars

Three stars

Four stars

Five stars

Pros

Using one image per rating is straightforward and semantic.

The method is not reliant on CSS.

Minimal markup.

Cons

It creates many HTTP requests as there are many different images.

On top of the performance issue, it can be a maintenance nightmare as authors have to deal with more assets (images to create, to push to a CDN, to modify when site colors change, etc.).

Text selection is not possible in Opera (at least in version 9.52) as the alternate text is ignored

One image per unit

From the whatwg’s working draft:

<img alt="4 out of 5" src="one-star.png">
<img alt="" src="one-star.png">
<img alt="" src="one-star.png">
<img alt="" src="one-star.png">
<img alt="" src="no-star.png">

One star

Two stars

Three stars

Four stars

Five stars

Pros

Using two img elements per rating diminishes the number of HTTP requests.

The method is not reliant on CSS.

Cons

In Opera, when images are disabled, alternate text is not selectable, and (in small-screen view) that text is rendered with a border which makes it less legible.

Note that this is taken from a controversial working draft. In my opinion, this method is not acceptable because the alternate text does not describe the image accurately and succinctly. Besides, if the basis of this approach is that these images represent content, then why leave some of them with no alt text?

On Ajaxian, for example, the author is using alternate text with every single image, which makes a lot of sense if he considers that each one is content:

<img [snip] alt="+" src="star1.png"/>
<img [snip] alt="+" src="star1.png"/>
<img [snip] alt="+" src="star1.png"/>
<img [snip] alt="-" src="star0.png"/>
<img [snip] alt="-" src="star0.png"/>

In any case, using as many images as there are stars versus using a single element (an img or something else) has the main advantage of facilitating voting mechanisms – where a user selects one of the stars to cast his vote. So we should keep this in mind…

A sprite for background images

The following technique is a adaptation of a strategy originally implemented by developers at Yahoo! Music:

Markup

<span class="rating r1 stars">1 of 5</span>
<span class="rating r2 stars">2 of 5</span>
<span class="rating r3 stars">3 of 5</span>
<span class="rating r4 stars">4 of 5</span>
<span class="rating r5 stars">5 of 5</span>

CSS

.stars {
  background: transparent url(img/sprite.png) no-repeat;
}
.rating {
  font-size: 0;
  height: 19px;
  overflow: hidden;
  vertical-align: middle;
  width: 96px;
  display: block;
}
.r1 { background-position: -385px 0; }
.r2 { background-position: -288px 0; }
.r3 { background-position: -192px 0; }
.r4 { background-position: -96px 0; }

One star

1 of 5

Two stars

2 of 5

Three stars

3 of 5

Four stars

4 of 5

Five stars

5 of 5

Pros

This method requires a single HTTP request as it relies on a single sprite image.

Minimal "foot print".

Cons

Content is not revealed with images off.

Nothing shows when the page is printed (a print stylesheet could take care of this issue).

In Opera, the high contrast stylesheet makes all the stars disappear; the same is true in High Contrast Mode Optimization.

Text selection is possible, but it’s not obvious (via highlighting).

A sprite in the markup

This approach is based on the TIP method, which uses a sprite image as an <img> element rather than a background image:

Markup

<span title="1 of 5" class="rating r1"><img width="0" height="1" src="sprite.gif" alt=""/>1 out of 5</span>
<span title="2 of 5" class="rating r2"><img width="0" height="1" src="sprite.gif" alt=""/>2 out of 5</span>
<span title="3 of 5" class="rating r3"><img width="0" height="1" src="sprite.gif" alt=""/>3 out of 5</span>
<span title="4 of 5" class="rating r4"><img width="0" height="1" src="sprite.gif" alt=""/>4 out of 5</span>
<span title="5 of 5" class="rating r5"><img width="0" height="1" src="sprite.gif" alt=""/>5 out of 5</span>

CSS

.rating {
  position: relative;
  height: 1.6em;
  width: 8.1em;
  overflow: hidden;
  vertical-align: middle;
  display: block;
}
.rating img {
  position: absolute;
  width: 40.5em;
  height: 1.55em;
  top: 0;
  border: 1px solid #fff;
}
.r1 img { right: 0; }
.r2 img { left: -24.4em; }
.r3 img { left: -16.2em; }
.r4 img { left: -8.1em; }

One star

1 out of 5

Two stars

2 out of 5

Three stars

3 out of 5

Four stars

4 out of 5

Five stars

5 out of 5

Pros

This method requires a single HTTP request.

This technique is the only one of the four methods above that reveals content when Firefox users select "hide images" or "make images invisible" (from the developer’s toolbar).

When images are unavailable a red "x" appears only in the highest rating (i.e. 5 out of 5) instead of in each one as it is the case with other solutions that rely on img elements.

Cons

The display of images is reliant on CSS.

It is worth noting that unlike other Image Replacement techniques, this method allows:

• images to scale depending on text-size settings.
• images to be printed.
• alternate text to be easily selected as the whole image appears highlighted (Firefox).
• the image to not disappear in a high-contrast setting/stylesheet.
• alternate text selection in Opera (when images are disabled).
• borderless alternate text in Opera’s small screen view.

Markup to cast votes

Starting with a native mechanism

To cast votes, we need a low-level voting mechanism that allows simple user selection and submission. For this, we can rely on using a form with labels and controls:

Markup

<fieldset>
  <legend>Rating</legend>
  <label><input type="radio" name="movie" value="1_5">1/5</label>
  <label><input type="radio" name="movie" value="2_5">2/5</label>
  <label><input type="radio" name="movie" value="3_5">3/5</label>
  <label><input type="radio" name="movie" value="4_5">4/5</label>
  <label><input type="radio" name="movie" value="5_5">5/5</label>
</fieldset>

Result

Adding breaks and whitespace

For better legibility, we add <br> and whitespace.

Markup

<fieldset>  <legend>Rating</legend>
  <label><input type="radio" name="movie" value="1_5"> 1/5</label><br>
  <label><input type="radio" name="movie" value="2_5"> 2/5</label><br>
  <label><input type="radio" name="movie" value="3_5"> 3/5</label><br>
  <label><input type="radio" name="movie" value="4_5"> 4/5</label><br>
  <label><input type="radio" name="movie" value="5_5"> 5/5</label>
</fieldset>

Result

Introducing the sprite image in the markup

For this solution, we are using a smaller sprite than the one in the example above. It is now composed of two single stars (“on” and “off”).

We place img elements inside the labels. We assume they will have no value without CSS support, thus we "hide" them by setting specific dimensions via their width and height attributes. Note that using 0 with both attributes would show a broken image in some UAs.

<form ...>
  <fieldset>
    <legend>Rating</legend>
    <label class="one" title="1 out of 5"><input name="LandOf" value="1" checked="checked" type="radio"> 1/5<img src="star-sprite.gif" alt="" height="0" width="0"></label>
    <label class="two" title="2 out of 5"><input name="LandOf" value="2" type="radio"> 2/5<img src="star-sprite.gif" alt="" height="0" width="0"></label>
    <label class="three" title="3 out of 5"><input name="LandOf" value="3" type="radio"> 3/5<img src="star-sprite.gif" alt="" height="0" width="0"></label>
    <label class="four" title="4 out of 5"><input name="LandOf" value="4" type="radio"> 4/5<img src="star-sprite.gif" alt="" height="0" width="0"></label>
    <label class="five" title="5 out of 5"><input name="LandOf" value="5" type="radio"> 5/5<img src="star-sprite.gif" alt="" height="0" width="0"></label>
  </fieldset>
</form>

Note that with the above markup, we can expect (in most browsers) field selection via label selection.

Considering Accessibility

Unfortunately, as is, this markup creates issues in at least two screen-readers: JAWS and NVDA (see test case for these bugs). The problem is related to the use of a title attribute and an empty string for alternate text.

The workaround to not confuse screen-reader users is to use "stars" as alternate text (alt) and use JavaScript to insert title on mouseover.

Better Markup

<fieldset>  <legend>Rating</legend>
  <label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="1_5"> 1/5</label><br>
  <label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="2_5"> 2/5</label><br>
  <label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="3_5"> 3/5</label><br>
  <label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="4_5"> 4/5</label><br>
  <label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="5_5"> 5/5</label>
</fieldset> 

Result

Styling

Giving dimensions to the image via CSS

We use em to allow the image to grow or shrink depending on font-size.

Markup

Unchanged

CSS

img {
  width:2.8em;
  height:1.4em;
}

Result

As you can see already, clicking on an image selects the corresponding radio button. There is no need for scripting as implicit labeling produces this behavior (except in IE).

Removing the image from the flow

Styling the label with position:relative and the image with position:absolute with top/left values is enough to hide input and text inside the labels.

Markup

Unchanged

CSS

label {
  position:relative;
}
img {
  width:2.8em;
  height:1.4em;
  position:absolute;
  top:0;
  left:0;
}

Result

Displaying one star per label

We style the label so its dimensions match the height and width of a single star.

Markup

Unchanged

CSS

label {
  position:relative;
  height:1.4em;
  width:1.4em;
  overflow:hidden;
  display:block;
}
img {
  width:2.8em;
  height:1.4em;
  position:absolute;
  top:0;
  left:0;
}

Result

Displaying the stars horizontally

We remove the brs and we float the labels.

Markup

Unchanged

CSS

br {
  display:none;
}
label {
  position:relative;
  height:1.4em;
  width:1.4em;
  overflow:hidden;
  display:block;
  float:left;
}
img {
  width:2.8em;
  height:1.4em;
  position:absolute;
  top:0;
  left:0;
}

Result

Displaying the sprite image depending on rating

To set a "3 out of 5" rating, we apply the same class to the last two labels. This class will shift the position of the image inside the label.

Markup

<fieldset>
<legend>Rating</legend>
<label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="1_5"> 1/5</label><br>
<label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="2_5"> 2/5</label><br>
<label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="3_5"> 3/5</label><br>
<label class="no_star"><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="4_5"> 4/5</label><br>
<label class="no_star"><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="5_5"> 5/5</label>
</fieldset>

CSS

br {
  display:none;
}
label {
  position:relative;
  height:1.4em;
  width:1.4em;
  overflow:hidden;
  float:left;
}
img {
  width:2.8em;
  height:1.4em;
  position:absolute;
  top:0;
  left:0;
}
.no_star img {
  left:-1.4em;
}

Result

Not relying on image alone to display information

It’s important to offer an alternative to the display of stars in case images are not available. This is because labels and radio buttons are styled to be on top of each other. A simple solution is to move input and text off-screen (i.e. using text-indent:-999em) and apply a background color to the labels.

Markup

No change

CSS

br {
  display:none;
}
label {
  position:relative;
  height:1.4em;
  width:1.4em;
  overflow:hidden;
  float:left;
  background:teal;
  margin-right:1px;
  text-indent:-999em;
}
img {
  width:2.8em;
  height:1.4em;
  position:absolute;
  top:0;
  left:0;
}
.no_star {
  background:#ccc;
}
.no_star img {
  left:-1.4em;
}

Note:

• text-indent also fixes a upwards jump of the image each time the controls get focus.
• the right margin is to make sure background colors create squares and not rectangles (which would happen with adjacent labels sharing the same background color).

Result

Finishing touch

• We use the pseudo-class :hover to create some rollover effect,
• We hide the fieldset border,
• We hide the legend,
• We style the cursor.

Markup

Unchanged

CSS

br {
  display:none;
}
label {
  position:relative;
  height:1.4em;
  width:1.4em;
  overflow:hidden;
  float:left;
  background:teal;
  margin-right:1px;
  text-indent:-999em;
}
input {
  position:absolute;
  left:-999em;
  top:.5em;
}
img {
  width:2.8em;
  height:1.4em;
  position:absolute;
  top:0;
  left:0;
  cursor: pointer;
}
.no_star {
  background:#ccc;
}
.no_star img {
  left:-1.4em;
}
label:hover {
  opacity:.5;
  filter:alpha(opacity=50);
}
fieldset {
  border:0;
}
legend {
  text-indent:-999em;
}

Note: label:hover is ignored by IE6 and in Opera the background color bleeds through the images. In the demo page, instead of using opacity, I am using a different sprite that shows four states.

Result

Displaying the ratings without allowing user interaction

We can make the ratings "read-only" by adding disabled and checked attributes in the appropriate input fields.

Markup

<fieldset>
  <legend>Rating</legend>
  <label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="1_5" disabled> 1/5</label><br>
  <label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="2_5" disabled> 2/5</label><br>
  <label><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="3_5" checked="checked"> 3/5</label><br>
  <label class="no_star"><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="4_5" disabled> 4/5</label><br>
  <label class="no_star"><img src="img/small-sprite.gif"  width="0" height="1" alt="stars"><input type="radio" name="movie" value="5_5" disabled> 5/5</label>
</fieldset> 

CSS

The rule using :hover has been removed

h4>Result

Giving more thought to the process

At this point, it is possible to cast votes without script support, but sighted users have no clue about their selection. So we use JavaScript to:

• give feedback to the user regarding his selection,
• give keyboard users a visual clue while they navigate through the radio buttons.

At the same time, we take advantage of using a script to insert title attributes that will create "tooltips" when users hover over the labels/stars.

Because of the lack of feedback regarding selection without JavaScript, we style labels and form controls only if there is script support. To do so we use JavaScript to set a flag on the html element and then we create a rule based on descendant selectors containing that hook. If the flag is missing, that rule does not apply and elements are not styled.

This is the demo page, the final product. To see how this solution behaves according to various settings, you may want to use your favorite developer tools to increase text-size, break image paths, disable JavaScript, turn CSS off, and more…

Wrap up

Coming up with a "acceptable" solution requires to identify users’ needs, User Agents’ peculiarities, User Agents’ settings and more – which means extensive testing.

In this process, users’ feedback is essential because following best practices is not always a sure thing. For example, as mentioned earlier, setting no value for the alt attribute of the images within the labels seem to be the safe thing to do, but it turns out that it creates issues with at least two screenreaders (see test case).

Also, feedback from assistive devices’ users allows to ignore some validation error messages – as the one that the Firefox Accessibility Toolbar reports (according to http://bestpractices.cita.uiuc.edu/html/nav/form/).

The goal here was not to fix everything, though. Being able to cast votes without a pointing device was one of my priorities, but improving the look and feel of the solution in Opera when images are disabled is not something I consider essential.

The most interesting part of this "journey" was to make the solution accessible to many users under various conditions, addressing issues such as:

• images off,
• javascript off,
• CSS off,
• a combination of the above.

It is also nice to know that this technique relies on img elements rather than background images, which allows the stars to:

• resize themselves according to the user’s settings,
• show in high contrast mode,
• be printed by default (unlike background images).

All of this comes without sacrificing performance, as this solution relies on this single sprite:

Late finding

I recently discovered the system Amazon has built for its voting page. It is quite interesting as they serve a different solution depending on script support. If there is script support, they use an image <map> (interesting approach), if there is no script support they use radio buttons. In both cases, the solution is accessible to keyboard users, and this helps to maximize access to a feature that is a core differentiator for the Amazon platform.

Note that they do not use JavaScript to replace the radio buttons with a image <map>; instead, they use noscript elements in which table markup contains radio buttons.

"Out of the box" solutions

Dreamweaver^®

Spry Rating Widget

YUI

Star Rating Script for YUI

Star Rating script with YUI

JQuery

Half-Star Rating Plugin

jQuery Ajax Rater

Simple Star Rating System

5 star rating system in PHP, MySQL and jQuery

Wordpress

GD Star Rating System for WordPress

GD Star Rating

Star Rating for Reviews

Flash

5 Star rating system component

Misc.

How a star rating should be

Starry widget 2

Special thanks

Special thanks to Victor Tsaran and Todd Kloots for their valuable feedback.

XDR in YUI’s IO utility implements a Flash transport as a fallback for browsers that don’t support native XDR. An error in our implementation of the Flash fallback in YUI versions 3.1.x and 3.2.0pr1 allows the io.swf file to operate unsafely whether served from the Yahoo! CDN or from your own server. The remedy for this problem is twofold:

• If you have deployed the full YUI 3.1.x/3.2.0pr1 build directory to your server, replace build/io/io.swf in the affected version with the version included in YUI 3.1.2. Do so whether or not you are using the IO utility or its XDR feature.
• If you are using IO’s XDR feature, upgrading to the 3.1.2 version of io-swf addresses the security problem. Host version 3.1.2 of io.swf on your own server (this file cannot operate safely from a CDN; it is not included on the CDN as of 3.1.2). If you have been drawing io.swf from http://yui.yahooapis.com, remove this domain from your crossdomain.xml file.

More details about this issue can be found in the IO utility documentation.

(Click the screenshot to play with this example.)

Overview

To enter Quick Edit mode, call startQuickEdit(). To exit Quick Edit mode, call cancelQuickEdit().

It is your responsibility to save the changes before calling cancelQuickEdit(). To simplify this task, QuickEditDataTable provides getQuickEditChanges(). This returns an array of objects, one for each row. Each object contains only the values that were changed in that row, keyed off the column id’s. For example, if the table has 4 columns (title, author, year, quantity), and the user only changed the quantity in one row to 20, then the object for that row would be {quantity:20}. The other values would be omitted.

QuickEditDataTable can easily extend YAHOO.widget.ScrollingDataTable if you need that functionality. If you need this, simply make a copy of the source file and change the base class.

Configuration

Quick Edit is a modal state in which the cell formatters for editable columns are swapped out and replaced with special formatters that generate input, textarea, or select elements. Only columns that have quickEdit configuration will be editable. The configuration options are:

copyDown

If true, the top cell in the column will have a button to copy the value down to the rest of the rows.

formatter

The cell formatter which will render an appropriate form field: <input type=”text”>, <textarea>, or <select>. By default, the cell formatter YAHOO.widget.QuickEditDataTable.textQuickEditFormatter is used for all cells to produce input elements. To get a textarea element, configure a column to use YAHOO.widget.QuickEditDataTable.textareaQuickEditFormatter instead. You can also write a custom quick edit formatter — see below.

validation

Validation configuration for every field in the column.

css

CSS classes encoding basic validation rules:

yiv-required

Value must not be empty.

yiv-length:[x,y]

String must be at least x characters and at most y characters. At least one of x and y must be specified.

yiv-integer:[x,y]

The integer value must be at least x and at most y. x and y are both optional.

yiv-decimal:[x,y]

The decimal value must be at least x and at most y. Exponents are not allowed. x and y are both optional.

fn

A function that will be called with the DataTable as its scope and the cell’s form element as the argument. Return true if the value is valid. Otherwise, call this.displayQuickEditMessage(...) to display an error and then return false.

msg

A map of types to messages that will be displayed when a basic or regex validation rule fails. The valid types are: required, min_length, max_length, integer, decimal, and regex. There is no default for type regex, so you must specify a message if you configure a regex validation. The default error messages for the other types are stored in YAHOO.widget.QuickEditDataTable.Strings and can be overridden and/or localized.

regex

Regular expression that the value must satisfy in order to be considered valid.

Sometimes, a non-editable column must be rendered differently during Quick Edit mode. The best example is a column containing a link, since navigating away from the page while in Quick Edit mode can be disastrous. To remove the link during Quick Edit, configure qeFormatter for the column to be YAHOO.widget.QuickEditDataTable.readonlyLinkQuickEditFormatter. For email addresses, use YAHOO.widget.QuickEditDataTable.readonlyEmailQuickEditFormatter. You can also write you own custom, read-only formatter. Simply follow the normal rules for constructing a DataTable cell formatter.

Custom Quick Edit Formatters

To write a custom cell formatter for QuickEdit mode, you must structure the function as follows:

function myQuickEditFormatter(el, oRecord, oColumn, oData) {
  var markup =
    '<input type="text" class="{yiv} yui-quick-edit yui-quick-edit-key:{key}"/>' +
    YAHOO.widget.QuickEditDataTable.MARKUP_QE_ERROR_DISPLAY;
    el.innerHTML = lang.substitute(markup, {
      key: oColumn.key,
      yiv: oColumn.quickEdit.validation ? (oColumn.quickEdit.validation.css || '') : ''
    });
    el.firstChild.value = extractMyEditableValue(oData);
    YAHOO.widget.QuickEditDataTable.copyDownFormatter.apply(this, arguments);
};

You can use textarea or select instead of input, but you can only create a single field.

extractMyEditableValue() does not have to be a separate function nor must it be limited to using only oData. The work should normally be done inline in the formatter function, but the name of the sample function makes the point clear.

About the author: John Lindal (@jafl5272 on Twitter) is one of the lead engineers constructing the foundation on which Yahoo! APT is built. Previously, he worked on the Yahoo! Publisher Network.

DuckDuckGo is a search engine that uses YUI extensively. Here’s what it uses in particular:

• ImageLoader. Matt Mlinac’s YUI 2 ImageLoader was the first thing I implemented and what originally hooked me on YUI for this project. DuckDuckGo has favicons next to results and often has “Zero-click Info” above results that usually includes an image. I didn’t want these images to compete with the results when loading, as getting results as fast as possible is the ultimate goal.

  The ImageLoader Utility handles this well by loading the images after the page load. DDG also auto-loads the next page of results when you scroll down. Sometimes the favicons icons are therefore hidden, and with ImageLoader their load is delayed (sometimes indefinitely) until necessary. To accomplish this, there is a different image group per (internal) page, each with its own custom trigger.

  div.event=new YAHOO.util.CustomEvent('it');
      var ig1=new YAHOO.util.ImageLoader.group(div,'click');
      ig1.addCustomTrigger(div.event);
      div.ig = ig1;
  

• Cookie. DuckDuckGo has a lot of settings, which are stored via cookies and alternately via URL params. When cookies are used, I use Nicholas Zakas’s YUI 2 Cookie Utility to easily get and set the values.

    YAHOO.util.Cookie.set(cookie, value, { expires: new Date("January 12, 2025") });
    x=ki||YAHOO.util.Cookie.get("i");

• StyleSheet. Some DDG settings change the look and feel of the site. These changes are actually accomplished after page load via Luke Smith’s YUI 2 StyleSheet Utility. Some of these changes are straightforward and I can just use the setStyle Dom function.

  YAHOO.util.Dom.setStyle('b2','display','block');

  Others require actual class changes, which I use the utility to do.

  YAHOO.util.StyleSheet('DDG').set('.ci', {display: "block"}).
              set('.cid', {display: "block"}).
              set('.ci2', {display: "block"}).
              enable();

• Dom. I also use some functions in Matt Sweeney’s base YUI 2 Dom component. I referenced setStyle above, and I also use the related getStyle, addClass and removeClass functions. In addition, I find the getViewportHeight, getViewportWidth, getX and getY functions to be incredibly useful to make things work cross-browser, and now on mobile screens as well.

• KeyListener. DDG has a bunch of keyboard shortcuts that let you navigate results without the mouse. I use the YUI 2 KeyListener component to enable these shortcuts.

  kl14 = new YAHOO.util.KeyListener(document, { keys:[70] }, { fn:not } );kl14.enable();

• AutoComplete. I’m currently working on adding search suggestions to the search engine, and will be using Jenny Donnelly’s YUI 2 AutoComplete component for the front-end. I understand that AutoComplete is getting introduced in YUI 3 soon. Everything else I use has already been introduced in YUI 3, though I still use YUI 2. However, I will be exploring the migration to YUI 3 soon.

About the author: Gabriel Weinberg is the founder of the DuckDuckGo search engine, based out of Valley Forge, PA. Gabriel has been a startup founder for over ten years, and his last company was sold in 2006. Gabriel holds degrees from MIT in Physics and the Technology and Policy Program.

Fast and fun – that was the user requirement for the new Assembla.com Agile Planner – an AJAX interface for adding development tasks, building story/feature outlines, and scheduling them into releases. We were lucky to have YUI 3 to make it fast and fun to implement as well.

I had used YUI 2 for a number of prior projects and I had been impressed by the engineering of the UI components and the underlying library infrastructure. I wanted to learn more about YUI 3, with its compact syntax and deeper focus on DOM manipulation and CSS3-style selectors. This project, with a low dependence on ‘prebuilt widgets,’ was a perfect opportunity to get my feet wet with YUI 3. The facilities for ‘large app’ implementation via custom modules and integration with YUI loader made it a natural choice.

The Agile Planner supports a number of drag and drop user interactions with multiple interaction groups and context based behaviors. At the same time, it handles a complex set of interactions with the server, including merging in new data from the server, and propagating changes to the server.

We improved on the existing Planner which was based on Rails handlers and Prototype.js. YUI’s sandbox philosophy and strong OOP facilities made coexisting with Prototype.js a breeze.

We used a large number of YUI components, including:

• Async-Queue to offer a responsive experience on a page that can involve 1000+ simultaneous tickets
• Drag and Drop with interaction groups.
• IO as a connection manager to queue and massage server interaction.
• Event-delegate to allow simply hydrating html templates and forgetting about them.
• Event-key for keyboard interaction and navigation.
• Collection for giving us a consistent implementation experience across browsers.
• Cookie for easy short-term UI persistence.
• Profiler to find the biggest speed gains
• YUI Doc to leave information for the rest of the team

Working with YUI 3 on an app like this has been fun, and I am looking forward to hearing what our users will urge us to do next!

About the author: Joachim Larsen is a frontend engineer with Assembla.com.

Satyam (a.k.a Daniel Barreiro) is a long-time YUI contributor and one of the most prolific, generous experts in the YUI forums. He is also the author of a new book on YUI 2.8.0, YUI 2.8.0: Learning the Library. This article in the “Ask Satyam” series was suggested by Alberto Santini and Bryan Kane. Satyam will be answering several additional questions in the coming weeks here on YUIBlog as part of the series.

It’s a common problem in information architecture: You have tabular data, and you have the need to display additional information about the entity represented by each table row. Usually, this is accomplished by “expanding” the row on click or selection and showing the data directly below the chosen row. Sometimes this additional data comes in the way of a further DataTable which might also have its rows expandable into more nested levels. We call the basic use case of drilling down into a single row row expansion; when the use case involves further tabular data associated with each row, the feature is described as a nested DataTable.

So far there have been several serious attempts to support these features with the YUI 2 DataTable. DataTable’s own list of examples includes a Row Expansion example by Eric Gelinas. John Lindal presented his Treeble in a YUI Blog article some time ago with a version for YUI 3 in the Gallery. I also tried with my NestedDataTable project.

None of these solutions is completely satisfactory and the question tends to recur; in fact, two people asked for it as part of the Ask Satyam series. In this article, I’ll dive in again and explore strategies and options for dealing with row expansion and nested DataTables.

A few issues to consider

DataTable makes a couple of very basic assumptions. One is that the ordinal position of a Record corresponds to the same ordinal position of a row within the <tbody> of the markup. I count 17 occurrences of property sectionRowIndex which returns the ordinal number of a <tr> element within its section (that is, within the <tbody>, <thead> or <tfoot> where it is contained). There are also many occurrences where the ordinal position of the Record is used as an index into the array of rows. For example, in the Row Expansion example, let it run to the end, expand any row about half-way to the table and then execute the following two statements in the debugging console:

YAHOO.example.Basic.oDT.getTrEl(YAHOO.example.Basic.oDT.getRecord(17)).id

YAHOO.example.Basic.oDT.getNextTrEl(YAHOO.example.Basic.oDT.getRecord(17)).id 

Both will show yui-rec17 as the answer, which is not correct since the second statement should return the id of the next row. If you do the same with no rows expanded or using a low number, before the expanded row, the second statement will correctly return yui-rec18.

Obviously, all examples listed work in their basic form; the “bug” demonstrated above amounts to a trick. If your application stays within safe boundaries, you are fine. However, a feature added to your application at a later time, one that makes deeper assumptions about how the DataTable’s internals are operating, may lead to some problems. (For what it’s worth, DataTable is very robust. Its built-in functionality is pretty safe, it sorts columns, edits cells, selects and highlights fine, as far as I tested it. I wasn’t able to break its most popular built-in features.)

Nesting structures within the DataTable also invites some other complications: Clicking somewhere in an expanded custom row might be troublesome, since the click on the nested element would bubble up to the containing DataTable where it can mess things up. You must remember this point when listening to events such as cellClickEvent on the parent table since the target cell reported might not belong to the parent table but to a nested one — so fetching the Record or Column for that cell may fail.

Finally, there are some conceptual issues. What does getNextTrEl mean? Does it include only DataTable’s own rows (let’s call them data rows), or should it include custom rows added later, as it does now? I would say it should only include data rows since the custom rows, being nested, are not siblings to the data rows but children and, though the HTML markup forces us to use plain <TR> elements, conceptually, they are not siblings. Then, if you somehow reach a <TR> element and ask for its corresponding Record in the containing DataTable using method getRecord(), if that <TR> is a custom row, what would be its corresponding Record: null (since it doesn’t belong to the containing DataTable but to the nested one) or the Record of the data row it is a child of?

How do you want the stripes on the rows? Currently, the striping logic takes even and odd rows indiscriminately, whether data rows or custom rows but perhaps you would like the custom rows to carry on the same background color as the data row to which they belong.

These are some of the aspects of row-expansion functionality that require definition; any decision on them, as long as it is consistent and predictable, would likely accommodate most use cases.

Nesting without DataTable

Of course, we might live with these restrictions, but then what is the point of bothering with the DataTable at all? If all you want is to display some nested information in a tabular form, you could simply use a regular <table> element or something like it. In fact, the YUI 3 version of Treeble (example) does exactly that; since there is not yet a YUI 3 version of DataTable to be used, it uses none at all. You might as well do the very same thing with YUI 2, like in this example, where no DataTable nor HTML <table> was used at all. Admittedly, the example is very simple and visually ugly (I’ve never claimed to be artistic); but, if that is all you care for, at least you know it won’t fail you. Just an idea you might want to evaluate when you decide on what to do.

Row Expansion with DataTable

Finally, you might really want to use a DataTable. If so, how do we go about that? Both Treeble and my own NestedDataTable nest two DataTables. Eric Gelinas, in contrast, has used another approach, which I find more flexible. He does not make any assumptions on what is going to be in the expansion. It uses a rowExpansionTemplate configuration attribute that can take either a string template or a reference to a function. The string template is processed via YAHOO.lang.substitute along with the data from the Record object for the row about to be expanded. We already know that we don’t need to define in the column definitions array all the fields we have read with the DataSource; we can keep extra DataSource fields in reserve for later use. The template mechanism lets us display in the expansion row those other fields for which we didn’t have space in the regular row. The example lists picture names from Flickr, images which might be too big to show in the main DataTable. The fields to assemble the URL pointing to those pictures are loaded from the start. Upon row expansion, those bits are put together to built an <img> tag and the thumbnail for the picture is shown in the expansion row.

Now, if we set rowExpansionTemplate to a function reference, then we get all the flexibility we might possibly want. I used that idea in this example, but with a somewhat different rowexpansion.js file. The original was more focused on using the string template and it assumed that the expansion row could be destroyed and rebuilt at any time at no cost. That is not the case when the expansion is something more complex, such as a DataTable with further DataTables nested within. Every time a column is sorted, DataTable will delete all rows and start anew, which would be tremendously expensive with complex content if it was to be deleted and reconstructed as well. Instead, what I do is to keep a reference to the expansion row in the expansion state object (see description in method getExpansionState), which is stored in the Record of the parent table. This data is not deleted, and as a result it’s much more efficient to restore that same row whenever the parent row is re-rendered.

Sometimes, however, the parent rows will be deleted on purpose or the parent DataTable reloaded from the server with, possibly, different data which requires the children to be refreshed. I need to explicitly delete the child rows in such cases because otherwise they would remain in memory as zombies. Thus, I override several methods (deleteRow, deleteRows, initializeTable, destroy) and delete the nested content before its parent Record is deleted. Deleting, however, is not enough, since the content might need some more elaborate means of disposal. As with many complex components, DataTable has a destroy method which needs to be called to fully clear the instance and its associated events. I added the rowExpansionDestroyEvent event to signal that the nested row is about to be destroyed, thus allowing the developer to handle the content as required. For example:

albumDT.on(‘rowExpansionDestroyEvent’, function (state) {

    state[NESTED_DT].destroy();

});

All events receive the state object as their single argument. Here, I use the reference to the nested DataTable which I stored under a property name of my own (NESTED_DT) and call its destroy method.

RowExpansionDataTable adds the column that triggers row expansion automatically and also listens to clicks on that column. You don’t need to do anything for that column to show up and be active. It always adds it on the left hand side by using this simple code in the constructor:

var REDT = function(elContainer,aColumnDefs,oDataSource,oConfigs) {

     aColumnDefs.unshift({

          key:ROW_EXPANSION,

          label:”,

          className:CLASS_TRIGGER

     });

     REDT.superclass.constructor.call(this, elContainer,aColumnDefs,oDataSource,oConfigs);

};
YAHOO.widget.RowExpansionDataTable = REDT;

RowExpansionDataTable also sets a listener for cellClickEvent and checks if the column clicked is the one with its key set to the value stored in constant ROW_EXPANSION; there is no need for us to respond to that event, although we may want to set up further listeners for our own purposes on other columns.

Though the basis of my rowexpansion.js file is Eric Gelinas’s work, there are also many differences. I changed many of the variable, method and property names to conform to the standard naming conventions and fixed plenty of errors flagged by JSLint. In its basics, however, the code is still Eric’s.

The example is well commented and described after the sample table; the rowexpansion.js file is easy to follow and its API Docs are also available.

Overlaying children

Another alternative to adding rows is to make the expansion float above the parent row. I have used this in my own NestedDataTable example. This example also uses YQL tables via YQLDataSource and, as I mentioned in the previous article, the YQL Artists search table is somewhat clumsy to use along with YUI 2 AutoComplete as it won’t bring back partial matches with artist names.

Here, when you expand a row, a container <div> is created and appended to the document body. The container uses absolute positioning and is moved to overlap the row right below the one being expanded. The container thus covers the rows next to the one being expanded so, the height of this row is increased to make space for the overlapping container.

This mechanism spares us from the two issues I mentioned before: no row is added to the DataTable, the ordinal positions of Records and Rows match at all times and events can’t bubble from the containers to the DataTable since they are not descendants of the DataTable. However, maintaining the position of the containers requires paying attention to several events and recalculating their position. Sorting the main table with several children open will move all the containers to their new positions with ease, and so will resizing the browser window.

This example uses just two levels of nesting while the RowExpansionDataTable example could be expanded to any limit. I have tried to combine the two and I see no theoretical reason why it would not succeed; however, in trying to do so I found the example got so complex that it was hard to describe in a blog article of any reasonable size. The example, as it is, has complete control over the parent and child tables, knows when they expand or contract, move, get redrawn or change in any other way, and can easily access any of them and adjust their layout. In trying to extend this to any number of levels, I found that communicating all those changes up and down the hierarchy of nested components, not all of them necessarily DataTables, was hard, with changes deep in one branch possibly affecting nested components on other branches.

The complexity lies not so much in communicating those changes up and down and acting on them as in trying to provide standard interfaces for generic child elements to participate. If you have full control over the several containers and their content, it should be manageable; however, it would only make sense to do so if the RowExpansionDataTable fails in some particular application, as I admit it may, and cannot be fixed easily.

Conclusion

You don’t always need real DataTables to have tables nested inside each other, but if you do, my RowExpansionDataTable is a good choice, besides being a good example on how to extend DataTable. It has some issues, which I described so that if you bump into them, you know where to look as you work around them. DataTable itself is amazingly robust and handles itself quite nicely. Overlapping content in the DataTable is also a possible solution, if signaling the changes in size and position of the children can be solved efficiently, though it is hard to do in a generic component — and I didn’t try to do so here. Neither did I try a version inheriting from ScrollingDataTable; it is not that I forgot, but rather that I know it is not a trivial undertaking.

In June, Yahoo! hosted a BayJax meetup dedicated to web accessibility. Nicholas Zakas, Yahoo! homepage developer, and Victor Tsaran, Yahoo! senior accessibility program manager, gave a talk on the process of making Yahoo!’s homepage highly accessible.

We apologize for the uneven audio levels: there were technical issues with the microphones that we unfortunately were only able to adjust towards the second half of the talk.

If the video embed below doesn’t show up correctly in your RSS reader of choice, be sure to click through to watch the high-resolution version of the video on YUI Theater.

• Download HD video (480p ~1.4GB)
• Download video (m4v)

Other Recent YUI Theater Videos:

• Dennis Lembree: Making JavaScript Accessible — Dennis Lembree, an accessibility expert and the creator of AccessibleTwitter discusses the challenges of making JS-enabled sites accessible. The talk took place at the June 2010 BayJax meetup at Yahoo.

]]> http://www.yuiblog.com/blog/2010/08/16/video-zakas-tsaran/feed/ 4 http://www.yuiblog.com/blog/2010/08/16/video-zakas-tsaran/