APEX Field Notes: Create and Use APEX Style Templates with Data Substitutions

In Oracle APEX, style templates provide developers with the ability to define reusable layouts and visual formats for regions, reports, buttons, and items. By incorporating data substitutions into these templates, you can dynamically inject values from your database or application session into your user interface. This method not only ensures consistency across pages but also gives you the flexibility to personalize the display of content using placeholder variables like #COLUMN_NAME#, #TITLE#, or &ITEM_NAME.. Creating and using style templates with substitution strings helps streamline development, enforce branding standards, and deliver a more dynamic and responsive application experience.

In Oracle APEX, style templates define the layout and structure of how regions, reports, buttons, and items appear across your application. When combined with data substitutions, these templates become dynamic and capable of displaying personalized or data-driven content without hardcoding. Using substitution strings allows values to be inserted at runtime, enabling the template to adapt based on the user, session, or database contents.

Creating a Custom Style Template with Substitution Strings

Navigate to Shared Components
Open your APEX application. From the Application Builder, go to Shared Components.
Create or Modify a Template
Under the User Interface section, select Templates. You can either create a new template (such as a region, report, or label template) or edit an existing one.
Define Template Type
Choose the type of template you're working on—for example, a Region template or Classic Report template. Click Create or select an existing template to modify.
Insert Substitution Strings
In the template definition, especially under the HTML or Template Text areas, use substitution strings such as:
- #COLUMN_NAME# for report templates
- #LABEL#, #HELP_TEXT#, #ITEM_NAME# for item or region templates
- &APP_USER. to get the current logged-in user
- &SESSION. for the current session ID
- #VALUE# to display the value of a field or column
For example, a custom region template might include:
```
<div class="custom-box">
  <h3>#TITLE#</h3>
  <p>#BODY#</p>
  <span class="footer">User: &APP_USER.</span>
</div>
```
Reference the Template in Your Application
After saving the template, go to any region, report, or item and assign the custom template. This is done in the component’s Appearance or Layout section under the Template property.
Test Dynamic Substitutions
Run the application to ensure that all substitution strings are being interpreted correctly and that the content reflects actual data or session values.

Using Substitutions in Reports

When creating Classic Reports, substitution strings allow developers to control how each row of data is rendered. For example:

<a href="f?p=&APP_ID.:10:&SESSION.:::10:P10_ID:#EMPLOYEE_ID#">#EMPLOYEE_NAME#</a>

This turns the employee name into a clickable link that navigates to another page using the EMPLOYEE_ID as a parameter.

Best Practices

Use descriptive CSS classes in your templates for easy styling.
Store frequently used layouts as shared templates to ensure consistency.
Keep substitution logic readable and maintainable—avoid nesting complex logic directly into the template when possible.

By combining APEX style templates with substitution strings, you can centralize your formatting rules while allowing the actual data to drive how content is presented. This leads to cleaner code, better maintainability, and a more scalable application design.

In Oracle APEX, Data Substitutions allow you to insert dynamic data from your application’s database or context into your HTML templates or region templates. This is an extremely useful feature for customizing reports, forms, card regions, and other UI elements by embedding values directly from your data source.

This tutorial will walk you through how to create APEX Style Templates that incorporate Data Substitutions. You will learn how to:

Use APEX Substitution Variables in templates.
Customize templates with dynamic data.
Apply the templates to different APEX regions.

By the end of this tutorial, you'll be able to leverage dynamic data in your templates, providing a more flexible and data-driven user interface.

Step 1: Understanding APEX Substitution Variables

APEX Substitution Variables are placeholders that represent the values of your database columns or session data. When rendering a page, APEX replaces these variables with actual values from your SQL query, session, or application.

Some common substitution variables include:

&COLUMN_NAME.: Replaces with the value of a column from your query.
&APP_ID.: Replaces with the current application ID.
&SESSION.: Represents the current session ID.
&USER.: Represents the current APEX user.

Example of Substitution Variable Usage:

Let’s assume we have an employee table with columns like employee_id, first_name, last_name, and job_title. The SQL query might look like this:

SELECT employee_id, first_name, last_name, job_title FROM employees

In the template, you could use substitution variables like &FIRST_NAME., &LAST_NAME., and &JOB_TITLE. to insert employee data into a custom card layout.

Step 2: Creating a New APEX Application (if not already created)

Log in to your Oracle APEX workspace.
From the App Builder, click Create to start a new application or navigate to an existing one.
Create a simple page with a Classic Report or Card Report to test data substitutions. For example, a Card Report that lists employees.

Step 3: Applying Predefined APEX Style Templates with Data Substitutions

Oracle APEX provides predefined templates that you can customize to include substitution variables. For this example, we will customize a Card Report template to display dynamic employee information.

Example: Using Substitution Variables in Card Report Template

Create a Card Report Region:

In the App Builder, select your page or create a new page with a Card Report region.
Set the SQL Query for the Card Report. Example:
SELECT employee_id, first_name, last_name, job_title, department_name, salary FROM employees

Edit the Card Report Template:

After creating the report, go to the Region properties for the Card Report.
Under Region Attributes, locate the Template dropdown. Select Card - Simple or any other predefined card template.
To customize the template with data substitutions, click on the Template name to edit it.

Customize the Template with Substitution Variables: In the HTML Template area, you can add your APEX substitution variables. For example:

<h3 class="card-title">&FIRST_NAME. &LAST_NAME.</h3>

</div>

<p><strong>Job Title:</strong> &JOB_TITLE.</p>

<p><strong>Department:</strong> &DEPARTMENT_NAME.</p>

<p><strong>Salary:</strong> $&SALARY.</p>

</div>

<a href="f?p=&APP_ID.:DETAILS:&SESSION.::NO::P1_EMPLOYEE_ID:&EMPLOYEE_ID." class="btn btn-primary">View Details</a>

</div>

Explanation:

&FIRST_NAME., &LAST_NAME., &JOB_TITLE., etc., are APEX substitution variables that will be replaced with the actual values for each row in your query.
The View Details button includes a link to a detail page, passing the employee_id as a parameter.

Save the Changes and Preview the Page:

Save the template, and run the application.
The Card Report will now display employee data with dynamically substituted values (e.g., employee name, job title, department, salary).

Step 4: Customizing the Card Report with Additional Data Substitutions

You can use more advanced data substitutions within your templates, including conditional logic and additional columns from your query.

Example 1: Conditional Formatting with Substitutions

You can conditionally style elements using APEX substitution variables and HTML expressions.

Example: Change the card's background color based on salary:

<div class="custom-card" style="background-color: &IF &SALARY. > 70000 THEN 'lightgreen'; ELSE 'lightcoral'; END IF;">

<h3 class="card-title">&FIRST_NAME. &LAST_NAME.</h3>

</div>

<p><strong>Job Title:</strong> &JOB_TITLE.</p>

<p><strong>Department:</strong> &DEPARTMENT_NAME.</p>

<p><strong>Salary:</strong> $&SALARY.</p>

</div>

<a href="f?p=&APP_ID.:DETAILS:&SESSION.::NO::P1_EMPLOYEE_ID:&EMPLOYEE_ID." class="btn btn-primary">View Details</a>

</div>

Explanation:

The IF statement changes the background color of the card depending on the employee's salary. If the salary is greater than 70,000, the background is light green; otherwise, it is light coral.

Example 2: Adding an Image (with Substitution Variables)

You can also use substitution variables for images or links. For example, you may want to display an employee's photo.

If your table includes a photo_url column, you can dynamically insert the image in the template:

<h3 class="card-title">&FIRST_NAME. &LAST_NAME.</h3>

</div>

<p><strong>Job Title:</strong> &JOB_TITLE.</p>

<p><strong>Department:</strong> &DEPARTMENT_NAME.</p>

<p><strong>Salary:</strong> $&SALARY.</p>

</div>

Explanation:

&PHOTO_URL. is a substitution variable that dynamically loads the employee's photo from the photo_url column in the query result.

Step 5: Applying Custom CSS for Styling

You can further style your templates by adding custom CSS. For example, you can style the card header, body, or footer differently depending on the type of data or the design you want.

Navigate to the Page’s CSS:

In App Builder, go to the page where you want to apply custom styles.
Under the Page Attributes section, find the Inline CSS field.

Add Custom CSS: Example CSS to enhance the card design:

.custom-card {

border: 2px solid #ccc;

border-radius: 10px;

padding: 20px;

margin: 15px;

box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1);

}

.custom-card-header {

background-color: #f4f4f4;

text-align: center;

padding: 10px;

}

.custom-card-footer {

text-align: center;

margin-top: 15px;

}

.employee-photo {

width: 60px;

height: 60px;

border-radius: 50%;

}

.btn-primary {

background-color: #4CAF50;

color: white;

padding: 10px 20px;

border-radius: 5px;

}

Save and Preview:

Save the CSS changes and run the page again to see the updated design.

Step 6: Testing and Debugging

Test the Page:

Run the application and inspect the rendered card report.
Verify that the substitution variables are correctly replaced with the data from your SQL query.
Check for any styling issues, especially with conditional formatting or dynamic content.

Debug with Browser Tools:

Use browser developer tools (F12) to inspect the HTML and see if the substitution variables are properly replaced.
If any dynamic content is not showing up as expected, check the region’s template and ensure that the substitution variables are correct.

Using APEX Style Templates with Data Substitutions allows you to create dynamic and data-driven applications. With substitution variables, you can

easily insert real-time data from your database into regions, reports, cards, and forms. This tutorial has shown you how to:

Create and use predefined APEX templates.
Customize templates with substitution variables.
Apply dynamic content and conditional formatting.

By following these steps, you can build richer, more dynamic UIs that respond to real-time data, making your applications more interactive and user-friendly.

By leveraging APEX style templates combined with data substitutions, developers can build robust UI components that reflect real-time data with minimal effort. This approach makes it easy to manage formatting centrally while providing flexibility to inject dynamic content. As your application evolves, using well-structured templates with substitutions ensures better maintainability, enhanced user experience, and a scalable design framework across your entire APEX environment.

APEX Field Notes

Search This Blog

Tuesday, July 1, 2025

How to Create and Use APEX Style Templates with Data Substitutions

Building your very first application with ORACLE APEX