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