Registreren

Using AJAX in your velocity scripts

Pay attention: In an older version of this script data-replace="$id" was used instead of data-target="#$id". 

With AJAX you can replace one or more existing html elements without reloading the whole page. The examples here use the jQuery library that our standard pages use as well, plus a javascript called app-ajax.js. The script changes the behavior of anchors and forms when the class app-ajax is added to the element. You can change app with you application's technical name. If you do be aware to change the classes in the script too.

Make sure the jQuery library and the app-ajax script are added in your surrounding page. The jQuery library is already added when you use the $document.getDefaultScripts() method in the surrounding page. You have to dowload the ajax script yourself and place it somewhere in your application directory. In the example below we used the directory called js. Dowload the app-ajax script here. 

$document.addScript("/js/app-ajax.js")

It will be included in the page if $!document.getScripts() is set in the surrounding page.

There are four basic situations.

  • Single element replace after clicking a link
    Clicking on an <a> tag replaces one single element on the page

  • Single element replace after a form submit
    Submitting a form replaces one singe element on the page

  • Multiple element replaces after clicking a link
    Clicking on an <a> tag replaces multiple elements on the page

  • Multiple element replaces after a form submit
    Submitting a form replaces multiple elements on the page

In all situations the class app-ajax has to be added tot either the anchor or the form.

Situation 1: Single element replace after clicking a link

Suppose we are working in a velocity file called test.vm. The following code shows a message on screen after clicking a link. The attribute data-target should contain the id of the element you want to be replaced by the response of your AJAX request. In our case this is #to_be_replaced. We assign it to a variable called $id. In the data attribute we prefix the id with a hash # so it looks like this: data-target="#$id".

#set($id = "to_be_replaced")

#if($request.isAjaxRequest())
    Your request has been received.
    #stop
#end

$document.surround()
$document.addScript("/js/app-ajax.js")

<a href="/test.vm" class="app-ajax" data-target="#$id">Click here</a>
<span id="$id"></span>

 

Situation 2: Single element replace after a form submit

In this example a form is submitted and the result is replacing an element on the page.

#set($id = "to_be_replaced")

#if($request.isAjaxRequest())
    You just typed: $request.get('text')
    #stop
#end

$document.surround()
$document.addScript("/js/app-ajax.js")

<form action="/test.vm" id="$id" class="app-ajax" data-target="#$id">
    <textarea name="text" placeholder="Your text here"></textarea>
    <input type="submit">
</form>

 

Situation 3: Multiple element replaces after clicking a link

If you want to replace more than one element, you will need to return JSON. Just create a map using the id attribute of the element as key and the html fragment as value. Calling the $map.toJSON() method will render the appropriate response. Be sure to set the content type of the $response object to JSON as well. 

#set($id1 = "to_be_replaced_1")
#set($id2 = "to_be_replaced_2")

#if($request.isAjaxRequest())
    $response.setContentType('application/json')
    #set($map = $engine.newMap())
    $map.putVoid("#$id1", "<span id='$id1'>Hallo 1: $application.newDate()</span>")
    $map.putVoid("#$id2", "<span id='$id2'>Hallo 2: $application.newDate()</span>")
    $map.toJSON()
    #stop
#end

$document.surround()
$document.addScript("/js/app-ajax.js")

<a href="/test.vm" class="app-ajax">Click here</a>
<span id="$id1"></span>
<span id="$id2"></span>

 

Situation 4: Multiple element replaces after a form submit

 Here a submit af a form replaces two existing elements on the page 

#set($id1 = "to_be_replaced_1")
#set($id2 = "to_be_replaced_2")

#if($request.isAjaxRequest())
    $response.setContentType('application/json')
    #set($map = $engine.newMap())
    $map.putVoid('#$id1', "<span id='$id1'>1 - $request.get('text')</span>")
    $map.putVoid('#$id2', "<span id='$id2'>2 - $application.newDate()</span>")
    $map.toJSON()
    #stop
#end

$document.surround()
$document.addScript("/js/app-ajax.js")

<form action="/test.vm" class="app-ajax">
    <textarea name="text">Your text here</textarea>
    <input type="submit">
</form>
<span id="$id1"></span>
<span id="$id2"></span>

 

Other considarations

In all examples the AJAX request is sent to the original page. This is not necessary, but often convenient because you can use the same code to generate a full html response or a partial one. You can use the isAjaxRequest method of the $request object to discriminate between the two. In case the request is a ajax request you have to return either a HTML string or a JSON object.

You can use the #stop command to arrest evaluation and return the result immediately to the browser. Make sure to omit a surrounding page when handling an ajax request: no $document.surround()