forked from jquery/api.jquery.com
/
val.xml
214 lines (206 loc) · 7.98 KB
/
val.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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
<?xml version="1.0"?>
<entries>
<desc>Get the current value of the first element in the set of matched elements or set the value of every matched element.</desc>
<entry type="method" name="val">
<return type="String"/>
<return type="Number"/>
<return type="Array"/>
<title>.val()</title>
<signature>
<added>1.0</added>
</signature>
<desc>Get the current value of the first element in the set of matched elements.</desc>
<longdesc>
<p>The <code>.val()</code> method is primarily used to get the values of form elements such as <code>input</code>, <code>select</code> and <code>textarea</code>. When the first element in the collection is a <code>select-multiple</code> (i.e., a <code>select</code> element with the <code>multiple</code> attribute set), it returns an array containing the value of each selected option, or an empty array if no options are selected. When called on an empty collection, it returns <code>undefined</code>.</p>
<p>For selects and checkboxes, you can also use the <a href="/selected-selector/">:selected</a> and <a href="/checked-selector/">:checked</a> selectors to get at values, for example:</p>
<pre><code>
// Get the value from a dropdown select
$( "select.foo option:selected").val();
// Get the value from a dropdown select even easier
$( "select.foo" ).val();
// Get the value from a checked checkbox
$( "input:checkbox:checked" ).val();
// Get the value from a set of radio buttons
$( "input:radio[name=bar]:checked" ).val();
</code></pre>
<div class="warning">
<p><strong>Note: </strong> At present, using <code>.val()</code> on textarea elements strips carriage return characters from the browser-reported value. When this value is sent to the server via XHR however, carriage returns are preserved (or added by browsers which do not include them in the raw value). A workaround for this issue can be achieved using a valHook as follows:</p>
</div>
<pre><code>
$.valHooks.textarea = {
get: function( elem ) {
return elem.value.replace( /\r?\n/g, "\r\n" );
}
};
</code></pre>
</longdesc>
<example>
<desc>Get the single value from a single select and an array of values from a multiple select and display their values.</desc>
<code><![CDATA[
function displayVals() {
var singleValues = $( "#single" ).val();
var multipleValues = $( "#multiple" ).val();
$( "p" ).html( "<b>Single:</b> " + singleValues +
" <b>Multiple:</b> " + multipleValues.join( ", " ) );
}
$( "select" ).change( displayVals );
displayVals();
]]></code>
<css><![CDATA[
p {
color: red;
margin: 4px;
}
b {
color: blue;
}
]]></css>
<html><![CDATA[
<p></p>
<select id="single">
<option>Single</option>
<option>Single2</option>
</select>
<select id="multiple" multiple="multiple">
<option selected="selected">Multiple</option>
<option>Multiple2</option>
<option selected="selected">Multiple3</option>
</select>
]]></html>
</example>
<example>
<desc>Find the value of an input box.</desc>
<code><![CDATA[
$( "input" )
.keyup(function() {
var value = $( this ).val();
$( "p" ).text( value );
})
.keyup();
]]></code>
<css><![CDATA[
p {
color: blue;
margin: 8px;
}
]]></css>
<html><![CDATA[
<input type="text" value="some text">
<p></p>
]]></html>
</example>
<category slug="attributes"/>
<category slug="forms"/>
<category slug="manipulation/general-attributes"/>
<category slug="version/1.0"/>
<category slug="version/1.4"/>
</entry>
<entry type="method" name="val" return="jQuery">
<signature>
<added>1.0</added>
<argument name="value">
<type name="String"/>
<type name="Number"/>
<type name="Array"/>
<desc>A string of text, a number, or an array of strings corresponding to the value of each matched element to set as selected/checked.</desc>
</argument>
</signature>
<signature>
<added>1.4</added>
<argument name="function" type="Function">
<argument name="index" type="Integer" />
<argument name="value" type="String" />
<return type="String" />
<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 value as arguments.</desc>
</argument>
</signature>
<desc>Set the value of each element in the set of matched elements.</desc>
<longdesc>
<p>This method is typically used to set the values of form fields. </p>
<p><code>val()</code> allows you to pass an array of element values. This is useful when working on a jQuery object containing elements like <code><input type="checkbox"></code>, <code><input type="radio"></code>, and <code><option></code>s inside of a <code><select></code>. In this case, the <code>input</code>s and the <code>option</code>s having a <code>value</code> that matches one of the elements of the array will be checked or selected while those having a <code>value</code> that don't match one of the elements of the array will be unchecked or unselected, depending on the type. In case of <code><input type="radio"></code>s that are part of a radio group and <code><select></code>s, any previously selected element will be deselected.</p>
<p>Setting values using this method (or using the native <code>value</code> property) does not cause the dispatch of the <code>change</code> event. For this reason, the relevant event handlers will not be executed. If you want to execute them, you should call <code>.trigger( "change" )</code> after setting the value.</p>
<p>The <code>.val()</code> method allows us to set the value by passing in a function. As of jQuery 1.4, the function is passed two arguments, the current element's index and its current value: </p>
<pre><code>
$( "input:text.items" ).val(function( index, value ) {
return value + " " + this.className;
});
</code></pre>
<p>This example appends the string " items" to the text inputs' values.</p>
</longdesc>
<example>
<desc>Set the value of an input box.</desc>
<code><![CDATA[
$( "button" ).click(function() {
var text = $( this ).text();
$( "input" ).val( text );
});
]]></code>
<css><![CDATA[
button {
margin: 4px;
cursor: pointer;
}
input {
margin: 4px;
color: blue;
}
]]></css>
<html><![CDATA[
<div>
<button>Feed</button>
<button>the</button>
<button>Input</button>
</div>
<input type="text" value="click a button">
]]></html>
</example>
<example>
<desc>Use the function argument to modify the value of an input box.</desc>
<code><![CDATA[
$( "input" ).on( "blur", function() {
$( this ).val(function( i, val ) {
return val.toUpperCase();
});
});
]]></code>
<html><![CDATA[
<p>Type something and then click or tab out of the input.</p>
<input type="text" value="type something">
]]></html>
</example>
<example>
<desc>Set a single select, a multiple select, checkboxes and a radio button .</desc>
<code><![CDATA[
$( "#single" ).val( "Single2" );
$( "#multiple" ).val([ "Multiple2", "Multiple3" ]);
$( "input").val([ "check1", "check2", "radio1" ]);
]]></code>
<css><![CDATA[
body {
color: blue;
}
]]></css>
<html><![CDATA[
<select id="single">
<option>Single</option>
<option>Single2</option>
</select>
<select id="multiple" multiple="multiple">
<option selected="selected">Multiple</option>
<option>Multiple2</option>
<option selected="selected">Multiple3</option>
</select>
<br>
<input type="checkbox" name="checkboxname" value="check1"> check1
<input type="checkbox" name="checkboxname" value="check2"> check2
<input type="radio" name="r" value="radio1"> radio1
<input type="radio" name="r" value="radio2"> radio2
]]></html>
</example>
<category slug="attributes"/>
<category slug="forms"/>
<category slug="manipulation/general-attributes"/>
<category slug="version/1.0"/>
<category slug="version/1.4"/>
</entry>
</entries>