jQuery UI API - Widget Factory

Category

Utilities | Widgets

jQuery.widget( name [, base ], prototype ) Usage

Description: Create stateful jQuery plugins using the same abstraction as all jQuery UI widgets.

You can use the $.Widget object as the base to inherit from, or you can explicitly inherit from existing jQuery UI or third-party widgets and create new widgets from scratch. Defining a widget with the same name to inherit from the base widget allows you to extend the widget appropriately.

jQuery UI contains many stateful widgets, so it uses a slightly different pattern than typical jQuery plugins. All jQuery UI widgets use the same pattern, which is defined by the Widget Factory. So, once you learn to use one widget, you know how to use the others.

Note: This section uses the Progressbar Widget to demonstrate examples, but the syntax applies to every widget.

Initialization

To keep track of the state of the widget, we need to introduce the full life cycle of the widget. The life cycle starts when the widget is initialized. To initialize a widget, we simply call the plugin on one or more elements.

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

This will initialize each element in the jQuery object. In the example above, the element has the id "elem".

Options

Since the progressbar() call is made without arguments, the widget is initialized with the default options. We can pass a set of options during initialization to override the defaults:

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

You can pass as many options as you like, and any options you do not pass will use their default values.

You can pass multiple option arguments, and they will be merged into a single object (similar to $.extend( true, target, object1, objectN )). This is useful for overriding some settings for all instances and sharing options between instances:

var options = { modal: true, show: "slow" };
$( "#dialog1" ).dialog( options );
$( "#dialog2" ).dialog( options, { autoOpen: false });

All options passed during initialization are deep-copied, ensuring that subsequent modifications to the object do not affect the widget. Arrays are the only exception, as they are referenced as-is. This exception is to support data binding properly, where the data source must be referenced.

Default values are stored in the widget's property, so we can override the values set by jQuery UI. For example, after the following setting, all future progressbar instances will default to a value of 80:

$.ui.progressbar.prototype.options.value = 80;

Options are part of the widget's state, so we can also set options after initialization. We will see 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 performed as method calls. To call a method on a widget, we pass the name of the method 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:

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

Each widget has its own method settings, which are based on the functionality provided by the widget. However, there are some methods that exist on all widgets, which will be explained in detail below.

Events

All widgets have events related to their various behaviors to notify you when their state changes. For most widgets, when an event is triggered, the name is prefixed with the lowercase name of the widget. For example, we can bind the change event of a progress bar, which is triggered when the value changes.

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

Each event has a corresponding callback, which serves as an option. If needed, we can catch the change callback of the progress bar without binding the progressbarchange event.

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

All widgets have a change event that is triggered upon instantiation.

Instantiation

Widget instances are stored using the full widget name as the key with jQuery.data(). Therefore, you can retrieve the instance object of the Progressbar Widget from the element using the following code.

$( "#elem" ).data( "ui-progressbar" );

To check if an element is bound to a given widget, you can use the :data selector.

$( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true
$( "#elem" ).is( ":data( 'ui-draggable' )" ); // false

You can also use :data to get a list of all elements that are instances of a given widget.

$( ":data( 'ui-progressbar' )" );

Properties

All widgets have the following properties:

• defaultElement: The element to use when constructing a widget instance without providing an element. For example, since the defaultElement of the progress bar is "<div>", $.ui.progressbar({ value: 50 }) instantiates a progress bar widget instance on a newly created <div>.

• document: The document that contains the widget element. Useful when interacting with the widget within an iframe.

• element: A jQuery object containing the element used to instantiate the widget. If you select multiple elements and call .myWidget(), a separate widget instance will be created for each element. Therefore, this property always contains one element.

• namespace: The location of the widget prototype in the global jQuery object. For example, a namespace of "ui" indicates that the widget prototype is stored in $.ui.

• options: An object containing the options currently used by the widget. Any options provided by the user at instantiation are automatically merged with the defaults defined in $.myNamespace.myWidget.prototype.options. User-specified options override the defaults.

• uuid: A unique integer representing the control identifier.

• version: The string version of the widget. For jQuery UI widgets, this property is set to the version of jQuery UI used by the widget. Plugin developers must explicitly set this property in their prototype.

• widgetEventPrefix: The prefix added to the widget event names. For example, the widgetEventPrefix of the Draggable Widget is "drag", so when creating a draggable, the event name is "dragcreate". By default, the widgetEventPrefix of a widget is its name. Note: This property is deprecated and will be removed in future versions. Event names will be changed to widgetName:eventName (e.g.,

• widgetFullName: The full name of the widget including the namespace. For $.widget( "myNamespace.myWidget", {} ), widgetFullName will be "myNamespace-myWidget". -widgetName: The name of the widget. For $.widget( "myNamespace.myWidget", {} ), widgetName will be "myWidget".

-window: The window that contains the widget element. Useful when interaction with the widget is needed within a frame.

jQuery.Widget Basic Widget Usage

Description: The base widget used by the Widget Factory.

Quick Navigation