Ajaxform

Ajaxform is a JavaScript library that can turn any XHTML <form> into a form that get submitted by Ajax, without the need to reload the page.

Ajaxform uses progressive enhancement, users without JavaScript can still use the form in a traditional way; users with JavaScript will get a more sophisticated experience.

In the background, whenever a form is submitted, Ajaxform intercepts the submission, serializes the values of the fields, and then issues an HTTP request to the relevant action page using Ajax (either GET or POST, depending on what's specified as the method attribute of the form in the XHTML).

HTTP requests issued by Ajaxform will use "tmt.ajaxform" as the value of the "X-Requested-With" field in the HTTP header. This will allow server-side scripts to be aware if the form submission is coming from Ajax or not.

In order to use this library you need tmt_core.js, tmt_net.js, tmt_form.js and tmt_ajaxform.js

Samples

Syntax reference

There are only four attributes that apply to the form tag

tmt:ajaxform This attribute must be set to true in order to enable Ajaxform. This is the only required attribute
tmt:ajaxoncomplete Optional. JavaScript's function name. By default text from the server's response is displayed inside a box above the form. You can change this behavior by specifying a custom function that will be executed and get full control the server's response. Using this attribute requires some basic JavaScript programming skills (see sample)

Inside the function you can access:

  • this.response.responseText: HTTP response as text
  • this.response.responseXML: HTTP response as XML (if any)
  • this.response.status: HTTP status code
  • this.response.statusText: HTTP status text
  • this.response.url: url
  • this.response.allResponseHeaders: whole HTTP response header as a single string
  • this.response.contextData.domNode: the form as DOM node
tmt:ajaxonerror Optional. JavaScript's function name. This is the equivalent of ajaxoncomplete for handling error messages (yes, many things can go wrong using Ajax). Using this attribute requires some basic JavaScript programming skills (see sample)

Inside the function you can access:

  • this.response.responseText: HTTP response as text
  • this.response.responseXML: HTTP response as XML (if any)
  • this.response.status: HTTP status code
  • this.response.statusText: HTTP status text
  • this.response.url: url
  • this.response.allResponseHeaders: whole HTTP response header as a single string
  • this.response.contextData.domNode: the form as DOM node
tmt:ajaxonsubmit Optional. JavaScript's function name. A function that will be invoked as soon as the form is submitted, just before the HTTP call is send to the server (see sample). The function will receive one argument:
  • formNode: a reference to the form's tag DOM node
tmt:ajaxerrmessage Use this attribute to specify an error message that will be displayed inside a box above the form
It's recommended to use tmt:ajaxonerror to get more granular control
tmt:ajaxformcallback Deprecated, use tmt:ajaxoncomplete instead
tmt:ajaxformerrback Deprecated, use tmt:ajaxonerror instead

Sample XHTML code

Include the relevant JavaScript files first:

<script type="text/javascript" src="tmt_core.js"></script>
<script type="text/javascript" src="tmt_net.js"></script>
<script type="text/javascript" src="tmt_form.js"></script>
<script type="text/javascript" src="tmt_ajaxform.js"></script>

Then use an almost plain vanilla XHTML form:

<form action="action.htm" tmt:ajaxform="true">
<label>
Full name
<input type="text" name="full_name" />
</label>
<input type="submit" value="Submit" />
</form>

API

tmt.ajaxform.submit(formNode, [url], [contextData]) You can submit a form programmatically using this method. See sample
  • formNode: either an id (string) or a DOM node reference. Required
  • url: the url that will process the form. Optional
  • contextData: This is a very special kind of argument, an object where the caller can store any arbitrary content that will be available inside the callback. Optional. See sample

Gotchas