Inforama tutorial

You can download the Inforama project files for this example by clicking the attachments link at the bottom of this page.

 

So far we have merged data directly into the generated documents as is, but in many cases it's desirable to manipluate the data before it gets inserted. It may also be required to check data values in order to set the state on checkboxes. In this section we'll look at how the built-in data formatters can be used to automatically format data and also how custom formatters can be created in Java and introduced into your projects.

 

Basic formatting

To begin with, we'll look at how you might want to format string, numeric, currency and date data. Before doing so we'll amend the customer query to include the fields create_date, last_update and active.

 

SELECT customer_id, first_name, last_name, email, cust_addr.address, cust_addr.address2, cust_addr.district, cust_addr.postal_code, cust_addr.phone, city.city, country.country, create_date, customer.last_update, active FROM customer, address as cust_addr, city, country WHERE customer.address_id = cust_addr.address_id AND city.city_id = cust_addr.city_id AND country.country_id = city.country_id and customer.customer_id = '$P{customer_id}'

 

Enter this query in the Datasets dialog and save it. Open the WelcomeLetter where we'll enter a line about the registration date as shown in figure 1.

 

Figure 1: Data binding

 

Immediately below the binding is the generated PDF and as you can see the date isn't in the format that we would want to send to a customer. In order to rectify this we can use the built-in date formatter. In the Data frame shown in figure 2 below, select the field that you wish to insert into the template and click the bottom toolbar button indicated to display the data formatter dialog shown in figure 3.

 

Figure 2: The data frame

 

Figure 3: The data formatter dialog

 

Item	Description
1	List of built-in formatters
2	Easy to read preview of the formatter mask. This shown how the formatted data will appear when documents are generated
3	Actual mask to be applied to the formatter. This varies depending on the formatter type
4	The expression which will be used in the document to apply the mask to the data

 

Select the Date formatter from the list indicated by the number 1 in figure 3. This will automatically fill the list indicated by the number 2 in figure 3 with easy to read format masks. Select the format that you would like the date field to appear in and the actual format mask will appear in the text box indicated by the number 3 in figure 3. If you wish to change the value in this text box you can so and the expression in the text area indicated by the number 4 in figure 3 will automatically change to reflect this.

These format masks use standard Java formatting. For more on how to use these format masks have a look at the Java documentation at http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html

When you are happy with the format that will be applied to the data click OK in the data formatter dialog and the formatting expression will be inserted into the document as follows.
 

$E{$V{DateFormatter}.format($F{customerDS.create_date}, "dd MMM yyyy")}
 

The beginning of this expression, $E{$V{DateFormatter}, uses a built in variable which refers to a formatter Java class. Passed to this variable are the data to be formatted and the mask to be applied to the data. More on this will be explored when we look at creating custom data formatters.

Now when we preview the document the date value will appear in the generated document using the format we specified as shown in figure 4.

 

Figure 4: Preview the formatted date

 

Using expressions to implement basic logic

To demonstrate how we can implement some basic logic we'll assume that we have had our application form modified to indicate whether a customer is active or not. We've added a checkbox to the application form which we will turn on or off depending on the value of the active field in the customer table of the database. Select the new active checkbox in the editor and double-click the active field in the Data frame to create the binding to the checkbox as shown in figure 5.

 

Figure 5: Binding data to a checkbox

 

Preview the document and depending on the value of the active flag in the database the checkbox state will toggle as shown in figure 6.

 

Figure 6: Preview the checkbox data binding

 

More advanced expressions

In the previous example we simply used the value of the active field in the database to determine state of the checkbox. There may be cases where data in several fields needs to be checked in order to set the state. This is where expressions come into play and this will require more advanced bindings to be created. Say for example that we wanted to check the active flag and also check that the customer's profile has been updated after a certain date we could do the following.

 

$E{$F{customerDS.active} && ($F{customerDS.last_update}.getYear() + 1900)>2006}
 

Expressions contained within the tag $E{ ... } will get processed as Java expressions using the Groovy runtime interpreter. Before the expression is evaluated any fields or parameters will be replaced with the actual values so that the data is worked upon.

For more on the Groovy scripting language go to the Groovy homepage at http://groovy.codehaus.org/

Now when you preview the document the checkbox won't get checked. Try changing the year to 2005 in the expression and when the document is previewed it will be checked.

Now we can try changing some text in a letter depending on the value of a parameter. To do this open the WelcomeLetter document template and enter the paragraph shown in figure 7.

 

Figure 7: Returning different string depending on data values

 

We have added the subscription_level parameter and the following expression tests this parameter to control the text that is displayed within the paragraph.

 

$E{ if ( $P{subscription_level}.equals("1") ) { return "Silver" } else if ($P{subscription_level}.equals("2")) { return "Gold" } else if ($P{subscription_level}.equals("3")) { return "Platinum" } }

 

Now when we preview the document and set the subscription_level parameter it generates with the correct text value in the paragraph as shown in figure 8.

 

Figure 8: Previewing the subscription level conditional text

 

Creating a custom formatter

When formatting expression are getting lengthy and complex it may be a good idea to create a custom Java class which can also be reused thoughout a project. To demonstrate this we'll replace the somewhat unwieldy code used earlier to display the subscription level. Begin by creating the custom class below.

package org.inforama.formatters;

 

public class CustomFormatter {

 

  public static String getLevel( String level ) {

    if ( level.equals( "1" ) ) {

       return "Silver";

    } else if ( level.equals( "2" ) ) {

       return "Gold";

    } else if ( level.equals( "3" ) ) {

       return "Platinum";

    }

    return "";

  }

}

 

As you can see the code is doing the same as earlier code was doing. Compile the class and create a jar file. Open the classpath dialog by clicking the Options – Classpath editor... menu item as shown in figure 9.

 

Figure 9: Referencing the custom library from Inforama

 

Click the Add a JAR button, locate the CustomFormatter.jar file and it will appear in the list of jars referenced. Click the Save classpath button to save your changes. Now open the WelcomeLetter template and replace the line original line which output the subscription level to the following.

$E{ org.inforama.formatters.CustomFormatter.getLevel($P{subscription_level}) }

 

Registering the formatter as a variable

It's possible to make the reference to the CustomFormatter class within the document even cleaner. All of the built-in formatters are registered by using the variables.xml file in the project directory. Open this file in a text editor and add the line shown in red below.

 

<variables>

<variable name="DateFormatter" class="org.in4ama.documentengine.format.DateFormatter"/>

...

<variable name="CustomFormatter" class="org.inforama.formatters.CustomFormatter"/>

</variables>

 

You will need to restart the Studio in order for this change to be picked up. When the Studio has restarted open the project again and once again open the WelcomeLetter template. Now change the line outputting the subscription level to.

 

$E{ $V{CustomFormatter}.getLevel($P{subscription_level}) }

 

This isn't a dramatic change to what we had earlier but it does make it easier to reference the class from numerous templates if necessary. The document should now look like that shown in figure 10.

 

Figure 10: The modified paragraph referencing the custom formatter class