jQuery UI 1.8 is currently at the release candidate stage and, barring the discovery of a major bug or flaw, will shortly become the current stable release of jQuery's official UI library. So what has changed since the last current stable release of 1.7.2? One of the major differences of course is that the library now runs on the latest release of jQuery itself - version 1.4.1, but there have been many other changes including the addition of some great new components, which we'll look at over the course of this article.
Free Copies of jQuery UI 1.7
The author of this article, Dan Wellman, recently released jQuery UI 1.7, from Packt Publishing. It's a fantastic read, and I'm pleased to announce that we have a handful of copies to randomly give out. Simply leave a comment about the article, and you'll automatically be entered into the drawing. Check back on Monday to find out if you're a winner!
1. Bug Zapping
This release of the library brings several bug fixes for some key components including the Datepicker and Dialog widgets and the Droppable, Resizable and Selectable interaction helpers. None of the bugs were show-stoppers, but nevertheless, clearing out the bugs is a critical part of the ongoing progression of the library. One important point to note is that the beforeclose event of the Dialog widget has been deprecated and replaced with beforeClose so that it follows the same naming convention as the events of other components.
As well as bugs in the code, several styling and accessibility issues have also been addressed; notably the title text of Dialog widgets can no longer disappear behind the close icon, and the keyboard navigability of the new button widget has been improved. For a complete list of all bug fixes included with version 1.8 see the changelog at http://jqueryui.com/docs/Changelog/1.8rc1
jQuery UI now has a unique positioning system that that can be used whenever a widget needs to be positioned relative to another element, such as with a drop-down menu or a floating tooltip. The Position utility allows us to easily specify, using a series of simple strings, which part of the positioned element should be fixed to which part of the specified target element. So for example, the "top left" point of one element can be fixed to the "bottom right" of another specified element.
The utility also features a robust collision detection system which prevents viewers of the page being exposed to unsightly toolbars if the element being positioned gets too close to the edge of the viewport, or cannot otherwise occupy its positioned place.
The API for this utility is compact, with just 7 configurable options at this stage. This gives us all the control we need however and allows us to specify up to 81 possible combinations of positioning; options we can configure include the following:
- Refers to the position on the target element the element being positioned will be fixed to; the method accepts a single string comprised of the value for the horizontal axis (either right, center, or left) followed by the value for the vertical axis (either top, center, or bottom). There is no separating character between the 2 values.
- If the bgiframe plugin is available on the page, this option will apply an iframe shim to the positioned element, which can help to prevent select elements showing above the positioned content in IE6.
- This option determines how collisions are handled; it accepts one of the following strings: flip, fit or none. The default is flip, which causes the element being positioned to invert the position relative to the target element, e.g. "right center" will become "left center".
- Refers to the element being positioned; accepts same values as at.
- Accepts a jQuery selector specifying the target element.
- Specify a number of pixels to offset the element being positioned on the target element.
- A callback function can be used with this option allowing you to animate the positioning of the element.
One of my favourite widgets has returned as an official UI component! Autocomplete was a beta widget in an early 1.6 version of the library and is now back after a complete refactor. It is attached to text inputs on the page and supplies a list of possible choices when a visitor begins typing in the text field.
Autocomplete is a highly configurable widget and features a full API of options, methods and events to make use of. It's completely themable via SteamRoller and fully keyboard navigable. All in all this component brings a lot of functionality to your pages. At some future point caching may also be a configurable behaviour.
Let's take a look at its API; it contains the following three configuration options:
- We can specify the number of milliseconds the widget should wait before displaying the suggestion menu when the visitor begins typing in the input.
- This option takes an integer that refers to how many characters should be typed into the input before the suggestion menu is displayed.
- We configure the data source using this option; possible values include an array of strings representing the items to show in the suggestion menu, or an array of objects where each object contains two properties - the first is the label shown in the suggestion menu, the second is the value that will be added to the input if an item in the suggestion menu is selected. We can also supply a single string representing a remote resource that can return the data asynchronously, or a callback function that can request the data and return it to the widget in the required format.
The following two methods are exposed by Autocomplete:
- Used to close the suggestion menu.
- Perform a search of the available data and display the suggestions if the term is matched. Can take a predefined value as the term which is passed into the method as an argument, or the value of the input field it is associated with.
We can also hook callback functions into the following custom events:
- Fired after an item in the suggestion menu is selected and the menu is closed.
- Fired whenever the suggestion menu is closed, whether or not an item was selected. Precedes the change event.
- Fired directly before focus is given to an item in the suggestion menu.
- Fired once the data has been returned, directly before the suggestion menu is displayed.
- Fired directly before the data source is searched. The search can be cancelled by returning false from a callback function bound to this event.
- This event is triggered when an item from the menu before the menu closes.
As a special bonus, the source file for the Autocomplete widget also contains the beta Menu widget, which is still currently in development and is due for release in a later version of the library. So far it looks like a robust and attractive addition to the library, and allows us to transform an unordered list into an attractive drop-down or fly-out menu. Many features are supported including sub-menus, icons, dividers and even a drill-down menu with breadcrumb.
The button widget allows us to implement attractive and functional buttons that can be configured to behave like a particular type of button; for example, we can crate standard push buttons, radio-style buttons where only a single button in a set may be selected, or check-style buttons where any number in a particular set may be selected. Several types of button that incorporate a simple drop-down menu can also be created.
It's a very flexible widget and can be built using a variety of underlying elements including <button>, <input> and <a>. The buttons are fully accessible and ARIA compliant, adding or removing the appropriate roles and states when necessary. The API is relatively simple at this point, but covers all essentials with three configurable options and a single method to invoke; the configuration options are as follows:
- This option allows us to specify primary and secondary icons to display on the button. It expects an object with the keys primary and secondary, and CSS class names as the values.
- With this option we can set the text that is displayed on the button; a string value is expected, but if this is not supplied the value of the underlying HTML element from which the button is created can be used.
- The text option accepts a Boolean indicating whether or not to show a text label on the button, which could be the case if a simple icon is all that is needed. The default value is true.
The event that we can bind to in order to execute a callback function and react to interaction is the click event; the native click event of the browser is used unless with the radio or checkbox-style buttons, in which case the event is fired by the widget, not the underlying element.
5. Mouse Utility
The final new utility to be found in jQuery UI 1.8 is the Mouse utility, which is used by other library components in order to better distribute related implementations of the same behaviour by different widgets. This is great for developers because it means that if mouse interaction is a required behaviour of a custom UI widget, the logic in this utility can be used without having to rewrite it manually. Like the Menu component however, this utility should be considered beta and subject to considerable revision in future releases.
The API is very compact; there are just three configurable options; there are a series of private methods that are used internally by the plugin, but nothing we would need to manually invoke. The configurable options are as follows:
- This option accepts a string value containing selectors and allows us to configure elements that interaction should be cancelled on. The default value is ':input, option' so for example, in a drag and drop implementation, these elements would not be draggable.
- This option accepts an integer representing the number of pixels the mouse should move before the interaction is registered. The default is 1.
- This option also accepts an integer, but this time refers to the number of milliseconds that should elapse before the interaction is registered. The default of this option is 0.
jQuery UI 1.8 is shaping up to be a fine release of the library; with a combination of both bug-fixes and new components it's looking like an important milestone in the library's roadmap. We first looked at the library's new positioning system which gives us easy access to a huge number of different was of positioning one element relative to another element. We then looked at the two new components Autocomplete and Button and saw the different configuration options, methods and events exposed by each of their APIs.