type safe templating

Previous Tutorial contents Next

Jamon Tutorial - 3. Template Arguments

Templates do not exist in a vacuum; templates exist in order to display information. In a model-view-controller architecture, that information comes from the model and is passed to the templates to as arguments.

Arguments to a Jamon template are declared between <%args> ... <%/args> tags: 


<%args>
  String         title = "Account Summary";
  java.util.Date effectiveDate;
  String         userName;
  java.math.BigDecimal totalBalance;
  String         alertMessage = "";
</%args>
The above Jamon code declares a template with three required and two optional arguments. The required arguments are:
  1. java.util.Date effectiveDate
  2. String userName
  3. java.math.BigDecimal totalBalance
Any Java class that invokes this template must provide these three arguments, and they must be provided to the render method in the order specified in the <%args> ... <%/args> tag.

In addition, there are two optional arguments. Any java class that invokes this class may provide values to override the default values via the set methods:

The above setter methods return the template, allowing multiple calls to be chained together. Thus, to the sample template shown above could be invoked with the following code: 
    sampleTemplate
        .setTitle("Most Recent Account Balance");
        .render(new OutputStreamWriter(System.out),
                new Date(), "John Public", new BigDecimal("9.99"));
In the above example, the calling code sets the optional argument title, does not change the default value for the optional argument alertMessage, and then calls the render method with the required Writer and the three required arguments.

Note that the render method must be called after after the setter methods for the optional arguments.
Note that all arguments, both required and optional, are translated into Java as final variables. Thus, the following Jamon code would not work: 
<%args>
  String message;
  boolean isError;
</%args>
<%java if (isError) { message = "There was an error"; } // WILL NOT WORK %>
<% message %>

Putting it all together

  1. Create a Jamon template AccountSummaryTemplate.jamon: 
    <%args>
  String         title = "Account Summary";
  java.util.Date effectiveDate;
  String         userName;
  java.math.BigDecimal totalBalance;
  String         alertMessage = "";
</%args>

Title:             <% title %>
Effective Date:    <% effectiveDate %>
Name:              <% userName %>
<%java java.math.BigDecimal scaledBalance =
   totalBalance.setScale(2, java.math.BigDecimal.ROUND_HALF_UP); %>
Total Balance:     <% scaledBalance %>

<% alertMessage %>
  2. Write a java class to call the template: AccountSummaryTut3.java: 
    import java.io.OutputStreamWriter;
import java.util.Date;
import java.math.BigDecimal;

public class AccountSummaryTut3 {
  public static void main(String[] argv) throws Exception {
    new AccountSummaryTemplate()
      .setTitle("Most Recent Account Balances")
      .render(new OutputStreamWriter(System.out),
              new Date(), "John Public", new BigDecimal(9.99));
  }
}
  3. Set the classpath, process the template, compile, and run the program: 
        export CLASSPATH=.:/path/to/jamon-runtime.jar:/path/to/jamon-api.jar:/path/to/jamon-processor.jar
    java org.jamon.TemplateProcessor --destDir=. AccountSummaryTemplate
    javac AccountSummaryTut3.java AccountSummaryTemplate*.java
    java AccountSummaryTut3
  4. You should see: 
    Title:             Most Recent Account Balances
Effective Date:    Wed Aug 12 20:38:30 EDT 2009
Name:              John Public
Total Balance:     9.99

Previous Tutorial contents Next