|
109 | 109 |
|
110 | 110 | <h3>Instance</h3> |
111 | 111 |
|
112 | | - <p>The widget's instance is stored using <a href="//api.jquery.com/jQuery.data/"><code>jQuery.data()</code></a> with the widget's full name as the key. Therefore, you can use the following to retrieve the progressbar widget's instance object from the element.</p> |
| 112 | + <p>The widget's instance can be retrieved from a given element using the <a href="#method-instance"><code>instance()</code></a> method.</p> |
113 | 113 |
|
114 | 114 | <pre><code> |
115 | | - $( "#elem" ).data( "ui-progressbar" ); |
| 115 | + $( "#elem" ).progressbar( "instance" ); |
116 | 116 | </code></pre> |
117 | 117 |
|
118 | | - <p>Whether an element has a given widget bound to it can be determined using the <a href="/data-selector/"><code>:data</code></a> selector.</p> |
| 118 | + <p>If the <code>instance()</code> method is called on an element that is not associated with the widget, <code>undefined</code> is returned.</p> |
| 119 | + |
| 120 | + <pre><code> |
| 121 | + $( "#not-a-progressbar" ).progressbar( "instance" ); // undefined |
| 122 | + </code></pre> |
| 123 | + |
| 124 | + <p>The instance is stored using <a href="//api.jquery.com/jQuery.data/"><code>jQuery.data()</code></a> with the widget's full name as the key. Therefore, the <a href="/data-selector/"><code>:data</code></a> selector can also determine whether an element has a given widget bound to it.</p> |
119 | 125 |
|
120 | 126 | <pre><code> |
121 | 127 | $( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true |
122 | 128 | $( "#elem" ).is( ":data( 'ui-draggable' )" ); // false |
123 | 129 | </code></pre> |
124 | 130 |
|
| 131 | + <p>Unlike <code>instance()</code>, <code>:data</code> can be used even if the widget being tested for has not loaded.</p> |
| 132 | + |
| 133 | + <pre><code> |
| 134 | + $( "#elem" ).nonExistentWidget( "instance" ); // TypeError |
| 135 | + $( "#elem" ).is( ":data( 'ui-nonExistentWidget' )" ); // false |
| 136 | + </code></pre> |
| 137 | + |
125 | 138 | <p>You can also use <code>:data</code> to get a list of all elements that are instances of a given widget.</p> |
126 | 139 |
|
127 | 140 | <pre><code> |
|
181 | 194 | <xi:include href="../includes/widget-option-show.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
182 | 195 | </options> |
183 | 196 | <methods suppress-auto-examples="true"> |
184 | | - <method name="destroy"> |
185 | | - <desc> |
186 | | - Removes the <placeholder name="name"/> functionality completely. This will return the element back to its pre-init state. |
187 | | - </desc> |
188 | | - <example> |
189 | | - <desc>Destroy the widget when any of its anchors are clicked.</desc> |
190 | | - <code><![CDATA[ |
191 | | -this._on( this.element, { |
192 | | - "click a": function( event ) { |
193 | | - event.preventDefault(); |
194 | | - this.destroy(); |
195 | | - } |
196 | | -}); |
197 | | -]]></code> |
198 | | - </example> |
199 | | - </method> |
200 | | - <method name="disable"> |
201 | | - <desc> |
202 | | - Disables the <placeholder name="name"/>. |
203 | | - </desc> |
204 | | - <example> |
205 | | - <desc>Disable the widget when any of its anchors are clicked.</desc> |
206 | | - <code><![CDATA[ |
207 | | -this._on( this.element, { |
208 | | - "click a": function( event ) { |
209 | | - event.preventDefault(); |
210 | | - this.disable(); |
211 | | - } |
212 | | -}); |
213 | | -]]></code> |
214 | | - </example> |
215 | | - </method> |
216 | | - <method name="enable"> |
217 | | - <desc> |
218 | | - Enables the <placeholder name="name"/>. |
219 | | - </desc> |
220 | | - <example> |
221 | | - <desc>Enable the widget when any of its anchors are clicked.</desc> |
222 | | - <code><![CDATA[ |
223 | | -this._on( this.element, { |
224 | | - "click a": function( event ) { |
225 | | - event.preventDefault(); |
226 | | - this.enable(); |
227 | | - } |
228 | | -}); |
229 | | -]]></code> |
230 | | - </example> |
231 | | - </method> |
232 | | - <method name="option" return="jQuery"> |
233 | | - <desc> |
234 | | - Sets one or more options for the <placeholder name="name"/>. |
235 | | - </desc> |
236 | | - <signature return="Object" example-return-var="isDisabled" example-params='"disabled"'> |
237 | | - <desc>Gets the value currently associated with the specified <code>optionName</code>.</desc> |
238 | | - <argument name="optionName" type="String"> |
239 | | - <desc>The name of the option to get.</desc> |
240 | | - </argument> |
241 | | - <example> |
242 | | - <desc>Retrieve the value of the <code>width</code> option.</desc> |
243 | | - <code><![CDATA[ |
244 | | -this.option( "width" ); |
245 | | -]]></code> |
246 | | - </example> |
247 | | - </signature> |
248 | | - <signature return="PlainObject" example-return-var="options"> |
249 | | - <desc>Gets an object containing key/value pairs representing the current <placeholder name="name"/> options hash.</desc> |
250 | | - <example> |
251 | | - <desc>Log the key and value of each of the widget's options for debugging.</desc> |
252 | | - <code><![CDATA[ |
253 | | -var options = this.option(); |
254 | | -for ( var key in options ) { |
255 | | - console.log( key, options[ key ] ); |
256 | | -} |
257 | | -]]></code> |
258 | | - </example> |
259 | | - </signature> |
260 | | - <signature example-params='"disabled", true'> |
261 | | - <desc>Sets the value of the <placeholder name="name"/> option associated with the specified <code>optionName</code>.</desc> |
262 | | - <argument name="optionName" type="String"> |
263 | | - <desc>The name of the option to set.</desc> |
264 | | - </argument> |
265 | | - <argument name="value" type="Object"> |
266 | | - <desc>A value to set for the option.</desc> |
267 | | - </argument> |
268 | | - <example> |
269 | | - <desc>Set the <code>width</code> option to <code>500</code>.</desc> |
270 | | - <code><![CDATA[ |
271 | | -this.option( "width", 500 ); |
272 | | -]]></code> |
273 | | - </example> |
274 | | - </signature> |
275 | | - <signature example-params="{ disabled: true }"> |
276 | | - <desc>Sets one or more options for the <placeholder name="name"/>.</desc> |
277 | | - <argument name="options" type="Object"> |
278 | | - <desc>A map of option-value pairs to set.</desc> |
279 | | - </argument> |
280 | | - <example> |
281 | | - <desc>Set the <code>height</code> and <code>width</code> options to <code>500</code>.</desc> |
282 | | - <code><![CDATA[ |
283 | | -this.option({ |
284 | | - width: 500, |
285 | | - height: 500 |
286 | | -}); |
287 | | -]]></code> |
288 | | - </example> |
289 | | - </signature> |
290 | | - </method> |
291 | | - <method name="widget" return="jQuery" example-return-var="widget"> |
292 | | - <desc> |
293 | | - Returns a <code>jQuery</code> object containing the <placeholder name="widget-element"/>. |
294 | | - </desc> |
295 | | - <example> |
296 | | - <desc>Place a red border around the widget's original element when it's created.</desc> |
297 | | - <code><![CDATA[ |
298 | | -_create: function() { |
299 | | - this.widget().css( "border", "2px solid red" ); |
300 | | -} |
301 | | -]]></code> |
302 | | - </example> |
303 | | - </method> |
| 197 | + <xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
| 198 | + <xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
| 199 | + <xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
| 200 | + <xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
| 201 | + <xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
| 202 | + <xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> |
304 | 203 | <method name="_create"> |
305 | 204 | <desc> |
306 | 205 | The <code>_create()</code> method is the widget's constructor. |
|
0 commit comments