type safe templating

Previous Tutorial contents Next

Jamon Tutorial - 7. Subtemplates: Functional Decomposition of Templates

Jamon templates can define subtemplates. These are exactly analogous to methods of a class, except that they are written in Jamon and are called from the main template or other subtemplates of the main template. Calling a subtemplate will cause it to print its output to the same output stream as the main template.

There are actually two types of subtemplates: private and protected. Private subtemplates are described in this document. Private subtemplates are accessible only from the template in which they are defined. Protected subtemplates, which are described in the tutorial section on inheritance, can also be called from templates that inherit from the main template.

Private subtemplates are declared in a template file with the <%def subtemplate-name> ... </%def> tag. Inside this tag, the subtemplate can declare required and/or optional arguments just as a top level template can by using the <%args> ... </%args> tag.

Subtemplates are called just like any other template, however subtemplates defined with the <%def subtemplate-name> ... </%def> tag are only visible within the template that defined them. Subtemplates can call themselves as well as other subtemplates in the same file or other top level templates.

An Example

  1. The template SubtemplateTemplate.jamon, shown below, uses two subtemplates to help format a table of user account information. The top level template builds a table with a row for each entry in an array of names provided as an argument to the top level template. It calls the subtemplate row to generate each row of table data. The subtemplate row calls the subtemplate generateLink to compose a URL for each user account. 
    <%args>
  String[] names;
  String externalLink;
  String cgiParamName = null;
</%args>

<table>
  <tr>
    <th>Customer Name</th>
    <th>Account Page</th>
  </tr>
<%for String name : names %>
    <%doc>Call a subtemplate to build each row of the table.</%doc>
    <& row; name = name; link = externalLink; cgiParam = cgiParamName &>
</%for>

<%doc>A sub-template to construct each row of the table.</%doc>
<%def row>
  <%args>
    String name;
    String link;
    String cgiParam;
  </%args>
  <tr>
    <td align="left"> <% name %> </td>
    <td> <& generateLink; link = link; name = cgiParam;
            value = name &> </td>
  </tr>
</%def>

<%doc>This sub-template builds a URL.</%doc>
<%def generateLink>
<%args>
    String link;
    String name = null;
    String value;
</%args>
<%doc> The following emit tags use '#u' to force URL style
escaping for the CGI parameters. (The 'link' should already
be in proper format.)</%doc>
<a href="<% link %><% name == null ? "" : "?" + name + "=" + value #u%>">
  Account information for <% name %> </a>
</%def>
  2. This template is called from the Java class SubtemplateTut7.java: 
    import java.io.OutputStreamWriter;

public class SubtemplateTut7 {
  public static void main(String[] argv) throws Exception {
    // data to pass to the template
    String[] accountNames = new String[] {
      "John Doe", "Mary Jane", "Bonnie Blue", "Johnny Reb" };
    String accountInfoUrl = "http://www.bank.com/accountInfo";
    // call the template ...
    new SubtemplateTemplate()
      .setCgiParamName("username")
      .render(new OutputStreamWriter(System.out),
              accountNames, accountInfoUrl);
  }
}
  3. Process the template and Java class with the following commands. 
            export CLASSPATH=.:/path/to/jamon-runtime.jar:/path/to/jamon-api.jar:/path/to/jamon-processor.jar
        java org.jamon.TemplateProcessor --destDir=. SubtemplateTemplate
        javac SubtemplateTut7.java SubtemplateTemplate*.java
        java SubtemplateTut7
  4. The output should be 
    <table>
  <tr>
    <th>Customer Name</th>
    <th>Account Page</th>
  </tr>

    <tr>
    <td align="left"> John Doe </td>
    <td> <a href="http://www.bank.com/accountInfo%3Fusername%3DJohn+Doe">
  Account information for username </a>
 </td>
  </tr>


    <tr>
    <td align="left"> Mary Jane </td>
    <td> <a href="http://www.bank.com/accountInfo%3Fusername%3DMary+Jane">
  Account information for username </a>
 </td>
  </tr>


    <tr>
    <td align="left"> Bonnie Blue </td>
    <td> <a href="http://www.bank.com/accountInfo%3Fusername%3DBonnie+Blue">
  Account information for username </a>
 </td>
  </tr>


    <tr>
    <td align="left"> Johnny Reb </td>
    <td> <a href="http://www.bank.com/accountInfo%3Fusername%3DJohnny+Reb">
  Account information for username </a>
 </td>
  </tr>

Previous Tutorial contents Next