上傳轉載

時間 2019-12-11

標籤上傳轉載简体版

原文原文鏈接

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 src="http://ajax.googleapis.com/ajax/libs/jquery/1.7/jquery.js"></script>
    <script src="http://malsup.github.com/jquery.form.js"></script>

    <script>
        // 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!javascript

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.php

Form Plugin API

The Form Plugin API provides several methods that allow you to easily manage form data and form submission.

ajaxForm

Prepares a form to be submitted via AJAX by adding all of the necessary event listeners. It does not submit the form. Use ajaxForm in your document's ready function to prepare your form(s) for AJAX submission. 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 ajaxFormhtml

Example:java

$('#myFormId').ajaxForm();

ajaxSubmit

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 ajaxSubmitjquery

Example:git

// 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;
});

formSerialize

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:github

var queryString = $('#myFormId').formSerialize();

// the data could now be submitted using $.get, $.post, $.ajax, etc
$.post('myscript.php', queryString);

fieldSerialize

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:ajax

var queryString = $('#myFormId .specialFields').fieldSerialize();

fieldValue

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:json

// get the value of the password input
var value = $('#myFormId :password').fieldValue();
alert('The password is: ' + value[0]);

resetForm

Resets the form to its original state by invoking the form element's native DOM method.
Chainable: Yes.

Example:api

$('#myFormId').resetForm();

clearForm

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();

clearFields

Clears field elements. This is handy when you need to clear only a part of the form.
Chainable: Yes.

$('#myFormId .specialFields').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:

beforeSerialize

Callback function to be invoked before the form is serialized. This provides an opportunity to manipulate the form before it's values are retrieved. The beforeSerialize function is invoked with two arguments: the jQuery object for the form, and the Options Object passed into ajaxForm/ajaxSubmit.

beforeSerialize: function($form, options) {
    // return false to cancel submit		         
}

Default value: null

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.

beforeSubmit: function(arr, $form, options) {
    // The array of form data takes the following form:
    // [ { name: 'username', value: 'jresig' }, { name: 'password', value: 'secret' } ]
    
    // return false to cancel submit		         
}

Default value: null

clearForm

Boolean flag indicating whether the form should be cleared if the submit is successful
Default value: null

data

An object containing extra data that should be submitted along with the form.

data: { key1: 'value1', key2: 'value2' }

dataType

Expected data type of the response. One of: null, 'xml', 'script', or 'json'. The dataType option provides a means for specifying how the server response should be handled. This maps directly to the 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

error

Callback function to be invoked upon error.

forceSync

Boolean value. Set to true to remove short delay before posting form when uploading files (or using the iframe option). The delay is used to allow the browser to render DOM updates prior to performing a native form submit. This improves usability when displaying notifications to the user, such as "Please Wait..."
Default value: false

Added in v2.38

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

iframeSrc

String value that should be used for the iframe's src attribute when/if an iframe is used.
Default value: about:blank
Default value for pages that use https protocol: javascript:false

iframeTarget

Identifies the iframe element to be used as the response target for file uploads. By default, the plugin will create a temporary iframe element to capture the response when uploading files. This options allows you to use an existing iframe if you wish. When using this option the plugin will make no attempt at handling the response from the server.
Default value: null

Added in v2.76

replaceTarget

Optionally used along with the the target option. Set to true if the target should be replaced or false if only the target contents should be replaced.
Default value: false

Added in v2.43

resetForm

Boolean flag indicating whether the form should be reset if the submit is successful
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". You should only set the semantic option to true if your server has strict semantic requirements and your form contains an input element of type="image".
Default value: false

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 following arguments:

1.) responseText or responseXML value (depending on the value of the dataType option).
2.) statusText
3.) xhr (or the jQuery-wrapped form element if using jQuery < 1.4)
4.) jQuery-wrapped form element (or undefined if using jQuery < 1.4)

Default value: null

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

type

The method in which the form data should be submitted, 'GET' or 'POST'.
Default value: value of form's method attribute (or 'GET' if none found)

uploadProgress

Callback function to be invoked with upload progress information (if supported by the browser). The callback is passed the following arguments:

1.) event; the browser event
2.) position (integer)
3.) total (integer)
4.) percentComplete (integer)

Default value: null

url

URL to which the form data will be submitted.
Default value: value of form's action attribute

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.

Code Samples

The following code controls the HTML form beneath it. It uses ajaxForm to bind the form and demonstrates how to use pre- and post-submit callbacks.

// prepare the form when the DOM is ready
$(document).ready(function() {
    var options = {
        target:        '#output1',   // target element(s) to be updated with server response
        beforeSubmit:  showRequest,  // pre-submit callback
        success:       showResponse  // post-submit callback

        // other available options:
        //url:       url         // override for form's 'action' attribute
        //type:      type        // 'get' or 'post', override for form's 'method' attribute
        //dataType:  null        // 'xml', 'script', or 'json' (expected server response type)
        //clearForm: true        // clear all form fields after successful submit
        //resetForm: true        // reset the form after successful submit

        // $.ajax options can be used here too, for example:
        //timeout:   3000
    };

    // bind form using 'ajaxForm'
    $('#myForm1').ajaxForm(options);
});

// pre-submit callback
function showRequest(formData, jqForm, options) {
    // formData is an array; here we use $.param to convert it to a string to display it
    // but the form plugin does this for you automatically when it submits the data
    var queryString = $.param(formData);

    // jqForm is a jQuery object encapsulating the form element.  To access the
    // DOM element for the form do this:
    // var formElement = jqForm[0];

    alert('About to submit: \n\n' + queryString);

    // here we could return false to prevent the form from being submitted;
    // returning anything other than false will allow the form submit to continue
    return true;
}

// post-submit callback
function showResponse(responseText, statusText, xhr, $form)  {
    // for normal html responses, the first argument to the success callback
    // is the XMLHttpRequest object's responseText property

    // if the ajaxForm method was passed an Options Object with the dataType
    // property set to 'xml' then the first argument to the success callback
    // is the XMLHttpRequest object's responseXML property

    // if the ajaxForm method was passed an Options Object with the dataType
    // property set to 'json' then the first argument to the success callback
    // is the json data object returned by the server

    alert('status: ' + statusText + '\n\nresponseText: \n' + responseText +
        '\n\nThe output div should have already been updated with the responseText.');
}

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。