How to create an ajax form using ajax form for

Added for version: 0.4
Updated for version: 0.7

If you want to update only part of your webpage instead of the entire page, based on data from a form, you can use ajax-form-for.

Ajax-form-for works similarly to form-for but includes some ajax specific options. The arguments for ajax-form-for are request-map, options (optional) and body. Request-map and body are exactly the same as form-for. Options includes all of the options for form-for plus :update, :method, and :confirm.

Update

Update tells ajax-form-for what to call when the ajax request returns. Update can be either a scriptjure function, or a map containing two keys, :success and :failure.

If Update is a scriptjure function, then it is called when the ajax request completes successfully. Conjure includes a success-fn which can handle most of the common tasks of an ajax success.

Success-fn takes one or two arguments. The first or only argument is the id of the tag you wish to update. The second argument is the position of the update. The position can be any of the following:

• :content – Replaces the content of the tag.
• :replace – Replaces the entire tag.
• :before – Adds before the tag.
• :after – Adds after the tag
• :top – Adds as content at the first position of the tag.
• :bottom – Adds as content at the last position of the tag.
• :remove – Removes the tag.

If you don’t include a position, it is assumed to be :content.

For example, as success-fn to update the tag with id “update-me” by replacing its contents looks like:

(success-fn "update-me")

To replace the tag with id “update-me” use:

(success-fn "update-me" :replace)

The most basic ajax-form-for call which simply calls an action called :show and updates a tag with id “update-me” by replacing its content looks like:

(ajax-form-for { :action :show, :update (success-fn "update-me") }
  (form-button "Click Me"))

If we want to perform some special action if the ajax request fails, pass a map to :update. The map must contain a key :success and optionally can contain a :failure key. The success option must be a scriptjure function which will be called when the ajax request succeeds. The failure option is a scriptjure function which will be called if the ajax function fails.

Conjure comes with an error-fn function which displays a default message if the ajax request fails. It is automatically called if you do not pass a failure function. As an example, we’ll explicitly call it:

(ajax-form-for
  { :action :show, 
    :update 
      { :success (success-fn "update-me"),
        :failure (error-fn) }
  (form-button "Click Me"))

I broke the option map into multiple lines so it is easier to read. In the above call, the function returned by (success-fn “update-me”) will be called when the ajax request succeeds, and the function returned by (error-fn) will be called if it fails.

Method

The method option set the request method used in the ajax request to the server. Possible values are POST, GET, PUT, and DELETE. The default is POST.

To make our ajax-form-for call use a GET request we can do:

(ajax-form-for 
  { :action :show, 
    :update (success-fn "update-me"), 
    :method "GET" }
  (form-button "Click Me"))

Confirm

The confirm option is a scriptjure function which can will be called before the ajax request. If the confirm function returns false, then the ajax request is aborted, otherwise it continues.

To show a confirmation message, Conjure includes a confirm-fn function. Simply call the function and pass a message to display, and confirm-fn will return a scriptjure function for use in the confirm option.

To show a “Are you sure?” confirmation message use:

(ajax-form-for
  { :action :show, 
    :update (success-fn "update-me"), 
    :confirm (confirm-fn "Are you sure?") }
  (form-button "Click Me"))