|
| 1 | +--- |
| 2 | +title: How jQuery UI Works |
| 3 | +level: Beginner |
| 4 | +--- |
| 5 | + |
| 6 | +jQuery UI contains many widgets that maintain [state](http://en.wikipedia.org/wiki/State_%28computer_science%29) and therefore may have a slightly different usage pattern than typical jQuery plugins you are already used to. While the initialization is the same as most jQuery plugins, jQuery UI's widgets are built on top of the [Widget Factory](/jquery-ui/widget-factory/) which provides the same general API to all of them. So if you learn how to use one, then you'll know how to use all of them! This document will walk you through the common functionality, using the [progressbar](http://jqueryui.com/progressbar/) widget for the code examples. |
| 7 | + |
| 8 | +## Initialization |
| 9 | + |
| 10 | +In order to track the state of the widget, we must introduce a full life cycle for the widget. |
| 11 | +The life cycle starts when the widget is initalized. |
| 12 | +To initialize a widget, we simply call the plugin on one or more elements. |
| 13 | + |
| 14 | +``` |
| 15 | + $( "#elem" ).progressbar(); |
| 16 | +``` |
| 17 | + |
| 18 | +This will initialize each element in the jQuery object, in this case the element with an id of "elem". |
| 19 | +Because we called the `progressbar()` method with no parameters, the widget is initialized with its default options. |
| 20 | +We can pass a set of options during initialization in order to override the default options. |
| 21 | + |
| 22 | +``` |
| 23 | + $( "#elem" ).progressbar({ value: 20 }); |
| 24 | +``` |
| 25 | + |
| 26 | +We can pass as many or as few options as we want during initialization. |
| 27 | +Any options that we don't pass will just use their default values. |
| 28 | + |
| 29 | +The options are part of the widget's state, |
| 30 | +so we can set options after initialization as well. |
| 31 | +We'll see this later with the `option` method. |
| 32 | + |
| 33 | +## Methods |
| 34 | + |
| 35 | +Now that the widget is initialized, we can query its state or perform actions on the widget. |
| 36 | +All actions after initialization take the form of a method call. |
| 37 | +To call a method on a widget, we pass the name of the method to the jQuery plugin. |
| 38 | +For example, to call the `value` method on our progressbar widget, we would use: |
| 39 | + |
| 40 | +``` |
| 41 | + $( "#elem" ).progressbar( "value" ); |
| 42 | +``` |
| 43 | + |
| 44 | +If the method accepts parameters, we can pass them after the method name. |
| 45 | +For example, to pass the parameter `40` to the `value` method, we can use: |
| 46 | + |
| 47 | +``` |
| 48 | + $( "#elem" ).progressbar( "value", 40 ); |
| 49 | +``` |
| 50 | + |
| 51 | +Just like other methods in jQuery, most widget methods return the jQuery object for chaining. |
| 52 | + |
| 53 | +``` |
| 54 | + $( "#elem" ) |
| 55 | + .progressbar( "value", 90 ) |
| 56 | + .addClass( "almost-done" ); |
| 57 | +``` |
| 58 | + |
| 59 | +### Common Methods |
| 60 | + |
| 61 | +Each widget will have its own set of methods based on the functionality that the widget provides. |
| 62 | +However, there are a few methods that exist on all widgets. |
| 63 | + |
| 64 | +#### option |
| 65 | + |
| 66 | +As we mentioned earlier, we can change options after initialization through the `option` method. |
| 67 | +For example, we can change the progressbar's value to 30 by calling the `option` method. |
| 68 | + |
| 69 | +``` |
| 70 | + $( "#elem" ).progressbar( "option", "value", 30 ); |
| 71 | +``` |
| 72 | + |
| 73 | +Note that this is different from the previous example where we were calling the `value` method. |
| 74 | +In this example, we're calling the `option` method and saying that we want to change the value option to 30. |
| 75 | + |
| 76 | +We can also get the current value for an option. |
| 77 | + |
| 78 | +``` |
| 79 | + $( "#elem" ).progressbar( "option", "value" ); |
| 80 | +``` |
| 81 | + |
| 82 | +In addition, we can update multiple options at once by passing an object to the `option` method. |
| 83 | + |
| 84 | +``` |
| 85 | + $( "#elem" ).progressbar( "option", { |
| 86 | + value: 100, |
| 87 | + disabled: true |
| 88 | + }); |
| 89 | +``` |
| 90 | + |
| 91 | +You may have noticed that the `option` method has the same signature as getters and setters in jQuery core, such as `.css()` and `.attr()`. |
| 92 | +The only difference is that you have to pass the string "option" as the first parameter. |
| 93 | + |
| 94 | +#### disable |
| 95 | + |
| 96 | +As you might guess, the `disable` method disables the widget. |
| 97 | +In the case of progressbar, this changes the styling to make the progressbar look disabled. |
| 98 | + |
| 99 | +``` |
| 100 | + $( "#elem" ).progressbar( "disable" ); |
| 101 | +``` |
| 102 | + |
| 103 | +Calling the `disable` method is equivalent to setting the `disabled` option to `true`. |
| 104 | + |
| 105 | +#### enable |
| 106 | + |
| 107 | +The `enable` method is the opposite of the `disable` method. |
| 108 | + |
| 109 | +``` |
| 110 | + $( "#elem" ).progressbar( "enable" ); |
| 111 | +``` |
| 112 | + |
| 113 | +Calling the `enable` method is equivalent to setting the `disabled` option to `false`. |
| 114 | + |
| 115 | +#### destroy |
| 116 | + |
| 117 | +If you no longer need the widget, you can destroy it and return back to the original markup. |
| 118 | +This ends the life cycle of the widget. |
| 119 | + |
| 120 | +``` |
| 121 | + $( "#elem" ).progressbar( "destroy" ); |
| 122 | +``` |
| 123 | + |
| 124 | +Once you destroy a widget, you can no longer call any methods on it unless you initialize the widget again. |
| 125 | +If you're removing the element, either directly via `.remove()` or by modifying an ancestor with `.html()` or `.empty()`, |
| 126 | +the widget will automatically destroy itself. |
| 127 | + |
| 128 | +#### widget |
| 129 | + |
| 130 | +Some widgets generate wrapper elements, or elements disconnected from the original element. |
| 131 | +In these cases, the `widget` method will return the generated element. |
| 132 | +In cases like the progressbar, where there is no generated wrapper, the `widget` method returns the original element. |
| 133 | + |
| 134 | +``` |
| 135 | + $( "#elem" ).progressbar( "widget" ); |
| 136 | +``` |
| 137 | + |
| 138 | +## Events |
| 139 | + |
| 140 | +All widgets have events associated with their various behaviors to notify you when the state is changing. |
| 141 | +For most widgets, when the events are triggered, the names are prefixed with the widget name. |
| 142 | +For example, we can bind to progressbar's change event which is triggered whenever the value changes. |
| 143 | + |
| 144 | +``` |
| 145 | + $( "#elem" ).bind( "progressbarchange", function() { |
| 146 | + alert( "The value has changed!" ); |
| 147 | + }); |
| 148 | +``` |
| 149 | + |
| 150 | +Each event has a corresponding callback, which is exposed as an option. |
| 151 | +We can hook into progressbar's `change` callback instead of binding to the `progressbarchange` event, if we wanted to. |
| 152 | + |
| 153 | +``` |
| 154 | + $( "#elem" ).progressbar({ |
| 155 | + change: function() { |
| 156 | + alert( "The value has changed!" ); |
| 157 | + } |
| 158 | + }); |
| 159 | +``` |
| 160 | + |
| 161 | +### Common Events |
| 162 | + |
| 163 | +While most events will be widget specific, all widgets have a `create` event. |
| 164 | +This event will be triggered immediately after the widget is created. |
0 commit comments