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.
• Loop Directives
  Use the loop directive to repeat text once for each item in a multi-value (character delimited) item or column value.
• With and Apply Directives
  Use the with directive to assign values to placeholders for the Template Component that is specified in the apply directive.

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.

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.

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/}

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/}

3.11.4 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 substitution symbols:

• 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>

3.11.5 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/}
PLACEHOLDER1:=EXPRESSION1
PLACEHOLDER2:=EXPRESSION2
{apply TEMPLATE_INTERNAL_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.