How to Create and Use Built-in Substitution Variables in Oracle APEX

 In Oracle APEX, built-in substitution variables play a critical role in creating dynamic and responsive applications. These variables act as placeholders that are automatically replaced at runtime with relevant context-based values, such as user session details, application information, page identifiers, and environment settings. By using built-in substitution variables, developers can build pages that adapt to users, simplify logic across applications, and reduce hardcoded values. Whether you're customizing page titles, building conditional logic, or referencing application metadata, substitution variables streamline development and enhance maintainability.

In Oracle APEX, built-in substitution variables are predefined variables that allow you to access runtime values such as user session details, page metadata, and environment-specific properties. These variables can be used in SQL queries, PL/SQL code, HTML templates, JavaScript, conditions, and other dynamic expressions across your application. They provide a powerful way to make your application context-aware, dynamic, and more maintainable without hardcoding values.

How to Use Substitution Variables in Oracle APEX

1. Syntax of Substitution Variables
Built-in substitution variables follow the format &VARIABLE_NAME. when used in static text (such as HTML templates) and :VARIABLE_NAME when used in PL/SQL or SQL.

Example (in SQL or PL/SQL expressions):

:APP_USER

Example (in HTML or templates):

Welcome, &APP_USER.!

2. Common Built-in Substitution Variables

• APP_USER – Returns the username of the current logged-in user.

• APP_ID – Returns the numeric ID of the current application.

• APP_NAME – Returns the name of the current application.

• APP_PAGE_ID – Returns the ID of the current page.

• APP_SESSION – Returns the session ID for the user.

• APP_ALIAS – Returns the alias of the application (e.g., F?p alias).

• WORKSPACE_NAME – Returns the name of the current workspace.

• APP_IMAGES – Returns the path to the application images.

• APP_DATE_TIME_FORMAT – Returns the default date and time format.

• DEBUG – Returns YES if debug mode is enabled, else NO.

3. Where to Use Them

• Page Titles and Regions
  You can use &APP_USER. in the page title or region headings to personalize the user interface.

• HTML Expressions in Classic Reports
  Embed dynamic content based on session values:

  <b>Submitted by: &APP_USER.</b>
  

• Conditions
  Show or hide buttons, regions, or items based on the logged-in user:

  :APP_USER = 'ADMIN'
  

• PL/SQL Process Code
  Use these variables to log or branch based on application ID, user role, or session data.

4. Example: Conditional Display Based on User
In a button or region, set a Server-side Condition of type PL/SQL Expression:

:APP_USER = 'HR_MANAGER'

This ensures that only the HR_MANAGER sees the component.

5. Example: Logging Page Access
You can create a process that logs the page access using:

INSERT INTO page_log (app_id, page_id, user_name, access_time)
VALUES (:APP_ID, :APP_PAGE_ID, :APP_USER, SYSDATE);

6. Substitution Variables in URLs
You can pass and use values in the URL like:

f?p=100:1:&APP_SESSION.::NO::P1_ITEM_ID:123

In this case, &APP_SESSION. ensures the session is maintained when navigating pages.

7. Notes and Best Practices

• Always differentiate between & (substitution) and : (bind) variables.

• Substitution variables are resolved before the page is rendered, whereas bind variables are used during SQL execution.

• Avoid using substitution variables directly in SQL queries where bind variables are safer (to prevent SQL injection).

By using built-in substitution variables effectively, you reduce redundancy, increase maintainability, and allow the application to respond dynamically to the current context of the user and session.

Examples

In Oracle APEX, substitution variables allow you to dynamically insert values from the APEX environment into your pages, regions, and other components. These variables make it easier to access important application and session data in your templates, SQL queries, and dynamic actions.

In this tutorial, we will explore the built-in substitution variables available in Oracle APEX, including:

• &APP_USER.

• &APP_ID.

• &APP_PAGE_ID.

• &APP_SESSION.

• &APP_FILES.

• &WORKSPACE_FILES.

• &REQUEST.

• &DEBUG.

• &APEX_FILES.

• &IMAGE_PREFIX. (legacy - use &APEX_FILES. instead)

• &APEX_VERSION.

• &APEX_BASE_VERSION.

We will discuss how to use these substitution variables in real-life scenarios with examples.

Step 1: Understanding the Built-in Substitution Variables

Here is a breakdown of the built-in substitution variables available in Oracle APEX:

1. &APP_USER.

• Purpose: Represents the logged-in user’s username.

• Usage: You can use this variable to customize content based on the logged-in user.

SELECT * FROM users WHERE username = '&APP_USER.';

2. &APP_ID.

• Purpose: Represents the application ID of the current APEX application.

• Usage: Useful when you need to reference or log the application ID dynamically.

SELECT * FROM application_info WHERE app_id = '&APP_ID.';

3. &APP_PAGE_ID.

• Purpose: Represents the current page ID.

• Usage: You can use this variable to create page-specific content or for debugging purposes.

SELECT page_name FROM pages WHERE page_id = '&APP_PAGE_ID.';

4. &APP_SESSION.

• Purpose: Represents the current session ID.

• Usage: Useful when you need to log or track sessions or pass session-related data in URLs.

SELECT * FROM session_logs WHERE session_id = '&APP_SESSION.';

5. &APP_FILES.

• Purpose: Points to the directory where files associated with the APEX application are stored.

• Usage: You can use it when you need to reference or store files in your APEX application.

<a href="&APP_FILES./myfile.pdf">Download PDF</a>

6. &WORKSPACE_FILES.

• Purpose: Represents the directory where files associated with the workspace are stored.

• Usage: This is used when referencing files that are specific to the workspace.

<img src="&WORKSPACE_FILES./images/logo.png" alt="Logo">

7. &REQUEST.

• Purpose: Represents the current request parameter (e.g., GET or POST request).

• Usage: Useful for passing or reading dynamic values from the URL or form submission.

SELECT * FROM logs WHERE request_id = '&REQUEST.';

8. &DEBUG.

• Purpose: Indicates whether the debug mode is enabled ("YES") or disabled ("NO").

• Usage: You can use this to conditionally display debug information.

IF '&DEBUG.' = 'YES' THEN

  -- Show detailed debug information

END IF;

9. &APEX_FILES.

• Purpose: Represents the folder used for application-related files (this is often the same as &APP_FILES. but is more specifically used for APEX-related files).

• Usage: You can use this when referencing or storing files related to APEX applications.

<img src="&APEX_FILES./uploads/image.jpg" alt="Image">

10. &IMAGE_PREFIX. (legacy - use &APEX_FILES. instead)

• Purpose: The legacy prefix for images in your APEX application, now replaced by &APEX_FILES..

• Usage: You can still find it in older APEX versions, but it is now recommended to use &APEX_FILES..

11. &APEX_VERSION.

• Purpose: Represents the current version of Oracle APEX.

• Usage: Use this to display or log the APEX version for tracking purposes.

SELECT * FROM version_info WHERE apex_version = '&APEX_VERSION.';

12. &APEX_BASE_VERSION.

• Purpose: Represents the base version of Oracle APEX (e.g., the version of the software before any patches).

• Usage: Use this for compatibility or version tracking.

SELECT * FROM patch_info WHERE base_version = '&APEX_BASE_VERSION.';

---

Step 2: Practical Examples of Using Substitution Variables

Now that we know what each substitution variable does, let’s look at some practical examples of how to use them in APEX.

Example 1: Custom Greeting for Logged-in User

You can use the &APP_USER. substitution variable to create a personalized greeting for the logged-in user.

1. Create a Region in your APEX application (e.g., a Static Content region).

2. In the HTML Expression field, use the following code:

<h1>Welcome back, &APP_USER.!</h1>

3. When the page is rendered, it will display:

4. Welcome back, JOHN_DOE!

(assuming JOHN_DOE is the logged-in user).

Example 2: Displaying Application and Session Information

You can display the current application and session ID using the &APP_ID. and &APP_SESSION. variables.

1. Create a Static Content Region.

2. In the HTML Expression field, add the following code:

<p>Application ID: &APP_ID.</p>

<p>Session ID: &APP_SESSION.</p>

3. When the page loads, it will display:

4. Application ID: 100

5. Session ID: 123456789

Example 3: Debugging Mode Information

You can conditionally display debug information if the debug mode is enabled by using the &DEBUG. variable.

1. Create a Dynamic Action or PL/SQL Code on your page to check for debug mode:

BEGIN

  IF '&DEBUG.' = 'YES' THEN

    -- Display additional debug information

    htp.p('Debug Mode is enabled.');

  END IF;

END;

2. When Debug Mode is enabled, it will show:

3. Debug Mode is enabled.

Example 4: Custom File References Using &APP_FILES.

If you are working with files in your APEX application, you can reference them dynamically using &APP_FILES..

1. Suppose you have a PDF document stored in the Files directory.

2. You can create a link to download the file:

3. <a href="&APP_FILES./mydocument.pdf">Download Document</a>

4. When the page is rendered, the link will point to the correct location based on the application’s file directory.

Example 5: Displaying the APEX Version

You can display the current version of Oracle APEX using &APEX_VERSION. to inform users about the version running on the server.

1. Create a Static Content Region.

2. Add the following HTML expression:

3. <p>You are using Oracle APEX version &APEX_VERSION.</p>

4. When the page loads, it will display:

5. You are using Oracle APEX version 22.1.

Step 3: Using Substitution Variables in URLs

Substitution variables can also be useful when constructing dynamic URLs. For example, to navigate to a different page in your application, you can create a link that uses substitution variables to pass session and page information.

Example: Dynamic URL Based on Session ID

Suppose you want to create a link that includes the current session ID as part of the URL.

1. Create a Link in a region or item:

2. <a href="f?p=&APP_ID.:2:&APP_SESSION.:NO::&REQUEST.">Go to Page 2</a>

3. When the user clicks the link, it will navigate to Page 2 of the current application, passing the current session ID and request value.

Understanding how and where to use these variables can significantly improve the efficiency and clarity of your APEX applications. From referencing APP_USER to identify the logged-in user, to using APP_PAGE_ID for context-sensitive conditions, substitution variables allow you to embed intelligence directly into SQL, PL/SQL, HTML, and JavaScript within your application. By mastering these built-in tools, developers can build smarter, more secure, and scalable applications that respond automatically to user context and application behavior.