Template Directives in APEX: Customizing Report Row Markup

Beyond Default Report Layouts

APEX’s Classic Reports and Cards regions use row templates that define the HTML markup for each row of data. While the built in templates cover most use cases, there are times when you need custom markup, such as a card layout with conditional badges, color coded status indicators, or a custom list format. Template Directives let you embed conditional logic and column substitutions directly into the row template without writing any JavaScript.

Basic Substitution Syntax

The simplest template directive is a column substitution using the hash syntax: #COLUMN_NAME#. This inserts the column value into the HTML at that position. Combined with standard HTML and CSS classes from Universal Theme, you can create rich layouts:

<div class="t-Card">
    <div class="t-Card-titleWrap">
        <h3 class="t-Card-title">#EMPLOYEE_NAME#</h3>
        <span class="t-Card-subtitle">#JOB_TITLE#</span>
    </div>
    <div class="t-Card-body">
        <p>Department: #DEPARTMENT_NAME#</p>
        <p>Hired: #HIRE_DATE#</p>
    </div>
</div>

Conditional Display With Template Directives

Starting in APEX 18.1, template directives support conditional logic using curly brace syntax. This lets you show or hide parts of the template based on column values without any JavaScript:

{if STATUS/}
    <span class="u-color-{if STATUS eq ACTIVE/}29{endif/}{if STATUS eq INACTIVE/}9{endif/}-text">
        #STATUS#
    </span>
{endif/}

{case STATUS/}
    {when ACTIVE/}
        <span class="t-Badge t-Badge--success">Active</span>
    {when PENDING/}
        <span class="t-Badge t-Badge--warning">Pending</span>
    {when INACTIVE/}
        <span class="t-Badge t-Badge--danger">Inactive</span>
{endcase/}

Loop Directives

For more advanced scenarios, APEX 21.1 introduced the {loop/} directive that works with JSON array columns. If your query returns a JSON array in a column, you can iterate over it in the template. This is powerful for displaying tags, skills, or other multi value attributes without needing separate queries or APEX collections.

Practical Tips

Keep your template directives as simple as possible. If the conditional logic becomes deeply nested, consider moving the logic into the SQL query itself by computing derived columns. Use the APEX builder’s “Template” section in the report attributes to preview your markup. And always test with NULL values, because missing columns in conditional directives can produce unexpected whitespace or broken HTML.