Skip to content

Commit 06c7c0a

Browse files
mgolmgol
committed
All: Mark event aliases as deprecated
Fixes jquerygh-1205
1 parent b415ca6 commit 06c7c0a

File tree

1 file changed

+106
-64
lines changed

1 file changed

+106
-64
lines changed

‎entries/blur.xml

+106-64
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,108 @@
11
<?xml version="1.0"?>
2-
<entry type="method" name="blur" return="jQuery">
3-
<title>.blur()</title>
2+
<entries>
43
<desc>Bind an event handler to the "blur" JavaScript event, or trigger that event on an element.</desc>
5-
<signature>
6-
<added>1.0</added>
7-
<argument name="handler" type="Function">
8-
<desc>A function to execute each time the event is triggered.</desc>
9-
<argument name="eventObject" type="Event" />
10-
</argument>
11-
</signature>
12-
<signature>
13-
<added>1.4.3</added>
14-
<argument name="eventData" type="Anything" optional="true">
15-
<desc>An object containing data that will be passed to the event handler.</desc>
16-
</argument>
17-
<argument name="handler" type="Function">
18-
<desc>A function to execute each time the event is triggered.</desc>
19-
<argument name="eventObject" type="Event" />
20-
</argument>
21-
</signature>
22-
<signature>
23-
<added>1.0</added>
24-
</signature>
25-
<longdesc>
26-
<p>This method is a shortcut for <code>.on( "blur", handler )</code> in the first two variations, and <code>.trigger( "blur" )</code> in the third.</p>
27-
<p>The <code>blur</code> event is sent to an element when it loses focus. Originally, this event was only applicable to form elements, such as <code>&lt;input&gt;</code>. In recent browsers, the domain of the event has been extended to include all element types. An element can lose focus via keyboard commands, such as the Tab key, or by mouse clicks elsewhere on the page.</p>
28-
<p>For example, consider the HTML:</p>
29-
<pre><code>
30-
&lt;form&gt;
31-
&lt;input id="target" type="text" value="Field 1"&gt;
32-
&lt;input type="text" value="Field 2"&gt;
33-
&lt;/form&gt;
34-
&lt;div id="other"&gt;
35-
Trigger the handler
36-
&lt;/div&gt;
37-
The event handler can be bound to the first input field:
38-
$( "#target" ).blur(function() {
39-
alert( "Handler for .blur() called." );
40-
});
41-
</code></pre>
42-
<p>Now if the first field has the focus, clicking elsewhere or tabbing away from it displays the alert:</p>
43-
<p>
44-
<samp>Handler for .blur() called.</samp>
45-
</p>
46-
<p>To trigger the event programmatically, apply <code>.blur()</code> without an argument:</p>
47-
<pre><code>
48-
$( "#other" ).click(function() {
49-
$( "#target" ).blur();
50-
});
51-
</code></pre>
52-
<p>After this code executes, clicks on <samp>Trigger the handler</samp> will also alert the message.</p>
53-
<p>The <code>blur</code> event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the <code>blur</code> event will not work consistently across browsers. As of version 1.4.2, however, jQuery works around this limitation by mapping <code>blur</code> to the <code>focusout</code> event in its event delegation methods, <a href="/live/"><code>.live()</code></a> and <a href="/delegate/"><code>.delegate()</code></a>.</p>
54-
</longdesc>
55-
<note id="detach-shorthand" type="additional" data-event="blur"/>
56-
<example>
57-
<desc>To trigger the blur event on all paragraphs:</desc>
58-
<code><![CDATA[
59-
$( "p" ).blur();
60-
]]></code>
61-
</example>
62-
<category slug="events/form-events"/>
63-
<category slug="forms"/>
64-
<category slug="version/1.0"/>
65-
<category slug="version/1.4.3"/>
66-
</entry>
4+
<entry type="method" name="on" return="jQuery">
5+
<title>blur event</title>
6+
<signature>
7+
<added>1.7</added>
8+
<argument name="&quot;blur&quot;" type="string">
9+
<desc>The string <code>"blur"</code>.</desc>
10+
</argument>
11+
<argument name="eventData" type="Anything" optional="true">
12+
<desc>An object containing data that will be passed to the event handler.</desc>
13+
</argument>
14+
<argument name="handler" type="Function">
15+
<desc>A function to execute each time the event is triggered.</desc>
16+
<argument name="eventObject" type="Event" />
17+
</argument>
18+
</signature>
19+
<longdesc>
20+
<p>The <code>blur</code> event is sent to an element when it loses focus. Originally, this event was only applicable to form elements, such as <code>&lt;input&gt;</code>. In recent browsers, the domain of the event has been extended to include all element types. An element can lose focus via keyboard commands, such as the Tab key, or by mouse clicks elsewhere on the page.</p>
21+
<p>For example, consider the HTML:</p>
22+
<pre><code>
23+
&lt;form&gt;
24+
&lt;input id="target" type="text" value="Field 1"&gt;
25+
&lt;input type="text" value="Field 2"&gt;
26+
&lt;/form&gt;
27+
&lt;div id="other"&gt;
28+
Trigger the handler
29+
&lt;/div&gt;
30+
The event handler can be bound to the first input field:
31+
$( "#target" ).on( "blur", function() {
32+
alert( "Handler for `blur` called." );
33+
} );
34+
</code></pre>
35+
<p>Now if the first field has the focus, clicking elsewhere or tabbing away from it displays the alert:</p>
36+
<p>
37+
<samp>Handler for `blur` called.</samp>
38+
</p>
39+
<p>To trigger the event programmatically, call <code>.trigger( "blur" )</code>:</p>
40+
<pre><code>
41+
$( "#other" ).on( "click", function() {
42+
$( "#target" ).trigger( "blur" );
43+
} );
44+
</code></pre>
45+
<p>After this code executes, clicks on <samp>Trigger the handler</samp> will also alert the message.</p>
46+
<p>The <code>blur</code> event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the <code>blur</code> event will not work consistently across browsers. As of version 1.4.2, however, jQuery works around this limitation by mapping <code>blur</code> to the <code>focusout</code> event in its event delegation methods, <a href="/live/"><code>.live()</code></a> and <a href="/delegate/"><code>.delegate()</code></a>.</p>
47+
</longdesc>
48+
<note id="detach-shorthand" type="additional" data-event="blur"/>
49+
<example>
50+
<desc>To trigger the blur event on all paragraphs:</desc>
51+
<code><![CDATA[
52+
$( "p" ).trigger( "blur" );
53+
]]></code>
54+
</example>
55+
<category slug="events/form-events"/>
56+
<category slug="forms"/>
57+
<category slug="version/1.7"/>
58+
</entry>
59+
60+
<entry type="method" name="trigger" return="jQuery">
61+
<title>.trigger( "blur" )</title>
62+
<signature>
63+
<added>1.7</added>
64+
<argument name="&quot;blur&quot;" type="string">
65+
<desc>The string <code>"blur"</code>.</desc>
66+
</argument>
67+
</signature>
68+
<longdesc>
69+
<p>See the description for <a href="#on1"><code>.on( "blur", ... )</code></a>.</p>
70+
</longdesc>
71+
<category slug="events/form-events"/>
72+
<category slug="forms"/>
73+
<category slug="version/1.7"/>
74+
</entry>
75+
76+
<entry type="method" name="blur" return="jQuery">
77+
<title>.blur()</title>
78+
<signature>
79+
<added>1.0</added>
80+
<argument name="handler" type="Function">
81+
<desc>A function to execute each time the event is triggered.</desc>
82+
<argument name="eventObject" type="Event" />
83+
</argument>
84+
</signature>
85+
<signature>
86+
<added>1.4.3</added>
87+
<argument name="eventData" type="Anything" optional="true">
88+
<desc>An object containing data that will be passed to the event handler.</desc>
89+
</argument>
90+
<argument name="handler" type="Function">
91+
<desc>A function to execute each time the event is triggered.</desc>
92+
<argument name="eventObject" type="Event" />
93+
</argument>
94+
</signature>
95+
<signature>
96+
<added>1.0</added>
97+
</signature>
98+
<longdesc>
99+
<p><code>.blur( handler )</code> &amp; <code>.blur( eventData, handler )</code> are deprecated aliases of <code>.on( "blur", handler )</code> &amp; <code>.on( "blur", eventData, handler )</code> respectively.</p>
100+
<p><code>.blur()</code> is a deprecated alias of <code>.trigger( "blur" )</code>.</p>
101+
</longdesc>
102+
<category slug="events/form-events"/>
103+
<category slug="forms"/>
104+
<category slug="version/1.0"/>
105+
<category slug="version/1.4.3"/>
106+
<category slug="deprecated/deprecated-3.3"/>
107+
</entry>
108+
</entries>

0 commit comments

Comments
 (0)