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,''));