Skip to content
Browse files

jQuery.widget: Document that instance can be called on any element to…

… determine whether it is a widget. Fixes #77.

jQuery.widget: More explicit wording to clarify the difference between using :data and instance().

jQuery.widget: Minor updates
  • Loading branch information...
1 parent 06d80fe commit cde5d57d5255b820f34e934b622358371b2c585e @tjvantoll tjvantoll committed
Showing with 20 additions and 5 deletions.
  1. +16 −3 entries/jQuery.widget.xml
  2. +4 −2 includes/widget-method-instance.xml
View
19 entries/jQuery.widget.xml
@@ -87,17 +87,30 @@
<h3>Instance</h3>
- <p>The widget's instance can be retrieved from a given element using the <a href="#method-instance">instance method</a>.</p>
+ <p>The widget's instance can be retrieved from a given element using the <a href="#method-instance"><code>instance()</code></a> method.</p>
<pre><code>
$( "#elem" ).progressbar( "instance" );
</code></pre>
- <p>The instance is stored using <a href="http://api.jquery.com/jQuery.data/"><code>jQuery.data()</code></a> with the widget's full name as the key. Therefore, you can use the <a href="/data-selector"><code>:data</code></a> selector to determine whether an element has a given widget bound to it.</p>
+ <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>
+
+ <pre><code>
+ $( "#not-a-progressbar" ).progressbar( "instance" ); // undefined
+ </code></pre>
+
+ <p>The instance is stored using <a href="http://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>
<pre><code>
$( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true
- $( "#elem" ).is( ":data( 'ui-draggable' )" ); //false
+ $( "#elem" ).is( ":data( 'ui-draggable' )" ); // false
+ </code></pre>
+
+ <p>Unlike <code>instance()</code>, <code>:data</code> can be used even if the widget being tested for has not loaded.</p>
+
+ <pre><code>
+ $( "#elem" ).nonExistentWidget( "instance" ); // TypeError
+ $( "#elem" ).is( ":data( 'ui-nonExistentWidget' )" ); // false
</code></pre>
<p>You can also use <code>:data</code> to get a list of all elements that are instances of a given widget.</p>
View
6 includes/widget-method-instance.xml
@@ -1,6 +1,8 @@
<?xml version="1.0"?>
-<method name="instance">
+<method name="instance" return="Object">
<desc>
- Retrieves the <placeholder name="name"/>'s instance object.
+ <p>Retrieves the <placeholder name="name"/>'s instance object. If the element does not have an associated instance, <code>undefined</code> is returned.</p>
+
+ <p>Unlike other widget methods, <code>instance()</code> is safe to call on any element after the <placeholder name="name"/> plugin has loaded.</p>
</desc>
</method>

0 comments on commit cde5d57

Please sign in to comment.
Something went wrong with that request. Please try again.