Introducing the API

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.

Method type	Description
The plugin method	This method is used to initialize the component and is simply the name of the component, followed by parentheses. I will refer to this throughout the book as the plugin method or the widget method.
Shared API methods	The destroy method can be used with any of the components to completely disable the widget being used and in most cases returns the underlying HTML to its original state. The option method is used by all components to get or set any configuration option after initialization. The enable and disable methods are used by most library components to enable or disable the component. The widget method, exposed by all widgets, returns a reference to the current widget.
Specialized methods	Each component has one or more methods unique to that particular component that perform specialized functions.

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 use the following code:

$("#someElement").accordion("destroy");

See how easy that was! Every single method that is exposed by all of the different components is called in this same simple way.

Some methods such as 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 use the following code:

$("#someElement").tabs("disable", 1);

The disable method, when used in conjunction with the tabs widget, accepts an integer that refers to the index of the individual tab within the widget. Similarly, to enable the tab again we would use the enable method as shown in the following code:

$("#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");

The previous code would return the current value of the navigation option of the accordion widget. So to trigger the getter mode, we just supply the option name that we'd like to retrieve.

In order to use the option method in the setter mode instead, we can supply the option name and the new value as arguments:

$("#someElement").accordion("option", "navigation", true);

The previous 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", {
  animate: "bounceslide",
  heightStyle: "fill"
});

As you can see, although the option method gives us the power to use both the get and set configuration options, it still retains the same easy-to-use format of the other methods.

Events and callbacks

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 options = {
  select: function() {
  ...
  }
};
$("#myTabs").tabs(options);

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 the jQuery's on() method. To use events in this way, we simply specify the name of the component followed by the name of the event:

$("#someElement").on("tabsselect", function() {
...
});

Usually, but not always, callback functions used with the on() method are executed after the event has been fired, while callbacks that are 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 and 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 cancelable 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) {
    event.preventDefault();
}

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.

Callback arguments

An important feature of using any widget is its ability to accept callbacks. We can use callbacks to run anonymous functions that perform a specific task. For example, we could fire an alert on screen each time a particular header is clicked in an Accordion widget.

Any anonymous functions that we supply as callback functions to the different events automatically pass two arguments: the original, extended or modified event object, and an object containing useful information about the widget. The information contained in the second object varies between components. As an example, let's take a look at a callback that could be implemented when using the Accordion widget:

$("#myAccordion").accordion({
  activate: function (event, ui) {
    if(ui.newHeader.length > 0){
      alert(ui.newHeader.attr("id"));
    } else {
      // closed
    }
  }
});

Here we've passed the arguments to the function and used them to determine which accordion heading is open, before displaying the result on screen. The same principle of passing these objects to any callback functions that we define applies to all components; we will cover this in detail in later chapters.