We're now ready to take a look at jQuery's most popular plugin: UI. UI of course, stands for User Interface. The jQuery UI plugin takes many of the most popular tasks that the developers have already made simple through jQuery, and makes them even simpler. I know, it's hard to imagine it getting any easier, but that's exactly what this plugin does. Most importantly, while the enhanced effects are nice, the UI plugin provides interface widgets and an easy way to style or "theme" them without the need for coding up specific interface elements such as tabs, dialog boxes, and more.
In this chapter, we'll:
- Take a look at the UI plugin and how to get started with it quickly
- Learn how to apply jQuery UI widgets to our WordPress site, make it more intuitive, easier to understand content, and encourage users to take action
- Learn how to implement popular UI features and widgets with common WordPress features
Let's get started.
You can take a tour of the jQuery UI plugin by heading on over to http://www.jqueryui.com.
The UI plugin offers a set of standardized widgets, interactions, and effects. Let's take a look at each type of offering in detail.
The term "widget" within jQuery is a bit different from a WordPress widget, which is a small plugin designed to sit nicely in a sidebar of a theme. Within jQuery's UI plugin, widgets describe a set of fully-featured, user interface controls that are commonly needed in projects and created by jQuery developers. The UI widgets save jQuery developers a lot of time writing jQuery statements and chaining functions together to create the same interface and effect. Here are the interface widget's jQuery UI offers:
- Accordion: This widget expands and collapses content that is broken into logical sections by clicking on the headers of each section. Only one section can be opened at any given time.
- Autocomplete (1.8+): This is a new feature available in version 1.8. The Autocomplete widgets provide suggestions while you type into the field. The suggestion source is provided as a basic JavaScript array.
- Button (1.8+): Also new to 1.8 is the Button widget. This lets you take different types of markup and apply the UI's button styling and functionality to it.
- Datepicker: The Datepicker widget can be applied a standard form input field. Focus on the input field opens an interactive calendar in a small overlay.
- Dialog: This widget is an overlay positioned within the page. It has a title bar and a content area, and can be moved, resized, and closed with the 'x' icon by default or by additional button parameters passed to it.
- Progressbar: The Progressbar widget is designed to simply display the current percentage complete for a process passed to it through a value parameter. It scales to fit inside its parent container by default.
- Slider: The jQuery UI Slider widget turns objects, such as empty
divtags into sliders. There are various options such as multiple handles, and ranges that can then be passed to other objects and functions. You can mouse or use the arrow keys to change the slider's position. - Tabs: The Tabs widget is used to break content into multiple sections that can be swapped by clicking the tab header to save space, much like an accordion.
jQuery UI interactions takes a collection of the more common complex jQuery behaviors that developers need to create, most often for projects, and packages them into convenient and easy-to-use functions as follows:
- Draggable: This interaction makes the selected elements draggable by mouse.
- Droppable: This interaction works with the draggable elements and makes the selected ones droppable (meaning that they accept being dropped on by the draggable elements).
- Resizable: This interaction makes the selected elements resizable by adding visual "handles" to the object. You can specify one or more handles as well as min and max width and height.
- Selectable: This interaction allows elements to be selected by dragging a "lasso" or box with the mouse over the elements.
- Sortable: This makes the selected elements sortable by dragging with the mouse.
The main feature is the .effect() function, but the standard animation functions and shortcuts that are available in jQuery are enhanced with the jQuery UI plugin's "effects core". This core also includes the ability to color, animate, and also include additional easing options; so, if you include it into your project, you won't need the Color or Easing plugins that we've been working with previously. The jQuery effects comprise:
- Effect: This function allows you to assign an effect from a set of 15 to any object.
- Show: This enhanced show method optionally accepts jQuery UI advanced effects.
- Hide: This enhanced hide method optionally accepts jQuery UI advanced effects.
- Toggle: This enhanced toggle method optionally accepts jQuery UI advanced effects.
- Color animation: The Color plugin that we learned about in Chapter 5, jQuery Animation within WordPress, is included into the jQuery UI effects core. Again, it simply extends the
animatefunction to be able to animate colors as well. - Add class: Adds the specified class to each of the set of matched elements with an optional transition between the states.
- Remove class: Removes all or a specified class from each of the set of matched elements with an optional transition between the states.
- Toggle class: Adds the specified class if it is not present, and removes the specified class if it is present, using an optional transition.
- Switch class: Switches from the class defined in the first argument to the class defined as second argument, using an optional transition.
Most of the jQuery UI plugin's main widget and interaction cores are available bundled into your WordPress installation. If you're using WordPress 2.9.2, you've got jQuery 1.3.2 bundled in and the UI plugin core is 1.7.1 and you've also got the following jQuery UI widgets and interactions available: Dialog, Draggable, Droppable, Resizable, Selectable, Sortable, and Tabs.
If you're using WordPress 3.0+, you've got jQuery 1.4.2 bundled in with your installation with the UI core 1.7.3 bundled in. Again, this is with the same widgets and interactions as mentioned in the previous paragraph.
If you'd like to take advantage of the UI plugin's effects or, if you're using jQuery 1.4.2 and want to take advantage of the UI plugin's 1.8+ features, you'll need to include a copy of the UI plugin version 1.8+ separately through your own download from the jQuery's UI site or through Google's CDN.
The advantage of downloading from the jQuery's UI site is you can pick and choose only what you need for your project. If you go to the download page at http://www.jqueryui.com/download, you'll see on the right-hand side that you can pick version 1.7.3 or 1.8.4 and click on the Download button; this will give you everything.
For development purposes, you can just download the whole thing. The ZIP file is over 4 MB but that includes a development bundle directory chock full of examples and documentation; none of that would get loaded into your project.
With all options selected, the actual UI plugin's .js file you'll load into your WordPress project is about 200 KB, and you can count on adding about another 100 KB to the project for your CSS theme depending on what you choose from the site or how you rolled your own. If you know exactly what features you're using, you can shave off some kilobytes by only selecting what you want to use.
The download page is great because it won't let you deselect anything that is dependent on another feature you've selected, and that you'd like to use. This is a screenshot of an alert for selecting something you need:
Tip
Make sure you download the correct UI plugin version for your version of jQuery!
If your project is using WordPress 2.9.2, the bundled version is of jQuery 1.3.2, so you'll want to make sure you download the UI plugin version 1.7.3. If you're using the Google CDN or your own jQuery download version 1.4+, you can download and work with the jQuery UI plugin version 1.8+.
No matter where you're pulling in the UI plugin from, your own download, the Google CDN, or the WordPress bundled UI options, you'll need to provide your own styles for it. You can include one of many great themes into your project or easily "roll" your own to best match your site's design.
On the jQuery's UI site select Themes from the navigation bar, or go to: http://jqueryui.com/themeroller/.
You can tweak the resulting theme's CSS stylesheet directly or by simply loading the jQuery UI stylesheet up before your WordPress stylesheet. Using the WebDeveloper's Toolbar or Firebug in Firefox, it's very easy to see what styles the UI is producing and overwrite them in your main WordPress stylesheet.
By now, you should be pretty comfortable including jQuery plugins into your WordPress sites. Because specific components of the UI plugins are available bundled in WordPress, we'll review getting them into your project in a few different ways.
The jQuery's UI plugin bundled into WordPress is separated out into individual .js files. You'll have to register the UI core file in your project first, as well as each widget or specific interaction that you'd like to include in your project. Again, the only widgets and interactions available are: Dialog, Draggable, Droppable, Resizable, Selectable, Sortable, and Tabs.
To register the core in your WordPress theme:
...
<?php
if (!is_admin()) {//checking for is_admin makes sure that the UI doesn't load in admin
//adding array('jquery') means the ui-core requires jquery
wp_enqueue_script("jquery-ui-core", array('jquery'));
}//end of is_admin
?>
...
Then, register a particular widget you want:
...
<?php
if (!is_admin()) {//checking for is_admin makes sure that the UI doesn't load in admin
//requires jquery AND the ui-core
wp_enqueue_script("jquery-ui-dialog",
array('jquery','jquery-ui-core'));
}//end of is_admin()
?>
...
Just repeat the above code for additional widgets. The widget .js file names are as follows:
jquery-ui-tabs jquery-ui-sortable jquery-ui-draggable jquery-ui-droppable jquery-ui-selectable jquery-ui-resizable jquery-ui-dialog
Note
Again, the full list of bundled JavaScripts for WordPress can be found in the codex: http://codex.wordpress.org/Function_Reference/wp_enqueue_script.
You can include jQuery's UI plugin very similarly to including jQuery via the Google CDN. The UI plugin path is: http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.0/jquery-ui.min.js. Note the bold version number here. You can change it to the version of the UI plugin that you require. If you're using jQuery version 1.3.2, be sure to target 1.7.2. If you're using 1.4.2, you can target 1.8.0.
Let's refresh on how to use wp_register_script to call up a script available from the bundle from Google's CDN:
...
if (!is_admin()) {//checking for is_admin makes sure that UI doesn't load in admin
wp_deregister_script( 'jquery-ui-core' );
wp_register_script( 'jquery-ui-core', 'http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.0/jquery-ui.min.js');
/*this brings over the entire 1.8 core and all widgets, interactions and effects from the Google CDN*/
}//end of is_admin
...
You should note that although we're deregistering the bundled jquery-ui-core file, what we're loading in from the Google CDN is the complete jQuery UI plugin with access to all its widgets, interactions, and effects. It might be wise to add a comment in your code so that the other developers will know that they don't need to register individual widgets and interactions from the bundle into the project.
If you've included the UI into your theme or a plugin directory you'll load it up, again using wp_enqueue_script, using the following methods:
Including a local copy of the UI plugin from a theme:
...
if (!is_admin()) {//checking for is_admin() makes sure that UI doesn't load in admin
wp_enqueue_script('jquery-ui-1.8.custom.min', get_bloginfo('stylesheet_directory') . '/js/jquery-ui-1.8.custom.min.js', array('jquery'), '20100410' );
}//end of is_admin()
...
Again, by adding array('jquery') at the end of the script, this lets WordPress know that jQuery is required, just in case it hasn't already been registered.
To include a local copy of the UI plugin from a WordPress plugin use the wp_register_script function as follows:
...
function myPluginFunction(){
if (!is_admin()) {//checking for is_admin makes sure that the UI doesn't load in admin
wp_register_script('jquery-ui-1.8.custom.min',
WP_PLUGIN_URL . '/js/jquery-ui-1.8.custom.min.js');
}//end of is_admin
}//end of myPluginFunction()
add_action('wp_head', 'myPluginFunction');
...
No matter where you're pulling the UI plugin from, WordPress, Google's CDN, or your own download, you'll need to include CSS styles for the UI plugin. If you didn't play around with the theme roller earlier, go back now and do so. Select a theme or amend one of the themes with the theme roller or just roll your own from scratch to create widgets that look great with your site's existing design.
Once you've done that, you can take your selected theme or custom rolled theme and place it in your theme or a plugin directory. Make sure to include the images directory that comes with the theme. You can then include it using a direct link into your header.php theme file or use the wp_enque_style function we've used before to include it into a plugin or your theme through the functions.php page:
To include a UI theme directly in your WordPress theme, by linking to it directly, use the following:
...
<link rel="stylesheet" href="<?php bloginfo('stylesheet_directory'); ?>/js/smoothness/jquery-ui-1.8.custom.css" type="text/css" media="screen" />
...
Include a UI theme into a WordPress theme from the theme's functions.php page using wp_enqueue_style:
...
<?php
function addUIstyles(){
wp_enqueue_style('ui-theme', bloginfo('stylesheet_directory')
'/js/smoothness/jquery-ui-1.8.custom.css', array('style'), '1.0', 'screen');
}
add_action('init', 'addUIstyles');
?>
...
Including a UI theme into a WordPress plugin using wp_enqueue_style, is similar to the above example, but be sure to use WP_PLUGIN_DIR to target your plugin directory.
...
wp_enqueue_style('ui-theme', WP_PLUGIN_DIR .
.'/js/smoothness/jquery-ui-1.8.custom.css',
array('style'), '1.0', 'screen');
...