Introduction
Oracle APEX Template Components allow you to build reusable UI structures with dynamic content by leveraging template directives, substitution parameters, and template functions. These tools offer a powerful way to separate design from logic while keeping your application modular and maintainable. In this blog post, we’ll explore how to use APEX templates with parameters, control flow directives, and functions to build highly customizable and dynamic UI components.
Using APEX Template Application with Parameters, Directives, and Functions
-
Template Parameters
Template parameters are defined as placeholders within your template text using the syntax{parameter_name}. These parameters are substituted at runtime with values passed from your APEX components like Cards, Regions, or Lists.Example:
<div class="user-info"> <strong>{USERNAME}</strong> <span>{EMAIL}</span> </div>-
In your region/component settings, map
USERNAMEandEMAILto the appropriate column or static values.
-
-
Directives
Directives control the flow and logic of the template. These include:-
{if},{elseif},{else},{endif} -
{case},{when},{otherwise},{endcase} -
{loop},{endloop}
Example:
{if STATUS = 'ACTIVE'} <span class="badge badge-success">Active</span> {else} <span class="badge badge-secondary">Inactive</span> {endif} -
-
Template Functions
Functions likeapex_escape.html()orapex_util.get_session_state()can be used inside template logic to perform transformations or retrieve runtime data.Example:
<div>{apex_escape.html(NAME)}</div> -
Combining All Three
You can combine parameters, functions, and directives to build logic-heavy templates:<div> {if SHOW_IMAGE = 'Y'} <img src="{IMAGE_URL}" alt="{apex_escape.html(USERNAME)}"> {endif} <p>{USERNAME}</p> </div>
Best Practices
-
Keep your template logic simple—move complex decisions into SQL or PL/SQL when possible.
-
Use
apex_escapefunctions to avoid XSS vulnerabilities. -
Name parameters clearly and document expected values.
-
Test templates in isolation to verify conditional logic renders correctly.
-
Reuse template components across multiple pages for consistency and reduced maintenance.
Oracle APEX Documentation
You can find more details in the official Oracle documentation:
APEX Template Component Reference
1. applyTemplate Function
Purpose:
The applyTemplate function allows you to process a template string with placeholders and directives, substituting them with values or expressions.
Example:
You can create a template where placeholders like &P1_PROFILE_IMAGE_FILE are dynamically replaced with actual data from the page items or objects.
var options = { placeholders: { MESSAGE: "All is well." } };
apex.jQuery("#notification").html(
apex.util.applyTemplate("<div>#MESSAGE#</div>", options)
);
This will render the message "All is well." inside a <div> element with the id #notification.
Use case:
Dynamically updating parts of the page (like messages or images) based on page items or variables.
2. arrayEqual Function
Purpose:
Compares two arrays and returns true if the arrays have the same number of elements and each element is strictly equal.
Example:
var result1 = apex.util.arrayEqual([1, "two", 3], [1, "two", 3]); // true
var result2 = apex.util.arrayEqual([1, "two", 3], [1, "two", "3"]); // false
Use case:
Compare arrays to check if the data has not changed.
Useful when validating if two arrays in a form are equal.
3. debounce Function
Purpose:
Returns a debounced version of a function. It delays execution of the function until after a certain amount of time has passed since the last call.
Example:
function formatValue() {
var value = $v("P1_PHONE_NUMBER");
$s("P1_PHONE_NUMBER_DISPLAY", value);
}
apex.jQuery("#P1_PHONE_NUMBER").on("keypress", apex.util.debounce(formatValue, 100));
Here, formatValue is called only after the user has stopped typing for 100 milliseconds, which reduces unnecessary function calls.
Use case:
To optimize handling of user input events like typing in form fields.
Avoid unnecessary server calls or updates when typing.
4. escapeCSS Function
Purpose:
Escapes CSS meta-characters in a string, ensuring that it can be safely used as part of a CSS selector.
Example:
apex.jQuery("#" + apex.util.escapeCSS("my.id"));
Use case:
Dynamically generating CSS selectors when element IDs or class names may contain special characters like periods (.), which could interfere with CSS selectors.
5. escapeHTML Function
Purpose:
Escapes special HTML characters to prevent XSS (Cross-Site Scripting) attacks when inserting untrusted data into the DOM.
Example:
apex.jQuery("#show_user").append(apex.util.escapeHTML($v("P1_UNTRUSTED_NAME")));
Use case:
When inserting user-generated content or external data into HTML, always escape it to prevent potential security vulnerabilities.
6. escapeHTMLAttr Function
Purpose:
Escapes special HTML characters in attribute values to avoid XSS attacks.
Example:
apex.jQuery("#show_user").attr("title", apex.util.escapeHTMLAttr($v("P1_UNTRUSTED_NAME")));
Use case:
Safely injecting user data into HTML attributes like title, alt, etc., to prevent XSS vulnerabilities.
7. getDateFromISO8601String Function
Purpose:
Converts an ISO 8601 date string into a JavaScript Date object.
Example:
var date1 = apex.util.getDateFromISO8601String("1987-01-23T13:05:09.040Z");
Use case:
Convert ISO 8601 date strings into JavaScript Date objects for manipulation or formatting.
Useful for dealing with date strings returned from APIs or databases.
8. getNestedObject Function
Purpose:
Returns a nested object at a specific path within a complex object structure.
Example:
var options = {
views: {
grid: {
features: {
cellRangeActions: true
}
}
}
};
var o = apex.util.getNestedObject(options, "views.grid.features");
o.cellRangeActions = false; // now options.views.grid.features.cellRangeActions === false
Use case:
Used when you need to manipulate deeply nested properties within an object, ensuring that missing properties are created dynamically.
9. getScrollbarSize Function
Purpose:
Returns the size of the system scrollbar (if present).
Example:
var size = apex.util.getScrollbarSize();
console.log(size); // { width: 17, height: 17 }
Use case:
Helps in layout adjustments when adding or removing scrollbars dynamically.
10. htmlBuilder Function
Purpose:
Returns an htmlBuilder interface, which allows you to build HTML dynamically.
Example:
var builder = apex.util.htmlBuilder();
builder.div().content("Hello World").end();
var html = builder.toString();
apex.jQuery("#container").html(html);
Use case:
Dynamically constructing HTML elements in a more programmatic and reusable manner.
11. invokeAfterPaint and cancelInvokeAfterPaint Functions
Purpose:
invokeAfterPaint: Executes a function before the next browser paint (reflow/repaint).
cancelInvokeAfterPaint: Cancels the previously scheduled function call.
Example:
var id = apex.util.invokeAfterPaint(function() {
console.log("This will be executed before the next repaint.");
});
// Optionally cancel the execution before the paint happens
apex.util.cancelInvokeAfterPaint(id);
Use case:
Perform tasks like animations or layout adjustments before the page is visually updated.
12. showSpinner Function
Purpose:
Displays a loading spinner on the page, indicating that some processing is taking place.
Example:
var lSpinner$ = apex.util.showSpinner($("#container_id"));
lSpinner$.remove(); // Removes the spinner once processing is complete.
Use case:
Display a spinner while processing a form or making an AJAX request to give users feedback that something is happening in the background.
13. stripHTML Function
Purpose:
Removes all HTML tags from a string.
Example:
var text = "Please <a href='www.example.com/ad'>click here</a>";
var strippedText = apex.util.stripHTML(text);
console.log(strippedText); // "Please click here"
Use case:
Strip unwanted HTML tags from user input or data that will be displayed as plain text.
14. toArray Function
Purpose:
Converts a value into an array. If the value is a string, it splits it based on a separator. If it's already an array or jQuery object, it converts it into a true JavaScript array.
Example:
var products = apex.util.toArray("Bags:Shoes:Shirts", ":");
console.log(products); // ["Bags", "Shoes", "Shirts"]
Use case:
Convert values into arrays for easier processing, such as when working with lists of items or elements on the page.
EXAMPLE:
Table – Table name: Requests
Code:
CREATE TABLE "CARDTEST"
( "ID" NUMBER GENERATED BY DEFAULT ON NULL AS IDENTITY MINVALUE 1 MAXVALUE 9999999999999999999999999999 INCREMENT BY 1 START WITH 1 CACHE 20 NOORDER NOCYCLE NOKEEP NOSCALE NOT NULL ENABLE,
"DISPLAYTHENAME" VARCHAR2(200 CHAR),
"USERNAME" VARCHAR2(200 CHAR),
"TITLE" VARCHAR2(200 CHAR),
"MAINPHONE" VARCHAR2(200 CHAR),
"MOBILEPHONE" VARCHAR2(200 CHAR),
"EMAIL" VARCHAR2(200 CHAR),
"SERVICEREQUEST_TEST1A" VARCHAR2(200 CHAR),
"SERVICEREQUEST_TEST2A" VARCHAR2(200 CHAR),
"SERVICEREQUEST_TEST3A" VARCHAR2(200 CHAR),
"MAINTENANCEREQUEST_TEST1B" VARCHAR2(200 CHAR),
"MAINTENANCEREQUEST_TEST2B" VARCHAR2(200 CHAR),
"MAINTENANCEREQUEST_TEST3B" VARCHAR2(200 CHAR),
"OTHERREQUEST_TEST1C" VARCHAR2(200 CHAR),
"OTHERREQUEST_TEST2C" VARCHAR2(200 CHAR),
"OTHERREQUEST_TEST3C" VARCHAR2(200 CHAR),
CONSTRAINT "CARDTEST_PK" PRIMARY KEY ("ID")
USING INDEX ENABLE
) ;
Add the Data
We’ll be looking to display to cards (one for each data row)
Report Card-1 (row 1 data)
Report Card-2 (row 2 data)
Create a “CARDS” Page
Step 1
Display of the web page with two cards, one for each data row.
We want to make the data display something like this:
Lets set up the name header area:
Notes:
We want this area to display ONLY when DisplayTheName =Y
Any othe value will display a blank area.
Place this code in a Notepad for easier use and edit
To implement this logic we have to use the following:
#{if <condition>}
<content>
#{else}
<alternative_content>
#{/if}
In the code we will enter the following:
<div class="t-Report t-Report--stretch " style="width:100%">
{case DisplayTheName /}
{when Y/}
<!--- Code for the table goes here when the value is “Y” -->
{when N/}
<!--- Code for the table goes here when the value is “N” -->
{otherwise/}
<!--- Code for the table goes here when the value is neither “Y” or “N”-->
{endcase/}
</div>
Then we will add the HTML code for the table where the value is “Y”:
<table class="t-Report-report u-textCenter">
<thead class="t-Report-report u-textCenter">
<tr>
<th class="t-Report-colHead u-bold ">Display Name</th>
<th class="t-Report-colHead u-bold ">Job Title </th>
<th class="t-Report-colHead u-bold ">Business Phone </th>
<th class="t-Report-colHead u-bold ">Mobile Phone </th>
<th class="t-Report-colHead u-bold ">Email </th>
</tr>
</thead>
<tbody>
<tr>
<td class="t-Report-cell"> &USERNAME. </td>
<td class="t-Report-cell"> &TITLE. </td>
<td class="t-Report-cell"> &PRIMARYPHONE. </td>
<td class="t-Report-cell"> &MOBILEPHONE. </td>
<td class="t-Report-cell"> &EMAIL. </td>
</tr>
</tbody>
</table>
Here is the code inserted into the “IF” loop
<div class="t-Report t-Report--stretch " style="width:100%">
{case DisplayTheName /}
{when Y/}
<!--- Code for the table goes here when the value is “Y” -->
<table class="t-Report-report u-textCenter">
<thead class="t-Report-report u-textCenter">
<tr>
<th class="t-Report-colHead u-bold ">Display Name</th>
<th class="t-Report-colHead u-bold ">Job Title </th>
<th class="t-Report-colHead u-bold ">Business Phone </th>
<th class="t-Report-colHead u-bold ">Mobile Phone </th>
<th class="t-Report-colHead u-bold ">Email </th>
</tr>
</thead>
<tbody>
<tr>
<td class="t-Report-cell"> &USERNAME. </td>
<td class="t-Report-cell"> &TITLE. </td>
<td class="t-Report-cell"> &PRIMARYPHONE. </td>
<td class="t-Report-cell"> &MOBILEPHONE. </td>
<td class="t-Report-cell"> &EMAIL. </td>
</tr>
</tbody>
</table>
{when N/}
<!--- Code for the table goes here when the value is “N” -->
{otherwise/}
<!--- Code for the table goes here when the value is neither “Y” or “N”-->
{endcase/}
</div>
Now, where go to the page in order to add the new code.
Select the Report in the page
Select the attribute:
Navigate to the “Body” region on the right hand side, below the “Attributes” section and turn on the “Advanced Formating”
Select the Arrow button
Add the code in the window:
Your page should now look something like this:
If you run the page you will see that nothing has changed:
So what went wrong?
We need to make the search criteria upper case, so we will change the code
from {case DisplayTheName /}
to {case DISPLAYTHENAME /}
Now save and run the page and we get the following result:
Next, we will add the rest of the HTML code, making sure that all of the replacement variables
Have a “&” at the start of the variable name.
Are in upper case.
Have a “.” Period at the end of the name.
They should look something like this “&XXXXXXXXXXX.”
<br>
<!-- second line-->
<div class="t-Report t-Report--stretch" style="width:100%">
<table class="t-Report-report u-textCenter">
<thead class="t-Report-report u-textCenter">
<tr>
<th class="t-Report-colHead u-bold ">Service Request</th>
<th class="t-Report-colHead u-bold ">Maintenance Request </th>
<th class="t-Report-colHead u-bold ">Other </th>
</tr>
</thead>
<tbody>
<tr>
<td class="t-Report-cell"> Test1A: &SERVICEREQUEST_TEST1A. </td>
<td class="t-Report-cell"> Test1B: &MAINTENANCEREQUEST_TEST1B. </td>
<td class="t-Report-cell"> Test1C: &OTHERREQUEST_TEST1C.</td>
</tr>
<tr>
<td class="t-Report-cell"> Test2A: & SERVICEREQUEST_TEST 2A.</td>
<td class="t-Report-cell"> Test2B: & MAINTENANCEREQUEST_TEST2B. </td>
<td class="t-Report-cell"> Test2C: & OTHERREQUEST_TEST 2C. </td>
</tr>
<tr>
<td class="t-Report-cell"> Test3A: & SERVICEREQUEST_TEST 3A.</td>
<td class="t-Report-cell"> Test3B: & MAINTENANCEREQUEST_TEST3B. </td>
<td class="t-Report-cell"> Test3C: & OTHERREQUEST_TEST 3C. </td>
</tr>
</tbody>
</table>
</div>
Make sure that you add the code outside of the “IF” loop
<br>
<!-- second line-->
<div class="t-Report t-Report--stretch" style="width:100%">
<table class="t-Report-report u-textCenter">
<thead class="t-Report-report u-textCenter">
<tr>
<th class="t-Report-colHead u-bold ">Service Request</th>
<th class="t-Report-colHead u-bold ">Maintenance Request </th>
<th class="t-Report-colHead u-bold ">Other </th>
</tr>
</thead>
<tbody>
<tr>
<td class="t-Report-cell">TEST1A: &SERVICEREQUEST_TEST1A. </td>
<td class="t-Report-cell"> TEST1B: &MAINTENANCEREQUEST_TEST1B. </td>
<td class="t-Report-cell"> TEST1C: &OTHERREQUEST_TEST1C.</td>
</tr>
<tr>
<td class="t-Report-cell"> TEST2A: &SERVICEREQUEST_TEST2A.</td>
<td class="t-Report-cell"> TEST2B: &MAINTENANCEREQUEST_TEST2B. </td>
<td class="t-Report-cell"> TEST2C: &OTHERREQUEST_TEST2C. </td>
</tr>
<tr>
<td class="t-Report-cell"> TEST3A: &SERVICEREQUEST_TEST3A.</td>
<td class="t-Report-cell"> TEST3B: &MAINTENANCEREQUEST_TEST3B. </td>
<td class="t-Report-cell"> TESTC: &OTHERREQUEST_TEST3C. </td>
</tr>
</tbody>
</table>
Here are the results:
When the “DISPLAYTHENAME” value is “Y” we display the header, otherwise nothing displays.
Conclusion
Using APEX template parameters, directives, and functions effectively enables you to design flexible, reusable components that respond dynamically to data and user input. These features reduce redundancy and increase the maintainability of your Oracle APEX applications. By following best practices and utilizing the available directives, you can streamline UI development and deliver consistent, scalable results.
