Introduction
In Oracle APEX, style templates define how components such as regions, buttons, and reports are rendered in HTML. Using data substitution strings within these templates allows developers to dynamically inject values like labels, IDs, and data at runtime. This technique gives your application a consistent layout while maintaining flexibility and reusability. In this guide, you’ll learn how to create and use APEX Style Templates that include data substitutions, allowing your APEX components to render intelligently based on user interactions and stored data.
How to Create and Use APEX Style Templates with Data Substitutions
-
Access the Template Builder
Open your APEX application, navigate to Shared Components, then click on Templates under the User Interface section. Choose the type of template you want to build (Region, Button, Report, etc.). -
Create a New Template
Click Create and select From Scratch or Copy Existing depending on whether you're starting fresh or customizing an existing template. -
Define Template HTML with Substitution Strings
In the Template Definition section, use substitution strings to allow dynamic data injection. These strings are placeholders replaced by actual values at runtime.For example, a simple custom region template:
<div class="custom-container #REGION_CSS_CLASSES#"> <h2>#TITLE#</h2> <div class="custom-body">#BODY#</div> <div class="meta">Region ID: #REGION_STATIC_ID#</div> </div>Key substitution strings used here:
-
#TITLE#: The title of the region -
#BODY#: The content of the region -
#REGION_STATIC_ID#: The region’s static ID
-
-
Use Template Options for Enhanced Customization
Within the template definition, you can use template options as additional substitution strings. These allow developers to toggle styles or layouts.
Define them under Template Options, then reference using#OPTION_NAME#in your HTML. -
Apply JavaScript or Dynamic Substitution Values
You can include JavaScript in the template to respond to values or IDs injected through substitutions.
Example:<script> console.log("Region loaded: #REGION_STATIC_ID#"); </script> -
Apply the Template to Components
Go to any page that uses the component type you just templated (for example, a region), and under Appearance, select your custom template. If you added options, set their values under Template Options. -
Preview and Debug
Run your application and inspect how the substitution values are being applied. Use browser developer tools to inspect HTML output and confirm your placeholders are being correctly replaced. -
Common Substitution Strings by Template Type
-
Region Templates:
#BODY#,#TITLE#,#REGION_STATIC_ID#,#REGION_CSS_CLASSES# -
Report Templates:
#ROWS#,#ROWNUM#,#COLUMN_HEADER#,#COLUMN_VALUE# -
Button Templates:
#LABEL#,#BUTTON_ID#,#BUTTON_CSS_CLASSES# -
List Templates:
#TEXT#,#LINK#,#IMAGE#
-
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:
<div class="custom-card">
<div class="custom-card-header">
<h3 class="card-title">&FIRST_NAME. &LAST_NAME.</h3>
</div>
<div class="custom-card-body">
<p><strong>Job Title:</strong> &JOB_TITLE.</p>
<p><strong>Department:</strong> &DEPARTMENT_NAME.</p>
<p><strong>Salary:</strong> $&SALARY.</p>
</div>
<div class="custom-card-footer">
<a href="f?p=&APP_ID.:DETAILS:&SESSION.::NO::P1_EMPLOYEE_ID:&EMPLOYEE_ID." class="btn btn-primary">View Details</a>
</div>
</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;">
<div class="custom-card-header">
<h3 class="card-title">&FIRST_NAME. &LAST_NAME.</h3>
</div>
<div class="custom-card-body">
<p><strong>Job Title:</strong> &JOB_TITLE.</p>
<p><strong>Department:</strong> &DEPARTMENT_NAME.</p>
<p><strong>Salary:</strong> $&SALARY.</p>
</div>
<div class="custom-card-footer">
<a href="f?p=&APP_ID.:DETAILS:&SESSION.::NO::P1_EMPLOYEE_ID:&EMPLOYEE_ID." class="btn btn-primary">View Details</a>
</div>
</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:
<div class="custom-card">
<div class="custom-card-header">
<img src="&PHOTO_URL." alt="Employee Photo" class="employee-photo">
<h3 class="card-title">&FIRST_NAME. &LAST_NAME.</h3>
</div>
<div class="custom-card-body">
<p><strong>Job Title:</strong> &JOB_TITLE.</p>
<p><strong>Department:</strong> &DEPARTMENT_NAME.</p>
<p><strong>Salary:</strong> $&SALARY.</p>
</div>
</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.
Conclusion
Using data substitutions in APEX Style Templates allows you to create smart, dynamic layouts that respond to both developer-defined settings and runtime data. By mastering this feature, you can deliver highly reusable templates that maintain clean, semantic HTML and reduce duplication throughout your APEX app. Whether you're building branded UI components or optimizing layout flexibility, substitution strings are a key tool in building professional-grade Oracle APEX applications.
