3
* version: 2.36 (07-NOV-2009)
4
* @requires jQuery v1.2.6 or later
6
* Examples and documentation at: http://malsup.com/jquery/form/
7
* Dual licensed under the MIT and GPL licenses:
8
* http://www.opensource.org/licenses/mit-license.php
9
* http://www.gnu.org/licenses/gpl.html
16
Do not use both ajaxSubmit and ajaxForm on the same form. These
17
functions are intended to be exclusive. Use ajaxSubmit if you want
18
to bind your own submit handler to the form. For example,
20
$(document).ready(function() {
21
$('#myForm').bind('submit', function() {
25
return false; // <-- important!
29
Use ajaxForm when you want the plugin to manage all the event binding
32
$(document).ready(function() {
33
$('#myForm').ajaxForm({
38
When using ajaxForm, the ajaxSubmit function will be invoked for you
39
at the appropriate time.
43
* ajaxSubmit() provides a mechanism for immediately submitting
44
* an HTML form using AJAX.
46
$.fn.ajaxSubmit = function(options) {
47
// fast fail if nothing selected (http://dev.jquery.com/ticket/2752)
49
log('ajaxSubmit: skipping submit process - no element selected');
53
if (typeof options == 'function')
54
options = { success: options };
56
var url = $.trim(this.attr('action'));
58
// clean url (don't include hash vaue)
59
url = (url.match(/^([^#]+)/)||[])[1];
61
url = url || window.location.href || '';
65
type: this.attr('method') || 'GET',
66
iframeSrc: /^https/i.test(window.location.href || '') ? 'javascript:false' : 'about:blank'
69
// hook for manipulating the form data before it is extracted;
70
// convenient for use with rich editors like tinyMCE or FCKEditor
72
this.trigger('form-pre-serialize', [this, options, veto]);
74
log('ajaxSubmit: submit vetoed via form-pre-serialize trigger');
78
// provide opportunity to alter form data before it is serialized
79
if (options.beforeSerialize && options.beforeSerialize(this, options) === false) {
80
log('ajaxSubmit: submit aborted via beforeSerialize callback');
84
var a = this.formToArray(options.semantic);
86
options.extraData = options.data;
87
for (var n in options.data) {
88
if(options.data[n] instanceof Array) {
89
for (var k in options.data[n])
90
a.push( { name: n, value: options.data[n][k] } );
93
a.push( { name: n, value: options.data[n] } );
97
// give pre-submit callback an opportunity to abort the submit
98
if (options.beforeSubmit && options.beforeSubmit(a, this, options) === false) {
99
log('ajaxSubmit: submit aborted via beforeSubmit callback');
103
// fire vetoable 'validate' event
104
this.trigger('form-submit-validate', [a, this, options, veto]);
106
log('ajaxSubmit: submit vetoed via form-submit-validate trigger');
112
if (options.type.toUpperCase() == 'GET') {
113
options.url += (options.url.indexOf('?') >= 0 ? '&' : '?') + q;
114
options.data = null; // data is null for 'get'
117
options.data = q; // data is the query string for 'post'
119
var $form = this, callbacks = [];
120
if (options.resetForm) callbacks.push(function() { $form.resetForm(); });
121
if (options.clearForm) callbacks.push(function() { $form.clearForm(); });
123
// perform a load on the target only if dataType is not provided
124
if (!options.dataType && options.target) {
125
var oldSuccess = options.success || function(){};
126
callbacks.push(function(data) {
127
$(options.target).html(data).each(oldSuccess, arguments);
130
else if (options.success)
131
callbacks.push(options.success);
133
options.success = function(data, status) {
134
for (var i=0, max=callbacks.length; i < max; i++)
135
callbacks[i].apply(options, [data, status, $form]);
138
// are there files to upload?
139
var files = $('input:file', this).fieldValue();
141
for (var j=0; j < files.length; j++)
145
var multipart = false;
146
// var mp = 'multipart/form-data';
147
// multipart = ($form.attr('enctype') == mp || $form.attr('encoding') == mp);
149
// options.iframe allows user to force iframe mode
150
// 06-NOV-09: now defaulting to iframe mode if file input is detected
151
if ((files.length && options.iframe !== false) || options.iframe || found || multipart) {
152
// hack to fix Safari hang (thanks to Tim Molendijk for this)
153
// see: http://groups.google.com/group/jquery-dev/browse_thread/thread/36395b7ab510dd5d
154
if (options.closeKeepAlive)
155
$.get(options.closeKeepAlive, fileUpload);
162
// fire 'notify' event
163
this.trigger('form-submit-notify', [this, options]);
167
// private function for handling file uploads (hat tip to YAHOO!)
168
function fileUpload() {
171
if ($(':input[name=submit]', form).length) {
172
alert('Error: Form elements must not be named "submit".');
176
var opts = $.extend({}, $.ajaxSettings, options);
177
var s = $.extend(true, {}, $.extend(true, {}, $.ajaxSettings), opts);
179
var id = 'jqFormIO' + (new Date().getTime());
180
var $io = $('<iframe id="' + id + '" name="' + id + '" src="'+ opts.iframeSrc +'" />');
183
$io.css({ position: 'absolute', top: '-1000px', left: '-1000px' });
185
var xhr = { // mock object
191
getAllResponseHeaders: function() {},
192
getResponseHeader: function() {},
193
setRequestHeader: function() {},
196
$io.attr('src', opts.iframeSrc); // abort op in progress
201
// trigger ajax global events so that activity/block indicators work like normal
202
if (g && ! $.active++) $.event.trigger("ajaxStart");
203
if (g) $.event.trigger("ajaxSend", [xhr, opts]);
205
if (s.beforeSend && s.beforeSend(xhr, s) === false) {
206
s.global && $.active--;
215
// add submitting element to data if we know it
219
if (n && !sub.disabled) {
220
options.extraData = options.extraData || {};
221
options.extraData[n] = sub.value;
222
if (sub.type == "image") {
223
options.extraData[name+'.x'] = form.clk_x;
224
options.extraData[name+'.y'] = form.clk_y;
229
// take a breath so that pending repaints get some cpu time before the upload starts
230
setTimeout(function() {
231
// make sure form attrs are set
232
var t = $form.attr('target'), a = $form.attr('action');
234
// update form attrs in IE friendly way
235
form.setAttribute('target',id);
236
if (form.getAttribute('method') != 'POST')
237
form.setAttribute('method', 'POST');
238
if (form.getAttribute('action') != opts.url)
239
form.setAttribute('action', opts.url);
241
// ie borks in some cases when setting encoding
242
if (! options.skipEncodingOverride) {
244
encoding: 'multipart/form-data',
245
enctype: 'multipart/form-data'
251
setTimeout(function() { timedOut = true; cb(); }, opts.timeout);
253
// add "extra" data to form if provided in options
254
var extraInputs = [];
256
if (options.extraData)
257
for (var n in options.extraData)
259
$('<input type="hidden" name="'+n+'" value="'+options.extraData[n]+'" />')
262
// add iframe to doc and submit the form
263
$io.appendTo('body');
264
io.attachEvent ? io.attachEvent('onload', cb) : io.addEventListener('load', cb, false);
268
// reset attrs and remove "extra" input elements
269
form.setAttribute('action',a);
270
t ? form.setAttribute('target', t) : $form.removeAttr('target');
271
$(extraInputs).remove();
275
var domCheckCount = 50;
278
if (cbInvoked++) return;
280
io.detachEvent ? io.detachEvent('onload', cb) : io.removeEventListener('load', cb, false);
284
if (timedOut) throw 'timeout';
285
// extract the server response from the iframe
288
doc = io.contentWindow ? io.contentWindow.document : io.contentDocument ? io.contentDocument : io.document;
290
var isXml = opts.dataType == 'xml' || doc.XMLDocument || $.isXMLDoc(doc);
292
if (!isXml && (doc.body == null || doc.body.innerHTML == '')) {
293
if (--domCheckCount) {
294
// in some browsers (Opera) the iframe DOM is not always traversable when
295
// the onload callback fires, so we loop a bit to accommodate
300
log('Could not access iframe DOM after 50 tries.');
304
xhr.responseText = doc.body ? doc.body.innerHTML : null;
305
xhr.responseXML = doc.XMLDocument ? doc.XMLDocument : doc;
306
xhr.getResponseHeader = function(header){
307
var headers = {'content-type': opts.dataType};
308
return headers[header];
311
if (opts.dataType == 'json' || opts.dataType == 'script') {
312
// see if user embedded response in textarea
313
var ta = doc.getElementsByTagName('textarea')[0];
315
xhr.responseText = ta.value;
317
// account for browsers injecting pre around json response
318
var pre = doc.getElementsByTagName('pre')[0];
320
xhr.responseText = pre.innerHTML;
323
else if (opts.dataType == 'xml' && !xhr.responseXML && xhr.responseText != null) {
324
xhr.responseXML = toXml(xhr.responseText);
326
data = $.httpData(xhr, opts.dataType);
330
$.handleError(opts, xhr, 'error', e);
333
// ordering of these callbacks/triggers is odd, but that's how $.ajax does it
335
opts.success(data, 'success');
336
if (g) $.event.trigger("ajaxSuccess", [xhr, opts]);
338
if (g) $.event.trigger("ajaxComplete", [xhr, opts]);
339
if (g && ! --$.active) $.event.trigger("ajaxStop");
340
if (opts.complete) opts.complete(xhr, ok ? 'success' : 'error');
343
setTimeout(function() {
345
xhr.responseXML = null;
349
function toXml(s, doc) {
350
if (window.ActiveXObject) {
351
doc = new ActiveXObject('Microsoft.XMLDOM');
356
doc = (new DOMParser()).parseFromString(s, 'text/xml');
357
return (doc && doc.documentElement && doc.documentElement.tagName != 'parsererror') ? doc : null;
363
* ajaxForm() provides a mechanism for fully automating form submission.
365
* The advantages of using this method instead of ajaxSubmit() are:
367
* 1: This method will include coordinates for <input type="image" /> elements (if the element
368
* is used to submit the form).
369
* 2. This method will include the submit element's name/value data (for the element that was
370
* used to submit the form).
371
* 3. This method binds the submit() method to the form for you.
373
* The options argument for ajaxForm works exactly as it does for ajaxSubmit. ajaxForm merely
374
* passes the options argument along after properly binding events for submit elements and
377
$.fn.ajaxForm = function(options) {
378
return this.ajaxFormUnbind().bind('submit.form-plugin', function() {
379
$(this).ajaxSubmit(options);
381
}).bind('click.form-plugin', function(e) {
382
var target = e.target;
384
if (!($el.is(":submit,input:image"))) {
385
// is this a child element of the submit el? (ex: a span within a button)
386
var t = $el.closest(':submit');
393
if (target.type == 'image') {
394
if (e.offsetX != undefined) {
395
form.clk_x = e.offsetX;
396
form.clk_y = e.offsetY;
397
} else if (typeof $.fn.offset == 'function') { // try to use dimensions plugin
398
var offset = $el.offset();
399
form.clk_x = e.pageX - offset.left;
400
form.clk_y = e.pageY - offset.top;
402
form.clk_x = e.pageX - target.offsetLeft;
403
form.clk_y = e.pageY - target.offsetTop;
407
setTimeout(function() { form.clk = form.clk_x = form.clk_y = null; }, 100);
411
// ajaxFormUnbind unbinds the event handlers that were bound by ajaxForm
412
$.fn.ajaxFormUnbind = function() {
413
return this.unbind('submit.form-plugin click.form-plugin');
417
* formToArray() gathers form element data into an array of objects that can
418
* be passed to any of the following ajax functions: $.get, $.post, or load.
419
* Each object in the array has both a 'name' and 'value' property. An example of
420
* an array for a simple login form might be:
422
* [ { name: 'username', value: 'jresig' }, { name: 'password', value: 'secret' } ]
424
* It is this array that is passed to pre-submit callback functions provided to the
425
* ajaxSubmit() and ajaxForm() methods.
427
$.fn.formToArray = function(semantic) {
429
if (this.length == 0) return a;
432
var els = semantic ? form.getElementsByTagName('*') : form.elements;
434
for(var i=0, max=els.length; i < max; i++) {
439
if (semantic && form.clk && el.type == "image") {
440
// handle image inputs on the fly when semantic == true
441
if(!el.disabled && form.clk == el) {
442
a.push({name: n, value: $(el).val()});
443
a.push({name: n+'.x', value: form.clk_x}, {name: n+'.y', value: form.clk_y});
448
var v = $.fieldValue(el, true);
449
if (v && v.constructor == Array) {
450
for(var j=0, jmax=v.length; j < jmax; j++)
451
a.push({name: n, value: v[j]});
453
else if (v !== null && typeof v != 'undefined')
454
a.push({name: n, value: v});
457
if (!semantic && form.clk) {
458
// input type=='image' are not found in elements array! handle it here
459
var $input = $(form.clk), input = $input[0], n = input.name;
460
if (n && !input.disabled && input.type == 'image') {
461
a.push({name: n, value: $input.val()});
462
a.push({name: n+'.x', value: form.clk_x}, {name: n+'.y', value: form.clk_y});
469
* Serializes form data into a 'submittable' string. This method will return a string
470
* in the format: name1=value1&name2=value2
472
$.fn.formSerialize = function(semantic) {
473
//hand off to jQuery.param for proper encoding
474
return $.param(this.formToArray(semantic));
478
* Serializes all field elements in the jQuery object into a query string.
479
* This method will return a string in the format: name1=value1&name2=value2
481
$.fn.fieldSerialize = function(successful) {
483
this.each(function() {
486
var v = $.fieldValue(this, successful);
487
if (v && v.constructor == Array) {
488
for (var i=0,max=v.length; i < max; i++)
489
a.push({name: n, value: v[i]});
491
else if (v !== null && typeof v != 'undefined')
492
a.push({name: this.name, value: v});
494
//hand off to jQuery.param for proper encoding
499
* Returns the value(s) of the element in the matched set. For example, consider the following form:
502
* <input name="A" type="text" />
503
* <input name="A" type="text" />
504
* <input name="B" type="checkbox" value="B1" />
505
* <input name="B" type="checkbox" value="B2"/>
506
* <input name="C" type="radio" value="C1" />
507
* <input name="C" type="radio" value="C2" />
510
* var v = $(':text').fieldValue();
511
* // if no values are entered into the text inputs
513
* // if values entered into the text inputs are 'foo' and 'bar'
516
* var v = $(':checkbox').fieldValue();
517
* // if neither checkbox is checked
519
* // if both checkboxes are checked
522
* var v = $(':radio').fieldValue();
523
* // if neither radio is checked
525
* // if first radio is checked
528
* The successful argument controls whether or not the field element must be 'successful'
529
* (per http://www.w3.org/TR/html4/interact/forms.html#successful-controls).
530
* The default value of the successful argument is true. If this value is false the value(s)
531
* for each element is returned.
533
* Note: This method *always* returns an array. If no valid value can be determined the
534
* array will be empty, otherwise it will contain one or more values.
536
$.fn.fieldValue = function(successful) {
537
for (var val=[], i=0, max=this.length; i < max; i++) {
539
var v = $.fieldValue(el, successful);
540
if (v === null || typeof v == 'undefined' || (v.constructor == Array && !v.length))
542
v.constructor == Array ? $.merge(val, v) : val.push(v);
548
* Returns the value of the field element.
550
$.fieldValue = function(el, successful) {
551
var n = el.name, t = el.type, tag = el.tagName.toLowerCase();
552
if (typeof successful == 'undefined') successful = true;
554
if (successful && (!n || el.disabled || t == 'reset' || t == 'button' ||
555
(t == 'checkbox' || t == 'radio') && !el.checked ||
556
(t == 'submit' || t == 'image') && el.form && el.form.clk != el ||
557
tag == 'select' && el.selectedIndex == -1))
560
if (tag == 'select') {
561
var index = el.selectedIndex;
562
if (index < 0) return null;
563
var a = [], ops = el.options;
564
var one = (t == 'select-one');
565
var max = (one ? index+1 : ops.length);
566
for(var i=(one ? index : 0); i < max; i++) {
570
if (!v) // extra pain for IE...
571
v = (op.attributes && op.attributes['value'] && !(op.attributes['value'].specified)) ? op.text : op.value;
582
* Clears the form data. Takes the following actions on the form's input fields:
583
* - input text fields will have their 'value' property set to the empty string
584
* - select elements will have their 'selectedIndex' property set to -1
585
* - checkbox and radio inputs will have their 'checked' property set to false
586
* - inputs of type submit, button, reset, and hidden will *not* be effected
587
* - button elements will *not* be effected
589
$.fn.clearForm = function() {
590
return this.each(function() {
591
$('input,select,textarea', this).clearFields();
596
* Clears the selected form elements.
598
$.fn.clearFields = $.fn.clearInputs = function() {
599
return this.each(function() {
600
var t = this.type, tag = this.tagName.toLowerCase();
601
if (t == 'text' || t == 'password' || tag == 'textarea')
603
else if (t == 'checkbox' || t == 'radio')
604
this.checked = false;
605
else if (tag == 'select')
606
this.selectedIndex = -1;
611
* Resets the form data. Causes all form elements to be reset to their original value.
613
$.fn.resetForm = function() {
614
return this.each(function() {
615
// guard against an input with the name of 'reset'
616
// note that IE reports the reset function as an 'object'
617
if (typeof this.reset == 'function' || (typeof this.reset == 'object' && !this.reset.nodeType))
623
* Enables or disables any matching elements.
625
$.fn.enable = function(b) {
626
if (b == undefined) b = true;
627
return this.each(function() {
633
* Checks/unchecks any matching checkboxes or radio buttons and
634
* selects/deselects and matching option elements.
636
$.fn.selected = function(select) {
637
if (select == undefined) select = true;
638
return this.each(function() {
640
if (t == 'checkbox' || t == 'radio')
641
this.checked = select;
642
else if (this.tagName.toLowerCase() == 'option') {
643
var $sel = $(this).parent('select');
644
if (select && $sel[0] && $sel[0].type == 'select-one') {
645
// deselect all other options
646
$sel.find('option').selected(false);
648
this.selected = select;
653
// helper fn for console logging
654
// set $.fn.ajaxSubmit.debug to true to enable debug logging
656
if ($.fn.ajaxSubmit.debug && window.console && window.console.log)
657
window.console.log('[jquery.form] ' + Array.prototype.join.call(arguments,''));