How to Create and Use APEX If Condition Directives

 

Introduction
In Oracle APEX, controlling when components such as regions, buttons, items, or processes display or run is a fundamental part of application design. APEX If Condition directives give you the flexibility to show or hide components based on specific logic—like user roles, page items, or session state. This dynamic behavior enhances the user experience, enforces security, and reduces clutter by ensuring users only see what's relevant to them.

How to Create and Use APEX If Condition Directives

1. Understanding If Conditions
   If Conditions in APEX are evaluated during page rendering or processing. You can apply them to nearly every component: regions, items, buttons, processes, dynamic actions, validations, and more.
2. Where to Set If Conditions
   • Navigate to a component (for example, a Region).
   • Go to the Server-Side Condition or Condition section.
   • Choose the type of condition to apply.
3. Common Types of Conditions
   • Item = Value: Display if a specific item equals a given value.
   • Value of Item in Expression 1 = Expression 2: Compare two values dynamically.
   • Function Body Returning Boolean: Use PL/SQL logic that returns TRUE or FALSE.
   • Current User is in Role: Useful for role-based access control.
   • Exists (SQL Query): Show component if a query returns data.
   • No Condition: Always show.
   • Never: Never show.
   • Page is in Printer-Friendly Mode
   • Request = Expression 1: Check if the page request matches a value.
   • Application Item = Value: Compare application-level session state.
4. Example: Hide a Button Unless the User is Admin
   • Set the Button’s Server-Side Condition to:
     Type: PL/SQL Function Body Returning Boolean
     Code:
     return upper(:APP_USER) = 'ADMIN';
5. Example: Only Show a Region if an Item is Checked
   • Condition Type: Item = Value
   • Item: P10_SHOW_DETAILS
   • Value: Y
6. Using Conditional Logic with Authorization Schemes
   • Select Type: Current User is Authorized (by Authorization Scheme)
   • Pick the desired Authorization Scheme to centralize access logic.

Best Practices

• Use PL/SQL Function Bodies when the condition logic is complex or involves querying tables.
• Reuse logic through Authorization Schemes or Application Items to reduce duplication.
• For performance, avoid complex SQL or PL/SQL conditions that may slow rendering.
• Use simple conditions like Item = Value for better maintainability when appropriate.
• Document your condition logic clearly in comments or the component description.

Official Oracle APEX Documentation
Explore official documentation for full coverage of conditional display logic:
Oracle APEX Conditions Documentation

In Oracle APEX, If condition directives are used to dynamically control the behavior and content of your pages based on certain conditions. They allow you to use conditional logic (similar to IF statements in programming) directly in your APEX application. These directives enable you to show or hide regions, items, or perform specific actions based on values like the current user, session, or specific conditions within your data.

The If condition directives are often used in regions, dynamic actions, and SQL queries. In this tutorial, we will cover the basics of these directives and provide practical examples of how to use them in Oracle APEX.

Step 1: Understanding If Condition Directives

APEX If condition directives allow you to check conditions dynamically and display or execute content based on the evaluation of those conditions.

Syntax of the IF Directive

The syntax of the IF directive in APEX is:

#{if <condition>} 

    <content>

#{else} 

    <alternative_content>

#{/if}

• : This is the condition you want to evaluate. It can be a comparison between values, checking session variables, or even page item values.
• : The content that will be displayed or action executed if the condition is true.
• <alternative_content>: The content to be displayed or action to be executed if the condition is false (optional).
• #{/if}: This ends the if block.

Step 2: Using IF Condition Directives in APEX

Let’s explore a few practical examples of how to use If condition directives in various scenarios in Oracle APEX.

Example 1: Showing Content Based on Session Variables

You can use the IF directive to show different content based on the session variables or page items, such as displaying a personalized message for the logged-in user.

Steps:

1. Create a Static Content Region on your page.
2. In the HTML Expression field, add the following code:

#{if &APP_USER. == 'ADMIN'}

    <h2>Welcome, Administrator!</h2>

    <p>You have full access to the application.</p>

#{else}

    <h2>Welcome, &APP_USER.!</h2>

    <p>Limited access based on your role.</p>

#{/if}

• Explanation: In this example, if the logged-in user (&APP_USER.) is "ADMIN", the region will display a message for the administrator. Otherwise, it will display a generic message for all other users.

Expected Output:

• If the logged-in user is "ADMIN":
• Welcome, Administrator!
• You have full access to the application.
• If the logged-in user is not "ADMIN":
• Welcome, JohnDoe!
• Limited access based on your role.

Example 2: Show or Hide Regions Based on Item Value

You can also use If condition directives to conditionally show or hide regions based on a page item value.

Steps:

1. Create a Page Item: Create a page item (e.g., a checkbox or select list) called P1_SHOW_DETAILS.
2. Create a Region: Create a Static Content region where you want to display conditional content.
3. In the HTML Expression field, use the following code:

#{if :P1_SHOW_DETAILS == 'Y'}

    <h3>Details Section</h3>

    <p>This section contains additional information.</p>

#{else}

    <h3>Details Section</h3>

    <p>This section is hidden because the checkbox is not checked.</p>

#{/if}

• Explanation: This code checks the value of P1_SHOW_DETAILS (a page item). If it is set to 'Y' (checked or selected), the content in the if block is shown. Otherwise, the else block content is shown.

Expected Output:

• If P1_SHOW_DETAILS is set to 'Y':
• Details Section
• This section contains additional information.
• If P1_SHOW_DETAILS is set to 'N':
• Details Section
• This section is hidden because the checkbox is not checked.

Example 3: Conditional Display of Regions Based on Application Item

You can conditionally display regions based on application items, such as checking whether a user is logged in or not.

Steps:

1. Create an Application Item: Create an application item, e.g., APP_USER_LOGGED_IN.
2. Set the Application Item: You can set APP_USER_LOGGED_IN in a login process to 'Y' if the user is logged in.
3. Create a Region: Add a Static Content region with the following HTML Expression:

#{if :APP_USER_LOGGED_IN == 'Y'}

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

    <p>Your previous session was restored.</p>

#{else}

    <h2>Welcome to the Application</h2>

    <p>Please log in to access your data.</p>

#{/if}

• Explanation: This will display a message to the user based on whether they are logged in or not. The APP_USER_LOGGED_IN application item determines if the user is logged in.

Expected Output:

• If APP_USER_LOGGED_IN is 'Y':
• Welcome back, JohnDoe!
• Your previous session was restored.
• If APP_USER_LOGGED_IN is 'N':
• Welcome to the Application
• Please log in to access your data.

Example 4: Using IF Directive in Dynamic Actions

You can also use the IF condition within Dynamic Actions to execute actions based on conditions, such as page item values or session states.

Steps:

1. Create a Page Item: Create a page item (e.g., P1_STATUS).
2. Create a Dynamic Action: Create a Dynamic Action triggered by a change in P1_STATUS.
3. Set the Action Type: Use Execute JavaScript as the action and add the following JavaScript code:

if ("#{P1_STATUS}" == "ACTIVE") {

    alert("The status is active!");

} else {

    alert("The status is not active.");

}

• Explanation: This JavaScript code checks the value of the P1_STATUS page item. If it is set to 'ACTIVE', it shows an alert stating that the status is active. Otherwise, it shows a different message.

Expected Output:

• If P1_STATUS is "ACTIVE":
• Alert: "The status is active!"
• If P1_STATUS is not "ACTIVE":
• Alert: "The status is not active."

Step 3: Advanced Conditional Logic

You can combine multiple conditions using AND, OR, and other logical operators to create more advanced logic within your IF directives.

Example: Check Multiple Conditions

#{if &APP_USER. == 'ADMIN' && :P1_STATUS == 'ACTIVE'}

    <p>Welcome back, Admin. The status is active!</p>

#{else}

    <p>Either you are not an Admin, or the status is not active.</p>

#{/if}

• Explanation: In this case, the IF condition checks two things: if the user is "ADMIN" and if the page item P1_STATUS is set to 'ACTIVE'. If both conditions are true, the first message will be displayed. Otherwise, the else message will be shown.

By using these directives, you can create flexible and responsive applications that adapt to different user interactions, session states, or data values.

 

Conclusion
Oracle APEX If Condition directives are a core feature for dynamic and secure application behavior. Whether you're tailoring the interface to user roles or managing complex workflows, mastering these conditions ensures that your app responds intelligently to users and context. With careful planning and the use of best practices, If Conditions can greatly enhance both usability and maintainability.

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

Introduction
Oracle APEX includes a powerful feature called substitution variables that allows developers to insert dynamic values into SQL, PL/SQL, HTML, and JavaScript. These variables provide flexibility in referencing session state, system values, and application-level information without hardcoding. Built-in substitution variables come pre-defined and can be used throughout your application to simplify coding, personalize the user experience, and support debugging and navigation.

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

Built-in substitution variables are predefined by APEX and are automatically available in your application without requiring explicit creation. They are used by placing them within & delimiters, such as &APP_USER. or &APP_ID..

1. Common Built-in Substitution Variables

   • &APP_USER. – The currently logged-in username

   • &APP_ID. – The Application ID

   • &APP_PAGE_ID. – The current page number

   • &APP_ALIAS. – The application alias

   • &APP_SESSION. – The session ID

   • &APP_IMAGES. – Path to the images directory

   • &PRINTER_FRIENDLY. – Whether the page is in printer-friendly mode (YES or NO)

2. Where You Can Use Them

   • In SQL queries (e.g., WHERE created_by = '&APP_USER.')

   • In PL/SQL blocks

   • In static content (e.g., region HTML or labels)

   • In URLs to pass parameters between pages (e.g., f?p=&APP_ID.:10:&APP_SESSION.::NO::P10_ID:123)

   • In dynamic actions and JavaScript expressions

3. Usage Examples

   • Displaying the logged-in user on the page:
     Create a Static Content region with the text: Welcome, &APP_USER.!

   • Using in a SQL report:

     SELECT * FROM orders WHERE sales_rep = '&APP_USER.'
     

   • Creating links between pages:
     Use the Link column attribute to set a target using:
     f?p=&APP_ID.:2:&APP_SESSION.::NO::P2_ID:#ID#

4. Best Practices

   • Always terminate substitution variables with a dot . to avoid conflicts

   • Use htf.escape_sc or APEX functions to escape values if used in HTML output

   • For security and clarity, don’t rely on substitution in sensitive queries; use bind variables where appropriate

   • Test how values render at runtime to avoid unexpected behaviors

 

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.

Conclusion
Built-in substitution variables in Oracle APEX offer a simple yet powerful way to incorporate session, user, and application context throughout your application. They enable you to personalize experiences, build dynamic URLs, and maintain readable code. When used correctly, these variables reduce development time and ensure your application behaves consistently across sessions and users. Understanding where and how to apply them is an essential skill for every APEX developer.