8000 api docs: code indentation and formatting (u, v and w entries) · GitObjects/api.jquery.com@ea76275 · GitHub
[go: up one dir, main page]
Skip to content 8000

Commit ea76275

Browse files
agcolomagcolom
committed
api docs: code indentation and formatting (u, v and w entries)
1 parent fb0204c commit ea76275

File tree

10 files changed

+592
-349
lines changed

10 files changed

+592
-349
lines changed

‎entries/unbind.xml

Lines changed: 71 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -27,98 +27,125 @@
2727
</argument>
2828
</signature>
2929
<longdesc>
30-
<p>Event handlers attached with <code>.bind()</code> can be removed with <code>.unbind()</code>. (As of jQuery 1.7, the <a href="http://api.jquery.com/on"><code>.on()</code></a> and <a href="http://api.jquery.com/off"><code>.off()</code></a> methods are preferred to attach and remove event handlers on elements.) In the simplest case, with no arguments, <code>.unbind()</code> removes all handlers attached to the elements:</p>
31-
<pre><code>$('#foo').unbind();</code></pre>
30+
<p>Event handlers attached with <code>.bind()</code> can be removed with <code>.unbind()</code>. (As of jQuery 1.7, the <a href="/on/"><code>.on()</code></a> and <a href="/off/"><code>.off()</code></a> methods are preferred to attach and remove event handlers on elements.) In the simplest case, with no arguments, <code>.unbind()</code> removes all handlers attached to the elements:</p>
31+
<pre><code>
32+
$( "#foo" ).unbind();
33+
</code></pre>
3234
<p>This version removes the handlers regardless of type. To be more precise, we can pass an event type:</p>
33-
<pre><code>$('#foo').unbind('click');</code></pre>
35+
<pre><code>
36+
$( "#foo").unbind( "click" );
37+
</code></pre>
3438
<p>By specifying the <code>click</code> event type, only handlers for that event type will be unbound. This approach can still have negative ramifications if other scripts might be attaching behaviors to the same element, however. Robust and extensible applications typically demand the two-argument version for this reason:</p>
35-
<pre><code>var handler = function() {
36-
alert('The quick brown fox jumps over the lazy dog.');
39+
<pre><code>
40+
var handler = function() {
41+
alert( "The quick brown fox jumps over the lazy dog." );
3742
};
38-
$('#foo').bind('click', handler);
39-
$('#foo').unbind('click', handler);
40-
</code></pre>
43+
$( "#foo" ).bind( "click", handler );
44+
$( "#foo" ).unbind( "click", handler );
45+
</code></pre>
4146
<p>By naming the handler, we can be assured that no other functions are accidentally removed. Note that the following will <em>not</em> work:</p>
42-
<pre><code>$('#foo').bind('click', function() {
43-
alert('The quick brown fox jumps over the lazy dog.');
47+
<pre><code>
48+
$( "#foo" ).bind( "click", function() {
49+
alert( "The quick brown fox jumps over the lazy dog." );
4450
});
4551

46-
// will NOT work
47-
$('#foo').unbind('click', function() {
48-
alert('The quick brown fox jumps over the lazy dog.');
49-
});</code></pre>
52+
// Will NOT work
53+
$( "#foo" ).unbind( "click", function() {
54+
alert( "The quick brown fox jumps over the lazy dog." );
55+
});
56+
</code></pre>
5057
<p>Even though the two functions are identical in content, they are created separately and so JavaScript is free to keep them as distinct function objects. To unbind a particular handler, we need a reference to that function and not a different one that happens to do the same thing.</p>
5158
<div class="warning">
5259
<p><strong>Note:</strong> Using a proxied function to unbind an event on an element will unbind all proxied functions on that element, as the same proxy function is used for all proxied events. To allow unbinding a specific event, use unique class names on the event (e.g. <code>click.proxy1</code>, <code>click.proxy2</code>) when attaching them.</p>
5360
</div>
5461
<h4>Using Namespaces</h4>
5562
<p>Instead of maintaining references to handlers in order to unbind them, we can namespace the events and use this capability to narrow the scope of our unbinding actions. As shown in the discussion for the <code>.bind()</code> method, namespaces are defined by using a period (<code>.</code>) character when binding a handler:</p>
56-
<pre><code>$('#foo').bind('click.myEvents', handler);</code></pre>
63+
<pre><code>
64+
$( "#foo" ).bind( "click.myEvents", handler);
65+
</code></pre>
5766
<p>When a handler is bound in this fashion, we can still unbind it the normal way:</p>
58-
<pre><code>$('#foo').unbind('click');</code></pre>
67+
<pre><code>
68+
$( "#foo" ).unbind( "click" );
69+
</code></pre>
5970
<p>However, if we want to avoid affecting other handlers, we can be more specific:</p>
60-
<pre><code>$('#foo').unbind('click.myEvents');</code></pre>
71+
<pre><code>
72+
$( "#foo" ).unbind( "click.myEvents" );
73+
</code></pre>
6174
<p>We can also unbind all of the handlers in a namespace, regardless of event type:</p>
62-
<pre><code>$('#foo').unbind('.myEvents');</code></pre>
75+
<pre><code>
76+
$( "#foo" ).unbind( ".myEvents" );
77+
</code></pre>
6378
<p>It is particularly useful to attach namespaces to event bindings when we are developing plug-ins or otherwise writing code that may interact with other event-handling code in the future.</p>
6479
<h4>Using the Event Object</h4>
6580
<p>The third form of the <code>.unbind()</code> method is used when we wish to unbind a handler from within itself. For example, suppose we wish to trigger an event handler only three times:</p>
66-
<pre><code>var timesClicked = 0;
67-
$('#foo').bind('click', function(event) {
68-
alert('The quick brown fox jumps over the lazy dog.');
81+
<pre><code>
82+
var timesClicked = 0;
83+
$( "#foo" ).bind( "click", function( event ) {
84+
alert( "The quick brown fox jumps over the lazy dog." );
6985
timesClicked++;
70-
if (timesClicked &gt;= 3) {
71-
$(this).unbind(event);
86+
if ( timesClicked &gt;= 3 ) {
87+
$( this ).unbind( event );
7288
}
7389
});
74-
</code></pre>
90+
</code></pre>
7591
<p>The handler in this case must take a parameter, so that we can capture the event object and use it to unbind the handler after the third click. The event object contains the context necessary for <code>.unbind()</code> to know which handler to remove.
7692
This example is also an illustration of a closure. Since the handler refers to the <code>timesClicked</code> variable, which is defined outside the function, incrementing the variable has an effect even between invocations of the handler.</p>
7793
</longdesc>
7894
<example>
7995
<desc>Can bind and unbind events to the colored button.</desc>
8096
<code><![CDATA[
8197
function aClick() {
82-
$("div").show().fadeOut("slow");
98+
$("div").show().fadeOut("slow");
8399
}
84-
$("#bind").click(function () {
85-
// could use .bind('click', aClick) instead but for variety...
86-
$("#theone").click(aClick)
87-
.text("Can Click!");
100+
$( "#bind" ).click(function() {
101+
// Could use .bind( "click", aClick ) instead but for variety...
102+
$( "#theone" ).click( aClick )
103+
.text( "Can Click!" );
88104
});
89-
$("#unbind").click(function () {
90-
$("#theone").unbind('click', aClick)
91-
.text("Does nothing...");
105+
$( "#unbind" ).click(function() {
106+
$( "#theone" ).unbind( "click", aClick )
107+
.text( "Does nothing..." );
92108
});
93-
94109
]]></code>
95110
<css><![CDATA[
96-
button { margin:5px; }
97-
button#theone { color:red; background:yellow; }
111+
button {
112+
margin: 5px;
113+
}
114+
button#theone {
115+
color: red;
116+
background: yellow;
117+
}
98118
]]></css>
99-
<html><![CDATA[<button id="theone">Does nothing...</button>
119+
<html><![CDATA[
120+
<button id="theone">Does nothing...</button>
100121
<button id="bind">Bind Click</button>
101122
<button id="unbind">Unbind Click</button>
102-
103-
<div style="display:none;">Click!</div>]]></html>
123+
<div style="display:none;">Click!</div>
124+
]]></html>
104125
</example>
105126
<example>
106127
<desc>To unbind all events from all paragraphs, write:</desc>
107-
<code><![CDATA[$("p").unbind()]]></code>
128+
<code><![CDATA[
129+
$( "p" ).unbind();
130+
]]></code>
108131
</example>
109132
<example>
110133
<desc>To unbind all click events from all paragraphs, write:</desc>
111-
<code><![CDATA[$("p").unbind( "click" )]]></code>
134+
<code><![CDATA[
135+
$( "p" ).unbind( "click" );
136+
]]></code>
112137
</example>
113138
<example>
114139
<desc>To unbind just one previously bound handler, pass the function in as the second argument:</desc>
115-
<code><![CDATA[var foo = function () {
116-
// code to handle some kind of event
140+
<code><![CDATA[
141+
var foo = function() {
142+
// Code to handle some kind of event
117143
};
118144
119-
$("p").bind("click", foo); // ... now foo will be called when paragraphs are clicked ...
145+
$( "p" ).bind( "click", foo ); // ... Now foo will be called when paragraphs are clicked ...
120146
121-
$("p").unbind("click", foo); // ... foo will no longer be called.]]></code>
147+
$( "p" ).unbind( "click", foo ); // ... foo will no longer be called.
148+
]]></code>
122149
</example>
123150
<category slug="events/event-handler-attachment"/>
124151
<category slug="version/1.0"/>

‎entries/undelegate.xml

Lines changed: 41 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -42,67 +42,79 @@
4242
</argument>
4343
</signature>
4444
<longdesc>
45-
<p>The <code>.undelegate()</code> method is a way of removing event handlers that have been bound using <a href="/delegate"><code>.delegate()</code></a>. <strong>As of jQuery 1.7</strong>, the <a href="http://api.jquery.com/on"><code>.on()</code></a> and <a href="http://api.jquery.com/off"><code>.off()</code></a> methods are preferred for attaching and removing event handlers.</p>
45+
<p>The <code>.undelegate()</code> method is a way of removing event handlers that have been bound using <a href="/delegate/"><code>.delegate()</code></a>. <strong>As of jQuery 1.7</strong>, the <a href="/on/"><code>.on()</code></a> and <a href="/off/"><code>.off()</code></a> methods are preferred for attaching and removing event handlers.</p>
4646
</longdesc>
4747
<example>
4848
<desc>Can bind and unbind events to the colored button.</desc>
4949
<code><![CDATA[
5050
function aClick() {
51-
$("div").show().fadeOut("slow");
51+
$( "div" ).show().fadeOut( "slow" );
5252
}
53-
$("#bind").click(function () {
54-
$("body").delegate("#theone", "click", aClick)
55-
.find("#theone").text("Can Click!");
53+
$( "#bind" ).click(function() {
54+
$( "body" ).delegate( "#theone", "click", aClick )
55+
.find( "#theone" ).text( "Can Click!" );
5656
});
57-
$("#unbind").click(function () {
58-
$("body").undelegate("#theone", "click", aClick)
59-
.find("#theone").text("Does nothing...");
57+
$( "#unbind" ).click(function() {
58+
$( "body" ).undelegate( "#theone", "click", aClick )
59+
.find( "#theone" ).text( "Does nothing..." );
6060
});
6161
]]></code>
6262
<css><![CDATA[
63-
button { margin:5px; }
64-
button#theone { color:red; background:yellow; }
63+
button {
64+
margin: 5px;
65+
}
66+
button#theone {
67+
color: red;
68+
background: yellow;
69+
}
6570
]]></css>
66-
<html><![CDATA[<button id="theone">Does nothing...</button>
71+
<html><![CDATA[
72+
<button id="theone">Does nothing...</button>
6773
<button id="bind">Bind Click</button>
6874
<button id="unbind">Unbind Click</button>
69-
<div style="display:none;">Click!</div>]]></html>
75+
<div style="display:none;">Click!</div>
76+
]]></html>
7077
</example>
7178
<example>
7279
<desc>To unbind all delegated events from all paragraphs, write:</desc>
73-
<code><![CDATA[$("p").undelegate()]]></code>
80+
<code><![CDATA[
81+
$( "p" ).undelegate();
82+
]]></code>
7483
</example>
7584
<example>
7685
<desc>To unbind all delegated click events from all paragraphs, write:</desc>
77-
<code><![CDATA[$("p").undelegate( "click" )]]></code>
86+
<code><![CDATA[
87+
$( "p" ).undelegate( "click" );
88+
]]></code>
7889
</example>
7990
<example>
8091
<desc>To undelegate just one previously bound handler, pass the function in as the third argument:</desc>
81-
<code><![CDATA[var foo = function () {
82-
// code to handle some kind of event
92+
<code><![CDATA[
93+
var foo = function () {
94+
// Code to handle some kind of event
8395
};
84-
85-
// ... now foo will be called when paragraphs are clicked ...
86-
$("body").delegate("p", "click", foo);
87-
96+
// ... Now foo will be called when paragraphs are clicked ...
97+
$( "body" ).delegate( "p", "click", foo );
8898
8999
// ... foo will no longer be called.
90-
$("body").undelegate("p", "click", foo); ]]></code>
100+
$( "body" ).undelegate( "p", "click", foo );
101+
]]></code>
91102
</example>
92103
<example>
93104
<desc>To unbind all delegated events by their namespace:</desc>
94-
<code><![CDATA[var foo = function () {
95-
// code to handle some kind of event
105+
<code><![CDATA[
106+
var foo = function() {
107+
// Code to handle some kind of event
96108
};
97109
98-
// delegate events under the ".whatever" namespace
99-
$("form").delegate(":button", "click.whatever", foo);
110+
// Delegate events under the ".whatever" namespace
111+
$( "form" ).delegate( ":button", "click.whatever", foo );
100112
101-
$("form").delegate("input[type='text']", "keypress.whatever", foo);
113+
$( "form" ).delegate( "input[type='text'] ", "keypress.whatever", foo );
102114
103-
// unbind all events delegated under the ".whatever" namespace
104-
105-
$("form").undelegate(".whatever");]]></code>
115+
// Unbind all events delegated under the ".whatever" namespace
116+
$("form").undelegate(".whatever");
117+
]]></code>
106118
</example>
107119
<category slug="events/event-handler-attachment"/>
108120
<category slug="version/1.4.2"/>

‎entries/unload.xml

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,23 +18,28 @@
1818
</signature>
1919
<desc>Bind an event handler to the "unload" JavaScript event.</desc>
2020
<longdesc>
21-
<p>This method is a shortcut for <code>.on('unload', handler)</code>.</p>
21+
<p>This method is a shortcut for <code>.on( "unload", handler )</code>.</p>
2222
<p>The <code>unload</code> event is sent to the <code>window</code> element when the user navigates away from the page. This could mean one of many things. The user could have clicked on a link to leave the page, or typed in a new URL in the address bar. The forward and back buttons will trigger the event. Closing the browser window will cause the event to be triggered. Even a page reload will first create an <code>unload</code> event.</p>
2323
<div class="warning">
2424
<p>The exact handling of the <code>unload</code> event has varied from version to version of browsers. For example, some versions of Firefox trigger the event when a link is followed, but not when the window is closed. In practical usage, behavior should be tested on all supported browsers, and contrasted with the proprietary <code>beforeunload</code> event.</p>
2525
</div>
2626
<p>Any <code>unload</code> event handler should be bound to the <code>window</code> object:</p>
27-
<pre><code>$(window).unload(function() {
28-
alert('Handler for .unload() called.');
27+
<pre><code>
28+
$( window ).unload(function() {
29+
alert( "Handler for .unload() called." );
2930
});
30-
</code></pre>
31+
</code></pre>
3132
<p>After this code executes, the alert will be displayed whenever the browser leaves the current page.
3233
It is not possible to cancel the <code>unload</code> event with <code>.preventDefault()</code>. This event is available so that scripts can perform cleanup when the user leaves the page.
3334
</p>
3435
</longdesc>
3536
<example>
3637
<desc>To display an alert when a page is unloaded:</desc>
37-
<code><![CDATA[$(window).unload( function () { alert("Bye now!"); } );]]></code>
38+
<code><![CDATA[
39+
$( window ).unload(function() {
40+
alert( "Bye now!" );
41+
});
42+
]]></code>
3843
</example>
3944
<category slug="events/document-loading"/>
4045
<category slug="version/1.0"/>

‎entries/unwrap.xml

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,24 @@
1111
<example>
1212
<desc>Wrap/unwrap a div around each of the paragraphs.</desc>
1313
<code><![CDATA[
14-
var pTags = $("p");
15-
$("button").click( function(){
16-
if ( pTags.parent().is("div") ) {
14+
var pTags = $( "p" );
15+
$( "button" ).click(function() {
16+
if ( pTags.parent().is( "div" ) ) {
1717
pTags.unwrap();
1818
} else {
19-
pTags.wrap("<div></div>");
19+
pTags.wrap( "<div></div>" );
2020
}
21-
});]]></code>
21+
});
22+
]]></code>
2223
<css><![CDATA[
23-
div { border: 2px solid blue; }
24-
p { background:yellow; margin:4px; }
25-
]]></css>
24+
div {
25+
border: 2px solid blue;
26+
}
27+
p {
28+
background: yellow;
29+
margin: 4px;
30+
}
31+
]]></css>
2632
<html><![CDATA[<button>wrap/unwrap</button>
2733
<p>Hello</p>
2834
<p>cruel</p>

0 commit comments

Comments
 (0)
0