Debian Codegraph @

closure-library/closure/goog/dom/forms.js

raw
1 // Copyright 2006 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Utilities for manipulating a form and elements.
17 *
18 * @author [email protected] (Erik Arvidsson)
19 */
20
21 goog.provide('goog.dom.forms');
22
23 goog.require('goog.dom.InputType');
24 goog.require('goog.dom.TagName');
25 goog.require('goog.structs.Map');
26 goog.require('goog.window');
27
28
29
30 /**
31 * Submits form data via a new window. This hides references to the parent
32 * window and should be used when submitting forms to untrusted 3rd party urls.
33 * By default, this uses the action and method of the specified form
34 * element. It is possible to override the default action and method if an
35 * optional submit element with formaction and/or formmethod attributes is
36 * provided.
37 * @param {!HTMLFormElement} form The form.
38 * @param {!HTMLElement=} opt_submitElement The `<button>` or `<input>` element
39 * used to submit the form. The element should have a submit type.
40 * @return {boolean} true If the form was submitted succesfully.
41 * @throws {!Error} If opt_submitElement is not a valid form submit element.
42 */
43 goog.dom.forms.submitFormInNewWindow = function(form, opt_submitElement) {
44 var formData = goog.dom.forms.getFormDataMap(form);
45 var action = form.action;
46 var method = form.method;
47
48 if (opt_submitElement) {
49 if (goog.dom.InputType.SUBMIT != opt_submitElement.type.toLowerCase()) {
50 throw new Error('opt_submitElement does not have a valid type.');
51 }
52
53
54 var submitValue =
55 /** @type {?string} */ (goog.dom.forms.getValue(opt_submitElement));
56 if (submitValue != null) {
57 goog.dom.forms.addFormDataToMap_(
58 formData, opt_submitElement.name, submitValue);
59 }
60
61 if (opt_submitElement.getAttribute('formaction')) {
62 action = opt_submitElement.getAttribute('formaction');
63 }
64
65 if (opt_submitElement.getAttribute('formmethod')) {
66 method = opt_submitElement.getAttribute('formmethod');
67 }
68 }
69
70 return goog.dom.forms.submitFormDataInNewWindow(action, method, formData);
71 };
72
73 /**
74 * Submits form data via a new window. This hides references to the parent
75 * window and should be used when submitting forms to untrusted 3rd party urls.
76 * @param {string} actionUri uri to submit form content to.
77 * @param {string} method HTTP method used to submit the form.
78 * @param {!goog.structs.Map<string, !Array<string>>} formData A map of the form
79 * data as field name to arrays of values.
80 * @return {boolean} true If the form was submitted succesfully.
81 */
82 goog.dom.forms.submitFormDataInNewWindow = function(
83 actionUri, method, formData) {
84 var newWin = goog.window.openBlank('', {noreferrer: true});
85
86 // This could be null if a new window could not be opened. e.g. if it was
87 // stopped by a popup blocker.
88 if (!newWin) {
89 return false;
90 }
91
92 var newDocument = newWin.document;
93
94 var newForm =
95 /** @type {!HTMLFormElement} */ (newDocument.createElement('form'));
96 newForm.method = method;
97 newForm.action = actionUri;
98
99 // After this point, do not directly reference the form object's functions as
100 // field names can shadow the form's properties.
101
102 formData.forEach(function(fieldValues, fieldName) {
103 for (var i = 0; i < fieldValues.length; i++) {
104 var fieldValue = fieldValues[i];
105 var newInput = newDocument.createElement('input');
106 newInput.name = fieldName;
107 newInput.value = fieldValue;
108 newInput.type = 'hidden';
109 HTMLFormElement.prototype.appendChild.call(newForm, newInput);
110 }
111 });
112
113 HTMLFormElement.prototype.submit.call(newForm);
114 return true;
115 };
116
117
118 /**
119 * Returns form data as a map of name to value arrays. This doesn't
120 * support file inputs.
121 * @param {HTMLFormElement} form The form.
122 * @return {!goog.structs.Map<string, !Array<string>>} A map of the form data
123 * as field name to arrays of values.
124 */
125 goog.dom.forms.getFormDataMap = function(form) {
126 var map = new goog.structs.Map();
127 goog.dom.forms.getFormDataHelper_(
128 form, map, goog.dom.forms.addFormDataToMap_);
129 return map;
130 };
131
132
133 /**
134 * Returns the form data as an application/x-www-url-encoded string. This
135 * doesn't support file inputs.
136 * @param {HTMLFormElement} form The form.
137 * @return {string} An application/x-www-url-encoded string.
138 */
139 goog.dom.forms.getFormDataString = function(form) {
140 var sb = [];
141 goog.dom.forms.getFormDataHelper_(
142 form, sb, goog.dom.forms.addFormDataToStringBuffer_);
143 return sb.join('&');
144 };
145
146
147 /**
148 * Returns the form data as a map or an application/x-www-url-encoded
149 * string. This doesn't support file inputs.
150 * @param {HTMLFormElement} form The form.
151 * @param {Object} result The object form data is being put in.
152 * @param {Function} fnAppend Function that takes {@code result}, an element
153 * name, and an element value, and adds the name/value pair to the result
154 * object.
155 * @private
156 */
157 goog.dom.forms.getFormDataHelper_ = function(form, result, fnAppend) {
158 var els = form.elements;
159 for (var el, i = 0; el = els[i]; i++) {
160 if ( // Make sure we don't include elements that are not part of the form.
161 // Some browsers include non-form elements. Check for 'form' property.
162 // See http://code.google.com/p/closure-library/issues/detail?id=227
163 // and
164 // http://www.whatwg.org/specs/web-apps/current-work/multipage/the-input-element.html#the-input-element
165 (el.form != form) || el.disabled ||
166 // HTMLFieldSetElement has a form property but no value.
167 el.tagName == goog.dom.TagName.FIELDSET) {
168 continue;
169 }
170
171 var name = el.name;
172 switch (el.type.toLowerCase()) {
173 case goog.dom.InputType.FILE:
174 // file inputs are not supported
175 case goog.dom.InputType.SUBMIT:
176 case goog.dom.InputType.RESET:
177 case goog.dom.InputType.BUTTON:
178 // don't submit these
179 break;
180 case goog.dom.InputType.SELECT_MULTIPLE:
181 var values = goog.dom.forms.getValue(el);
182 if (values != null) {
183 for (var value, j = 0; value = values[j]; j++) {
184 fnAppend(result, name, value);
185 }
186 }
187 break;
188 default:
189 var value = goog.dom.forms.getValue(el);
190 if (value != null) {
191 fnAppend(result, name, value);
192 }
193 }
194 }
195
196 // input[type=image] are not included in the elements collection
197 var inputs = form.getElementsByTagName(String(goog.dom.TagName.INPUT));
198 for (var input, i = 0; input = inputs[i]; i++) {
199 if (input.form == form &&
200 input.type.toLowerCase() == goog.dom.InputType.IMAGE) {
201 name = input.name;
202 fnAppend(result, name, input.value);
203 fnAppend(result, name + '.x', '0');
204 fnAppend(result, name + '.y', '0');
205 }
206 }
207 };
208
209
210 /**
211 * Adds the name/value pair to the map.
212 * @param {!goog.structs.Map<string, !Array<string>>} map The map to add to.
213 * @param {string} name The name.
214 * @param {string} value The value.
215 * @private
216 */
217 goog.dom.forms.addFormDataToMap_ = function(map, name, value) {
218 var array = map.get(name);
219 if (!array) {
220 array = [];
221 map.set(name, array);
222 }
223 array.push(value);
224 };
225
226
227 /**
228 * Adds a name/value pair to an string buffer array in the form 'name=value'.
229 * @param {Array<string>} sb The string buffer array for storing data.
230 * @param {string} name The name.
231 * @param {string} value The value.
232 * @private
233 */
234 goog.dom.forms.addFormDataToStringBuffer_ = function(sb, name, value) {
235 sb.push(encodeURIComponent(name) + '=' + encodeURIComponent(value));
236 };
237
238
239 /**
240 * Whether the form has a file input.
241 * @param {HTMLFormElement} form The form.
242 * @return {boolean} Whether the form has a file input.
243 */
244 goog.dom.forms.hasFileInput = function(form) {
245 var els = form.elements;
246 for (var el, i = 0; el = els[i]; i++) {
247 if (!el.disabled && el.type &&
248 el.type.toLowerCase() == goog.dom.InputType.FILE) {
249 return true;
250 }
251 }
252 return false;
253 };
254
255
256 /**
257 * Enables or disables either all elements in a form or a single form element.
258 * @param {Element} el The element, either a form or an element within a form.
259 * @param {boolean} disabled Whether the element should be disabled.
260 */
261 goog.dom.forms.setDisabled = function(el, disabled) {
262 // disable all elements in a form
263 if (el.tagName == goog.dom.TagName.FORM) {
264 var els = /** @type {!HTMLFormElement} */ (el).elements;
265 for (var i = 0; el = els[i]; i++) {
266 goog.dom.forms.setDisabled(el, disabled);
267 }
268 } else {
269 // makes sure to blur buttons, multi-selects, and any elements which
270 // maintain keyboard/accessibility focus when disabled
271 if (disabled == true) {
272 el.blur();
273 }
274 el.disabled = disabled;
275 }
276 };
277
278
279 /**
280 * Focuses, and optionally selects the content of, a form element.
281 * @param {Element} el The form element.
282 */
283 goog.dom.forms.focusAndSelect = function(el) {
284 el.focus();
285 if (el.select) {
286 el.select();
287 }
288 };
289
290
291 /**
292 * Whether a form element has a value.
293 * @param {Element} el The element.
294 * @return {boolean} Whether the form has a value.
295 */
296 goog.dom.forms.hasValue = function(el) {
297 var value = goog.dom.forms.getValue(el);
298 return !!value;
299 };
300
301
302 /**
303 * Whether a named form field has a value.
304 * @param {HTMLFormElement} form The form element.
305 * @param {string} name Name of an input to the form.
306 * @return {boolean} Whether the form has a value.
307 */
308 goog.dom.forms.hasValueByName = function(form, name) {
309 var value = goog.dom.forms.getValueByName(form, name);
310 return !!value;
311 };
312
313
314 /**
315 * Gets the current value of any element with a type.
316 * @param {Element} el The element.
317 * @return {string|Array<string>|null} The current value of the element
318 * (or null).
319 */
320 goog.dom.forms.getValue = function(el) {
321 // Elements with a type may need more specialized logic.
322 var type = /** @type {!HTMLInputElement} */ (el).type;
323 switch (goog.isString(type) && type.toLowerCase()) {
324 case goog.dom.InputType.CHECKBOX:
325 case goog.dom.InputType.RADIO:
326 return goog.dom.forms.getInputChecked_(el);
327 case goog.dom.InputType.SELECT_ONE:
328 return goog.dom.forms.getSelectSingle_(el);
329 case goog.dom.InputType.SELECT_MULTIPLE:
330 return goog.dom.forms.getSelectMultiple_(el);
331 default:
332 // Not every element with a value has a type (e.g. meter and progress).
333 return el.value != null ? el.value : null;
334 }
335 };
336
337
338 /**
339 * Returns the value of the named form field. In the case of radio buttons,
340 * returns the value of the checked button with the given name.
341 *
342 * @param {HTMLFormElement} form The form element.
343 * @param {string} name Name of an input to the form.
344 *
345 * @return {Array<string>|string|null} The value of the form element, or
346 * null if the form element does not exist or has no value.
347 */
348 goog.dom.forms.getValueByName = function(form, name) {
349 var els = form.elements[name];
350
351 if (els) {
352 if (els.type) {
353 return goog.dom.forms.getValue(els);
354 } else {
355 for (var i = 0; i < els.length; i++) {
356 var val = goog.dom.forms.getValue(els[i]);
357 if (val) {
358 return val;
359 }
360 }
361 }
362 }
363 return null;
364 };
365
366
367 /**
368 * Gets the current value of a checkable input element.
369 * @param {Element} el The element.
370 * @return {?string} The value of the form element (or null).
371 * @private
372 */
373 goog.dom.forms.getInputChecked_ = function(el) {
374 return el.checked ? /** @type {?} */ (el).value : null;
375 };
376
377
378 /**
379 * Gets the current value of a select-one element.
380 * @param {Element} el The element.
381 * @return {?string} The value of the form element (or null).
382 * @private
383 */
384 goog.dom.forms.getSelectSingle_ = function(el) {
385 var selectedIndex = /** @type {!HTMLSelectElement} */ (el).selectedIndex;
386 return selectedIndex >= 0 ?
387 /** @type {!HTMLSelectElement} */ (el).options[selectedIndex].value :
388 null;
389 };
390
391
392 /**
393 * Gets the current value of a select-multiple element.
394 * @param {Element} el The element.
395 * @return {Array<string>?} The value of the form element (or null).
396 * @private
397 */
398 goog.dom.forms.getSelectMultiple_ = function(el) {
399 var values = [];
400 for (var option, i = 0;
401 option = /** @type {!HTMLSelectElement} */ (el).options[i]; i++) {
402 if (option.selected) {
403 values.push(option.value);
404 }
405 }
406 return values.length ? values : null;
407 };
408
409
410 /**
411 * Sets the current value of any element with a type.
412 * @param {Element} el The element.
413 * @param {*=} opt_value The value to give to the element, which will be coerced
414 * by the browser in the default case using toString. This value should be
415 * an array for setting the value of select multiple elements.
416 */
417 goog.dom.forms.setValue = function(el, opt_value) {
418 // Elements with a type may need more specialized logic.
419 var type = /** @type {!HTMLInputElement} */ (el).type;
420 switch (goog.isString(type) && type.toLowerCase()) {
421 case goog.dom.InputType.CHECKBOX:
422 case goog.dom.InputType.RADIO:
423 goog.dom.forms.setInputChecked_(
424 el,
425 /** @type {string} */ (opt_value));
426 return;
427 case goog.dom.InputType.SELECT_ONE:
428 goog.dom.forms.setSelectSingle_(
429 el,
430 /** @type {string} */ (opt_value));
431 return;
432 case goog.dom.InputType.SELECT_MULTIPLE:
433 goog.dom.forms.setSelectMultiple_(
434 el,
435 /** @type {!Array<string>} */ (opt_value));
436 return;
437 default:
438 // Not every element with a value has a type (e.g. meter and progress).
439 el.value = opt_value != null ? opt_value : '';
440 }
441 };
442
443
444 /**
445 * Sets a checkable input element's checked property.
446 * #TODO(user): This seems potentially unintuitive since it doesn't set
447 * the value property but my hunch is that the primary use case is to check a
448 * checkbox, not to reset its value property.
449 * @param {Element} el The element.
450 * @param {string|boolean=} opt_value The value, sets the element checked if
451 * val is set.
452 * @private
453 */
454 goog.dom.forms.setInputChecked_ = function(el, opt_value) {
455 el.checked = opt_value;
456 };
457
458
459 /**
460 * Sets the value of a select-one element.
461 * @param {Element} el The element.
462 * @param {string=} opt_value The value of the selected option element.
463 * @private
464 */
465 goog.dom.forms.setSelectSingle_ = function(el, opt_value) {
466 // unset any prior selections
467 el.selectedIndex = -1;
468 if (goog.isString(opt_value)) {
469 for (var option, i = 0;
470 option = /** @type {!HTMLSelectElement} */ (el).options[i]; i++) {
471 if (option.value == opt_value) {
472 option.selected = true;
473 break;
474 }
475 }
476 }
477 };
478
479
480 /**
481 * Sets the value of a select-multiple element.
482 * @param {Element} el The element.
483 * @param {Array<string>|string=} opt_value The value of the selected option
484 * element(s).
485 * @private
486 */
487 goog.dom.forms.setSelectMultiple_ = function(el, opt_value) {
488 // reset string opt_values as an array
489 if (goog.isString(opt_value)) {
490 opt_value = [opt_value];
491 }
492 for (var option, i = 0;
493 option = /** @type {!HTMLSelectElement} */ (el).options[i]; i++) {
494 // we have to reset the other options to false for select-multiple
495 option.selected = false;
496 if (opt_value) {
497 for (var value, j = 0; value = opt_value[j]; j++) {
498 if (option.value == value) {
499 option.selected = true;
500 }
501 }
502 }
503 }
504 };