Skip to content

Commit

Permalink
jQuery.widget: More explicit wording to clarify the difference betwee…
Browse files Browse the repository at this point in the history
…n using :data and instance().
  • Loading branch information
tjvantoll committed Mar 23, 2013
1 parent 9db5f21 commit b55a711
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 4 deletions.
13 changes: 10 additions & 3 deletions entries/jQuery.widget.xml
Expand Up @@ -87,25 +87,32 @@


<h3>Instance</h3> <h3>Instance</h3>


<p>The widget's instance can be retrieved from a given element using the <a href="#method-instance"><code>instance</code> 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> <pre><code>
$( "#elem" ).progressbar( "instance" ); $( "#elem" ).progressbar( "instance" );
</code></pre> </code></pre>


<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> <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> <pre><code>
$( "#not-a-progressbar" ).progressbar( "instance" ); // undefined $( "#not-a-progressbar" ).progressbar( "instance" ); // undefined
</code></pre> </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>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> <pre><code>
$( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true $( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true
$( "#elem" ).is( ":data( 'ui-draggable' )" ); //false $( "#elem" ).is( ":data( 'ui-draggable' )" ); //false
</code></pre> </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> <p>You can also use <code>:data</code> to get a list of all elements that are instances of a given widget.</p>


<pre><code> <pre><code>
Expand Down
4 changes: 3 additions & 1 deletion includes/widget-method-instance.xml
@@ -1,6 +1,8 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<method name="instance" return="Object"> <method name="instance" return="Object">
<desc> <desc>
Retrieves the <placeholder name="name"/>'s instance object. Unlike other widget methods, <code>instance</code> is safe to call on any element after the <placeholder name="name"/> plugin has loaded. If the element does not have an associated instance, <code>undefined</code> is returned. <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> </desc>
</method> </method>

0 comments on commit b55a711

Please sign in to comment.