Widgets the YUI Way

Why are there so many lightbox implementations? Why are there numerous “versions” of widgets? Do you know which fork is the latest and greatest? Probably not, and for good reason. The current system sucks.

Over the past few days I’ve been studying the YUI library and it’s accompanying ecosystem. It’s truly a well oiled machine. But besides being developed by a web giant, what makes it tick? There are numerous things I’ve come to conclude, and it shines a light on why widget efforts by Prototype developers et al have largely failed.

The public face

• Documentation: This is the most obvious one, but the one we get wrong 90% of the time. If you’ve written a widget, you have intimate knowledge of it’s inner workings and how to use it, knowledge your audience doesn’t have. We make the assumption that consumers will understand our products on the same level we do. This isn’t the case. Even YUI beta code has full documentation and a host of examples.
• Centralization: If you want a YUI calendar control, where is the first place you look? On the YUI site. If you search Google for YUI, you get the official YUI calendar and also a collection of blog post showing some cool tricks and general usage of the official control. If you want to learn how to use the YUI Calendar control, where is the first place you look? The YUI site. It’s all organized and centralized.
• Standardization: Everything is standardized. Everything from how articles are written and structured to the release cycles and code conventions. Take a look at the Drag and Drop landing page and then the Dom Collection landing page. Notice the clear and concise explanation of whatthe component is. Also note the bullet points for quickly navigating a page, the “Getting Started” headers, the cheat sheets and the examples—It’s extremely helpful. Don’t forget about YUI Theatre either.

The code

• Modularity: The code is extremely well structured. It’s not all or nothing. I’ve not been a fan of deep namespacing (e.g. YAHOO.widget.Menu), but in this context I think it’s important. It not only has utility, it creates a visual hierarchy with only small overhead. I definitely prefer common utilities such as $('foo) and baked in enumerations (augmenting native prototypes), but I’m fine with doing var menu = new YAHOO.widget.Menu("mymenu");.
• Event Driven: This one was enlightening for me. Most of YUI’s widgets rely heavily on custom events to pass messages internally and externally. Notice how all of the “interesting moments”, both private and public are handled through events setup in a Menu’s initialization routine. None of them are directly invoked by another method.
• Inline documentation: I debated whether this was important enough to warrant a bullet point (it was encompassed with the public api docs), but as I continued to study the code the inline API comments were indispensable. Whenever I wondered what an argument meant, I could see it documented a few lines above where I was scanning the code. Check out this snippet from YUI’s CustomEvent object.

    /**
     * Notifies the subscribers.  The callback functions will be executed
     * from the scope specified when the event was created, and with the 
     * following parameters:
     *   <ul>
     *   <li>The type of event</li>
     *   <li>All of the arguments fire() was executed with as an array</li>
     *   <li>The custom object (if any) that was passed into the subscribe() 
     *       method</li>
     *   </ul>
     * @method fire 
     * @param {Object*} arguments an arbitrary set of parameters to pass to 
     *                            the handler.
     * @return {boolean} false if one of the subscribers returned false, 
     *                   true otherwise
     */
    fire: function() {
     //...
   }
   //...

Notice the method signature for fire. At first glance it looks like it doesn’t take any arguments, but take a look at the signature in the documentation. Pretty nifty trick. Notice this line in the comments: @param {Object*} arguments. The * tells JsDoc Toolkit to treat the following word as an argument for the method. JsDoc Toolkit can do some really cool stuff and has made vast improvements since it’s inception as JSDoc. It also now speaks Prototype.

Summing up

We can learn a lot from YUI, it has some of the smartest minds in the industry working on it. I encourage you to have a look yourself, study it, and take note of their practices and apply them to your own ventures in the world of widgets.