How to create an ajax link using ajax link to

Added for version: 0.4
Updated for version: 0.7

If you only want to update part of a webpage instead of the entire page when a user clicks on a link you can use the ajax-link-to function.

The ajax-link-to function takes the text of the link and params. The text argument works just like the text argument of link-to. Params has the same valid parameters as url-for, but also include parameters specifically for the ajax request.

The only required ajax parameter is :update. Update can be a map or a scriptjure function. If it is a scriptjure function, then the function is called when the ajax request succeeds. If it is a map, then ajax-link-to looks for the keys :success and :failure.

Success is a scriptjure function and is called when the ajax request succeeds. Failure is another scriptjure function and is called when the ajax request fails.

Here is a basic ajax-link-to call:

(ajax-link-to "Click Me" { :action :ajax-click-me, :update (success-fn "targetid") })

The above ajax-link-to call creates an ajax link with the text “Click Me” which calls the action “ajax-click-me” in the same controller as where the link was called from. If the ajax request is successful, then the javascript function returned as a string from the call to success-fn is called.

Success-fn is a convenience function which constructs a simple scriptjure function which updates the tag with the given id. In the above example, the call (success-fn “targetid”) will take whatever is returned by the action “ajax-click-me” and add it as the content of the tag with the id “targetid”.

If you want to replace the tag with id “targetid” instead of update it’s contents, you can pass :replace as the position parameter:

(ajax-link-to "Click Me" { :action :ajax-click-me, :update (success-fn "targetid" :replace) })

The following positions are supported by success-fn:

• :content – Replaces the content of the tag (default)
• :replace – Replaces the tag
• :before – Adds before the tag
• :after – Adds after the tag
• :top – Adds to the content at the top position of the tag
• :bottom – Adds to the content at the bottom position of the tag
• :remove – Removes the tag.

To add a function to call on error use a map for :update and add :failure as a key. The value of :failure is another scriptjure function.

Example:

(ajax-link-to "Click Me"
  { :action :ajax-click-me, 
    :update 
    { :success (success-fn "targetid") 
      :failure (error-fn) } })

In the above example, :update is a map with a success function which updates the tag with id “targetid”, and a standard Conjure error function. Error-fn returns a scriptjure function which simply calls the ajaxError function in the conjure javascript library. It isn’t necessary for to use error-fn for the failure function since Conjure automatically calls ajaxError if no other failure function is given.

You can change the request method from the default “POST” to “GET” using the :method parameter:

(ajax-link-to "Click Me"
  { :action :ajax-click-me, 
    :update (success-fn "targetid" :replace)
    :method "GET" })

To add a function to call before the ajax call is executed use the :confirm parameter. Confirm is a scriptjure function which returns true if the ajax execution should continue or false if it should abort. Confirm is useful if you want to display a message to the user and get a yes or no answer.

Conjure includes a simple confirm-fn function which takes a message to display to the user and returns a scriptjure function to display an alert and do the proper action on user confirmation.

To get confirmation from the user that it is “Ok to continue” use:

(ajax-link-to "Click Me"
  { :action :ajax-click-me, 
    :update (success-fn "targetid" :replace)
    :confirm (confirm-fn "Ok to continue") })