You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+42-42Lines changed: 42 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,26 +1,26 @@
1
-
#jQuery Form [](https://travis-ci.org/jquery-form/form)
1
+
#jQuery Form [](https://travis-ci.org/jquery-form/form)
2
2
3
-
##Overview
3
+
##Overview
4
4
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.
5
5
6
6
No special markup is needed, just a normal form. Submitting a form with AJAX doesn't get any easier than this!
7
7
8
-
##Community
8
+
##Community
9
9
Want to contribute to jQuery Form? Awesome! See [CONTRIBUTING](CONTRIBUTING.md) for more information.
10
10
11
-
###Code of Conduct
11
+
###Code of Conduct
12
12
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md) to ensure that this project is a welcoming place for **everyone** to contribute to. By participating in this project you agree to abide by its terms.
13
13
14
-
##Requirements
14
+
##Requirements
15
15
Requires jQuery 1.7 or later. Compatible with jQuery 2.x and 3.x.
The jqXHR object is stored in element <em>data</em>-cache with the <code>jqxhr</code> key after each <code>ajaxSubmit</code>
38
38
call. It can be accessed like this:
39
39
@@ -46,7 +46,7 @@ xhr.done(function() {
46
46
});
47
47
````
48
48
49
-
###ajaxForm( options )
49
+
###ajaxForm( options )
50
50
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 existing forms for AJAX submission, or with the `delegation` option to handle forms not yet added to the DOM.
51
51
Use ajaxForm when you want the plugin to manage all the event binding for you.
52
52
@@ -57,7 +57,7 @@ $('form').ajaxForm({
57
57
});
58
58
````
59
59
60
-
###ajaxSubmit( options )
60
+
###ajaxSubmit( options )
61
61
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.
62
62
Use ajaxSubmit if you want to bind your own submit handler to the form.
**Note:** All standard [$.ajax](http://api.jquery.com/jQuery.ajax) options can be used.
78
78
79
-
###beforeSerialize
79
+
###beforeSerialize
80
80
Callback function invoked prior to form serialization. Provides an opportunity to manipulate the form before its values are retrieved. Returning `false` from the callback will prevent the form from being submitted. The callback is invoked with two arguments: the jQuery wrapped form object and the options object.
Callback function invoked prior to form submission. Returning `false` from the callback will prevent the form from being submitted. The callback is invoked with three arguments: the form data in array format, the jQuery wrapped form object, and the options object.
Boolean flag indicating whether the form should be cleared if the submit is successful
112
112
113
-
###data
113
+
###data
114
114
An object containing extra data that should be submitted along with the form.
115
115
116
116
````
117
117
data: { key1: 'value1', key2: 'value2' }
118
118
````
119
119
120
-
###dataType
120
+
###dataType
121
121
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 jQuery's dataType method. The following values are supported:
122
122
123
123
* 'xml': server response is treated as XML and the 'success' callback method, if specified, will be passed the responseXML value
124
124
* 'json': server response will be evaluted and passed to the 'success' callback, if specified
125
125
* 'script': server response is evaluated in the global context
126
126
127
-
###delegation
127
+
###delegation
128
128
true to enable support for event delegation
129
129
*requires jQuery v1.7+*
130
130
@@ -135,97 +135,97 @@ $('form').ajaxForm({
135
135
});
136
136
````
137
137
138
-
###error
138
+
###error
139
139
Callback function to be invoked upon error.
140
140
141
-
###forceSync
141
+
###forceSync
142
142
Only applicable when explicity using the iframe option or when uploading files on browses that don't support XHR2.
143
143
Set to `true` to remove the short delay before posting form when uploading files. 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..."
144
144
145
-
###iframe
145
+
###iframe
146
146
Boolean flag indicating whether the form should *always* target the server response to an iframe instead of leveraging XHR when possible.
147
147
148
-
###iframeSrc
148
+
###iframeSrc
149
149
String value that should be used for the iframe's src attribute when an iframe is used.
150
150
151
-
###iframeTarget
151
+
###iframeTarget
152
152
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.
153
153
154
-
###replaceTarget
154
+
###replaceTarget
155
155
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.
156
156
157
-
###resetForm
157
+
###resetForm
158
158
Boolean flag indicating whether the form should be reset if the submit is successful
159
159
160
-
###semantic
160
+
###semantic
161
161
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"`.
162
162
163
-
###success
163
+
###success
164
164
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 standard jQuery arguments:
165
165
166
166
1.`data`, formatted according to the dataType parameter or the dataFilter callback function, if specified
167
167
2.`textStatus`, string
168
168
3.`jqXHR`, object
169
169
4.`$form` jQuery object containing form element
170
170
171
-
###target
171
+
###target
172
172
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.
173
173
174
-
###type
174
+
###type
175
175
The method in which the form data should be submitted, 'GET' or 'POST'.
176
176
177
-
###uploadProgress
177
+
###uploadProgress
178
178
Callback function to be invoked with upload progress information (if supported by the browser). The callback is passed the following arguments:
179
179
180
180
1. event; the browser event
181
181
2. position (integer)
182
182
3. total (integer)
183
183
4. percentComplete (integer)
184
184
185
-
###url
185
+
###url
186
186
URL to which the form data will be submitted.
187
187
188
188
---
189
189
190
-
##Utility Methods
191
-
###formSerialize
190
+
##Utility Methods
191
+
###formSerialize
192
192
Serializes the form into a query string. This method will return a string in the format: `name1=value1&name2=value2`
193
193
194
194
````javascript
195
195
var queryString =$('#myFormId').formSerialize();
196
196
````
197
197
198
-
###fieldSerialize
198
+
###fieldSerialize
199
199
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`
200
200
201
201
````javascript
202
202
var queryString =$('#myFormId .specialFields').fieldSerialize();
203
203
````
204
204
205
-
###fieldValue
205
+
###fieldValue
206
206
Returns the value(s) of the element(s) in the matched set in an array. 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.
207
207
208
-
###resetForm
208
+
###resetForm
209
209
Resets the form to its original state by invoking the form element's native DOM method.
210
210
211
-
###clearForm
211
+
###clearForm
212
212
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. It does *not* clear hidden field values.
213
213
214
-
###clearFields
214
+
###clearFields
215
215
Clears selected field elements. This is handy when you need to clear only a part of the form.
216
216
217
217
---
218
218
219
-
##File Uploads
219
+
##File Uploads
220
220
The Form Plugin supports use of [XMLHttpRequest Level 2]("http://www.w3.org/TR/XMLHttpRequest/") and [FormData](https://developer.mozilla.org/en/XMLHttpRequest/FormData) objects on browsers that support these features. As of today (March 2012) that includes Chrome, Safari, and Firefox. On these browsers (and future Opera and IE10) files uploads will occur seamlessly through the XHR object and progress updates are available as the upload proceeds. For older browsers, a fallback technology is used which involves iframes. [More Info](http://malsup.com/jquery/form/#file-upload)
221
221
222
222
---
223
223
224
-
##Contributors
224
+
##Contributors
225
225
This project has transferred from [github.com/malsup/form](https://github.com/malsup/form/), courtesy of [Mike Alsup](https://github.com/malsup).
226
226
See [CONTRIBUTORS](CONTRIBUTORS.md) for details.
227
227
228
-
##License
228
+
##License
229
229
230
230
This project is dual licensed under the MIT and LGPLv3 licenses:
0 commit comments