[Sommaire] [Imprimer]

   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: form.js 1021 2007-01-12 01:45:09Z malsup $

  10   */
  11  
  12  /**

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

  14   *

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

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

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

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

  19   *

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

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

  22   *            or a DOM element.

  23   *            default value: null

  24   *

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

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

  27   *  

  28   *  method:   @deprecated use 'type'

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

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

  31   *

  32   *  before:   @deprecated use 'beforeSubmit'

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

  34   *            default value: null

  35   *

  36   *  after:    @deprecated use 'success'

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

  38   *            and the response has been returned from the server

  39   *            default value: null

  40   *

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

  42   *            default value: null

  43   *

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

  45   *            default value: false

  46   *

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

  48   *

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

  50   *

  51   *

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

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

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

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

  56   * The form data array takes the following form:

  57   *

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

  59   *

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

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

  62   * See jQuery.ajax for further details.

  63   *

  64   *

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

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

  67   * 

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

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

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

  71   *                   the 'after' callback, if specified

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

  73   *

  74   *

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

  76   * are provided the target will be ignored.

  77   *

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

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

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

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

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

  83   *

  84   *

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

  86   *

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

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

  89   *     return false; // cancel conventional submit

  90   * });

  91   *

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

  93   *

  94   * @example

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

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

  97   * });

  98   * @desc Submit form and alert server response

  99   *

 100   *

 101   * @example

 102   * var options = {

 103   *     target: '#myTargetDiv'

 104   * };

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

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

 107   *

 108   *

 109   * @example

 110   * var options = {

 111   *     success: function(responseText) {

 112   *         alert(responseText);

 113   *     }

 114   * };

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

 116   * @desc Submit form and alert the server response

 117   *

 118   *

 119   * @example

 120   * var options = {

 121   *     beforeSubmit: function(formArray, jqForm) {

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

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

 124   *             return false;

 125   *         }

 126   *     }

 127   * };

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

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

 130   *

 131   *

 132   * @example

 133   * var options = {

 134   *     url: myJsonUrl.php,

 135   *     dataType: 'json',

 136   *     success: function(data) {

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

 138   *     }

 139   * };

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

 141   * @desc json data returned and evaluated

 142   *

 143   *

 144   * @example

 145   * var options = {

 146   *     url: myXmlUrl.php,

 147   *     dataType: 'xml',

 148   *     success: function(responseXML) {

 149   *        // responseXML is XML document object

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

 151   *     }

 152   * };

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

 154   * @desc XML data returned from server

 155   *

 156   *

 157   * @example

 158   * var options = {

 159   *     resetForm: true

 160   * };

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

 162   * @desc submit form and reset it if successful

 163   *

 164   * @example

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

 166   *    $(this).ajaxSubmit();

 167   *    return false;

 168   * });

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

 170   *

 171   *

 172   * @name ajaxSubmit

 173   * @type jQuery

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

 175   * @cat Plugins/Form

 176   * @return jQuery

 177   * @see formToArray

 178   * @see ajaxForm

 179   * @see $.ajax

 180   * @author jQuery Community

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

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

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

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

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

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

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

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

 236   *

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

 238   *

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

 240   *    is used to submit the form).

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

 242   *    used to submit the form).

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

 244   *

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

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

 247   *

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

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

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

 251   *

 252   *

 253   * @example

 254   * var options = {

 255   *     target: '#myTargetDiv'

 256   * };

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

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

 259   *       when the form is submitted.

 260   *

 261   *

 262   * @example

 263   * var options = {

 264   *     success: function(responseText) {

 265   *         alert(responseText);

 266   *     }

 267   * };

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

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

 270   *

 271   *

 272   * @example

 273   * var options = {

 274   *     beforeSubmit: function(formArray, jqForm) {

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

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

 277   *             return false;

 278   *         }

 279   *     }

 280   * };

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

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

 283   *       is submitted.

 284   *

 285   *

 286   * @name   ajaxForm

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

 288   * @return jQuery

 289   * @cat    Plugins/Form

 290   * @type   jQuery

 291   * @see    ajaxSubmit

 292   * @author jQuery Community

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

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

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

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

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

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

 329   *

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

 331   *

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

 333   * ajaxSubmit() and ajaxForm() methods.

 334   *

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

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

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

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

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

 340   *

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

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

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

 344   *

 345   * @name formToArray

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

 347   * @type Array<Object>

 348   * @cat Plugins/Form

 349   * @see ajaxForm

 350   * @see ajaxSubmit

 351   * @author jQuery Community

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

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

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

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

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

 398   *

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

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

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

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

 403   *

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

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

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

 407   *

 408   * @name formSerialize

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

 410   * @type String

 411   * @cat Plugins/Form

 412   * @see formToArray

 413   * @author jQuery Community

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

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

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

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

 424   *

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

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

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

 428   *

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

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

 431   *

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

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

 434   *

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

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

 437   *

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

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

 440   *

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

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

 443   *

 444   * @name fieldSerialize

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

 446   * @type String

 447   * @cat Plugins/Form

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

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

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

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

 470   *

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

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

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

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

 475   *

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

 477   *

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

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

 480   *

 481   *

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

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

 484   *

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

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

 487   *

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

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

 490   *

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

 492   * @desc Get the value of the select control

 493   *

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

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

 496   *

 497   * @name fieldValue

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

 499   * @type String or Array<String>

 500   * @cat Plugins/Form

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

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

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

 525   * Returns the value of the field element.

 526   *

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

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

 529   * The default value of the successful argument is true.  If the given element is not

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

 531   *

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

 533   *

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

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

 536   *

 537   * @name fieldValue

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

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

 540   * @type String or Array<String>

 541   * @cat Plugins/Form

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

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

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

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

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

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

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

 580   *  - button elements will *not* be effected

 581   *

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

 583   * @desc Clears all forms on the page.

 584   *

 585   * @name clearForm

 586   * @type jQuery

 587   * @cat Plugins/Form

 588   * @see resetForm

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

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

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

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

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

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

 602   *  - button elements will *not* be effected

 603   *

 604   * @example $('.myInputs').clearInputs();

 605   * @desc Clears all inputs with class myInputs

 606   *

 607   * @name clearInputs

 608   * @type jQuery

 609   * @cat Plugins/Form

 610   * @see clearForm

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

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

 627   *

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

 629   * @desc Resets all forms on the page.

 630   *

 631   * @name resetForm

 632   * @type jQuery

 633   * @cat Plugins/Form

 634   * @see clearForm

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

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

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