Writing Your First YUI Application

The promise of JavaScript/CSS libraries like the free, BSD-licensed Yahoo! User Interface (YUI) Library is that they make it easier to create rich interfaces in the browser. In this article, we'll explore the creation of a simple web app using YUI and look closely at the YUI paradigm.

Getting Started

YUI consists of several CSS components and nearly three dozen JavaScript components, all of which are designed to empower the rapid creation of web applications that run in all the major web browsers. Yahoo! uses a Graded Browser Support approach in which we "white-list" a subset of browsers that we'll fully support — we call these the "A-Grade browsers," and, taken together, they represent more than 90% of traffic on Yahoo!'s network worldwide. YUI is tested and supported in all A-Grade browsers (including current versions of Safari, Opera, Firefox and Internet Explorer).

The best way to think about YUI and what it does for you is to consider the difference between the user interface language of the browser as compared with the desktop. In the browser, the "default" language is relatively limited. You have form elements (buttons, select menus, text inputs) and hyperlinks. On the desktop, you expect much more: Tabs, sliders, cascading menus, dialogs, tooltips, data grids, rich text editing, drag and drop, animation, autocompletion, and so on. Here's one way to visualize this difference, with the browser's native UI elements on the left and the richer set of desktop-style UI elements on the right:

In the browser, everything on the right side of this diagram requires some hard work. YUI, like other JavaScript/CSS libraries, aims to make that work less hard.

Getting to Know YUI

The best way to get to know YUI is to take a quick tour of the YUI website at http://developer.yahoo.com/yui/. You'll find that YUI contains four CSS components, a light JavaScript core engine (containing powerhouse elements like DOM normalization and an event system), JavaScript utilities (components like Drag & Drop that enable you to build rich interactions), widgets (fully-encapsulated user interactions like a Calendar date-picker), and developer tools.

CSS Components

• Reset
• Base
• Fonts
• Grids

JavaScript Core

• The YAHOO Global Object
• DOM Collection
• Event Utility

Utilities

• Animation Utility
• Browser History Manager
• Connection Manager
• Cookie Utility
• DataSource Utility
• Drag and Drop Utility
• Element Utility
• Get Utility
• ImageLoader Utility
• JSON Utility
• Resize Utility
• Selector Utility
• The YUI Loader Utility

Widgets

• AutoComplete
• Button
• Calendar
• Charts
• Color Picker
• Container
• DataTable
• ImageCropper
• Layout Manager
• Menu
• Rich Text Editor
• Slider
• TabView
• TreeView
• Uploader

Developer Tools

• Logger
• Profiler
• ProfilerViewer
• YUI Test

For each YUI component, you'll find on the website the following resources to help you get started:

User's Guide: Every YUI building block is fully documented with a User's Guide that steps through the most basic use cases. These documents also provide information about common configuration options, component-level events, customization strategies, and UI styling/skinning.



Cheat Sheets are printable one-page documents that summarize a component's API, configuration options, and common use cases. You can download the full cheat sheet packet from the YUI website — it makes for a useful desk reference as you work through YUI-based projects.



API Documentation: YUI's full, searchable API is available for review, including method, property, event, and source references.






Examples: Every YUI component ships with a full complement of examples covering common use cases.







Building Your First Application

The best way to get the feel for YUI is to build a sample application — so let's get started. In our sample application, we'll use the YUI AutoComplete Control powered by the Yahoo! Search web service to supercharge a standard site-search form. As a user types a search on our site (or sites), AutoComplete will query Yahoo! Search for possible results; when it finds pages that match the query, it will open a suggestion container with a menu of results for the user to choose from. This is equivalent to having the first page of search results come back on-the-fly. The user doesn't have to navigate to the results page; s/he doesn't even need to finish typing in the search terms, in some cases.

Once the container is open, the user can click on a result or arrow to a result using the keyboard; in the latter case, the enter key sends the user to the selected page.

Here's a screenshot of the app in its finished state:


Here are our requirements and the YUI components we need to meet those requirements:

1. The search control should work without JavaScript, taking the user to the standard Yahoo! Search results page.
2. The search suggestion container should have full arrow-key and mouse support; the YUI AutoComplete Control provides this functionality.
3. The suggestion container should be animated; AutoComplete has intrinsic support for this if we include YUI's Animation Utility.
4. We want to avoid using as server-side proxy (as would be required in traditional XHR/Ajax-style applications). Instead, we'll use a JSON-based webservice from Yahoo! Search and leverage YUI's Get Utility for this proxyless solution. AutoComplete implements the Get Utility for its proxyless, script-node based DataSource, so we'll make use of that.

Armed with this knowledge about our dependencies, we can go to the YUI Configurator on the YUI website and let it determine the full list of YUI files we'll need for our implementation.


Take the output of the Configurator and put the stylesheet and script information in the element of your document. Now we're ready to start writing our application.

Setting Up the Markup

The markup for our application is simple: We need a form, a text input, and a submit button for the basic form, and we need an element to serve as the suggestion container to be populated by AutoComplete. We'll add some Yahoo! Search-specific hidden fields to our form to ensure that, if submitted, results will only be returned for the sites we've selected:

	Site Search: 
    
    
	    
    

You can test out the markup portion of the application in the file 1-markup.html. The expected behavior is that submitting the form takes you to Yahoo! Search, where the two designated sites are searched for results. In this article, we're using the two sites dedicated to YUI (developer.yahoo.com/yui and yuiblog.com). You can easily change this setting to specify one or more sites relevant to your own work; just keep in mind that the sites must be open to Yahoo! Search indexing.

Adding AutoComplete to Your Search Form

From the functioning markup base, we can begin implementing the YUI components that we added to the head of the page. In any AutoComplete implemenation, we begin by creating a DataSource — effectively, establishing the pool of "suggestions" that AutoComplete can choose from in populating its suggestion container. You can read about the various kinds of AutoComplete DataSources on the AutoComplete User's Guide — they include basic JavaScript arrays, custom JavaScript functions, and XMLHttpRequest-based services, and script-node sources. (If you're playing around with this code, you may also want to print out a copy of the AutoComplete Cheat Sheet.) In this application, we'll use the script node solution which allows us to access cross-domain data from Yahoo! Search without using a server-side proxy. (Security note: You should never access cross-domain JavaScript from untrusted sources. In this case, we're trusting the Yahoo! Search webservice not to return a malicious script.)

Here's our code to set up the DataSource:

The schema array is important; these fields map to fields passed in by the JSON web service we are using, and we'll reference these when we format the results for our suggestion container in a moment. Note that Yahoo! Search gives us a literal URL for the result page and a "click URL". The click URL is the URL we should send users through to reach a search result, as it aids Yahoo! Search in evaluating the quality of results and in sorting results more intelligently for future searches.

With our DataSource in place, we can set up our AutoComplete instance. We need to pass four arguments to AutoComplete's constructor:

1. The ID of the text input element (searchinput);
2. the ID of the suggestion container element (searchcontainer);
3. the DataSource instance (created above; oDataSource);
4. and any configurations we want to make on our AutoComplete instance for things like animation (which we'll pass in as an object literal; a list of configuration options can be found in the AutoComplete API documentation).

Here's the annotated code for setting up the AutoComplete instance with some rational configurations applied for this kind of application:

None of these settings are sacred; feel free to play around with different configurations.

Next up, we need to format the results that AutoComplete puts in our suggestion container; we do that in our instance's formatResult function which is called for each result item. Nothing fancy in the markup...we'll simply use tags to specify page titles.

In the code above, oResultItem passed to formatResult is comprised of the fields we specified in our DataSource schema: Title, Url, and ClickUrl.

The function we just wrote populates the suggestion container. When a user selects an item from this container, the itemSelectEvent is fired. That's our cue to take the user to the page they selected from the search results. Let's subscribe to the itemSelectEvent and use that event to trigger navigation to the selected page:

We've snuck in a little hack here for Opera, which does not honor preventDefault in all cases; by disabling the submit button on our form when an item is selected, we can work around that bug while still allowing the form to submit normally when no item is selected via AutoComplete.

One more bit of business remains before we test out our application. AutoComplete, true to its name, wants to automatically complete the text being typed in the input field when an item is selected in the suggestion container. We don't want that here. Rather, we want the input field to remain untouched while item selection takes us to the designated page. To accomplish this, we're going to customize our AutoComplete instance by overriding one of its core methods:

At this point, we've looked at:

1. How to configure a YUI implementation and put YUI on the page;
2. How to set up the markup for a progressively-enhanced YUI widget;
3. How to instantiate and configure a YUI widget;
4. How to subscribe to and make use of the "custom events" provided by a YUI widget;
5. And how to override default behavior to get a bespoke implementation that maps to our requirements.

Although each YUI component has its own set of configurations and events, you'll find that this set of implementation concerns is consistent throughout the library. Use the User's Guides, API docs, and Cheat Sheets to identify the patterns used by each component.

With this code in place, our implementation is functional (though not as pretty as we want just yet, and not quite complete). We can look at this partial code milestone in 2-partial.html. Don't worry about how it looks yet — just note that it's functional and ready for some finishing touches.

Finishing Touches

To get the final look-and-feel from our requirements document, we need to add some CSS styling. We're going to center the search control in the middle of its host element; Jenny Han Donnelly, AutoComplete's author, has a nice tutorial on the CSS and JS customizations required for this purpose.

Here's the CSS portion:

We're using elements of YUI's default "skin", so we will apply the controlling class name for invoking that skin (yui-skin-sam) at the top level of our document (it need only be a parent element of the skinned control, but if you are only using one skin on a given page it is convenient to place the style on the document's <body> element. You can read more about skinning YUI on the YUI website.

As with most applications, there are some final touches to be made in our code to get our implementation in line with the comp we looked at earlier in this article. Here are the requisite changes to add in the footer and to correctly position the suggestion container:

With that code in place, our implementation is complete. You can check out the working example in the file 3-complete.html.

Summary

YUI is a comprehensive frontend toolkit — we've just looked at a tiny subset of its functionality here. But don't be daunted by YUI's comprehensiveness. It is, at heart, a straightforward framework on top of which you can build robust, scalable web applications that work across all the A-Grade browsers.

As you begin developing with YUI, you should consider joining the YUI community forum and subscribing to YUIBlog. In the community forum, you'll be joined by nearly 10,000 felow YUI users, many of whom have developed (and generously share) a deep expertise in specific aspects of the library. On the blog, you'll find articles and videos from the core YUI engineering team and links out to YUI resources in the community at large.