jQuery UI How It Works

jQuery UI includes many stateful widgets, so it differs slightly from typical jQuery plugin usage patterns. Its installation is similar to most jQuery plugins, with jQuery UI widgets being created based on the Widget Factory, which provides a common API. Therefore, once you learn to use one widget, you know how to use others. This tutorial will introduce common functionalities through the progressbar widget code example.

Installation

To track the widget's state, we first introduce the widget's full lifecycle. The lifecycle begins when the widget is installed. We simply call the plugin on one or more elements to install the widget.

$( "#elem" ).progressbar();

This initializes each element in the jQuery object, in this case, the element with the id "elem". Since we called .progressbar() without parameters, the widget initializes with its default options. We can pass a set of options at installation to override the defaults.

$( "#elem" ).progressbar({ value: 20 });

The number of options passed can vary according to our needs. Any options we don't pass will use their default values.

Options are part of the widget's state, so we can also set options after installation. We will cover this in the option method later.

Methods

Now that the widget is initialized, we can query its state or perform actions on the widget. All actions after initialization are done through method calls. To call a method on a widget, we pass the method name to the jQuery plugin. For example, to call the value method on the progressbar widget, we use:

$( "#elem" ).progressbar( "value" );

If the method accepts arguments, we pass them after the method name. For example, to pass the argument 40 to the value method, we use:

$( "#elem" ).progressbar( "value", 40 );

Like other methods in jQuery, most widget methods return the jQuery object for chaining.

$( "#elem" )
    .progressbar( "value", 90 )
    .addClass( "almost-done" );

Common Methods

Each widget has its own set of methods based on the functionality it provides. However, some methods are common to all widgets.

option

As mentioned earlier, we can change options after initialization using the option method. For example, we can change the progressbar's value to 30 by calling the option method.

$( "#elem" ).progressbar( "option", "value", 30 );

Note that this is different from the previous example where we called the value method. In this example, we call the option method to change the value option to 30.

We can also get the current value of an option.

$( "#elem" ).progressbar( "option", "value" );

Additionally, we can update multiple options at once by passing an object to the option method.

$( "#elem" ).progressbar( "option", {
    value: 100,
    disabled: true
});

You may notice that the option method has the same signature as getter and setter methods in jQuery, like .css() and .attr(). The only difference is that you must pass the string "option" as the first argument.

disable

The disable method disables the widget. In the progressbar example, this changes the style to show the progressbar as disabled.

$( "#elem" ).progressbar( "disable" );

Calling the disable method is equivalent to setting the disabled option to true.

enable

The enable method is the opposite of the disable method.

$( "#elem" ).progressbar( "enable" );

Calling the enable method is equivalent to setting the disabled option to false.

destroy

If you no longer need the widget, you can destroy it, returning to the original markup. This ends the widget's lifecycle.

$( "#elem" ).progressbar( "destroy" );

Once you destroy a widget, you cannot call any methods on that widget unless you initialize it again. If you want to remove the element, you can do so directly with .remove(), or by using .html() or .empty(), and the widget will be automatically destroyed.

widget

Some widgets generate wrapper elements or elements disconnected from the original element. In the example below, widget will return the generated element. In the case of the progressbar instance, there is no generated wrapper, so the widget method returns the original element.

$( "#elem" ).progressbar( "widget" );

Events

All widgets have events associated with their various behaviors, which notify you when the state changes. For most widgets, when an event is triggered, its name is prefixed with the widget name. For example, we can bind the change event of the progressbar, which triggers whenever the value changes.

$( "#elem" ).bind( "progressbarchange", function() {
    alert( "The value has changed!" );
});

Each event has a corresponding callback, which is presented as an option. We can use the change callback of the progressbar, which is equivalent to binding the progressbarchange event.

$( "#elem" ).progressbar({
    change: function() {
        alert( "The value has changed!" );
    }
});

Common Events

Most events are specific to certain widgets, but all widgets have a common create event. This event is triggered when the widget is created.