Plugins

While jQuery itself provides many amazing capabilities, we still need to develop the logic to do various things. But why recreate the wheel, so to speak, when someone else has already done the work and made it available to us to use. jQuery plugins provide anything from low level coding assistance to high level interfaces with only a few lines of code. How to use of these plugins is what this section is about.

How to find a plugin

The first challenge of using a plugin is finding one that works for your needs. Start with a visit to the jQuery Plugins page. Take some time to review what is here.

Tip: Click the All Plugins link under the Browse Plugins section on the left. Then use your browser's Find capability (usually CTRL-F) to search for a keyword related to what you are looking for. Use the Find Next option (usually F3) to find the next occurance. You'll find your plugins much quicker.

When you have found an interesting plugin, click on the name of that plugin to go to it's details page. Here you can download the necessary file, go to the Home Page (if one is specified), read the documentation (if available) or view outstanding issues with the plugins. It is a good idea to visit the home page for the plugin as that is usually where you'll find the best documentation.

When you find the plugin you are interested in, download the file and use it in your code.

The jQuery plugin page is NOT the only place to find plugins. There are many on the Net that have not been setup here. A Google Search is also a good starting point. For instance searching for the phrase "jQuery gallery" will also find some gallery type plugins. However using Google this way may mean more time is needed for searching and analyzing what you find. (Great way to learn things though.)

How to use a plugin

We can't tell you how to use EVERY plugin out there, but they all follow a similar pattern to get started. The problem is that each plugin does something different and we can only tell you how to get to the point where the plugin is available for use. Beyond that is highly dependant on the plugin itself. But we can address this somewhat.

  • First, download the desired plugin. If needed, decompress the .zip or .tar.gz file. These files are just a convenience to you when there is more than just the plugin library to download.
  • Examine the home page or documentation for the plugin (sometimes included in the downloaded files). This documentation will usually have detailed instructions on how to setup and use the plugin. If not the steps are usually the same as the following points.
  • If needed, download any other plugins your target plugin depends on. For instance the Autocomplete plugin requires the bgiframe plugin. Decompress these file(s) if needed.
  • Place the downloaded file(s) in a location your web page can access.
  • Include the necessary JavaScript library(ies) into your page.

    <script type="text/javascript" src="path/to/plugin/library.js">

    This line (or lines if you need other plugins or files included) should be placed AFTER where the jQuery file itself is included.
  • If needed, include any required stylesheet files.

    <style type="text/css">@import url(/path/to/stylesheet.css);</style>
    OR
    <link rel="stylesheet" type="text/css" href="/path/to/stylesheet.css" />
  • Call the plugin in your code. For instance, the tablesorter is used on a table element and makes it sortable by clicking the column headers.

    //sample of using the tablesorter plugin
    $("#mytable").tablesorter();
  • Examine the plugin documentation to determine the correct way to use the plugin, and what options may be passed to it.
  • In the event there is no posted documentation for the plugin, it is sometimes found in the plugin library file itself as comments. Failing that you can examine the code directly - in some cases this is very simple to decipher.

Here is a sample of the includes for a live web page that is using multiple plugins.

<script type="text/javascript" src="js/jquery-1.2.1.pack.js"></script>
<script type="text/javascript" src="js/ui.tabs/ui.tabs.js"></script>
<script type="text/javascript" src="js/jqModal.js"></script>
<script type="text/javascript" src="js/jquery.tablesorter.pack.js"></script>
<script type="text/javascript" src="js/jquery-calendar.pack.js"></script>
<script type="text/javascript" src="js/jquery.timeentry.pack.js"></script>
<script type="text/javascript" src="js/jquery.mousewheel.pack.js"></script>
<script type="text/javascript" src="js/jquery.corner.pack.js"></script>
<script type="text/javascript" src="js/myapp.js"></script>
<style>
@import url("js/ui.tabs/ui.tabs.css"); /* tab styles */
@import url("css/jqModal.css"); /* jqModal styles */
@import url("css/blue/style.css"); /* Tablesorter styles */
@import url("css//jquery-calendar.css"); /* datepicker styles */
@import url("css/style.css"); /* application specific styles */
</style>

How to structure a custom plugin

Learning jQuery has an excellent posting on recommended practices when creating a custom plugin. If you are moving beyond a simple plugin, this post is a great guide.

clueTip

The clueTip plugin is a good tool for showing "popup DIVs". These DIVs can contain more information (such as traditional tooltips), or can become part of an applications interface and allow interaction within the popup. The contents of the popup can either be hard coded on the page, or loaded via Ajax.

How to get dynamic content for clueTip popup

The documentation for clueTip is thorough and should be the primary source of information when using clueTip. However there are some topics that are not fully revealed. One such topic is passing dynamic data to an Ajax call, and then modifying the the results when they are retrieved and displayed.

NOTE: All clueTip options are defined at http://plugins.learningjquery.com/cluetip/#options. Please refer to this to learn more about the options used below.

For this sample, imagine you have a number of employee names listed as anchors, and when you click each one you want to see the details for that employee in a popup. We can do this by assigning a common class to these links (we'll use "employeeDetails"), and putting the employee ID into the ID of the anchor tag. To help keep the anchor IDs unique, we'll prefix the employee ID with "employee_". We'll assume the server side code is returning HTML, and that this HTML does not need any further processing before being displayed. And finally, if the user clicks the employee name in the popup, then we'll navigate to an edit page for that employee (interaction with the popup).

  1. First, follow the instructions for getting clueTip setup on your page.
  2. Set up the link with the name of the Ajax file to be called.

    <a href="#" id="employee-123" rel="employeeData.php">Employee</a>
    OR, from in code:
    $(".employeeDetails").attr("rel", "employeeData.php");

    clueTip uses the "rel" attribute to store the file it should call. The attribute used can be changed as an option to the clueTip method, but the default is fine in most cases. Think of the value we specify for the rel attribute to be the same as the "url" property of a $.ajax() call.

  3. Next, call the clueTip method

    $(".employeeDetails").cluetip({
    closePosition : "title",
    sticky : true,
    mouseOutClose : true
    });

    The values we have passed indicates we want a "close" link in the title area of the popup, the popup should not close when we move off the triggering element (make it sticky), but it should close if the mouse moves inside the popup then moves outside.

  4. Next we need to make sure our extra data is passed to the Ajax call. This is done via the ajaxSettings property.

    ajaxSettings : {
    type : "POST",
    data : "id=" + this.id
    }

    The ajaxSettings are identical to the $.ajax() method - except the "error", "success", "complete", and "url" properties.

  5. Finally, we need to assign the event handler so that when the employee name on the popup DIV is clicked, we show an edit page for that employee. This can be done via the onShow property.

    onShow : function () {
    $("#popupEmployeeName").click( function () {
    window.location.href = "editEmployee.php?id=" + this.id;
    $("#cluetip-close").click();
    return false;
    });
    }

    This is saying that when the popup is shown, we want to assign a click event handler to our #popupEmployeeName element. This handler will set the location of the web page, close the clueTip popup (by triggering a click event on the Close link), and prevent any further processing of the click. Our browser should navigate to the desired page at that point.

    The onShow property is the right place to assign event handlers, or do any last minute tweaks to presentation of the data - like setting classes or styles.

    6. Putting it all together, our sample call would look like this:

    $(".employeeDetails").attr("rel", "employeeData.php").cluetip({
    closePosition : "title",
    sticky : true,
    mouseOutClose : true,
    ajaxSettings : {
    type : "POST",
    data : "id=" + this.id
    },
    onShow : function () {
    $("#popupEmployeeName").click( function () {
    window.location.href = "editEmployee.php?id=" + this.id;
    $("#cluetip-close").click();
    return false;
    });
    }
    });

jQuery.UI

jQuery UI is a set of themable widgets and interactions, built on top of the jQuery JavaScript Library, that you can use to build highly interactive web applications.

The core of the library revolves around different mouse interactions, namely drag and dropping, sorting, selecting, and resizing.

Datepicker

The UI Datepicker plugin provides a dynamic and handy popup calendar for selecting dates. It is very flexible and can be configured and themed in different ways.

The definitive sample of what can be done with the Datepicker can be found at the official documentation or at the demo site.

To get started, download the CSS and JavaScript files. Both of these are available via the demo page. (Scroll down a little to the "Use jQuery UI Datepicker" section...).

With these two files, include them AFTER the jQuery library is included.

<script type="text/javascript" src="jquery-1.2.1.packed.js"></script>
<style type="text/css">@import url(ui.datepicker.css);</style>
<script type="text/javascript" src="ui.datepicker.js"></script>

Next you set up an input box to be a date field:

<input type="text" id="start_date">

And finally you apply the datepicker to the field.

<script type="text/javascript">
$(document).ready( function () {
//apply the date picker to the input field
$("#start_date").datepicker();
//
//another sample, with some options
$("#start_date").datepicker({
showOn: 'both',
buttonImageOnly: true,
buttonImage: 'calendar.gif',
buttonText: 'Calendar'
});
});
</script>

The full list of options can be found on the documentation page or via the demo page.