The version 1.5 release of jQuery UI was a milestone in the library's history. This was the release in which the API for each component was significantly simplified, making the library both easier to use and more powerful.
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 as follows:
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 tab in the tabs widget for example, we would do the following:
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:
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:
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:
This code would set the value of the navigation
option to true
. 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 that is fired any time a tab is selected, we could use the following code:
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.
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 triggers the event. For example, in a tabs widget with several tabs, the select
event will be fired from the actual tab that is clicked, not the tabs widget as a whole. This is extremely useful to us as developers, 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 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.
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 the widget's behavior.
Any anonymous functions that we supply as callback functions to the different events are automatically passed two objects, 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 this in greater detail in later chapters.
To use these two objects we just specify them as arguments to the function.
Every single component will automatically supply these objects to any callback functions we define.