Object used to define actions FormHelper will take upon form submission and
XHR lifecycle
Properties:
| Name |
Type |
Attributes |
Description |
form |
String
|
|
Form CSS selector string |
action |
String
|
<optional>
|
Where to post the XHR request. If ommitted,
will use the form's 'action' attribute value |
xhrOptions |
Object
|
<optional>
|
Custom XHR options to use. See jQuery documentation
for full list of options |
data |
Object
|
<optional>
|
Additional post data. Useful for defaults or
'always args'
Note the order order in which data is merged (later items take
precedence):
- formHelper.FormHelperRequest.Defaults.xhrOptions.data
- rule.xhrOptions.data
- rule.data
- serialized form data
|
isMultiForm |
Boolean
|
<optional>
|
Modify $form
to be the set of all matched FormRule.form elements as opposed to the
single submitted form, i.e. treat multiple forms as one single big form |
disableControls |
Boolean
|
<optional>
|
Automatically disable form controls
during submit |
scrollIntoViewOnUIUpdate |
Boolean
|
<optional>
|
Automatically scroll the form
into view (if it isn't already) if response caused us to modify the DOM |
focusFirstErroredControl |
Boolean
|
<optional>
|
Automatically focuses
the first errored control |
blankAllPasswordsOnSubmit |
Boolean
|
<optional>
|
Automatically call
blankAllPasswordFields on submit |
releaseFormAndUpdateUIOnXHRSuccess |
Boolean
|
<optional>
|
Automatically call
releaseForm and
updateUI after
xhrSuccess |
xhrReady |
FormRule.xhrReady
|
<optional>
|
Callback fired when xhrOptions
has been created but before the actual jqXHR has been created. The most
relevant non-StatusHandler callback |
xhrBeforeSend |
FormRule.xhrBeforeSend
|
<optional>
|
Callback fired during
the jqXHR beforeSend event:
beforeSend
This event, which is triggered before an Ajax request is started, allows you
to modify the XMLHttpRequest object (setting additional headers, if need be.)
|
xhrSuccess |
FormRule.xhrSuccess
|
<optional>
|
Callback fired during the
jqXHR success event:
success
This event is only called if the request was successful (no errors from the
server, no errors with the data).
|
xhrComplete |
FormRule.xhrComplete
|
<optional>
|
Callback fired during the
jqXHR complete event:
complete
This event is called regardless of if the request was successful, or not. You
will always receive a complete callback, even for synchronous requests.
|
xhrError |
FormRule.xhrError
|
<optional>
|
Callback fired during the jqXHR
error event:
error
This event is only called if an error occurred with the request (you can
never have both an error and a success callback with a request).
|
requestController |
function
|
<optional>
|
Class to instantiate to handle
FormRule execution. Defaults to FormHelperRequest |
customSubmitHandler |
function
|
<optional>
|
Prevents FormHelper from creating
a FormHelperRequest on submit and calls
this function instead. |
onComplete |
function
|
<optional>
|
Callback fired after when FormHelperRequest
is complete. |
status |
Object.<String, FormRule.StatusHandler>
|
<optional>
|
Object with keys matching FormHelperResponse status codes and their
accompanying StatusHandlers. Only the StatusHandler registered for the
returned status code will be invoked |
- Source:
Examples
{
form: '#form-login',
action: '/h/module/loginForm',
xhrOptions: {
type: 'POST', // Default value
data: {
foo: 'bar'
}
},
data: {
foo: 'bar',
baz: 'qux'
},
xhrReady: function(xhrOptions) {
// Everything is prepared, about to create jqXHR
},
xhrBeforeSend: function(jqXHR, settings) {
// jqXHR instantiated, about to make the request
},
xhrSuccess: function(data, textStatus, jqXHR) {
// Response received, all good.
},
xhrError: function(jqXHR, textStatus, errorThrown) {
// Something went wrong...
},
xhrComplete: function(jqXHR, textStatus) {
// jqXHR complete
},
status: {
SUCCESS: '/account', // Login successful, redirect user
ERROR: function() {
// Fired on a response status code of 'error'
this.find('#fancy-error-message').show();
}
}
}
{
form: '#form-sign-up',
action: '/h/module/signup',
xhrReady: function(xhrOptions) {
if (xhrOptions.data.accepts !== '1') {
this.cancel();
this.find('#message-accept-terms').show();
}
},
status: {
SUCCESS: function() {
this.$form.html(this.data);
}
}
}
Handler for a given
FormHelperResponse status. Can either be a
function or a string. If it's a function, it will be called in the context of
the
FormHelperRequest instance. If it's
a string, the browser will be forwarded to the given URL/path.