Skip to content

Commit 0a283b7

Browse files
scottgonzalezscottgonzalez
committed
Revert "Revert "jQuery.widget: Documenting 1.11's instance method for all widgets.""
This reverts commit cd2e4fb.
1 parent bf16123 commit 0a283b7

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
@@ -107,19 +107,32 @@
107107

108108
<h3>Instance</h3>
109109

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

112112
<pre><code>
113-
$( "#elem" ).data( "ui-progressbar" );
113+
$( "#elem" ).progressbar( "instance" );
114114
</code></pre>
115115

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

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

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

125138
<pre><code>
@@ -176,126 +189,12 @@
176189
<xi:include href="../includes/widget-option-show.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
177190
</options>
178191
<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"/>
299198
<method name="_create">
300199
<desc>
301200
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
@@ -207,6 +207,7 @@
207207
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
208208
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
209209
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
210+
<xi:include href="../includes/widget-method-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
210211
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
211212
<method name="refresh">
212213
<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)