Velocity library

Here is a small library of velocity code to solve some common "problems" in developing applications.

• Table paging
• Generating a pdf file
• Using a captcha
  
  

Table paging

If you want to show search results using a custom velocity page, you'll have to take care of the table paging yourself. This means dividing the table results into pages, displaying a number of records and providing some navigation between the pages. Here's an example of how to do this with the assistance of the TablePagingManager.

## The search statement; usually it will be a bit more elaborately than this off course.

#set($table = $session.getTable("products"))

## Retreiving the currentpage from the request. If it is not set, it will default to the first page.
## We choose 12 as the increment, so there will be 12 records shown on each page.

#set($currentPage = $request.getInteger("currentpage"))
#set($tablePagingManager = $table.newTablePagingManager(12, $currentPage))

## Show the page navigation.

#if($table.size() > 0) 
    #foreach($pageNumber in $tablePagingManager.getPageNumbers())
        #if($tablePagingManager.isCurrentPageNumber($pageNumber))
            $pageNumber
        #else
            <a href="/myapp/searchpage.vm?currentpage=$pageNumber">$pageNumber</a>
        #end
    #end
    <hr>
    ## Now, show the records on the page
    <ol>
    #foreach($record in $tablePagingManager.getVisibleRecords())
        <li>$record.getLabel()</li>
    #end
    </ol>
#end

Great, however the above code still executes the search statement every time a page is requested. Although search statements are cached automatically by the engine, you'd still have to pass the search parameters with every "turn" of the page, in order to be sure the same search statement is executed. Instead, it is far more easier to store the search results somewhere, so you can use this on every page. In fact a (new) search only needs to be executed when request parameters are passed. In the code below a user may search on product category.

Luckily you can use the reserved $variables map for this purpose. Here is an example for a search for products based on a category.

#set($category = $session.get("category"))
#if($category)
    #set($query = $session.newQuery("products"))
    $query.addFilter("category", $category)
    #set($table = $query.getTable())
    $variables.put("productsFound", $table)
#else
    $variables.get("productsFound"))
#end

When your search is a bit more elaborate, it is advisable to put the code that actually draws the html table in a different file which is parsed by the code that executes the search.

Finally, there is an alternative to this approach. This entails overwriting the snippet(s) that are involved in drawing a normal "engine" table, by a custom one. Page navigation etc... is than handled by the system. However, meddling with snippets, requires a more advanced awareness of how the application engine works.

Generating a pdf file

This is actually a very simple task. Basically all you have to do is write a template that creates a html file and "merge" it into a pdf file. There are loads of configurations possible for the layout such as headers & footers, page orientation and margins.

Below is a very basic example that creates a pdf and opens it.

 #set($context = $session.newVelocityContext())
 $context.putVoid('template', $record)
 $context.putVoid('record', $customer)
 $context.setPDFFileName('invoice.pdf');
 #set($file = $context.mergeToPDF('/template.vm'))

So, first a new context is created to which the template may be evaluated. Various object may be put into this context so the template can use them. The result of the merge is a SessionFile. This represents a temporary file created in the user session. Often such a file is sent to the browser for download or permanently stored in the database.

## Storing the pdf in the database. In this case without a record lock.
$record.unconditionalUpdate('PDF file', $file) 

## Send the file to the browser for download
$file.getReplaceScript() 

Some settings can be passed to the PDF generator as well, check the available VelocityContext methods in the Velocity API.

A few notes on the PDF template generator

The PDF Generator is a third party java product. Though you are welcome to report any quirks to us, we cannot offer you full support because we are not the developers of this product. Full Documentation may be found at http://pd4ml.com/. In our experience, the PDF Generator is more strict and limited in its interpretation of HTML and CSS than a browser. So keep your HTML simple, leave out fancy CSS positioning. The generator does support CSS printing styles to a certain extent.

Some HTML tags may be used that are specific to the PDF generator. These tags serve as a kind of commands and may be used within the HTML. Some examples:

Force a page break 

<pd4ml:page.break>

Define a repeatable header and footer. These items are configurable for example you can have the header/footer appear or dissappear on certain pages.

<pd4ml:page.header>
<center>
<img src="/images/logo.jpg">
</center>
</pd4ml:page.header>

<pd4ml:page.footer>	
<center class="footer">
Wubbo Ockels street 369 1054 SG Amsterdam<br>
Tel. 020 12345678<br>
info@ourcompany.com
</center>
</pd4ml:page.footer>

sdsd

Using a captcha

If you want to use a captcha on a custom form you can use our Captcha object using "$session.newCaptcha". The Chaptcha object will render an image and can check wether a code entered corresponds to symbols used in the image. Here is simplified example:

file 1: form.vm

#set($captcha = $session.newCaptcha())
$session.putVariable('captcha', $captcha)
#if($error)
    <h4>$error</h4>
#end
<form action="formHandler.vm">
#set($captchaUrl = $captcha.getImage().getClientUrl())
<img src="$captchaUrl">
Type the word: <input name="code">
<input type="submit">
</form>

file 2: formHandler.vm

#set($captcha = $session.getVariable('captcha'))
#set($code = $request.get('code'))
#if($captcha && $code)
    #if(!$captcha.isCorrect($code))
        #set($error = "Code is incorrect. Please try again")
        #parse("form.vm")
    #end
#end