Transformers

What Is This?

A transformer is a template-language block that rewrites part of the XML before the PDF controls are created. Transformers are written as text lines that start with @, followed by a block in braces.

Use transformers to include, choose, repeat or prepare XML:

Transformer	Use it for
`@if`	Include content only when a condition is true.
`@switch`	Choose one branch from several cases.
`@foreach`	Repeat XML for each item in a list supplied by the application.
`@for`	Repeat XML for a numeric range.
`@var`	Create a temporary value for one block.
`@alternate`	Rotate through values, usually row colors.

When Should I Use This?

Use a transformer when the XML structure itself needs to change. For example, use @if when a whole notice should appear or disappear, and use @foreach when one table row pattern should repeat for a list.

Do not use a transformer just to print a changing value. Use Template data for simple values such as @CustomerName, @InvoiceNumber or @StatusLabel.

When logic starts to become business-specific, ask the application team to prepare simpler values. Templates are easier to maintain when they choose between ready-to-print values instead of calculating them.

How Do I Start?

Start with one block and one visible result.

<template>
    <body>
        @if ShowNotice {
            <text>Review required</text>
        }
    </body>
</template>

The application must supply ShowNotice as a Boolean value. For a rendered version of this pattern, see Conditions with @if.

Transformer Lines

A transformer line starts in XML text, not as an XML element. The line names the transformer and gives it arguments:

@foreach Item in Items {
    <text>@Item</text>
}

In the transformer line, write expression names without @. Inside normal text or attributes, use @Item to print the temporary value.

The opening { starts the block. The closing } ends the block. Keep braces easy to see; most transformer mistakes are easier to find when each block is small.

Choose The Smallest Transformer

Need	Start with
Show or hide one section.	`@if`
Choose one label from a status value.	`@switch`
Repeat rows from application data.	`@foreach`
Repeat a fixed design pattern a known number of times.	`@for`
Name a value once inside a block.	`@var`
Alternate repeated row colors.	`@alternate`

Prefer @foreach over @for for real business lists. Prefer prepared data over complicated template expressions.

Small Transformer Shapes

Use the full examples in Template language when you need more detail.

@switch Status {
    @case "paid" {
        <text>Paid</text>
    }
    @default {
        <text>Status needs review</text>
    }
}

@case and @default only belong inside @switch. @default must be last.

@foreach Line in Lines with Index {
    <text>@Index: @Line</text>
}

Lines must be a collection supplied by the application. Index is zero-based.

@alternate on RowBackground with ["#ffffff", "#f8fafc"] {
    <border background="@RowBackground">
        <text>First row</text>
    </border>
}
@alternate on RowBackground {
    <border background="@RowBackground">
        <text>Second row</text>
    </border>
}

The first @alternate block supplies the list. Later blocks using the same variable advance through that list.

Common Transformer Mistakes

Writing @if @ShowNotice. In transformer expressions, use @if ShowNotice.
Using else if without @. Use @else if.
Putting regular XML directly inside @switch instead of inside @case or @default.
Using @foreach with a number or text value instead of a collection.
Using @for with a step that moves away from the end value.
Letting one transformer block do too much. Split large decisions into prepared data or smaller blocks.

Next Steps

Read Template language for the full starter reference and task examples. Read Troubleshooting when expressions do not evaluate. Read Table control for a generated repeated-row example.

Previous: Controls

Manual home

Next: Template language