3.10.1 About Using Substitution Strings

Learn about using substitution strings.

Tip:

App Builder supports many built-in substitution strings. You can reference these substitution strings to achieve specific types of functionality. To learn more, see Using Built-in Substitution Strings.

3.10.1.1 Placeholder Substitution Strings within Templates

Include a placeholder substitution string within a template to reference component values.

Placeholder substitution strings available within a template are denoted by the pound sign (#). For example:

#ABC#

Tip:

You can also use JavaScript API apex.util.applyTemplate to evaluate templates on the client side. See applyTemplate in Oracle APEX JavaScript API Reference.

3.10.1.2 Session State Substitution Syntax for Page or Application Items

Reference page or application items using Session State Substitution syntax (also called&ITEM. syntax).

To reference page or application items use Session State Substitution string syntax (also called &ITEM. syntax):

  1. Reference the page or application item in all capital letters.
  2. Precede the item name with an ampersand (&).
  3. Append a period (.) to the item name.

You can use Session State Substitution string syntax in a region, a region title, an item label, or in any of numerous other contexts in which static text is used.

The following example references to an application item named F101_X :

&F101_X.

Notice that item name ends with a required trailing period. When the page is rendered, APEX engine replaces the value the substitution string with the value of the item F101_X .

3.10.1.3 Substitution Strings for Interactive Grid, Cards, and Map Columns

Reference columns in an interactive grid, cards page, or map page using substitution variables.

To use substitution variables to reference columns in an interactive grid, cards page, or map page:

  1. Reference the column name in all capital letters.
  2. Precede the column name with an ampersand (&).
  3. Append a period (.) to the item name.

The following example references the interactive grid column ENAME:

&ENAME.

Notice that the column name ends with a required trailing period.

3.10.1.4 Substitution Strings for Other Report Columns

Reference columns in other reports using substitution variables.

To use substitution variables to reference columns in other reports:

  1. Reference the column name in all capital letters.
  2. Precede the column name with a pound sign (#).
  3. Append a pound sign (#) to the item name.

The following example references the interactive or classic report column ENAME:

#ENAME#

3.10.1.5 Using Double Quotation Marks for Special Characters or Case Sensitivity

If item or column names use a special character or are case sensitive, enclose the name with double quotation marks.

If the name contains special characters or is case sensitive, enclose items or columns with double quotation marks. For example:

&"ITEM-OR-COLUMN-NAME".

Use the following syntax:

&"<name>"[!<format>].

Where:

  • "<name>" is an application item or page item or column name. If not quoted, then it must be in set A-Z–0-9_$#
  • "<name>" is APP_TEXT$<message-name>

    Where <message-name> is an APEX text message name.

  • <format> is a predefined filter name: HTML, ATTR, JS, RAW, STRIPHTML as described in Controlling Output Escaping in Substitution Strings.

3.10.1.6 Substitutions in Text Messages (24.2 or later)

For applications with a Compatibility Mode of 24.2 or later, you can reference text messages by enclosing the message name in curly braces ({}).

Tip:

The short substitution syntax described in this section is only available if the application's Compatibility Mode is 24.2 or later. See Editing the Application Definition.

To reference text messages, wrap the message name in curly braces ({}), also known as curly brackets. The following example reference a text message named TEXT.MSG:

&{TEXT.MSG}.

The message name, for example TEXT.MSG, can contain special characters. However, white space and a closing curly brace are not supported.

Text message substitutions also support parameters. Before the closing brace, add name=value pairs, separated by white space. Note that the name $lang is special since it controls the message language. Names can contain any character except white space and "=".

Values can be one of the following:

  • Unquoted substitution, HTML-escaped by default. For example:

    &P1_NAME.

  • Quoted substitution, HTML-escaped by default. For example:

    &"X-1".

  • Unquoted literal value. Anything except double quotes. For example:

    he&she+it?

    White space and closing curly brace are not supported.

  • Quoted literal value. Enclose the value in double quotes. To insert a double quote, type it twice. For example:

    "Hello ""APEX"" world"

The following is an example for a complex text message with parameters:

&{TEXT->MSG
Unquoted_Substitution=&P1_NAME!RAW.
Quoted_Substitution=&"Quoted name"!RAW.
Unquoted_Literal=how/do.you!do?
Quoted_Literal="Jerry Garcia
Ron ""Pigpen"" McKerhan"
$lang=FR}!HTML.