Overview
The jQuery Form Plugin allows you to easily and unobtrusively upgrade HTML forms to use AJAX. The main methods,
ajaxForm
and
ajaxSubmit
, gather information from the form element to determine how to manage the submit process. Both of these methods support numerous options which allows you to have full control over how the data is submitted. Submitting a form with AJAX doesn't get any easier than this!
Quick Start Guide
1Add a form to your page. Just a normal form, no special markup required:
<form id="myForm" action="comment.php" method="post">
Name: <input type="text" name="name" />
Comment: <textarea name="comment"></textarea>
<input type="submit" value="Submit Comment" />
</form>
2Include jQuery and the Form Plugin external script files and a short script to initialize the form when the DOM is ready:
<html>
<head>
<script type="text/javascript" src="jquery-1.3.2.js"></script>
<script type="text/javascript" src="jquery.form.js"></script>
<script type="text/javascript">
// wait for the DOM to be loaded
$(document).ready(function() {
// bind 'myForm' and provide a simple callback function
$('#myForm').ajaxForm(function() {
alert("Thank you for your comment!");
});
});
</script>
</head>
...
That's it!
When this form is submitted the name and comment fields will be posted to comment.php. If the server returns a success status then the user will see a "Thank you" message.
Form Plugin API
The Form Plugin API provides several methods that allow you to easily manage form data and form submission.
- Prepares a form to be submitted via AJAX by adding all of the necessary event listeners. It does not submit the form. Use
ajaxForm
ready
ajaxForm
takes zero or one argument. The single argument can be either a callback function or an Options Object.
Chainable: Yes.
Note: You can pass any of the standard
$.ajax
options to ajaxForm
Example:
$('#myFormId').ajaxForm(); - Immediately submits the form via AJAX. In the most common use case this is invoked in response to the user clicking a submit button on the form.
ajaxSubmit
takes zero or one argument. The single argument can be either a callback function or an Options Object.
Chainable: Yes.
Note: You can pass any of the standard
$.ajax
options to ajaxSubmit
Example:
// attach handler to form's submit event $('#myFormId').submit(function() { // submit the form $(this).ajaxSubmit(); // return false to prevent normal browser submit and page navigation return false; }); - Serializes the form into a query string. This method will return a string in the format:
name1=value1&name2=value2
Chainable: No, this method returns a String.
Example:
var queryString = $('#myFormId').formSerialize(); // the data could now be submitted using $.get, $.post, $.ajax, etc $.post('myscript.php', queryString); - Serializes field elements into a query string. This is handy when you need to serialize only part of a form. This method will return a string in the format:
name1=value1&name2=value2
Chainable: No, this method returns a String.
Example:
var queryString = $('#myFormId .specialFields').fieldSerialize(); -
Returns the value(s) of the element(s) in the matched set in an array. As of version .91, this method always returns an array. If no valid value can be determined the array will be empty, otherwise it will contain one or more values.
Chainable: No, this method returns an array.
Example:
// get the value of the password input var value = $('#myFormId :password').fieldValue(); alert('The password is: ' + value[0]); -
Resets the form to its original state by invoking the form element's native DOM method.
Chainable: Yes.
Example:
$('#myFormId').resetForm(); -
Clears the form elements. This method emptys all of the text inputs, password inputs and textarea elements, clears the selection in any select elements, and unchecks all radio and checkbox inputs.
Chainable: Yes.
$('#myFormId').clearForm(); -
Clears field elements. This is handy when you need to clear only a part of the form.
Chainable: Yes.
$('#myFormId .specialFields').clearFields();
ajaxForm
ajaxSubmit
formSerialize
fieldSerialize
fieldValue
resetForm
clearForm
clearFields
ajaxForm and ajaxSubmit Options
Note: Aside from the options listed below, you can also pass any of the standard $.ajax options to ajaxForm and ajaxSubmit.
Both
ajaxForm and
ajaxSubmit support numerous options which can be provided using an Options Object. The Options Object is simply a JavaScript object that contains properties with values set as follows:
- target
-
Identifies the element(s) in the page to be updated with the server response. This value may be specified as a jQuery selection string, a jQuery object, or a DOM element.
Default value:
null
url -
URL to which the form data will be submitted.
Default value: value of form's
action
type -
The method in which the form data should be submitted, 'GET' or 'POST'.
Default value: value of form's
method
beforeSubmit - Callback function to be invoked before the form is submitted. The 'beforeSubmit' callback can be provided as a hook for running pre-submit logic or for validating the form data. If the 'beforeSubmit' callback returns false then the form will not be submitted. The 'beforeSubmit' callback is invoked with three arguments: the form data in array format, the jQuery object for the form, and the Options Object passed into ajaxForm/ajaxSubmit. The array of form data takes the following form:
Default value:[ { name: 'username', value: 'jresig' }, { name: 'password', value: 'secret' } ]null
success -
Callback function to be invoked after the form has been submitted. If a 'success' callback function is provided it is invoked after the response has been returned from the server. It is passed the responseText or responseXML value (depending on the value of the dataType option).
Default value:
null
dataType - Expected data type of the response. One of: null, 'xml', 'script', or 'json'. The
dataType
jQuery.httpData
method. The following values are supported:
'xml': if dataType == 'xml' the server response is treated as XML and the 'success' callback method, if specified, will be passed the responseXML value
'json': if dataType == 'json' the server response will be evaluted and passed to the 'success' callback, if specified
'script': if dataType == 'script' the server response is evaluated in the global context
Default value:
null
semantic - Boolean flag indicating whether data must be submitted in strict semantic order (slower). Note that the normal form serialization is done in semantic order with the exception of input elements of
type="image"
type="image"
.
Default value:
false
resetForm -
Boolean flag indicating whether the form should be reset if the submit is successful
Default value:
null
clearForm -
Boolean flag indicating whether the form should be cleared if the submit is successful
Default value:
null
iframe -
Boolean flag indicating whether the form should always target the server response to an iframe. This is useful in conjuction with file uploads. See the File Uploads documentation on the Code Samples page for more info.
Default value:
false
Example:
// prepare Options Object
var options = {
target: '#divToUpdate',
url: 'comment.php',
success: function() {
alert('Thanks for your comment!');
}
};
// pass options to ajaxForm
$('#myForm').ajaxForm(options);
Note that the Options Object can also be used to pass values to jQuery's
$.ajax
method. If you are familiar with the options supported by
$.ajax
you may use them in the Options Object passed to
ajaxForm
and
ajaxSubmit
.
![用jQuery实现一个简易的聊天框[图]](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=)