Skip to content

Commit 4bb2f69

Browse files
scottgonzalezjzaefferer
scottgonzalez
authored and
jzaefferer
committed
jQuery.widget: Document 1.11's instance method for all widgets
1 parent c26b3b2 commit 4bb2f69

17 files changed

+43
-123
lines changed

‎entries/accordion.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,7 @@
175175
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
176176
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
177177
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
178+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
178179
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
179180
<method name="refresh">
180181
<desc>Process any headers and panels that were added or removed directly in the DOM and recompute the height of the accordion panels. Results depend on the content and the <a href="#option-heightStyle"><code>heightStyle</code></a> option.</desc>

‎entries/autocomplete.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,7 @@
166166
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
167167
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
168168
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
169+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
169170
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
170171
<method name="search" example-params='""'>
171172
<desc>Triggers a <a href="#event-search"><code>search</code></a> event and invokes the data source if the event is not canceled. Can be used by a selectbox-like button to open the suggestions when clicked. When invoked with no parameters, the current input's value is used. Can be called with an empty string and <code>minLength: 0</code> to display all items.</desc>

‎entries/button.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@
7070
<method name="refresh">
7171
<desc>Refreshes the visual state of the button. Useful for updating button state after the native element's checked or disabled state is changed programmatically.</desc>
7272
</method>
73+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
7374
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
7475
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
7576
</methods>

‎entries/dialog.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -312,6 +312,7 @@
312312
<method name="open">
313313
<desc>Opens the dialog.</desc>
314314
</method>
315+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
315316
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
316317
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
317318
</methods>

‎entries/draggable.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,7 @@
205205
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
206206
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
207207
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
208+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
208209
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
209210
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
210211
</methods>

‎entries/droppable.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,7 @@
135135
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
136136
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
137137
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
138+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
138139
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
139140
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
140141
</methods>

‎entries/jQuery.widget.xml

Lines changed: 22 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -109,19 +109,32 @@
109109

110110
<h3>Instance</h3>
111111

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>
113113

114114
<pre><code>
115-
$( "#elem" ).data( "ui-progressbar" );
115+
$( "#elem" ).progressbar( "instance" );
116116
</code></pre>
117117

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>
119125

120126
<pre><code>
121127
$( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true
122128
$( "#elem" ).is( ":data( 'ui-draggable' )" ); // false
123129
</code></pre>
124130

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+
125138
<p>You can also use <code>:data</code> to get a list of all elements that are instances of a given widget.</p>
126139

127140
<pre><code>
@@ -181,126 +194,12 @@
181194
<xi:include href="../includes/widget-option-show.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
182195
</options>
183196
<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"/>
304203
<method name="_create">
305204
<desc>
306205
The <code>_create()</code> method is the widget's constructor.

‎entries/menu.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,7 @@
150150
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
151151
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
152152
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
153+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
153154
<method name="expand">
154155
<desc>
155156
Opens the sub-menu below the currently active item, if one exists.

‎entries/progressbar.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@
7070
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
7171
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
7272
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
73+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
7374
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
7475
<method name="value">
7576
<desc>Gets or sets the current value of the progressbar.</desc>

‎entries/resizable.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,7 @@
192192
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
193193
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
194194
<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"/>
195196
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
196197
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
197198
</methods>

‎entries/selectable.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@
9797
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
9898
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
9999
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
100+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
100101
<method name="refresh">
101102
<desc>Refresh the position and size of each selectee element. This method can be used to manually recalculate the position and size of each selectee when the <a href="#option-autoRefresh"><code>autoRefresh</code></a> option is set to <code>false</code>.</desc>
102103
</method>

‎entries/slider.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,7 @@
128128
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
129129
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
130130
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
131+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
131132
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
132133
<method name="value">
133134
<desc>Get or set the value of the slider.</desc>

‎entries/sortable.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -226,6 +226,7 @@
226226
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
227227
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
228228
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
229+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
229230
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
230231
<method name="refresh">
231232
<desc>Refresh the sortable items. Triggers the reloading of all sortable items, causing new items to be recognized.</desc>

‎entries/spinner.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,7 @@
110110
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
111111
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
112112
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
113+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
113114
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
114115
<method name="pageDown">
115116
<desc>

‎entries/tabs.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,7 @@
261261
</type>
262262
</argument>
263263
</method>
264+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
264265
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
265266
<method name="refresh">
266267
<desc>Process any tabs that were added or removed directly in the DOM and recompute the height of the tab panels. Results depend on the content and the <a href="#option-heightStyle"><code>heightStyle</code></a> option.</desc>

‎entries/tooltip.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@
9797
Programmatically open a tooltip. This is only intended to be called for non-delegated tooltips.
9898
</desc>
9999
</method>
100+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
100101
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
101102
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
102103
</methods>

‎includes/widget-method-instance.xml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<?xml version="1.0"?>
2+
<method name="instance">
3+
<desc>
4+
Retrieves the <placeholder name="name"/>'s instance object.
5+
</desc>
6+
</method>

0 commit comments

Comments
 (0)