FreeMarker Templates

This page explains how GLUE integrates FreeMarker templates for assembling text strings in modules.

FreeMarker is a powerful templating engine that allows dynamic generation of content by combining a template with a data model.

---

Overview of FreeMarker in GLUE

FreeMarker templates are used in GLUE modules to dynamically generate text strings based on a model, which often consists of GLUE data objects. This approach enables:

• Flexibility: Customize text output based on complex data structures.
• Integration: Directly access GLUE's relational database through property paths.
• Reusability: Define templates that can be reused across different workflows.

Examples of modules that support FreeMarker templates include:

• fastaAlignmentExporter: Customizes the FASTA header lines.
• webExporter: Generates custom HTML or JSON output.

Templates are embedded within GLUE module configuration files, typically using XML syntax.

---

Using FreeMarker Templates in GLUE

Template Syntax

FreeMarker templates use ${} for placeholders that reference data within the model. For example, ${sequence.sequenceID} would insert the value of the sequenceID property for a sequence.

Template in Module Configuration

FreeMarker templates are often embedded directly into the XML configuration files of GLUE modules. For example, the fastaAlignmentExporter module might use the following configuration:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<fastaAlignmentExporter>
    <idTemplate>${sequence.sequenceID}</idTemplate>
</fastaAlignmentExporter>

In this case, the idTemplate element defines how sequence IDs will appear in the FASTA headers. The placeholder ${sequence.sequenceID} dynamically inserts the sequenceID for each sequence.

---

Accessing GLUE Data

1. Property Paths:
   Use property paths to access data objects in the GLUE database. For instance:

   • ${sequence.name}: Retrieves the name of the current sequence.
   • ${alignment.name}: Accesses the name of the alignment.

2. Hierarchical Access:
   Navigate through related objects using dot notation:

   • ${sequence.source.name}: Retrieves the name of the source associated with a sequence.

---

Dynamic Template Features

1. Conditionals: Use <#if>...</#if> for conditional logic.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<fastaAlignmentExporter>
    <idTemplate>${sequence.sequenceID}</idTemplate>
</fastaAlignmentExporter>

2. Loops: Use <#list>...</#list> to iterate over collections.

<#if sequence.length > 1000>
    Large sequence: ${sequence.name}
</#if>

3. String Manipulation:

${sequence.name?upper_case} - Converts a sequence name to uppercase.

Examples

FASTA Header Customization

Example configuration for fastaAlignmentExporter:

<fastaAlignmentExporter>
    <idTemplate>${sequence.source.name}|${sequence.name}|${sequence.length}</idTemplate>
</fastaAlignmentExporter>

Generates FASTA headers like:

>Source1|Seq123|1024

Dynamic Web Output

Configuration for webExporter:

<webExporter>
    <template>
        {
            "alignmentName": "${alignment.name}",
            "sequenceCount": "${alignment.sequenceCount}"
        }
    </template>
</webExporter>

Produces JSON output:

{
  "alignmentName": "exampleAlignment",
  "sequenceCount": 42
}

Common Use Cases

• Customizing Module Output: Use templates to define the format of exported FASTA headers or web output.
• Dynamic Report Generation: Generate reports combining metadata and sequence data dynamically.
• Web Service Integration: Define templates for consistent and flexible web responses.

---

Reference

• FreeMarker Documentation: Detailed reference for FreeMarker template syntax and features.

---