Templates

< Variables Syntax >

Introduction

terp can be used in two modes: expression evaluation (terp -e) and template expansion (terp -t or terp -f). This section of the documentation is concerned with the latter mode.

In template expansion or text mode, the end result is always text. Typically, the majority of the input template consists of static text that has some embedded terp expressions sprinkled throughout.

Coincidentally, this documentation page was created by running the terp template engine over a template to embed the example in the page. Take a look at the following example which is located at examples/template/hostspec.xml. The template contains an XML skeleton that is filled in with information about the host on which the terp build was performed. This template was embedded in this page by using the following command:

${^file(^uri("../examples/template/hostspec.xml")).text[xmlencode]}

We manage to show you the embedded statement by using the HTML entity &#36; instead of the $ character. When we embed the "unescaped" version of the same statement, we end up with this result:

<!-- 
     Copyright (c) 2008-2016 by Codemesh, Inc.
  -->
<host name="${localhost.name}"
      address="${localhost.address}"
>
    <os name="${localhost.os.name}"
        family="${localhost.os.family}"
        code="${localhost.os.code}"
        version="${localhost.os.version}"
    />
    <procarchs>
${foreach(pa:localhost.procarchs)}        <pa name="${pa.name}"
            family="${pa.family}"
            code="${pa.code}"
            bits="${pa.bits}"
        />
${end}    </procarchs>
    <shell>
    </shell>
</host>

You might wonder about the double cast (String to URI, URI to File) in the example. We need a File instance to query the text property. If we created a File instance directly from the string, the resulting File instance would be relative to the parent directory of the present working directory rather than the parent directory of the template that is being expanded. By creating the File from a URI, the template source resolution mechanism kicks in and performs a template-relative expansion.

The [xmlencode] formatter escapes any active HTML characters so that the file's contents display correctly in this HTML page. This is only necessary because we're going to be viewing the results in this HTML page.

So now you know how to include a file's contents in an HTML page. What about including the expanded contents of that file in the same page? We can do this as well. The following snippet is used to include the expanded template in the page:

${expand("../examples/template/hostspec.xml")[xmlencode]}

This results in the following block of text:

<!-- 
     Copyright (c) 2008-2016 by Codemesh, Inc.
  -->
<host name="x2100"
      address="x2100/192.168.0.28"
>
    <os name="SunOS"
        family="sunos"
        code="sunos"
        version="5.10"
    />
    <procarchs>
        <pa name="AMD 64-bit Architecture"
            family="amd64"
            code="amd64"
            bits="64"
        />
        <pa name="Intel 32-bit Architecture"
            family="x86"
            code="i386"
            bits="32"
        />
    </procarchs>
    <shell>
    </shell>
</host>

This documentation page demonstrates two very useful terp features:

  • inclusion of unexpanded external content using a file instance's text property.
  • inclusion of expanded external content using the expand statement.

Just one more note: you might wonder what the difference between expand and import might be. Both statements add expanded external text to the output. expand returns the expanded text as a string value whereas import appends it directly to the output. Consequently, expand allows the application of formatters and transformers to the expanded text whereas import does not.


Copyright 2006-2016 by Codemesh, Inc., ALL RIGHTS RESERVED

:
terp template statements
codemesh.com home expressions templates ant about us contact us download   

Commandline