Introduction
Oracle APEX template directives use curly brackets {} as part of their substitution and logic syntax. This can create a challenge when you need to include a literal open bracket { in your template output—for example, when displaying JSON, HTML snippets, or code samples. To prevent Oracle APEX from interpreting it as the beginning of a directive, you need to escape it properly. This blog post explains how to escape an open bracket in Oracle APEX templates, when and why to do it, and offers best practices for clarity and maintenance.
How to Escape an Open Bracket in Oracle APEX Templates
In Oracle APEX, the open bracket { is reserved for use with template directives, such as {if}, {loop}, {apex$} and substitutions like {COLUMN_NAME}. If your output needs to include a literal {, such as in a code block or a display label, you cannot type it directly. Instead, APEX provides an escape sequence.
To display a literal {, use:
{{!
This tells APEX to output a single { character without starting a directive.
Example
If you want to output a JSON snippet inside a card template:
<pre>
{{!"name": "John", "age": 30}
</pre>
This will render:
{name: "John", "age": 30}
Notes
-
Only the first
{needs to be escaped. -
Closing brackets
}generally do not need escaping unless paired with directive logic.
Best Practices
-
Use
{{!only when you need literal output and are sure it’s not part of an APEX directive. -
Keep template content clean—wrap code or JSON examples in
<pre>or<code>blocks for readability. -
Avoid placing escape characters within dynamic SQL or PL/SQL code—this technique is only for APEX template regions.
Oracle APEX Documentation
Refer to the official Oracle APEX documentation on template directives and escaping rules:
Oracle APEX Template Directive Reference
In Oracle APEX, when working with templates, it is possible to encounter a situation where the open bracket { can be confused for the start of a directive (e.g., {if} or {loop}). This issue arises when the open bracket appears in the middle of the code, followed by a directive, causing a potential conflict. To avoid this confusion, you can escape the open bracket using the syntax {{/}.
In this tutorial, we will walk you through how and when to use the escape sequence {{/} in APEX templates, and provide examples to demonstrate its usage.
1. Why Do You Need to Escape the Open Bracket {?
The APEX templating engine uses brackets { and } to define directives, such as {if}, {loop}, {case}, etc. In some cases, when an open bracket is placed before these directives on the same line, it might be misinterpreted as the start of a directive, causing a parsing error.
Escape Sequence:
{{/}: The escape sequence to use when you need to display an open bracket { in the template text without it being interpreted as the start of a directive.
2. When Do You Need to Escape the Open Bracket {?
You need to escape the { when it appears before a directive in a line, causing the template engine to interpret it as part of a directive. For example:
{if VAL/}&VAL.{else/}unknown{endif/}
In the above case, if you want to include { literally (e.g., in a mathematical expression), the APEX engine will interpret it as the start of a directive. To avoid this, use the escape sequence {{/} to display the { symbol literally.
3. Example 1: Escaping the Open Bracket in a Mathematical Expression
Scenario:
You want to display coordinates such as {c, d}, but without the template engine interpreting { as the start of a directive.
Without escaping:
<span>The coordinates {c, d} = {if VAL/}&VAL.{else/}unknown{endif/}</span>
This could cause an error because the APEX engine might think {c, d} is part of a directive. To prevent this issue, you should escape the { by using the escape sequence {{/}.
Escaped version:
<span>The coordinates {{/}c, d} = {if VAL/}&VAL.{else/}unknown{endif/}</span>
Explanation:
{{/}c, d}: This ensures the { character is displayed literally and not treated as part of a directive.
The rest of the expression {if VAL/}&VAL.{else/}unknown{endif/} works as expected and shows either the value of VAL or unknown.
Expected Output:
If VAL is set to 10, the output will be:
The coordinates {c, d} = 10
If VAL is not set, it will display:
The coordinates {c, d} = unknown
4. Example 2: No Need to Escape Brackets in Simple Cases
In many cases, you won’t need to escape the open bracket {. If the { is simply part of your content and not followed by a directive on the same line, it will be treated as a regular character.
Scenario:
You want to display {c, d} in a regular expression or a descriptive sentence.
<span>The coordinates { c, d } = {if VAL/}&VAL.{else/}unknown{endif/}</span>
Explanation:
Here, the { c, d } part is simply text and doesn’t conflict with any directives.
The rest of the template will work as usual, displaying either the value of VAL or unknown.
Expected Output:
If VAL is set to 20, the output will be:
The coordinates { c, d } = 20
If VAL is not set, it will display:
The coordinates { c, d } = unknown
5. Example 3: Escaping Brackets When Using Directives
In some situations, the bracket { might appear in combination with a directive, and you need to escape it to prevent conflicts. Here's an example where you need to escape the open bracket before using an if directive.
Scenario:
You want to display an expression such as {c, d} = 10 only if a certain condition is true.
Without escaping:
<span>{c, d} = {if VAL/}&VAL.{else/}unknown{endif/}</span>
This could cause a parsing error, so you should use {{/} to escape the {.
Escaped version:
<span>{{/}c, d} = {if VAL/}&VAL.{else/}unknown{endif/}</span>
Expected Output:
If VAL is set to 10, the output will be:
{c, d} = 10
If VAL is not set, it will display:
{c, d} = unknown
6. Example 4: No Need to Escape Inside Block Directives
If you are using a block directive, such as {if} or {loop}, where the brackets {} appear inside the block, you don’t need to escape them. For instance:
{if VAL/}
<span>The coordinates {c, d} = {VAL}</span>
{else/}
<span>The coordinates {c, d} = unknown</span>
{endif/}
This will work perfectly fine because the {c, d} part is outside of the directive, and APEX doesn’t interpret the brackets as part of the directive.
7. Summary of When to Escape the Open Bracket
Escape Bracket: Use {{/} when you want to display { literally in a context where the APEX engine might interpret it as the start of a directive. This typically happens when an open bracket { is immediately followed by a directive, such as {if}, {loop}, or others.
No Escape Needed: You don't need to escape { when it’s simply part of the content (i.e., not immediately followed by a directive).
8. Best Practices
Be aware of directive boundaries: If you’re working with template expressions or custom formatting, always ensure that the { is not interpreted as part of a directive. If it’s in a context where it might be, use the escape sequence.
Use escaping sparingly: Only escape { when necessary. Overusing it can make your templates harder to read.
Conclusion
Escaping an open bracket in Oracle APEX templates is crucial when working with content that includes code, JSON, or any text requiring literal { characters. By using the {{! syntax, developers can safely display these characters without interfering with template rendering logic. Applying this technique with care ensures your templates behave as expected while remaining easy to maintain and understand.
