Welcome to jQuery UI 1.8: The User Interface Library for jQuery. This resource aims to take you from your first steps to an advanced usage of the JavaScript library of UI widgets and interaction helpers that are built on top of the hugely popular and easy-to-use jQuery.
jQuery UI extends the underlying jQuery library to provide a suite of rich and interactive widgets along with code-saving interaction helpers, built to enhance the user interfaces of your websites and web applications. It's the official UI library for jQuery and although it is not the only library built on top of jQuery, in my opinion it is without a doubt the best.
This chapter will cover the following topics:
How to obtain a copy of the library
How to set up a development environment
The structure of the library
ThemeRoller
Browser support
How the library is licensed
The format of the API
jQuery has quickly become one of the most popular JavaScript libraries in use today. jQuery UI will definitely become the extension library of choice, thanks to its ever-growing range of common UI widgets, high levels of configurability, and its exceptional ease of implementation.
jQuery UI runs on top of jQuery so the syntax used to initialize, configure, and manipulate the different components is in the same comfortable, easy-to-use style as jQuery. We automatically get all of the great jQuery functionality at our disposal as well. The library is also supported by a range of incredibly useful tools, such as the CSS framework that provides a range of helper CSS classes, and the excellent ThemeRoller application that allows us to visually create our own custom themes for the widgets, or choose from a growing library of pre-existing themes.
Over the course of this book, we'll look at each of the existing components that make up the library. We will also be looking at their configuration options and try out their methods in order to fully understand how they work and what they are capable of. By the end of the book, you'll be an expert in its configuration and use.
We already have a basic working knowledge of the components when we add a new widget or interaction helper, because of the consistency in how we implement the different components that make up the library. Therefore, we only need to learn any widget-specific functionality to master the particular component we wish to use.
To obtain a copy of the library, we should visit the download builder at http://jqueryui.com/download. This tool gives us a range of different options for building a download package that is tailored for our particular implementational requirements. The following screenshot shows the download builder:
We can either download the complete current release of the library (version 1.8.9 at the time of writing), or a complete package of a legacy version. We can also select just the components that we want and download a custom package.
Note
This book is specifically tailored towards version 1.8, which is above of jQuery UI and requires jQuery 1.3.2 or higher. To support older versions of jQuery, the legacy version 1.7.3 is also available from the download builder.
The page is laid out in a really friendly and easy-to-use way. It lists all of the different components in their respective groupings (core, interaction helpers, and widgets) and allows us to choose from one of 24 different predesigned themes (or no theme at all). The page also provides information about the package (including both its compressed and uncompressed size).
We'll look at the different files found within the library in just a moment, but for now we should download the complete library. It will contain everything we need, including the JavaScript and CSS files, as well as any images from the current theme that different components rely on. It even contains the latest version of jQuery itself, so we don't need to worry about downloading this separately.
For now, just use the Stable link at the top of the page. This will give us the default theme, which is called smoothness . We'll look at downloading and using other themes in the next chapter.
Tip
Hosted Files
We don't even need to download the library in order to implement it in a production web application. Both jQuery and jQuery UI are hosted on Google and Microsoft's
Content Delivery Networks (CDN), so we can include <script>
elements that link to these files instead of using local versions. Only the complete library (not individual components) is available, although there are a range of different releases.
On a live site that receives a lot of international traffic, using a CDN will help ensure that the library files are downloaded to a visitor's computer from a server that is geographically close to them. This helps in making the response quicker for them and saving our own bandwidth. This is not recommended for local development however.
Google's CDN can be found at: http://code.google.com/apis/libraries/.
Microsoft's CDN can be found at: http://www.asp.net/ajaxlibrary/cdn.ashx.
We'll need a location to unpack the jQuery UI library in order to easily access the different parts of it within our own files. We should first create a project folder, into which all of our example files, as well as all of the library and other associated resources, can be saved.
Create a new directory in your C:
drive, or in your home directory, and call it jqueryui
. This will be the root folder of our project and will be the location where we store all of the example files that we'll make over the course of the book.
Note
The structure of the accompanying code download for this book will mirror the local environment we are creating.
To unpack the library, open it up in a compression program, such as the open source 7-
zip
, and choose the extract
or unzip
command. When prompted for a location to unpack the archive to, choose the jqueryui
folder that we just created.
Note
7-zip can be found at: http://www.7-zip.org/
The code examples that we'll be looking at use other resources, mostly images, but occasionally some PHP files too. The accompanying code download available on Packt's website contains all of the images that we'll be using. You should download this now if you can. Visit: http://www.packtpub.com/support/book/user-interface-library-for-jquery. You'll need to create a new folder within the jqueryui
project folder and call it img
, then unpack all of the images within the img
folder in the archive, to this new folder.
The code download also contains all the examples files as well as the library itself. These files are provided in the hope that they will be used for reference purposes only. I'd urge you to follow the examples in the book as you go along, manually creating each file as it is shown, instead of just referring to the files in the code download. The best way to learn code is to code.
This is all that we need to do, no additional platforms or applications need to be installed and nothing needs to be configured or set up. As long as you have a browser and some kind of code or text editor, everything is in place to begin developing with the library.
Let's take a moment to look at the structure of the library once it has been unpacked, so that we know where to look for specific utilities and files. This will give us a feel for its composition and structure. Open up the jqueryui
folder where we unpacked the library. The contents of this folder should be as follows:
A
css
directoryA
development-bundle
directoryA
js
directoryAn
index
file
The css
folder is used to store the complete CSS framework that comes with the library. Within this folder will be a directory that has the name of the theme we chose when building the download package. Inside this is a single file that contains all of the CSS, and a folder that holds all the images used by the theme. We can also store the CSS files that we will be creating in this css
directory.
The js
folder contains minified versions of jQuery and the complete jQuery UI library, with all components rolled into one file. In a live project, it is the js
and css
folders that we'd want to drop into our site.
The index is an HTML file that gives a brief introduction to the library and displays all of the widgets along with some of the CSS classes. If this is the first time you've ever used the library, you can take a look at this file to see some of the things that we'll be working with throughout the course of this book.
The development-bundle
directory contains a series of resources to help us develop with the library. It consists of the following subdirectories:
Also present in the directory are the license files, documents showing the version of the library and its main contributors, and an uncompressed version of jQuery.
The
demos
folder contains a series of basic examples, showing all of the different components in action. The docs
folder
contains API documents for each of the different components.
The
external
folder contains a set of tools that may be of use to developers. They are as follows:
The bgiframe
plugin is used to fix the issue in IE6 where <select>
elements appear above other content, regardless of z-index
. The cookie
plugin makes it easy to use browser cookies. qunit
is jQuery's unit testing suite and can be used to run unit tests on widgets and plugins that we may create. For more information on QUnit, visit http://docs.jquery.com/QUnit.
The themes
folder contains the default theme, or the theme that was selected during in the download builder. Other themes that we download at a later point or themes we create ourselves, can also be stored here.
The ui
folder contains the individual and uncompressed source files of each of the different components of the library.
ThemeRoller is a custom tool written with jQuery and PHP. It allows us to visually produce our own custom jQuery UI theme and package it up in a convenient and downloadable archive, which we can drop into our project with no further coding (other than using the style sheet in an HTML <link>
element of course).
ThemeRoller was created by Filament Group, Inc. and makes use of a number of jQuery plugins released into the open source community. It can be found at http://ui.jquery.com/themeroller. It is due to be updated shortly to coincide with the 1.9 release of jQuery UI.
ThemeRoller is certainly the most comprehensive tool available for creating your own jQuery UI themes. We can very quickly and easily create an entire theme comprised of all of the styles needed for targeting the different widgets that make up the library, including the images we'll need.
If you looked at the index.html
file a little earlier, then the ThemeRoller landing page will instantly be familiar, as it shows all of the UI widgets on the page, skinned with the default smoothness theme.
The page features an interactive menu on the left that is used to work with the application. Each item within the menu expands to give you access to the available style settings for each part of the widget, such as the content and the clickable areas: the header and content areas of the widget, and other associated things such as warnings and error messages.
Here we can create our custom theme with ease and see the changes instantly, as they are applied to the different visible parts of each widget on the page:
When you're not feeling particularly inspired while creating a theme, there is also a gallery of pre-configured themes that you can instantly use to generate a fully configured theme. Aside from convenience, the best thing about these pre-selected themes is that when you select one, it is loaded into the left menu. Therefore, you can easily make little tweaks as required.
This is an excellent way to create a visually appealing custom theme that matches the style of your existing site, and is the recommended method of creating custom skins.
Installing and using the new theme is as easy as selecting or creating it. The Download theme button in the above screenshot takes us back to the download builder, which has the CSS and images for the new theme, integrated into the download package.
If it's just the new theme we want, we can deselect the actual components and just download the theme. Once downloaded, the css
folder within the downloaded archive will contain a folder that has the name of the theme. We can simply drag this folder into our own local css
folder, and then link to the style sheet from our pages.
We won't be looking at this tool in much detail throughout the book. We'll be focusing instead on the style rules that we need to manually override in our own custom style sheets to generate the desired look of the examples manually.
There are three types of components found within the jQuery UI library:
Low-level interaction helpers: designed to work primarily with mouse events.
Widgets: produce visible objects on the page.
Core components: components that other parts of the library rely on.
The core components consist of:
Core
Widget
Mouse
Position
The core
file sets up the construct that all components use to function, and adds some core functionality which is shared by all of the library components, such as keyboard mappings, parent-scrolling, and a z-index manager. This file isn't designed to be used standalone, and exposes no functionality that can be used outside of another component.
The interaction helpers are comprised of the following components:
Draggable
Droppable
Resizable
Selectable
Sortable
The higher-level widgets (at the time of writing) include:
Accordion
Autocomplete
Button
Datepicker
Dialog
Progressbar
Slider
Tabs
The widget factory literally creates the basis for all of the visible widgets exposed by the library. It implements the shared API common to all widgets, such as the create and destroy methods, and provides the event callback logic. It also allows us to create custom jQuery UI widgets which inherit the shared API.
Apart from these components and interaction-helpers, there are also a series of UI effects that produce different animations or transitions on targeted elements on the page. These are excellent for adding flair and style to our pages. We'll be looking at these effects in the final chapter of the book.
The great thing about jQuery UI's simplified API is that once you have learned to use all of the existing components (as this book will show you), you'll be able to pick up any new components very quickly. As this book is being written, there are already a number of new components nearing release, with many more in the pipeline, and all of these components will automatically be ThemeRoller-ready.
Like jQuery itself, jQuery UI supports all of the major browsers in use today, including the following:
IE6, IE7, IE8, and IE9
Firefox 2, Firefox 3, and Firefox 4, and Firefox 5
Opera 9, Opera 10, and Opera 11
Safari 3, Safari 4, and Safari 5
Chrome 1 to Chrome 9
The widgets are built from semantically correct HTML elements generated, as needed by the components. Therefore, we won't see excessive or unnecessary elements being created or used.
The library is as flexible as standard JavaScript. By this, I mean that there is often more than one way of doing the same thing, or achieving the same end. For example, the callback events used in the configuration objects for different components, can usually take either references to functions or inline anonymous functions, and use them with equal ease-and-efficiency.
In practice, it is advisable to keep your code as minimal as possible (which jQuery can really help with anyway). But to make the examples more readable and understandable, we'll be separating as much of the code as possible into discrete modules. Therefore, callback functions and configuration objects will be defined separately from the code that calls or uses them.
To reduce the number of files that we have to create and work with, all of the JavaScript will go into the host HTML page on which it runs, as opposed to in separate files. Please keep in mind that this is not advisable for production websites. When scripts reside within external js
files, the browser is able to cache them for vastly improved loading speeds. When scripts are in the <body>
element of a page, the browser cannot store them in the cache.
I'd also just like to make it clear that the main aim throughout the course of this book is to learn how to use the different components that make up jQuery UI. If an example seems a little convoluted, it may simply be that this is the easiest way to expose the functionality of a particular method or property, as opposed to a situation that we would find ourselves coding for in regular implementations.
I'd like to add here that the jQuery UI library is currently undergoing a rapid period of expansion and development. It is also constantly growing and evolving, with bug fixes and feature enhancements continually being added. It would be impossible to keep entirely up-to-date with this aggressive expansion and cover components that are literally about to be released.
Like jQuery, the jQuery UI library is dual licensed under the MIT and GPL open source licenses. These are both very unrestrictive licenses that allow the creators of the library to take credit for its production and retain intellectual rights over it, without preventing us as developers from using the library in any way that we like on any type of site.
The MIT license explicitly states that users of the software (jQuery UI in this case) are free to use, copy, merge, modify, publish, distribute, sublicense, and sell. This lets us do pretty much whatever we want with the library. The only requirement imposed by this license is that we must keep the original copyright and warranty statements intact.
This is an important point to make. You can take the library and do whatever you like with it. Build applications on top of the library and then sell those applications, or give them away for free. Put the library in embedded systems like cell phone OS and sell those. But whatever you do, leave the original text file with John Resig's name present in it. You may also duplicate it word-for-word in the help files or documentation of your application.
The MIT license is very lenient, but because it is not copyrighted itself, we are free to change it. We could therefore demand that users of our software give attribution to us instead of the jQuery team, or pass off the code as our own.
The GPL license is copyrighted, and offers an additional layer of protection for the library's creators and the users of our software. jQuery is provided for free and is open source. The GPL license ensures that it will always remain that way, regardless of the environment it may end up in, and that the original creators of the library are given the credit they deserve. Again, the original GPL license file must be available in some form, within your application or site.
The licenses are not there to restrict us in any way, and are not the same as the kind of license that comes with software you might purchase and install on your own computer. In most cases, how the library is licensed will not be a consideration when using it. Plugin authors, however, will want to ensure that their plugins are released under a similar license.
Once you've worked with one of the components from the library, you'll instantly feel at home when working with any of the other components, since the methods of each component are called in exactly the same way.
The API for each component consists of a series of different methods. While these are all technically methods, it may be useful to categorize them based on their particular function.
Methods are consistently called throughout each of the different components by passing the method that we'd like to call, as a simple string to the component's plugin
method, with any arguments that the method accepts passed as strings after the method name.
For example, to call the destroy
method of the accordion component, we would simply do the following:
$("#someElement").accordion("destroy");
See how easy that was? Every single method exposed by all of the different components, is called in this same simple way.
Some methods, like standard JavaScript functions, accept arguments that trigger different behavior in the component. If we wanted to call the disable
method on a particular tab in the tabs widget for example, we would do the following:
$("#someElement").tabs("disable", 1);
The disable
method, when used in conjunction with the tabs widget, accepts an integer, which refers to the index of the individual tab within the widget. Similarly, to enable the tab again we would use the
enable
method:
$("#someElement").tabs("enable", 1);
Again, we supply an argument to modify how the method is used. Sometimes the arguments that are passed to the method vary between components. The accordion widget, for example, does not enable or disable individual accordion panels, only the whole widget, so no additional arguments following the method name are required.
The option
method is slightly more complex than the other common methods, but it's also more powerful and is just as easy-to-use. The method is used to either get or set any configurable option, after the component has been initialized.
To use the option method in getter
mode to retrieve the current value of an option, we could use the following code:
$("#someElement").accordion("option", "navigation");
This code would return the current value of the navigation
option of the accordion widget. So to trigger getter
mode, we just supply the option name that we'd like to retrieve.
In order to use the option
method in setter
mode instead, we can supply the option name and the new value as arguments:
$("#someElement").accordion("option", "navigation", true);
This code would set the value of the navigation
option to true
. Note that, an object literal can also be passed to the option
method in order to set several different options at once, for example:
$("#someElement").accordion("option", { navigation: true, autoHeight: false });
As you can see, although the option
method gives us the power to both get and set configuration options, it still retains the same easy-to-use format of the other methods.
Using jQuery UI feels just like using jQuery and having built up confidence coding with jQuery, moving on to jQuery UI is the next logical step to take.
The API for each component also contains a rich event model that allows us to easily react to different interactions. Each component exposes its own set of unique custom events, yet the way in which these events are used is the same, regardless of which event is used.
We have two ways of working with events in jQuery UI. Each component allows us to add callback functions that are executed when the specified event is fired, as values for configuration options. For example, to use the select
event of the tabs widget, which is fired every time a tab is selected, we could use the following code:
var config = { select: function() { } };
The name of the event is used as the option
name and an anonymous function is used as the option
value. We'll look at all of the individual events that are used with each component in later chapters.
The other way of working with events is to use jQuery's bind()
method. To use events in this way, we simply specify the name of the component followed by the name of the event:
$("#someElement").bind("tabsselect", function() { });
Usually, but not always, callback functions used with the bind()
method are executed after the event has been fired, while callbacks specified using configuration options are executed directly before the event is fired.
The callback functions are called in the context of the DOMElement that triggered the event. For example, in a tabs widget with several tabs, the select
event will be triggered by the actual tab that is selected, not the tabs widget as a whole. This is extremely useful to us, because it allows us to associate the event with a particular tab.
Some of the custom events fired by jQuery UI components are cancellable and if stopped, can be used to prevent certain actions from taking place. The best example of this (which we'll look at later in the book) is preventing a dialog widget from closing, by returning false
in the callback function of the beforeclose
event:
beforeclose: function() { if (readyToClose === false) { return false }
If the arbitrary condition in this example was not met, false
would be returned by the callback function and the dialog would remain open. This is an excellent and powerful feature that can give us fine-grained control over each widget's behavior.
Any anonymous functions that we supply as callback functions to the different events, automatically pass two arguments, the original event object, and an object containing useful information about the widget. The information contained with the second object varies between components. We'll look at it in greater detail in later chapters.
To use these two objects we just specify them as arguments to the function:
select: function(e, ui) { e.target ui.index }
Every single component will automatically supply these objects to any callback functions we define.
jQuery UI removes the difficulty of building engaging and effective user interfaces. It provides a range of components that can quickly and easily be used out of the box with little configuration. They each expose a comprehensive set of properties and methods for integration with your pages or applications, if a more complex configuration is required.
Each component is designed to be efficient, lightweight, and semantically correct, along with making use of the latest object-oriented features of JavaScript. When combined with jQuery, it provides an awesome addition to any web developer's toolkit.
So far, we've seen how the library can be obtained, how your system can be set up to utilize it, and how the library is structured. We've also looked at how the different widgets can be themed or customized, how the API simply and consistently exposes the library's functionality, and the different categories of component.
We've covered some important topics during the course of this chapter, but now we can get on with using the components of jQuery UI and get down to some proper coding.