Previous Next JavaScript must be enabled to correctly display this content

## 3.11 Using Template Directives

Use template directives to control how attributes that support substitution strings are processed.

- About Template Directives
  Learn about template directives.
- If Condition Directives
  Use the `if` directive to conditionally show text based on if an item or column has a value.
- Case Condition Directives
  Use the `case` directive to show text based on the value of an item or column.
- With and Apply Directives
  Use the `with` directive to assign values to placeholders for the Template Component that is specified in the `apply` directive.
- Loop Directives
  Use the `loop directive` to repeat text once for each item in a multi-value (character delimited) item or column value.
- Escape Open Bracket "{"
  Learn about an escape open bracket "`{`".
- Comments
  Add comments to templates.
- Built-in Substitutions for Template Directives
  Learn about built in substitution strings available for template directives.

Parent topic: App Builder Concepts

### 3.11.1 About Template Directives

Learn about template directives.

Template directives are only supported by Template Component Plug-ins, specific attributes in email templates, and the following regions: cards, interactive grid, classic report, application search, and interactive report region. Directives can be nested which means any of the template texts can contain another directive. These directives are processed as part of client or server-side substitutions.

- Template Component Plug-ins
- Specific attributes in email templates
- Regions: cards, interactive grid, classic report, interactive reports regions
- Theme templates: button, label, list, region, and page templates

Template directives are processed as part of client or server-side substitutions.

To determine if an attribute supports template directives, Page Designer Help includes the text "Supports Client-side Template Directives" or "Supports Server-side Template Directives." For more details on directive syntax, see apex.util.applyTemplate in Oracle APEX JavaScript API Reference.

Note:

Syntax description text in this topic is noted by the use of square brackets and is optional. You do not actually type the square brackets. Upper case text represents something as described in the description.

Parent topic: Using Template Directives

### 3.11.2 If Condition Directives

Use the `if` directive to conditionally show text based on if an item or column has a value.

Syntax

    {if [!][?|=]NAME/}
    TRUE_TEMPLATE_TEXT
    {elseif [!][?|=]NAME2/}
    ELSE_TRUE_TEMPLATE_TEXT
    {else/}
    FALSE_TEMPLATE_TEXT
    {endif/}

Where:

- The `NAME` is an item, column name, or template component attribute.
- If the value is true then the text that follows is output.
- The value is false if it is an empty string or ‘`F`’, ‘`N`’, or ‘`0`’.
- Any value that is not false is true.
- If the `NAME` is proceeded by an exclamation mark (!) then the logic is negated and the following template text is processed if the value is false.
- A value is false if after trimming leading and trailing spaces it is an empty string.

The `if` condition directive handles both empty (or not empty) tests and Boolean true/false tests (using the convention of character true/false values such as '`Y'/'N'`) at the same time. This results in confusion for rare case where the intention is to test for not empty but the actual value is 'N', which is not empty but still considered false. The optional `'?'` prefix operator can be used to explicitly test if the value is empty. The optional `'='` prefix operator can be used to explicitly test if the value is true or false.

The following table summarizes the available condition directives.

Condition Directive | Description | PL/SQL Expression
--- | --- | ---
`{if MYITEM/}` | `MYITEM` has to contain a value and the value can not be`‘F’`, `‘N’`, or `‘0’`. | `:MYITEM is not null and upper( :MYITEM ) not in ( 'F', 'N', '0' )`
`{if ?MYITEM/}` | `MYITEM` has to contain a value. | `:MYITEM is not null`
`{if !MYITEM/}` | `MYITEM` can be empty or contain `‘F’`, `‘N’`, or`‘0’`. | `:MYITEM is null or upper( :MYITEM ) in ( 'F', 'N', '0' )`
`{if !?MYITEM/}` | `MYITEM` is empty. | `:MYITEM is null`
`{if =MYITEM/}` | `MYITEM` is empty or does NOT contain `‘F’`, `‘N’`, or`‘0’`. | `:MYITEM is null or upper( :MYITEM ) not in ( 'F', 'N', '0' )`
`{if !=MYITEM/}` | `MYITEM` contains a value which equals to `‘F’`, `‘N’`, or `‘0’`. | `upper( :MYITEM ) in ( 'F', 'N', '0' )`
`{if MYITEM%assigned/}` | Useful when consistent output is required for multiple rows of data. When a value like `&COLUMN_NAME.` is assigned to `MYITEM`, it might be empty for some rows after applying substitutions. The `%assigned` condition evaluates to true for all rows in this case. | n/a

There can be zero or more `elseif` directives. The `elseif` and `else` directive are optional. The directives must go in the order shown.

Example

A cards report contains a column named `DESCRIPTION`. The following HTML Expression attribute will display the description if it is not null (empty string) and “No description.” otherwise.

    {if DESCRIPTION/}&DESCRIPTION.{else/}No description.{endif/}

Parent topic: Using Template Directives

### 3.11.3 Case Condition Directives

Use the `case` directive to show text based on the value of an item or column.

Syntax

    {case NAME/}
    {when STRING1/}
    TEMPLATE_TEXT1
    {when STRING2/}
    TEMPLATE_TEXT2
    {otherwise/}
    TEMPLATE_TEXT
    {endcase/}

The `NAME` is an item, column name, or template component attribute. The value is compared with the strings after each `when` directive and if they are equal then the following text is output. If no `when` directive matches then the text after the `otherwise` directive, if there is one, is output. The value and each string is trimmed of leading and trailing spaces before comparison. The comparison is case sensitive.

Example

This example using the sample `EMP` table displays the compensation differently depending on the `JOB`. For sales people it shows both the salary and commission. For the president it shows “--” rather than salary and for all other jobs it shows just the salary.

    {case JOB/}
    {when SALESMAN/}
    &SAL. (&COMM.)
    {when PRESIDENT/}
    --
    {otherwise/}
    &SAL.
    {endcase/}

Parent topic: Using Template Directives

### 3.11.4 With and Apply Directives

Use the `with` directive to assign values to placeholders for the Template Component that is specified in the `apply` directive.

Syntax

    {with/}
    FORMAL_ARG1:=ARGUMENT_TEXT
    FORMAL_ARG2:=ARGUMENT_TEXT
    ...
    FORMAL_ARGn:=ARGUMENT_TEXT
    {apply TEMPLATE_NAME/}

Requirements when using this directive include:

- Use the `with` directive to assign values to placeholders for the Template Component plug-in that is specified in the `apply` directive.
- Template Component plug-ins use Server-side rendering.
- The use of Template Directives within value expressions is supported.

Example

    {with/}
    TYPE:=IMAGE
    IMAGE:=&IMAGE_URL.
    ALT:={if DESCRIPTION/}&DESCRIPTION.{else/}No description.{endif/}
    {apply THEME$AVATAR/}

In this example, `THEME$AVATAR` is the internal name of a Template Component plug-in installed in the application. This template has three placeholders, `TYPE`, `IMAGE` and `ALT` to which values are assigned.

Parent topic: Using Template Directives

### 3.11.5 Loop Directives

Use the `loop directive` to repeat text once for each item in a multi-value (character delimited) item or column value.

Syntax

    {loop ["SEP"] NAME/}
    TEMPLATE_TEXT
    {endloop/}

The `NAME` is an item or column name that has multiple values separated by the character given by `SEP`. The default separator is "`:`". If `SEP` is more than one character it is treated as a regular expression.

The template text within the loop can use these substitutions:

- `APEX$ITEM` - This is the value of the current item in the list.

- `APEX$I` - This is 1 based index of the current item in the list.

Example

The following example takes a column called `TAGS` that contains a comma (,) separated list of tags such as "apples,cherries,pears" and turns it into an HTML list that can be nicely styled with CSS.

    <ul class="tags">{loop "," TAGS/}
      <li class="tag-item">&APEX$ITEM.</li>
    {endloop/}</ul>

Parent topic: Using Template Directives

### 3.11.6 Escape Open Bracket "{"

Learn about an escape open bracket "`{`".

Syntax

    {{/}

In rare cases, a lone open bracket "`{`" can be confused for the start of a directive if another directive follows it on the same line.

Example

This is an example where the open bracket "`{`" has to be escaped.

    <span>The coordinates {{/}c, d} = {if VAL/}&VAL.{else/}unknown{endif/}</span>

Here are similar cases that do not require an escape.

    <span>The coordinates { c, d } = {if VAL/}&VAL.{else/}unknown{endif/}</span>

    <span>The coordinates {c, d} =
    {if VAL/}&VAL.{else/}unknown{endif/}</span>

Parent topic: Using Template Directives

### 3.11.7 Comments

Add comments to templates.

Syntax

    {!<comment-text>/}

This directive is substituted with nothing and enables you to add comments to templates. The `comment-text` can be any characters except new line and the "/}" sequence.

Example

This example includes a comment reminding the developer to complete something. In this case, replace a hard coded English string with a localizable text message.

    <span>Name: &P1_NAME.</span> {!to do replace Name: with text message/}

Parent topic: Using Template Directives

### 3.11.8 Built-in Substitutions for Template Directives

Learn about built in substitution strings available for template directives.

Note:

Template Directives in Template Component plug-ins also support a number of additional built-in substitutions. To learn more, see item help.

Substitution String | Description
--- | ---
`APEX$ITEM` | Available within a loop directive. Specifies the value of the current item in the list.
`APEX$I` | Available within a loop directive. Specifies the 1 based index of the current item in the list.
`APEX$DOM_ID` | Generates a unique random `DOM ID` for the current execution of the Template Directive snippet. Example usage:
    <h1 id="#APEX$DOM_ID#_heading">#HEADING#</h1><someelement aria-labelledby="#APEX$DOM_ID#_heading">

Parent topic: Using Template Directives