Registreren

Using velocity templates within the blueprint

You might want to change the design and layout of the pages that present the data in your application. This can be done using velocity templates. Templates are velocity scripts, which can be created and edited through the resource files. More info on creating scripts can be found in the velocity tutorial.

With a velocity template you can define how to present the data from your application. A velocity template can be used to change the presentation for the class details screen: in the blueprint, in the "properties" section of the class, under "HTML template", a path to a velocity script can be entered. When a record in the class is accessed in your application, instead of the standard detail screen, the template will be shown. If you use a template it will affect all detail screens. So you can use the template or the standard detail screens but not both.

Example: velocity template for class details

Imagine that your application has a class "product". If you go to the class detail page, the application engine will show the product data according to the section and field layout you have specified in the blueprint. This is an example of the standard view in your application:

 

However, you can also define a velocity template instead. Here is an example of (part of) such a template:

## first get the product id from the html request, and if there is no id, select the first available record:

#set($id = $request.get('id'))
#if($id)
    #set($record = $session.getRecord('product', $id))
#else
    #set($record = $session.getFirstRecord('product'))
#end

## now a html page can be generated using the record we have stored in the $record variable:

<h3>$record.get('name')</h3>
#if($record.get('image'))
    <img src="$record.getBlobUrl('image')" alt="">
#end
<p>$record.get('description')</p>  
<p>Price: € $record.get('price').format("en")</p>

The application engine will automatically put the appropriate record of the detail page in the velocity context as a variable, $record. When the template is evaluated to html, we get a different looking record detail page:

 

 

As we can now see, the "name"  field of our class is shown as a header, the image is aligned to the right, and the description and price are put in two paragraphs, based on the html generated by the velocity script.

At this point, the class detail screen is missing a few functions that will make the user's life easier, like links to the next or previous record, as well a link to go back to the search screen. If the user has rights to edit an edit link is shown as well. These can be easily added using built-in methods. 

## It is possible to ask the engine to give us the urls of the previous and next records:
#set($previousUrl = $service.getPreviousSiblingUrl())
#set($nextUrl = $service.getNextSiblingUrl())

#if($previousUrl)
    <a href="$previousUrl">last product</a> | 
#else
    last product | 
#end
#if($nextUrl)
    <a href="$nextUrl">next product</a> | 
#else
    next product | 
#end

## not everyone is allowed to edit, so first check if the current user is before we add an edit link:
#if($record.isAllowedToUpdate())
    <a href="$record.getEditUrl()">edit</a> | 
#end
<a href="$source.getUrl()">back to product search </a>

 

Advantages and disadvantages

If you use velocity code as a template specififed in the blueprint you have the following advantages:

  • The detail record of your class is automatically added to the context, you do not need code to retrieve it and you do not need to think about error handling (for example if a product with a certain id does not exist) 
  • Human readable url's can be used to access your detail pages, using the label of your record. For example /get/3425/14/Carved_Chess_Pieces. Standard functionality also allows you to easily use custom url naming like /products/games/carved_chess_pieces.
  • If you have a record of an object (in this case a product) on another page, the method Record.getUrl() will automatically translate to the proper url leading to the detail page of this object.

A disadvantage is that you need a little bit more specification work in your blueprint. Also, you may not be used to this type of scripting. And last but not least, you can only specify a velocity template to be used for (non-editable) detail pages at this point.

Read more about security considerations while developing class template on this page.