How They Help You Control Dynamic Content
In Oracle APEX, many template-driven attributes support Template Directives. These are special tokens you can place inside HTML expressions (or templates in cards, reports, interactive grids, and email templates) to control how text and substitution values are processed.
When an attribute supports template directives, you’ll see “Supports Template Directives” in the Page Designer help text for that attribute. Under the hood, APEX uses its apex.util.applyTemplate logic to evaluate these directives.
Template directives let you move logic out of SQL and into template markup. That keeps your SQL cleaner and lets you format or conditionally display content right in the template.
When to Use Template Directives
You can use template directives to:
Show or hide content based on a value
Render different content depending on a value
Repeat HTML for each value in a list
These directives are processed as part of client-side substitutions, meaning the evaluation happens when APEX renders the component.
Directives are supported only in specific places, such as:
Cards
Classic and Interactive Reports
Interactive Grid templates
Email template attributes
(not all APEX templates support directives, so check the attribute help first).
1. If Condition Directives
Use {if} to show or hide content based on whether an item or column has a value.
Syntax
{if [!]NAME/}
TRUE_TEXT
{elseif [!]NAME2/}
ELSE_TRUE_TEXT
{else/}
FALSE_TEXT
{endif/}
NAME is a column or page item
Without !, the directive checks if the value is “truthy”
With !, it checks if the value is falsey (empty or 0/N/F)
Example
Imagine a Cards region with a DESCRIPTION column. To show the description only when it exists:
{if DESCRIPTION/}
&DESCRIPTION.
{else/}
No description.
{endif/}
If DESCRIPTION has a value, it appears. Otherwise, the fallback text “No description.” is shown.
2. Case Condition Directives
Use {case} when you want different HTML or text based on the exact value of a column or item.
Syntax
{case NAME/}
{when VALUE1/} TEXT1
{when VALUE2/} TEXT2
{otherwise/} DEFAULT_TEXT
{endcase/}
NAME is the test field
APEX compares it with each VALUE in the when lines
{otherwise/} is optional and works like else in a CASE expression
Example
You might want to display different job details for different roles:
{case JOB/}
{when SALESMAN/}
&SAL. (&COMM.)
{when PRESIDENT/}
—
{otherwise/}
&SAL.
{endcase/}
If JOB is SALESMAN, the salary and commission are shown. For PRESIDENT it shows “–”, and for others just the salary.
3. Loop Directives
Loop directives are useful when a column contains multiple values separated by a character (like tags).
Syntax
{loop [“SEP”] NAME/}
LOOP_TEXT
{endloop/}
SEP is the separator character (default is “:” )
NAME is the multi-value item or column
Within the loop you can use special substitution strings like:
&APEX$ITEM. for the current item value
&APEX$I. for the 1-based position index
Example
If a TAGS column holds comma-separated values, you can make an HTML list:
<ul class=”tags”>
{loop “,” TAGS/}
<li class=”tag-item”>&APEX$ITEM.</li>
{endloop/}
</ul>
This expands each tag into its own <li> element.
With & Apply Directives
This pattern is very common with Universal Theme components like:
Avatars
Badges
Icons
Media objects
Think of it as calling a template with arguments, similar to a function call.
Basic Syntax
{with/}
ATTRIBUTE := VALUE
ATTRIBUTE := VALUE
{apply TEMPLATE_NAME/}
Real Example: THEME$AVATAR (Universal Theme)
This is a real-world, correct usage, exactly like what you shared.
{with/}
TYPE := IMAGE
IMAGE := #PROFILE_IMAGE#
IMAGE_ALT := Profile Image
SIZE := t-Avatar–lg
SHAPE := t-Avatar–circle
CSS_CLASSES := u-color-29
{apply THEME$AVATAR/}
How Template Directives Improve APEX Development
Template directives help you:
Keep SQL clean: Conditional display logic moves out of SQL and into templates.
Avoid unsafe workarounds: You don’t need to disable HTML escaping or build HTML in SQL.
Make templates more powerful: You can vary presentation without changing the core data query.
These directives work especially well in Cards and Classic Reports where data is presented with rich HTML formatting.
Checkout our sample app
URL: https://oracleapex.com/ords/r/ashish/template-directives-and-components/
Login: DEMO/DEMO
The post Oracle APEX Template Directives appeared first on Ontoor blogs.
