[Summary view] [Print] [Text view]

   1  /*

   2   * jQuery form plugin

   3   * @requires jQuery v1.0.3

   4   *

   5   * Dual licensed under the MIT and GPL licenses:

   6   *   http://www.opensource.org/licenses/mit-license.php

   7   *   http://www.gnu.org/licenses/gpl.html

   8   *

   9   * Revision: $Id$

  10   * Version: 0.9

  11   */
  12  
  13  /**

  14   * ajaxSubmit() provides a mechanism for submitting an HTML form using AJAX.

  15   *

  16   * ajaxSubmit accepts a single argument which can be either a success callback function

  17   * or an options Object.  If a function is provided it will be invoked upon successful

  18   * completion of the submit and will be passed the response from the server.

  19   * If an options Object is provided, the following attributes are supported:

  20   *

  21   *  target:   Identifies the element(s) in the page to be updated with the server response.

  22   *            This value may be specified as a jQuery selection string, a jQuery object,

  23   *            or a DOM element.

  24   *            default value: null

  25   *

  26   *  url:      URL to which the form data will be submitted.

  27   *            default value: value of form's 'action' attribute

  28   *

  29   *  method:   @deprecated use 'type'

  30   *  type:     The method in which the form data should be submitted, 'GET' or 'POST'.

  31   *            default value: value of form's 'method' attribute (or 'GET' if none found)

  32   *

  33   *  before:   @deprecated use 'beforeSubmit'

  34   *  beforeSubmit:  Callback method to be invoked before the form is submitted.

  35   *            default value: null

  36   *

  37   *  after:    @deprecated use 'success'

  38   *  success:  Callback method to be invoked after the form has been successfully submitted

  39   *            and the response has been returned from the server

  40   *            default value: null

  41   *

  42   *  dataType: Expected dataType of the response.  One of: null, 'xml', 'script', or 'json'

  43   *            default value: null

  44   *

  45   *  semantic: Boolean flag indicating whether data must be submitted in semantic order (slower).

  46   *            default value: false

  47   *

  48   *  resetForm: Boolean flag indicating whether the form should be reset if the submit is successful

  49   *

  50   *  clearForm: Boolean flag indicating whether the form should be cleared if the submit is successful

  51   *

  52   *

  53   * The 'beforeSubmit' callback can be provided as a hook for running pre-submit logic or for

  54   * validating the form data.  If the 'beforeSubmit' callback returns false then the form will

  55   * not be submitted. The 'beforeSubmit' callback is invoked with three arguments: the form data

  56   * in array format, the jQuery object, and the options object passed into ajaxSubmit.

  57   * The form data array takes the following form:

  58   *

  59   *     [ { name: 'username', value: 'jresig' }, { name: 'password', value: 'secret' } ]

  60   *

  61   * If a 'success' callback method is provided it is invoked after the response has been returned

  62   * from the server.  It is passed the responseText or responseXML value (depending on dataType).

  63   * See jQuery.ajax for further details.

  64   *

  65   *

  66   * The dataType option provides a means for specifying how the server response should be handled.

  67   * This maps directly to the jQuery.httpData method.  The following values are supported:

  68   *

  69   *      'xml':    if dataType == 'xml' the server response is treated as XML and the 'after'

  70   *                   callback method, if specified, will be passed the responseXML value

  71   *      'json':   if dataType == 'json' the server response will be evaluted and passed to

  72   *                   the 'after' callback, if specified

  73   *      'script': if dataType == 'script' the server response is evaluated in the global context

  74   *

  75   *

  76   * Note that it does not make sense to use both the 'target' and 'dataType' options.  If both

  77   * are provided the target will be ignored.

  78   *

  79   * The semantic argument can be used to force form serialization in semantic order.

  80   * This is normally true anyway, unless the form contains input elements of type='image'.

  81   * If your form must be submitted with name/value pairs in semantic order and your form

  82   * contains an input of type='image" then pass true for this arg, otherwise pass false

  83   * (or nothing) to avoid the overhead for this logic.

  84   *

  85   *

  86   * When used on its own, ajaxSubmit() is typically bound to a form's submit event like this:

  87   *

  88   * $("#form-id").submit(function() {

  89   *     $(this).ajaxSubmit(options);

  90   *     return false; // cancel conventional submit

  91   * });

  92   *

  93   * When using ajaxForm(), however, this is done for you.

  94   *

  95   * @example

  96   * $('#myForm').ajaxSubmit(function(data) {

  97   *     alert('Form submit succeeded! Server returned: ' + data);

  98   * });

  99   * @desc Submit form and alert server response

 100   *

 101   *

 102   * @example

 103   * var options = {

 104   *     target: '#myTargetDiv'

 105   * };

 106   * $('#myForm').ajaxSubmit(options);

 107   * @desc Submit form and update page element with server response

 108   *

 109   *

 110   * @example

 111   * var options = {

 112   *     success: function(responseText) {

 113   *         alert(responseText);

 114   *     }

 115   * };

 116   * $('#myForm').ajaxSubmit(options);

 117   * @desc Submit form and alert the server response

 118   *

 119   *

 120   * @example

 121   * var options = {

 122   *     beforeSubmit: function(formArray, jqForm) {

 123   *         if (formArray.length == 0) {

 124   *             alert('Please enter data.');

 125   *             return false;

 126   *         }

 127   *     }

 128   * };

 129   * $('#myForm').ajaxSubmit(options);

 130   * @desc Pre-submit validation which aborts the submit operation if form data is empty

 131   *

 132   *

 133   * @example

 134   * var options = {

 135   *     url: myJsonUrl.php,

 136   *     dataType: 'json',

 137   *     success: function(data) {

 138   *        // 'data' is an object representing the the evaluated json data

 139   *     }

 140   * };

 141   * $('#myForm').ajaxSubmit(options);

 142   * @desc json data returned and evaluated

 143   *

 144   *

 145   * @example

 146   * var options = {

 147   *     url: myXmlUrl.php,

 148   *     dataType: 'xml',

 149   *     success: function(responseXML) {

 150   *        // responseXML is XML document object

 151   *        var data = $('myElement', responseXML).text();

 152   *     }

 153   * };

 154   * $('#myForm').ajaxSubmit(options);

 155   * @desc XML data returned from server

 156   *

 157   *

 158   * @example

 159   * var options = {

 160   *     resetForm: true

 161   * };

 162   * $('#myForm').ajaxSubmit(options);

 163   * @desc submit form and reset it if successful

 164   *

 165   * @example

 166   * $('#myForm).submit(function() {

 167   *    $(this).ajaxSubmit();

 168   *    return false;

 169   * });

 170   * @desc Bind form's submit event to use ajaxSubmit

 171   *

 172   *

 173   * @name ajaxSubmit

 174   * @type jQuery

 175   * @param options  object literal containing options which control the form submission process

 176   * @cat Plugins/Form

 177   * @return jQuery

 178   * @see formToArray

 179   * @see ajaxForm

 180   * @see $.ajax

 181   * @author jQuery Community

 182   */
 183  jQuery.fn.ajaxSubmit = function(options) {
 184      if (typeof options == 'function')
 185          options = { success: options };
 186  
 187      options = jQuery.extend({
 188          url:    this.attr('action') || '',
 189          method: this.attr('method') || 'GET'
 190      }, options || {});
 191  
 192      // remap deprecated options (temporarily)

 193      options.success = options.success || options.after;
 194      options.beforeSubmit = options.beforeSubmit || options.before;
 195      options.type = options.type || options.method;
 196  
 197      var a = this.formToArray(options.semantic);
 198  
 199      // give pre-submit callback an opportunity to abort the submit

 200      if (options.beforeSubmit && options.beforeSubmit(a, this, options) === false) return this;
 201  
 202      var q = jQuery.param(a);
 203  
 204      if (options.type.toUpperCase() == 'GET') {
 205          // if url already has a '?' then append args after '&'

 206          options.url += (options.url.indexOf('?') >= 0 ? '&' : '?') + q;
 207          options.data = null;  // data is null for 'get'

 208      }
 209      else
 210          options.data = q; // data is the query string for 'post'

 211  
 212      var $form = this, callbacks = [];
 213      if (options.resetForm) callbacks.push(function() { $form.resetForm(); });
 214      if (options.clearForm) callbacks.push(function() { $form.clearForm(); });
 215  
 216      // perform a load on the target only if dataType is not provided

 217      if (!options.dataType && options.target) {
 218          var oldSuccess = options.success || function(){};
 219          callbacks.push(function(data, status) {
 220              jQuery(options.target).attr("innerHTML", data).evalScripts().each(oldSuccess, [data, status]);
 221          });
 222      }
 223      else if (options.success)
 224          callbacks.push(options.success);
 225  
 226      options.success = function(data, status) {
 227          for (var i=0, max=callbacks.length; i < max; i++)
 228              callbacks[i](data, status);
 229      };
 230  
 231      jQuery.ajax(options);
 232      return this;
 233  };
 234  
 235  /**

 236   * ajaxForm() provides a mechanism for fully automating form submission.

 237   *

 238   * The advantages of using this method instead of ajaxSubmit() are:

 239   *

 240   * 1: This method will include coordinates for <input type="image" /> elements (if the element

 241   *    is used to submit the form).

 242   * 2. This method will include the submit element's name/value data (for the element that was

 243   *    used to submit the form).

 244   * 3. This method binds the submit() method to the form for you.

 245   *

 246   * Note that for accurate x/y coordinates of image submit elements in all browsers

 247   * you need to also use the "dimensions" plugin (this method will auto-detect its presence).

 248   *

 249   * The options argument for ajaxForm works exactly as it does for ajaxSubmit.  ajaxForm merely

 250   * passes the options argument along after properly binding events for submit elements and

 251   * the form itself.  See ajaxSubmit for a full description of the options argument.

 252   *

 253   *

 254   * @example

 255   * var options = {

 256   *     target: '#myTargetDiv'

 257   * };

 258   * $('#myForm').ajaxSForm(options);

 259   * @desc Bind form's submit event so that 'myTargetDiv' is updated with the server response

 260   *       when the form is submitted.

 261   *

 262   *

 263   * @example

 264   * var options = {

 265   *     success: function(responseText) {

 266   *         alert(responseText);

 267   *     }

 268   * };

 269   * $('#myForm').ajaxSubmit(options);

 270   * @desc Bind form's submit event so that server response is alerted after the form is submitted.

 271   *

 272   *

 273   * @example

 274   * var options = {

 275   *     beforeSubmit: function(formArray, jqForm) {

 276   *         if (formArray.length == 0) {

 277   *             alert('Please enter data.');

 278   *             return false;

 279   *         }

 280   *     }

 281   * };

 282   * $('#myForm').ajaxSubmit(options);

 283   * @desc Bind form's submit event so that pre-submit callback is invoked before the form

 284   *       is submitted.

 285   *

 286   *

 287   * @name   ajaxForm

 288   * @param  options  object literal containing options which control the form submission process

 289   * @return jQuery

 290   * @cat    Plugins/Form

 291   * @type   jQuery

 292   * @see    ajaxSubmit

 293   * @author jQuery Community

 294   */
 295  jQuery.fn.ajaxForm = function(options) {
 296      return this.each(function() {
 297          jQuery("input:submit,input:image,button:submit", this).click(function(ev) {
 298              var $form = this.form;
 299              $form.clk = this;
 300              if (this.type == 'image') {
 301                  if (ev.offsetX != undefined) {
 302                      $form.clk_x = ev.offsetX;
 303                      $form.clk_y = ev.offsetY;
 304                  } else if (typeof jQuery.fn.offset == 'function') { // try to use dimensions plugin
 305                      var offset = jQuery(this).offset();
 306                      $form.clk_x = ev.pageX - offset.left;
 307                      $form.clk_y = ev.pageY - offset.top;
 308                  } else {
 309                      $form.clk_x = ev.pageX - this.offsetLeft;
 310                      $form.clk_y = ev.pageY - this.offsetTop;
 311                  }
 312              }
 313              // clear form vars

 314              setTimeout(function() {
 315                  $form.clk = $form.clk_x = $form.clk_y = null;
 316                  }, 10);
 317          })
 318      }).submit(function(e) {
 319          jQuery(this).ajaxSubmit(options);
 320          return false;
 321      });
 322  };
 323  
 324  
 325  /**

 326   * formToArray() gathers form element data into an array of objects that can

 327   * be passed to any of the following ajax functions: $.get, $.post, or load.

 328   * Each object in the array has both a 'name' and 'value' property.  An example of

 329   * an array for a simple login form might be:

 330   *

 331   * [ { name: 'username', value: 'jresig' }, { name: 'password', value: 'secret' } ]

 332   *

 333   * It is this array that is passed to pre-submit callback functions provided to the

 334   * ajaxSubmit() and ajaxForm() methods.

 335   *

 336   * The semantic argument can be used to force form serialization in semantic order.

 337   * This is normally true anyway, unless the form contains input elements of type='image'.

 338   * If your form must be submitted with name/value pairs in semantic order and your form

 339   * contains an input of type='image" then pass true for this arg, otherwise pass false

 340   * (or nothing) to avoid the overhead for this logic.

 341   *

 342   * @example var data = $("#myForm").formToArray();

 343   * $.post( "myscript.cgi", data );

 344   * @desc Collect all the data from a form and submit it to the server.

 345   *

 346   * @name formToArray

 347   * @param semantic true if serialization must maintain strict semantic ordering of elements (slower)

 348   * @type Array<Object>

 349   * @cat Plugins/Form

 350   * @see ajaxForm

 351   * @see ajaxSubmit

 352   * @author jQuery Community

 353   */
 354  jQuery.fn.formToArray = function(semantic) {
 355      var a = [];
 356      if (this.length == 0) return a;
 357  
 358      var form = this[0];
 359      var els = semantic ? form.getElementsByTagName('*') : form.elements;
 360      if (!els) return a;
 361      for(var i=0, max=els.length; i < max; i++) {
 362          var el = els[i];
 363          var n = el.name;
 364          if (!n) continue;
 365  
 366          if (semantic && form.clk && el.type == "image") {
 367              // handle image inputs on the fly when semantic == true

 368              if(!el.disabled && form.clk == el)
 369                  a.push({name: n+'.x', value: form.clk_x}, {name: n+'.y', value: form.clk_y});
 370              continue;
 371          }
 372          var v = jQuery.fieldValue(el, true);
 373          if (v === null) continue;
 374          if (v.constructor == Array) {
 375              for(var j=0, jmax=v.length; j < jmax; j++)
 376                  a.push({name: n, value: v[j]});
 377          }
 378          else
 379              a.push({name: n, value: v});
 380      }
 381  
 382      if (!semantic && form.clk) {
 383          // input type=='image' are not found in elements array! handle them here

 384          var inputs = form.getElementsByTagName("input");
 385          for(var i=0, max=inputs.length; i < max; i++) {
 386              var input = inputs[i];
 387              var n = input.name;
 388              if(n && !input.disabled && input.type == "image" && form.clk == input)
 389                  a.push({name: n+'.x', value: form.clk_x}, {name: n+'.y', value: form.clk_y});
 390          }
 391      }
 392      return a;
 393  };
 394  
 395  
 396  /**

 397   * Serializes form data into a 'submittable' string. This method will return a string

 398   * in the format: name1=value1&amp;name2=value2

 399   *

 400   * The semantic argument can be used to force form serialization in semantic order.

 401   * If your form must be submitted with name/value pairs in semantic order then pass

 402   * true for this arg, otherwise pass false (or nothing) to avoid the overhead for

 403   * this logic (which can be significant for very large forms).

 404   *

 405   * @example var data = $("#myForm").formSerialize();

 406   * $.ajax('POST', "myscript.cgi", data);

 407   * @desc Collect all the data from a form into a single string

 408   *

 409   * @name formSerialize

 410   * @param semantic true if serialization must maintain strict semantic ordering of elements (slower)

 411   * @type String

 412   * @cat Plugins/Form

 413   * @see formToArray

 414   * @author jQuery Community

 415   */
 416  jQuery.fn.formSerialize = function(semantic) {
 417      //hand off to jQuery.param for proper encoding

 418      return jQuery.param(this.formToArray(semantic));
 419  };
 420  
 421  
 422  /**

 423   * Serializes all field elements in the jQuery object into a query string.

 424   * This method will return a string in the format: name1=value1&amp;name2=value2

 425   *

 426   * The successful argument controls whether or not serialization is limited to

 427   * 'successful' controls (per http://www.w3.org/TR/html4/interact/forms.html#successful-controls).

 428   * The default value of the successful argument is true.

 429   *

 430   * @example var data = $("input").formSerialize();

 431   * @desc Collect the data from all successful input elements into a query string

 432   *

 433   * @example var data = $(":radio").formSerialize();

 434   * @desc Collect the data from all successful radio input elements into a query string

 435   *

 436   * @example var data = $("#myForm :checkbox").formSerialize();

 437   * @desc Collect the data from all successful checkbox input elements in myForm into a query string

 438   *

 439   * @example var data = $("#myForm :checkbox").formSerialize(false);

 440   * @desc Collect the data from all checkbox elements in myForm (even the unchecked ones) into a query string

 441   *

 442   * @example var data = $(":input").formSerialize();

 443   * @desc Collect the data from all successful input, select, textarea and button elements into a query string

 444   *

 445   * @name fieldSerialize

 446   * @param successful true if only successful controls should be serialized (default is true)

 447   * @type String

 448   * @cat Plugins/Form

 449   */
 450  jQuery.fn.fieldSerialize = function(successful) {
 451      var a = [];
 452      this.each(function() {
 453          var n = this.name;
 454          if (!n) return;
 455          var v = jQuery.fieldValue(this, successful);
 456          if (v && v.constructor == Array) {
 457              for (var i=0,max=v.length; i < max; i++)
 458                  a.push({name: n, value: v[i]});
 459          }
 460          else if (v !== null && typeof v != 'undefined')
 461              a.push({name: this.name, value: v});
 462      });
 463      //hand off to jQuery.param for proper encoding

 464      return jQuery.param(a);
 465  };
 466  
 467  
 468  /**

 469   * Returns the value of the field element in the jQuery object.  If there is more than one field element

 470   * in the jQuery object the value of the first successful one is returned.

 471   *

 472   * The successful argument controls whether or not the field element must be 'successful'

 473   * (per http://www.w3.org/TR/html4/interact/forms.html#successful-controls).

 474   * The default value of the successful argument is true.  If this value is false then

 475   * the value of the first field element in the jQuery object is returned.

 476   *

 477   * Note: If no valid value can be determined the return value will be undifined.

 478   *

 479   * Note: The fieldValue returned for a select-multiple element or for a checkbox input will

 480   *       always be an array if it is not undefined.

 481   *

 482   *

 483   * @example var data = $("#myPasswordElement").formValue();

 484   * @desc Gets the current value of the myPasswordElement element

 485   *

 486   * @example var data = $("#myForm :input").formValue();

 487   * @desc Get the value of the first successful control in the jQuery object.

 488   *

 489   * @example var data = $("#myForm :checkbox").formValue();

 490   * @desc Get the array of values for the first set of successful checkbox controls in the jQuery object.

 491   *

 492   * @example var data = $("#mySingleSelect").formValue();

 493   * @desc Get the value of the select control

 494   *

 495   * @example var data = $("#myMultiSelect").formValue();

 496   * @desc Get the array of selected values for the select-multiple control

 497   *

 498   * @name fieldValue

 499   * @param Boolean successful true if value returned must be for a successful controls (default is true)

 500   * @type String or Array<String>

 501   * @cat Plugins/Form

 502   */
 503  jQuery.fn.fieldValue = function(successful) {
 504      var cbVal, cbName;
 505  
 506      // loop until we find a value

 507      for (var i=0, max=this.length; i < max; i++) {
 508          var el = this[i];
 509          var v = jQuery.fieldValue(el, successful);
 510          if (v === null || typeof v == 'undefined' || (v.constructor == Array && !v.length))
 511              continue;
 512  
 513          // for checkboxes, consider multiple elements, for everything else just return first valid value

 514          if (el.type != 'checkbox') return v;
 515  
 516          cbName = cbName || el.name;
 517          if (cbName != el.name) // return if we hit a checkbox with a different name
 518              return cbVal;
 519          cbVal = cbVal || [];
 520          cbVal.push(v);
 521      }
 522      return cbVal;
 523  };
 524  
 525  /**

 526   * Returns the value of the field element.

 527   *

 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 the given element is not

 531   * successful and the successful arg is not false then the returned value will be null.

 532   *

 533   * Note: The fieldValue returned for a select-multiple element will always be an array.

 534   *

 535   * @example var data = jQuery.fieldValue($("#myPasswordElement")[0]);

 536   * @desc Gets the current value of the myPasswordElement element

 537   *

 538   * @name fieldValue

 539   * @param Element el The DOM element for which the value will be returned

 540   * @param Boolean successful true if value returned must be for a successful controls (default is true)

 541   * @type String or Array<String>

 542   * @cat Plugins/Form

 543   */
 544  jQuery.fieldValue = function(el, successful) {
 545      var n = el.name, t = el.type, tag = el.tagName.toLowerCase();
 546      if (typeof successful == 'undefined') successful = true;
 547  
 548      if (successful && ( !n || el.disabled || t == 'reset' ||
 549          (t == 'checkbox' || t == 'radio') && !el.checked ||
 550          (t == 'submit' || t == 'image') && el.form && el.form.clk != el ||
 551          tag == 'select' && el.selectedIndex == -1))
 552              return null;
 553  
 554      if (tag == 'select') {
 555          var index = el.selectedIndex;
 556          if (index < 0) return null;
 557          var a = [], ops = el.options;
 558          var one = (t == 'select-one');
 559          var max = (one ? index+1 : ops.length);
 560          for(var i=(one ? index : 0); i < max; i++) {
 561              var op = ops[i];
 562              if (op.selected) {
 563                  // extra pain for IE...

 564                  var v = jQuery.browser.msie && !(op.attributes['value'].specified) ? op.text : op.value;
 565                  if (one) return v;
 566                  a.push(v);
 567              }
 568          }
 569          return a;
 570      }
 571      return el.value;
 572  };
 573  
 574  
 575  /**

 576   * Clears the form data.  Takes the following actions on the form's input fields:

 577   *  - input text fields will have their 'value' property set to the empty string

 578   *  - select elements will have their 'selectedIndex' property set to -1

 579   *  - checkbox and radio inputs will have their 'checked' property set to false

 580   *  - inputs of type submit, button, reset, and hidden will *not* be effected

 581   *  - button elements will *not* be effected

 582   *

 583   * @example $('form').clearForm();

 584   * @desc Clears all forms on the page.

 585   *

 586   * @name clearForm

 587   * @type jQuery

 588   * @cat Plugins/Form

 589   * @see resetForm

 590   */
 591  jQuery.fn.clearForm = function() {
 592      return this.each(function() {
 593          jQuery('input,select,textarea', this).clearFields();
 594      });
 595  };
 596  
 597  /**

 598   * Clears the selected form elements.  Takes the following actions on the matched elements:

 599   *  - input text fields will have their 'value' property set to the empty string

 600   *  - select elements will have their 'selectedIndex' property set to -1

 601   *  - checkbox and radio inputs will have their 'checked' property set to false

 602   *  - inputs of type submit, button, reset, and hidden will *not* be effected

 603   *  - button elements will *not* be effected

 604   *

 605   * @example $('.myInputs').clearFields();

 606   * @desc Clears all inputs with class myInputs

 607   *

 608   * @name clearFields

 609   * @type jQuery

 610   * @cat Plugins/Form

 611   * @see clearForm

 612   */
 613  jQuery.fn.clearFields = jQuery.fn.clearInputs = function() {
 614      return this.each(function() {
 615          var t = this.type, tag = this.tagName.toLowerCase();
 616          if (t == 'text' || t == 'password' || tag == 'textarea')
 617              this.value = '';
 618          else if (t == 'checkbox' || t == 'radio')
 619              this.checked = false;
 620          else if (tag == 'select')
 621              this.selectedIndex = -1;
 622      });
 623  };
 624  
 625  
 626  /**

 627   * Resets the form data.  Causes all form elements to be reset to their original value.

 628   *

 629   * @example $('form').resetForm();

 630   * @desc Resets all forms on the page.

 631   *

 632   * @name resetForm

 633   * @type jQuery

 634   * @cat Plugins/Form

 635   * @see clearForm

 636   */
 637  jQuery.fn.resetForm = function() {
 638      return this.each(function() {
 639          // guard against an input with the name of 'reset'

 640          // note that IE reports the reset function as an 'object'

 641          if (typeof this.reset == 'function' || (typeof this.reset == 'object' && !this.reset.nodeType))
 642              this.reset();
 643      });
 644  };