Sandbox: JavaScript

Turns any form into an Ajax form updating the specified target in the DOM with the response.

Basic Usage

This is a form input. These buttons each submit different content to the server which just echos it back into the box below.

this box should get new text when you click the input above.
<form id="test" data-behavior="FormRequest" data-formrequest-update="!body #update" action="/sandbox/echo_html" method="get">
	<p>This is a form input. These buttons each submit different content to the server which just echos it back into the box below.</p>
	<input type="submit" name="html" class="btn btn-default" value="fetch html #1"/>
	<input type="submit" name="html" class="btn btn-default" value="fetch html #2"/>
</form>

<div id="update" class="box">
	this box should get new text when you click the input above.
</div>

Best Practices

When fetching data from a form submission, it's often easiest to write the page as normal with no AJAX in place and get everything working then add this Behavior after the fact and use the filter option to limit the response that's used.

This behavior also works well with Behavior.FormValidator.

Related Documentation

Note: Not all links in these work.

Behavior Filter: Behavior.FormRequest

Creates an instance of Form.Request for an element using the FormRequest data filter.

Example

<form data-behavior="FormRequest" data-formrequest-options="
  'update': '+.#target', //see additional targeting options below
  'filter': 'div.someSubsetOfTheResponse'
">
    <input name="foo" type="text"/>
    <input type="submit"/>
</form>
<div id="target">My content is replaced by the form response</div>

Required Settings

  • update - (string; required) The target element to update with the form response; any of the update values specified in the section below.

Options

  • filter - (string) If specified, the response tree will have this selector applied to it and the target will be filled with the result. I.e. if you specified div.foo as a filter and the response had a div with the class foo somewhere in it, only that div would be placed into the target.
  • resetForm - (boolean) If true (the default) the form is reset when it is submitted.

Update Values

The update option can have the following values:

  • self - this will have the form replace its own contents.
  • parent - the form will update it's parent. It's also acceptable to use the CSS selector supported by Slick for selecting parent nodes (<).
  • selector - a selector that is run from the form. In the example above, for instance, the selector is +.#target which says find my next sibling which has the id target.

Class: Form.Request

Updates a DOM element with the response from the submission of a form (via Ajax).

Demo

Implements

Form.Request Method: constructor

Syntax

new Form.Request(form, update[, options]);

Arguments

  1. form - (mixed) A form Element or the string id of a form Element to manage submissions.
  2. update - (mixed) An Element or the string id of an Element to update with the response.
  3. options - (object, optional) The options object described below:

Options

  • requestOptions - (object) The options passed on to the instance of [Request.HTML] created by the class that sends the form. Defaults to {evalScripts: true, useSpinner: true, url: , emulation: false, spinnerTarget: }.
  • extraData - (object) An optional set of key/value pairs to be included with the form data submitted to the server. If keys in this collide with data in the form, the form values will be preserved and the extraData discarded.
  • resetForm - (boolean) If true (the default), the form is reset when the request is sent.

Events

  • send - (function) The function to execute when the request is sent. Passed the form being submitted and the data (an object) being submitted.
  • failure - (function) The function to execute when the request fails. Passed the XHR that is returned by Request on failure.
  • success - (function) The function to execute when the request succeeds. Passed the target being updated, the request text, and the request xml.

Form.Request and Form.Validator

Form.Request integrates with Form.Validator to prevent the ajax being sent if the validation fails. It retrieves the Form.Validator instance from the form, so all that is required is that you instantiate the Form.Validator before you instantiate the instance of Fudpate. If the instance of Form.Validator has the stopOnFailure option set to true (the default) then Form.Request will not send the ajax request if the validator fails.

Form.Request Method: setTarget

Changes the target that the instance will update with the Request response.

Syntax

myformUpdate.setTarget(newTarget);

Arguments

  1. newTarget - (mixed) An Element or the string id of an Element to update with the response.

Returns

Form.Request Method: send

Sends the form.

Syntax

myformUpdate.send();

Returns

Form.Request Method: disable

Detaches the Form.Request from the form (disabling the ajax).

Syntax

myformUpdate.disable();

Returns

Form.Request Method: enable

Attaches the Form.Request to the form (enabling the ajax). Note that this is done on instantiation, so you only need to use this method if you disable the Form.Request instance and want to re-enable it.

Syntax

myformUpdate.enable();

Returns

Type: Element

Extends the Element Type with a reference to its Form.Request instance and a method to create one.

Element Method: formUpdate

Creates a new instance of Form.Request and calls its send method.

Syntax

$(element).formUpdate(update, options);

Arguments

  • update - (mixed) An Element or the string id of an Element to update with the response.
  • options - (object) a key/value set of options. See Form.Request:options.

Returns

  • (element) This Element.

Example

$(element).formUpdate($('myDiv'), { requestOptions: {useSpinner: false } });

Element property: form.request

Syntax

myForm.retrieve('form.request'); //the instance of Form.Request for the element