forked from jquery/api.jquery.com
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathattr.xml
163 lines (161 loc) · 7.54 KB
/
attr.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
<?xml version="1.0"?>
<entries>
<desc>Get the value of an attribute for the first element in the set of matched elements or set one or more attributes for every matched element.</desc>
<entry type="method" name="attr" return="String">
<title>.attr()</title>
<signature>
<added>1.0</added>
<argument name="attributeName" type="String">
<desc>The name of the attribute to get.</desc>
</argument>
</signature>
<desc>Get the value of an attribute for the first element in the set of matched elements.</desc>
<longdesc>
<p>The <code>.attr()</code> method gets the attribute value for only the <em>first</em> element in the matched set. To get the value for each element individually, use a looping construct such as jQuery's <code>.each()</code> or <code>.map()</code> method.</p>
<p><strong>As of jQuery 1.6</strong>, the <code>.attr()</code> method returns <code>undefined</code> for attributes that have not been set. In addition, <code>.attr()</code> should not be used on plain objects, arrays, the window, or the document. To retrieve and change DOM properties, use the <a href="http://api.jquery.com/prop/">.prop()</a> method.</p>
<p>Using jQuery's <code>.attr()</code> method to get the value of an element's attribute has two main benefits:</p>
<ol>
<li><strong>Convenience</strong>: It can be called directly on a jQuery object and chained to other jQuery methods.</li>
<li><strong>Cross-browser consistency</strong>: The values of some attributes are reported inconsistently across browsers, and even across versions of a single browser. The <code>.attr()</code> method reduces such inconsistencies.</li>
</ol>
<blockquote>
<p><strong>Note:</strong> Attribute values are strings with the exception of a few attributes such as value and tabindex.</p>
</blockquote>
</longdesc>
<example>
<desc>Find the title attribute of the first <em> in the page.</desc>
<code><![CDATA[
var title = $("em").attr("title");
$("div").text(title);
]]></code>
<css><![CDATA[
em { color:blue; font-weight:bold; }
div { color:red; }
]]></css>
<html><![CDATA[
<p>
Once there was a <em title="huge, gigantic">large</em> dinosaur...
</p>
The title of the emphasis is:<div></div>
]]></html>
</example>
<category slug="attributes"/>
<category slug="manipulation/general-attributes"/>
<category slug="version/1.0"/>
<category slug="version/1.1"/>
<category slug="version/1.6"/>
</entry>
<entry type="method" name="attr" return="jQuery">
<signature>
<added>1.0</added>
<argument name="attributeName" type="String">
<desc>The name of the attribute to set.</desc>
</argument>
<argument name="value">
<type name="String"/>
<type name="Number"/>
<desc>A value to set for the attribute.</desc>
</argument>
</signature>
<signature>
<added>1.0</added>
<argument name="attributes" type="PlainObject">
<desc>An object of attribute-value pairs to set.</desc>
</argument>
</signature>
<signature>
<added>1.1</added>
<argument name="attributeName" type="String">
<desc>The name of the attribute to set.</desc>
</argument>
<argument name="function(index, attr)" type="Function">
<desc>A function returning the value to set. <code>this</code> is the current element. Receives the index position of the element in the set and the old attribute value as arguments.</desc>
</argument>
</signature>
<desc>Set one or more attributes for the set of matched elements.</desc>
<longdesc>
<p>The <code>.attr()</code> method is a convenient way to set the value of attributes—especially when setting multiple attributes or using values returned by a function. Consider the following image:</p>
<pre><code><img id="greatphoto" src="brush-seller.jpg" alt="brush seller" /></code></pre>
<h4 id="setting-simple-attr">Setting a simple attribute</h4>
<p>To change the <code>alt</code> attribute, simply pass the name of the attribute and its new value to the <code>.attr()</code> method:</p>
<pre><code>$('#greatphoto').attr('alt', 'Beijing Brush Seller');</code></pre>
<p><em>Add</em> an attribute the same way:</p>
<pre><code>$('#greatphoto')
.attr('title', 'Photo by Kelly Clark');</code></pre>
<h4 id="setting-several-attrs">Setting several attributes at once</h4>
<p>To change the <code>alt</code> attribute and add the <code>title</code> attribute at the same time, pass both sets of names and values into the method at once using a plain JavaScript object. Each key-value pair in the object adds or modifies an attribute:</p>
<pre><code>$('#greatphoto').attr({
alt: 'Beijing Brush Seller',
title: 'photo by Kelly Clark'
});</code></pre>
<p>When setting multiple attributes, the quotes around attribute names are optional.</p>
<p><strong>WARNING</strong>: When setting the 'class' attribute, you must always use quotes!</p>
<p><strong>Note</strong>: jQuery prohibits changing the <code>type</code> attribute on an <code><input></code> or <code><button></code> element and will throw an error in all browsers. This is because the <code>type</code> attribute cannot be changed in Internet Explorer.</p>
<h4 id="computed-attr-values">Computed attribute values</h4>
<p>By using a function to set attributes, you can compute the value based on other properties of the element. For example, to concatenate a new value with an existing value:</p>
<pre><code>$('#greatphoto').attr('title', function(i, val) {
return val + ' - photo by Kelly Clark'
});</code></pre>
<p>This use of a function to compute attribute values can be particularly useful when modifying the attributes of multiple elements at once.</p>
<p><strong>Note: </strong>If nothing is returned in the setter function (ie. <code>function(index, attr){})</code>, or if <code>undefined</code> is returned, the current value is not changed. This is useful for selectively setting values only when certain criteria are met.</p>
</longdesc>
<example>
<desc>Set some attributes for all <img>s in the page.</desc>
<code><![CDATA[
$("img").attr({
src: "/resources/hat.gif",
title: "jQuery",
alt: "jQuery Logo"
});
$("div").text($("img").attr("alt"));
]]></code>
<css><![CDATA[
img { padding:10px; }
div { color:red; font-size:24px; }
]]></css>
<html><![CDATA[
<img />
<img />
<img />
<div><B>Attribute of Ajax</B></div>
]]></html>
</example>
<example>
<desc>Set the id for divs based on the position in the page.</desc>
<code><![CDATA[
$("div").attr("id", function (arr) {
return "div-id" + arr;
})
.each(function () {
$("span", this).html("(ID = '<b>" + this.id + "</b>')");
});
]]></code>
<css><![CDATA[
div { color:blue; }
span { color:red; }
b { font-weight:bolder; }
]]></css>
<html><![CDATA[
<div>Zero-th <span></span></div>
<div>First <span></span></div>
<div>Second <span></span></div>
]]></html>
</example>
<example>
<desc>Set the src attribute from title attribute on the image.</desc>
<code><![CDATA[
$("img").attr("src", function() {
return "/resources/" + this.title;
});
]]></code>
<html><![CDATA[
<img title="hat.gif"/>
]]></html>
</example>
<category slug="attributes"/>
<category slug="manipulation/general-attributes"/>
<category slug="version/1.0"/>
<category slug="version/1.1"/>
<category slug="version/1.6"/>
</entry>
</entries>