Blog: Archive for December, 2008

Configuring Your Machine For Testing With A Screen Reader

When developing using the WAI-ARIA Roles and States, you need to test your code in a screen reader to ensure everything is working as you expect. As a follow up to my presentation on Developing Accessible Widgets with ARIA and in the interest of helping other developers test their code, I thought I would provide some tips on how to configure your development environment for screen reader testing.

Step 1: Install A Virtual Machine

Before I install and configure screen readers I start by installing a virtual machine. (This is mostly out of necessity because I use a Mac and the most-popular screen readers run on Windows.) Using a virtual machine provides a couple of benefits when testing with a screen reader: To start, a virtual machine provides a sandboxed environment, so I am protected if anything goes awry when I am installing and configuring each screen reader. (So as not to give the impression that screen readers are unstable pieces of software, this is definitely the exception more than the rule.)

The second benefit to using a virtual machine is that they allow you to save and restore state. This is an especially helpful feature for efficiently testing and re-testing specific pieces or states of complex web applications. So, using a virtual machine can help save you time when testing.

Which virtual machine to use? If you use Windows, you can download and install Microsoft Virtual PC for free. As a Mac user, I have found both VMware Fusion and Parallels Desktop work well.

Step 2: Install Browsers

It is important to remember that to work, ARIA requires a team effort between the browser and the screen reader. To test ARIA you’ll need to install browsers that both support ARIA and are supported by screen readers that also support ARIA. For example, Opera has support for ARIA, but is not supported by screen readers. Currently only Internet Explorer 8 and Firefox 3 have support for ARIA, and are supported by several screen readers for Windows that also offer support for ARIA.

After installing each browser, be sure to save the state of the virtual machine. That way you’ll be able to quickly revert back to a clean, working state should anything go wrong during the screen reader installation.

Step 3: Install & Configure Screen Readers

With the browsers installed the next step is to install and configure each screen reader. The two most-popular screen readers for Windows, JAWS and Window-Eyes support ARIA and work with both Internet Explorer 8 and Firefox 3. Free, trial versions of both products are available for download from Freedom Scientific’s and GW Micro’s websites. The open-source screen reader NVDA also has excellent ARIA support and currently works with Firefox 3. Knowing that most visually impaired users use more than one screen reader, I recommend installing all three for testing.

As a sighted person I disable a couple of features of each screen reader and change some configurations so that I can test more efficiently. For example, most screen readers are configured to startup automatically when you start your computer. This is obviously not desirable when you have multiple screen readers installed, so I turn off that feature. Additionally, every screen reader uses a different keyboard shortcut for toggling the virtual buffer on and off. To avoid having to remember the keyboard shortcut for each screen reader, I configure them all to be the same: Ctrl + Shift + Space. (For more on the virtual buffer, read Making Ajax Work with Screen Readers.)

The following sections provide step-by-step instructions for configuring JAWS, Window-Eyes and NVDA.

Configuring JAWS

Changing The Virtual Buffer Toggle Keyboard Shortcut
  1. Open the “Keyboard Manager” dialog by selecting “Utilities” -> “Keyboard Manager” in the JAWS application menubar. Screen shot of the JAWS menubar.
  2. Select the “default” profile in the left, “Profile” pane.
  3. In the right pane, sort by the “Script Name” column, then find and select the item named “VirtualPCCursorToggle”.
  4. Open the “Change Keystroke” dialog by either right clicking on the “VirtualPCCursorToggle” item, or by pressing Ctrl + H. Screen shot of the Keyboard Manager dialog in JAWS .
  5. In the “Change Keystroke” dialog, choose the new keystroke by pressing the desired keys. (I use Ctrl + Shift + Space.) JAWS will warn you if the keystroke you choose in already in use. Screen shot of the Change Keystroke dialog in JAWS.
  6. Press the “OK” button to close the dialog.
Disabling JAWS From Starting Automatically
  1. Open the “Basic Settings” dialog by selecting “Options” -> “Basics” in the JAWS application menubar. Screen shot of the JAWS menubar.
  2. In the “Basic Settings” dialog, make sure the checkbox labeled “Automatically start JAWS” in not checked. Screen shot of the Basic Settings dialog in JAWS.

Configuring Window-Eyes

Changing The Virtual Buffer Toggle Keyboard Shortcut
  1. Open the “Browse Mode Hot Key Definitions” dialog by selecting “Hotkeys” -> “Browse Mode…” in the Window-Eyes application menubar. Screen shot of the Window-Eyes menubar.
  2. In the “Browse Mode Hot Key Definitions” dialog, scroll down to the item named “Browse Mode” in the scrollable “Keys” list. Screen shot of the Browse Mode Hot Key Definitions dialog in Window-Eyes.
  3. Select the “Browse Mode” item and then press the “Capture Key” button.
  4. Press the keyboard combination you want to use. (I use Ctrl + Shift + Space.)
  5. Press the “OK” button to close the dialog.
  6. Save the configuration by selecting “File” -> “Save” -> “Set File and All Dictionaries” in the Window-Eyes application menubar. Screen shot of the Window-Eyes menubar.
Disabling The Mouse Voice

By default Window-Eyes will speak in response to some mouse gestures. For example, when you press the left mouse button, Window-Eyes will say “left”. As a sighted person I find this feature unnecessary, so I disable this feature.

  1. Open the “Mouse Voice” dialog by selecting “Mouse” -> “Voice” in the Window-Eyes application menubar. Screen shot of the Window-Eyes menubar.
  2. Select the “Off” item. Screen shot of Mouse Voice dialog in Window-Eyes.
  3. Press the “OK” button to close the dialog.
  4. Save the configuration by selecting “File” -> “Save” -> “Set File and All Dictionaries” in the Window-Eyes application menubar. Screen shot of the Window-Eyes menubar.
Disabling Window-Eyes From Starting Automatically
  1. Open the “Startup Options” dialog by selecting “File” -> “Starup Options…” in the Window-Eyes application menubar. Screen shot of the Window-Eyes menubar.
  2. In the “Startup Options” dialog:
    • Uncheck the checkbox labeled “Run Window-Eyes at the Login Screen”.
    • Uncheck the checkbox labeled “Run Window-Eyes after login for all users”.
    • Select the radio button labeled “Never” under “After login for Current User, Run Window-Eyes”.

    Screen shot of the Startup Options dialog in Window-Eyes.

  3. Press the “OK” button to close the dialog.
  4. Save the configuration by selecting “File” -> “Save” -> “Set File and All Dictionaries” in the Window-Eyes application menubar. Screen shot of the Window-Eyes menubar.

Configuring NVDA

General Settings For Efficiency
  1. Uncheck the checkbox labeled “Show this dialog when NVDA starts” that pops up the first time NVDA starts Screen shot of the NVDA welcome dialog
  2. Disable the confirmation dialog that pops up when you exit the application:
    1. Open the “General settings” dialog by right clicking on the NVDA system tray icon and selecting to “Preferences” -> “General settings” in the context menu. Screen shot of the NVDA system tray context menu.
    2. In the “General settings” dialog, uncheck the checkbox labeled “Warn before exiting NVDA”. Screen shot of the General settings dialog in NVDA.
    3. Right click on the NVDA icon in the system tray and select the “Save configuration” menu item in the context menu. Screen shot of the NVDA system tray context menu.
Disabling the Mouse Voice

Like Window-Eyes, by default NVDA will speak in response to some mouse gestures. For example, when you move the mouse NVDA will play tones to help the user track the position of the mouse. As a sighted person I find this feature unnecessary, so I disable this feature.

  1. Open the “Mouse settings” dialog by right clicking on the NVDA icon in the system tray and selecting “Preferences” -> “Mouse settings” from the context menu. Screen shot of the NVDA system tray context menu.
  2. In the “Mouse settings” dialog, uncheck both “Report text under the mouse” and “play audio coordinates when the mouse moves”. Screen shot of the Mouse settings dialog in NVDA.
  3. Right click on the NVDA icon in the system tray and select the “Save configuration” menu item in the context menu. Screen shot of the NVDA system tray context menu.
Changing The Virtual Buffer Toggle Keyboard Shortcut
  1. Shut down NVDA – right click on the system track icon and choose “Exit” from the context menu.
  2. Navigate to the path “C:\Program Files\NVDA\appModules”. Screen capture of the contents of the appModules directory.
  3. Open the file named “_default_desktop.kbd”.
  4. Find the line: “NVDA+space=toggleVirtualBufferPassThrough”.
  5. Change to: “Control+Shift+space=toggleVirtualBufferPassThrough”.
  6. Save the file.
  7. Restart NVDA.

Step 4: Restart Windows & Save State

With all of the screen readers installed and configured, restart Windows. Once Windows is restarted, take another snapshot of the virtual machine’s state. If you are using the free, trial versions of JAWS and Window-Eyes they will require you to restart Windows after using either product for ~30 minutes. Using the virtual machine, you can revert back to using JAWS and Window-Eyes more quickly than you would if you had to restart Windows.

Steps Summary

That’s it. The steps for configuring your development environment for testing using a screen reader can be summarized as follows:

  1. Install virtualization software
  2. Install browsers & take a snapshot of that state
  3. Install and configure screen readers
  4. Restart the virtual machine & take a snapshot of that state

Resources & Further Reader

By Todd KlootsDecember 30th, 2008

YUI Theater — Douglas Crockford: "Ajax Performance"

Douglas Crockford returns to YUI Theater with another chapter in his evolving lecture series. This session, “Ajax Performance,” debunks common misconceptions about the relationship between JavaScript and performance and gives engineers a core focus for improving the performance of web apps: Reduce the value of n. Because DOM interactions are generally slow, leveraging Ajax to reduce the number of DOM operations, Douglas argues, is often the most important optmization you can make. In fact, it usually dwarfs other techniques in terms of its impact on the actual experience of using a website.

This talk joins an extensive library of Douglas’s lectures now available on YUI Theater, including his popular series on JavaScript.

Douglas Crockford: "Ajax Performance" @ Yahoo! Video

download (m4v)

In Case You Missed…

Some other recent videos from the YUI Theater series:

Subscribing to YUI Theater:

By Eric MiragliaDecember 23rd, 2008

YUI Theater — Nicole Sullivan: "Design Fast Websites (Don’t Blame the Rounded Corners)"

Nicole Sullivan is a website performance specialist and a former member of Yahoo’s Exceptional Performance Team. She is currently writing a book for O’Reilly with Stoyan Stefanov on performance optimization and she and Stoyan are the creators of Smushit, an engine for crushing images.

Nicole visited Yahoo last week to do an encore of her "Design Fast Websites" talk in which she outlines a set of practical guidelines for building websites that are supremely fast and visually rich. Her advice is to know your craft, to engage your designers, and to make sure that your collaboration with designers works intelligently in the service of users. She was kind enough to let us record the talk and share it with you here on YUI Theater.

Nicole Sullivan: "Design Fast Websites" @ Yahoo! Video

download (m4v)

In Case You Missed…

Some other recent videos from the YUI Theater series:

Subscribing to YUI Theater:

By Eric MiragliaDecember 23rd, 2008

Implementation Focus: pulpTunes

Alejandro Pedraza got his degree in Economics and was quickly bored to death in a regular office job for a couple of months. He realized he should follow his true life’s calling and turn night-and-weekend programming into something that would pay the bills, too. A failed startup and a couple of jobs later as lead developer, he’s been concentrating on building apps on the LAMP stack and Java and contributing to many open source projects during his free time. He is the author of pulpTunes, a new way of accessing your iTunes library via a Web browser. pulpTunes makes extensive use of YUI.

What got you interested in building a web interface to iTunes? Or is that a dumb question?

(No, not a dumb question :)) I’ve got a sizable song collection in my iTunes. An app for providing myself with web access seemed like a nice thing to have, and it would give me the opportunity to play with web and desktop technologies in the same application.

You chose YUI for many of the UI elements in your app. What specific YUI components are you using, and for what purposes?

YUI’s consistency and reusage of components accross the whole ecosystem lets you easily pick up on any new component you might need as the project advances. So I’ve been trying to stick with YUI-only, and I had to look elsewhere just for the flash song player, for obvious reasons.

pulpTunes produces a single web page, whose layout is declared through the Grids CSS lib. No need of nasty CSS hacks, and you can guarantee your page will look the same in all major browsers. This is one of my favorite YUI libraries, because of the huge time savings and peace of mind it provides.

The songs list is a DataTable accompained by a Paginator, fed through an XHR connection. Customizing the table and pagination looks was really easy by just overriding some CSS rules from the Sam skin, which is very well commented. The custom formatter for the Rating column is a 3-liner javascript code. The table (and the playlist section to the left) make use of the menu component to show a context menu to perform operations on a song or playlist.

I’m using a Slider component to adjust the player’s buffer. With it you point at which point in download progress you want the song to start playing.

There are few popup messages and dialogs in the app, that are rendered using the Container component.

Most of the YUI components I used (there are 12) are fetched from yui.yahooapis.com in a single request through the very convenient YUI Loader. And of course, I’m using the YUI compressor to compress to 15k the one javascript file that holds all the app’s logic.

You’re using Dav Glass’s Effects Package in addition to YUI. What functionality are you drawing from Dav’s collection specifically?

Coming from a Prototype+Scriptaculous world, I was very relieved to find that somebody had already ported to YUI all the great effects from Scriptaculous. And [because Dav is a member of the] YUI team, I could rest assured about its quality. I’m using the BlindDown and BlindUp effects to show and hide the songs cover art.

One of the main elements of your app is the DataTable that you use to display the songlists. What was your experience like building an XHR-fed DataTable with JSON data? What lessons did you learn that are worth sharing with other developers?

The XHR feeding part was pretty straightforward. Although I remembered trying to return some HTML in the JSON response which didn’t work, but that looked like a browser bug.

Pagination and sorting was easy as well, but I had to provide a custom generateRequest function because, if I recall correctly, YUI assumes the records should be sorted since the first request to the server, and in my case I wanted to wait till the user actually clicked on a column header to start returning sorted records.

I also had some trouble at first when trying to retrieve specific records in the table, but then I realized the existance of a whole bunch of helper methods just for that, like getTrEl() and getRecord() that are not mentioned in the general docs. So my obvious advice is that your read the entire API for any component you’ll be doing heavy work on.

pulpTunes is a SourceForge project. Are you looking to build a community of developers to work on the project with you?

Yes, that’s the idea. I’m also using SourceForge to track bugs and feature requests, so any kind of feedback from users is also welcomed. Graphical designers are invited as well, if they want to provide additional skins for the app.

What’s next for pulpTunes?

It’s been just a few days since the first stable release is out, and the response has been tremendous. I think I have already a pretty good idea of the major features for the next version: user authentication, search, shuffle and repeat buttons, and ability to rate songs.

By Eric MiragliaDecember 17th, 2008

In the Wild for December 12, 2008

This will be our last “In the Wild” post for 2008. It’s been a fun year, filled with a lot of exciting implementations and other developments in the YUI world. Here are the once we’ve noted lately:

  • YUI Sightings — PulpTunes: Here’s the elevator pitch for PulpTunes: “You’ve got a huge music collection in your iTunes at home.  You want to access that music from the office, at a friend’s party, or let other people hear it from anywhere in the world.  Install PulpTunes and access your music from anywhere, through a web browser.”  Check out the demo (filled with Creative Commons-licensed tunes) and see what a fantastic job Alejandro Pedraza has done in making a web-based jukebox app powered by a variety of YUI components.
  • Visual Event for YUI and JQuery: Visual Event is the brainchild of Allan Jardine.  Here’s how he describes it: “When working with events in Javascript, it is often easy to loose track of what events are subscribed where. This is particularly true if you are using a large number of events, which is typical in a modern interface employing progressive enhancement. Javascript libraries also add another degree of complexity to listeners from a technical point of view, while from a developers point of view they of course can make life much easier! But when things go wrong it can be difficult to trace down why this might be.  It is due to this I’ve put together a Javascript bookmarklet called Visual Event which visually shows the elements on a page that have events subscribed to them, what those events are and the function that the event would run when triggered. This is primarily intended to assist debugging, but it can also be very interesting and informative to see the subscribed events on other pages.”  Visual Event supports jQuery and YUI (version 2.6.0 has been tested, but others work as well).
  • YUI Sighting — G-Snap!: G-Snap is a new service that let’s you tap into ad-hoc communities that form around real-time events — say, an NFL game or a political rally.  Events are called snapcasts, and you can join them or create them on the fly, from your desktop or by phone.  The snapcast UI relies heavily on YUI, incorporating most of the utility foundation and several widgets.
  • Music Startup Bandcamp Using YUI: Oddpost co-founder Ethan Diamond has created Bandcamp as a means of providing bands with a means of distributing and promoting their music.
  • A Review of (and Tutorial For) YUITest: Fredrik Kalseth recently published on his blog an entry titled JavaScript is Code Too: Test It!. It’s well worth a read. After quickly summarizing why unit testing is important he walks through the steps necessary to create a unit test for a simple edit-in-place behavior. (Note that his edit-in-place code is written in jQuery; YUITest will test any type of JavaScript – the JS to be tested need not be written using YUI.) He concludes with his overall impressions of YUITest. Full source code for his demo test is available for download.
  • New YUI Controls Added at YUIAsp.Net: The YUIAsp.Net project has released another batch of YUI controls into the mix.  It now supports: AutoComplete, Button, Calendar, Charts, ColorPicker, DataTable, Editor, Logger, Menu, Paginator, Slider, TabView, and TreeView.  It’s now easier than ever to use YUI in your .Net projects.
  • YUI Sightings — WishAHome.com, Indian Real Estate Site: WishAHome.com is a real estate portal, according to its authors, that targets “Indian users [and] that tries to provide property listings in a unique and innovative way. The information provided by the site is to-the-point and extra care has been taken to ensure that the information posted by users is accurate.”  The site makes extensive use of YUI, including a nicely-skinned implementation of Matt Sweeney’s YUI TabView Control on the home page.
  • Creating a TextBox Calendar with YUI: Ryan Moore of Toolbox.com has been exploring YUI, and he’s posted one of the fruits of his early exploration — an adaptation of the YUI Calendar Control.  Writes Ryan: “This class is based on code posted by DavGlass, which was for YUI .12 – it allows you to pop up a YUI Calendar Control when you click on a text box, and then populate the text box with the calendar’s value when a date is selected.”
  • Todd Kloots on CodeTalks ARIA Theatre: The fantastic CodeTalks site, dedicated to web accessibility, has an ARIA Theatre section to which YUI accessibility specialist Todd Kloots’s recent video has been added.  This video archive should become a valuable resource for front-end engineers as it aggregates tech talks on the art and science of building accessible web applications.
  • BlueGriffon Adds Support for YUI CSS Grids-based Layouts: Daniel Glazman from the BlueGriffon project has added support for Nate Koechley‘s YUI CSS Grids.  BlueGriffon is a web page editor based on the Gecko rendering engine that powers Firefox.
  • Text Area Character Throttle: Some people (I’m not naming names, although “Miraglia” is a long name) tend to run on and on if you give them an open text field, so it’s sometimes necessary to throttle their otherwise undisciplined input in hopes that they’ll remove redundant, repetitive adjectives before submitting your form.  Lustr.nl has a YUI-based solution for you with its textarea character throttle.
  • YUI in DreamWeaver CS4: YUI founder Thomas Sha has been working with Adobe to improve YUI support in the new DreamWeaver CS4.  He’ll have more to say about this soon on the blog, but the question came up in the forums and we wanted to point you to Thomas’s response.  If you’re already using CS4, check out Thomas’s notes on how to get started with the new YUI extensions.
  • YUI Sightings — Montagraph: Montagraph is a fun site that allows you to create photo montages quickly from existing templates or to create your own template for sharing with others.  A number of YUI components, including Dav Glass’s ImageCropper Control, are in use on the site.
  • YUI Sightings — Life Log: Writes Life Log’s author, Haitao Li: “What were you doing ten years ago today? You would know if you used Life Log. Log your life, your work, or take meeting notes with tags. It even works as shared clipboard across computers.”  Life Log uses a variety of YUI components, including Matt Sweeney’s YUI TabView Control.
  • Make a YUI Menu of Your WordPress Pages: Chris McAfferty shows you how to load all your WordPress pages into a YUI Menu for compact, accessible access.  He gives you the WP code and notes that you need to load YUI Menu yourself; load it from Yahoo’s servers in two files (one for CSS and one for JS).

As always, please let us know what we missed by leaving a comment below.

By YUI TeamDecember 12th, 2008

YUI 3.0 PR2 Now Available: Widget and Plugin Infrastructure, Sample Widgets, and More

YUI 3.x

We’re pleased today to announce the second preview release of the new YUI 3.x codeline. This release adds significantly to PR1, providing an all-new widget foundation, two sample widgets, a new plugin architecture, a new ultralight plugin for menu-style navigation, and enhancements throughout the library. We’ve ported YUI Test and Profiler from 2.6.0, moving two steps closer to parity with the YUI 2.x core and utility platform. YUI 3.0 PR2 is available for download immediately from YUILibrary.com; you can discuss the release with the YUI community in the YUI3 forum on Yahoo Groups.

some key terms in YUI 3A key part of our focus in YUI 3.x is to provide more granularity so that you can fine-tune your implementation to include only the features that you’re actually using for a given component (watch the 3.x overview video for more on the larger goals for this codeline). Each 3.x component ships with a small functional core, and advanced features are added in the form of plugins or optional submodules. The submodule pattern was illustrated in PR1. In PR2, we’re adding in the Widget infrastructure, designed to promote maximal modularity and code reuse, along with two reference widgets. We’re also debuting the Plugin infrastructure. Plugins can be written to supplement a simple Node or to add features to a widget in a lightweight, a la carte fashion.

Here are the highlights of PR2:

  1. Widget Infrastructure: The biggest addition in PR2 is the debut of the Widget infrastructure. PR2 delivers the base Widget class for YUI 3.x, which will be the foundation class for all formal YUI widgets. (In 2.x, we called these components "controls" in order to avoid confusion with Yahoo/Konfabulator widgets, but in 3.x we are standardizing on "widgets.") The Widget class extends Base, which was part of PR1. If you’re interested in exploring the Widget infrastructure, we recommend reviewing Node, Event, Base, Widget, and Overlay (in that order) to get a sense how these pieces fit together.
  2. Slider, Overlay, Console Widgets: Slider, Overlay and Console (what was LogReader in 2.x) are provided as the initial set of widget implementations for YUI 3.x, along with examples leveraging the Widget infrastructure. Overlay will be of particular interest to those of you who want to study the inner workings of the modular Widget system. It is constructed by combining the core Widget module with WidgetPosition (basic xy positioning), WidgetPositionExt (extended positioning: align, center), WidgetStdMod (standard module support) and WidgetStack (zIndex, shim support) extensions, which can be mixed and matched as required to provide other custom implementations. These initial widgets are meant to establish and confirm the concepts we’re promoting in 3.x with respect to granular, reusable code. The widgets are likely to change as we move toward the GA for 3.x, but they should give you a good sense of how the library’s new core is performing.
  3. Plugin Infrastructure: Plugins provide atomic pieces of functionality that can be mixed and matched with other plugins to modify or add functionality on an existing widget (or Node). For example overlay.plug({fn:StdModIOPlugin, cfg:pluginCfg}) instantiates the StdModIOPlugin class and adds it to the host widget as the io property (the namespace defined by the plugin), adding input/output capabilities. In addition to adding completely new functionality, plugins may also modify existing functionality on the host by listening for events or by injecting code before or after the execution of methods on the host. For example, an Animation plugin might provide configurable animation effects that modify the base widget’s native hide and show methods.
  4. Node Plugins: The MenuNav Node Plugin provides a lightweight but feature-rich navigation menu as a simple one-line plugin to Node, with content/functionality driven entirely through markup/CSS. MenuNav, and Node plugins in general, are ideal choices for light implementations that don’t need programmatic (API/event) access to the control once instantiated. MenuNav is the first such Node plugin implementation for YUI 3.x, and it replicates the most commonly used functionality from the YUI 2.x Menu Control in under 5KB (gzipped) JavaScript and CSS.
  5. Event Updates: Event simulation (the ability to programatically fire events) has been moved into the Event utility in 3.0PR2; event simulation was previously part of YUI Test. The subscribe/publish methods have been expanded to support subscribing to or publishing mutliple events in a single call. Supplementary global events (available, contentready, focus, blur) and keyboard event support has been added.
  6. IO Updates: The IO utility adds form-mining and file upload support, available as optional sub-modules. Existing queue and cross-domain request (XDR) support have been broken out into optional submodules to increase the granularity of the component. Now, users not interested in the advanced features (queuing, XDR, form-mining, file upload), can use the lighter io-base module.
  7. Developer Tool Updates: The YUI Test framework, Profiler, and the Console widget are now available in the PR2 release. YUI Test adds support for mock objects. Mock objects allow you to isolate your tests from dependent code by defining objects that behave in predictable ways. Create mocks of XMLHttpRequest, document, or any other object on which your code depends without depending on the actual implementation.

Again, we’re eager for your feedback and hope you enjoy checking out this second Preview Release.

By Satyen DesaiDecember 9th, 2008

YUI Doc: A New Tool for Generating JavaScript API Documentation

We’re pleased today to release the first public version of YUI Doc, a python-based documentation tool that generates API documentation for JavaScript code. YUI Doc was developed by Adam Moore, one of the principal engineers on the YUI project since its inception, to support YUI’s API-level documentation.

Those familiar with JavaDoc, JSDoc, or the JsDoc Toolkit (the latter superceded JSDoc, which no longer sees active development) will find YUI Doc’s conventions familiar. It is a comment-driven system in which documentation is parsed from comment blocks that describe the structure of your code. Unlike some analagous systems, YUI Doc is designed to work purely from comments; as a result, there is no idiom or code pattern with which the tool is incompatible.

YUI Doc’s principal organizational structures are these:

  • Project: The project is the top-level bucket into which a set of documentation is grouped. In the case of YUI’s documetnation, YUI itself is the project.
  • Module: A module is used to group pieces of code that relate to a functional unit. For example, in YUI the Drag and Drop Utility is a module; the AutoComplte Control is a module; etc. Modules can depend on one another and can be further subdivided into submodules (in YUI 3, we make extensive use of submodule structures to deliver the smallest possible code payloads).
  • Class: Classes (and inner classes) are used to describe objects that function as instantiable or static classes in JavaScript. YUI Doc also supports concepts like augmentation, allowing you to document the inheritance structures that characterize your object-oriented applications.
  • Methods and Properties: Methods and properties are used in the conventional sense to document class members.
  • Events: We’ve added the event construct to YUI Doc to support YUI’s Custom Event infrastructure. Where you are building modules that publish events with well known parameters, YUI Doc can help you expose that information through this construct. (As a simple example, when a date is selected in the YUI Calendar Control, the selectEvent is fired.

YUI Doc is most likely to be of interest to those who are building library-style code to be used by other developers. Because it requires in-line documentation, it is only appropriate to use YUI Doc in combination with a minification tool (like Douglas Crockford’s JSMin or Julien Lecomte’s YUI Compressor). A common scenario would be to incorporate YUI Doc into an existing continuous-build process to generate and publish documentation at build time; your code might be concatenated and version-stamped by Ant, verified by JSLint, documented by YUI Doc, and then minified by YUI Compressor.

YUI and Git; photo by Dav GlassYUI Doc joins YUI Compressor in the portfolio of build-time processes that we’re making available as part of the YUI project. We look forward to your feedback on this beta release. The source code for YUI Doc has been published on GitHub; if you’d like to get involved in YUI Doc development, we invite you to check out the source (instructions here), sign a CLA, and join us in making this the best documentation engine available for serious frontend engineers.

Footnote: We’re hard at work prepping the YUI 2.x and 3.x code repositories for GitHub deployment as well. We’ll have more to share with you on that front in the near future.

By Eric MiragliaDecember 8th, 2008