APEX Field Notes: APEX$ID

Introduction:

In Oracle APEX, creating dynamic, data-rich user interfaces often requires leveraging template directives and substitution variables to control how data is displayed. When building custom report templates—especially with Cards, Classic Reports, or Regions—APEX provides powerful built-in variables like APEX$ID, APEX$I, and APEX$META. These variables are particularly useful when working inside {loop} directives, enabling developers to uniquely identify, count, and reference metadata about each row of data. Understanding how to use these variables correctly can significantly enhance the interactivity, uniqueness, and clarity of the UI components you design.

Using ARIAL font, font size: 14px, plain text

In Oracle APEX, when you create custom templates for regions such as Classic Reports or Card Reports, the use of loop directives and built-in substitution variables enhances your ability to dynamically control the display of each record. Among these substitution variables, APEX$ID, APEX$I, and APEX$META play a crucial role in managing behavior, formatting, and dynamic interactivity within loops.

APEX$ID
This variable returns the unique static ID of the current component instance. It is particularly useful when you need to uniquely identify elements within a loop. For example, if you are outputting rows with buttons, you might need to assign each button a unique id to bind JavaScript or CSS styles.

Example:

<button id="btn_#APEX$ID#">Edit</button>

This ensures each button has a unique ID, avoiding conflicts in DOM behavior.

APEX$I
This is the loop index variable. It gives the numeric position of the current iteration within the loop, starting from 1. This is useful for alternating styles (e.g., zebra striping) or referencing row numbers.

Example:

<div class="row-style-#APEX$I#">
  Row #APEX$I#
</div>

You could then apply conditional formatting using APEX$I to highlight every other row.

APEX$META
This variable provides access to metadata about the current item. It is useful when the column or attribute has associated metadata defined in the template or in the report settings. For example, it can provide contextual information such as the column label, alignment, or display type.

Example use in debug or dynamic layouts:

<span title="#APEX$META.COLUMN_NAME#">
  #COLUMN_VALUE#
</span>

Putting It All Together in a Card Template
Here's a simplified example using all three variables in a card region template:

<div id="card_#APEX$ID#" class="card row-#APEX$I#">
  <div class="card-header">#APEX$META.COLUMN_NAME#</div>
  <div class="card-body">#COLUMN_VALUE#</div>
</div>

In this example:

APEX$ID uniquely identifies the card.
APEX$I indicates the position in the loop.
APEX$META dynamically references metadata for display logic.

These can be particularly helpful in templates for reports, interactive grids, or any dynamic data display in APEX.

These variables are only evaluated inside the {loop} directive block, so they must be used within loop boundaries to function properly.

By mastering APEX$ID, APEX$I, and APEX$META, you can greatly improve how your reports, cards, and custom UI elements behave and appear—especially in dynamic or responsive layouts that rely on precise control over element attributes.

Overview of Special Data Substitutions

APEX$ID:

This substitution holds the identity of the record.
It is typically used to reference the record’s primary key or unique identifier.
You can retrieve the Record ID from model#getRecordId.

APEX$I:

This represents the 1-based index of the current record in the loop.
Useful for generating row numbers, applying row-specific styles, or displaying dynamic content that depends on the record position.

APEX$META:

This is an object containing metadata about the current record.
The object includes several properties that provide information about the record's state, validation, selected status, and more. These properties are:

valid: Whether the record is valid (Y) or has errors/warnings (N).
state: The state of the record (O, D, I, U, or empty).
allowedOperations: Determines if the record is editable (Update/Delete).
selected: Whether the record is selected (Y or N).
agg: The name of the aggregate record (e.g., "SUM").
highlight: The highlight name applied to the record.
endControlBreak: Indicates if this is the end of a control break.
grandTotal: Indicates if this is a grand total for the aggregate.
errorMessage: The error message if applicable.
warningMessage: The warning message if applicable.

Step 1: Loop Syntax with APEX$ID, APEX$I, and APEX$META

The general structure for using APEX$ID, APEX$I, and APEX$META in a loop looks like this:

{loop ["SEP"] NAME/}

Record ID: {APEX$ID}

Record Index: {APEX$I}

Metadata - State: {APEX$META.state}

Metadata - Valid: {APEX$META.valid}

{endloop/}

{loop ["SEP"] NAME/}: Starts the loop through a collection or set of data named NAME. The separator SEP is used between items (if needed).
{APEX$ID}: Displays the identity (primary key) of the current record.
{APEX$I}: Displays the 1-based index of the current record in the loop.
{APEX$META.state}: Displays the state of the current record (e.g., "I" for inserted, "U" for updated).

Step 2: Example 1 — Displaying Record ID and Index

Let's say you have a list of records and want to display the record ID and its position in the list.

Scenario:

You have a collection of products, and you want to display the product's record ID and the position (index) of the product in the list.

Create a Static Content Region.
Use the following HTML expression:

{loop ["SEP"] :P1_PRODUCTS/}

Product #{APEX$I} - Record ID: {APEX$ID}

{endloop/}

Explanation:

:P1_PRODUCTS is the collection of products (could be a page item or a result set).
{APEX$I}: Displays the position of the current product in the loop.
{APEX$ID}: Displays the unique record ID for the current product.

Expected Output:

For a list of products like:

Product 1 with ID 101
Product 2 with ID 102
Product 3 with ID 103

The output will look like this:

Product #1 - Record ID: 101

Product #2 - Record ID: 102

Product #3 - Record ID: 103

Step 3: Example 2 — Using APEX$META to Display Record Status

Scenario:

You want to show the status of each record, including whether it is new (inserted), updated, or deleted. You will also use the valid property to indicate whether the record is valid or has errors.

Use the following HTML expression:

{loop ["SEP"] :P1_RECORDS/}

Record ID: {APEX$ID}

Index: {APEX$I}

State: {APEX$META.state}

Valid: {APEX$META.valid}

Selected: {APEX$META.selected}

Errors: {APEX$META.errorMessage}

{endloop/}

Explanation:

{APEX$META.state}: Displays the state of the record (O, D, I, U, or empty string).
{APEX$META.valid}: Indicates if the record is valid ("Y" for valid, "N" for invalid).
{APEX$META.selected}: Displays if the record is selected.
{APEX$META.errorMessage}: Displays the error message if one exists.

Expected Output:

For records with different states, the output could look like this:

Record ID: 101

Index: 1

State: I (Inserted)

Valid: Y

Selected: N

Errors:

Record ID: 102

Index: 2

State: U (Updated)

Valid: N

Selected: Y

Errors: Missing value in required field

Record ID: 103

Index: 3

State: D (Deleted)

Valid: Y

Selected: N

Errors:

Step 4: Example 3 — Highlighting Specific Records Based on Metadata

Scenario:

You want to highlight certain records, such as aggregate records, records with errors, or selected records, by using different background colors.

Use the following HTML expression:

{loop ["SEP"] :P1_RECORDS/}

Record ID: {APEX$ID}

Index: {APEX$I}

State: {APEX$META.state}

Valid: {APEX$META.valid}

</div>

{endloop/}

Explanation:

If the record is selected, the background color will be yellow (#FFEB3B).
If the record has an error message, the background will be light red (#FFCDD2).
Otherwise, the background color will be white (#FFFFFF).

Expected Output:

For selected records and those with errors, the output might look like this:

Record ID: 101

Index: 1

State: I

Valid: Y

</div>

Record ID: 102

Index: 2

State: U

Valid: N

</div>

Record ID: 103

Index: 3

State: D

Valid: Y

</div>

Step 5: Example 4 — Aggregating Data Using APEX$META.agg

Scenario:

You have a collection that includes aggregate records (e.g., sum, average), and you want to display them separately from normal records.

Use the following HTML expression:

{loop ["SEP"] :P1_AGGREGATES/}

{if APEX$META.agg != ''}

{APEX$META.agg} Aggregation: {APEX$ID} - {APEX$I}

{else}

Record ID: {APEX$ID} - Index: {APEX$I}

{/if}

{endloop/}

Explanation:

The loop checks if the aggregate name (APEX$META.agg) is non-empty, meaning it's an aggregate record.
If it's an aggregate, it shows the aggregation type (e.g., "SUM", "AVG").
Otherwise, it displays normal records.

Expected Output:

SUM Aggregation: 104 - 1

Record ID: 102 - Index: 2

Record ID: 103 - Index: 3

Conclusion:
By integrating APEX$ID, APEX$I, and APEX$META into your custom report templates, you gain precise control over how each row of data is rendered in Oracle APEX. These variables help manage dynamic identifiers, conditional formatting, and context-aware behavior in your components, ensuring your applications are both functional and visually effective. As you continue building complex interfaces, mastering these tools will streamline your development process and lead to more maintainable, scalable APEX solutions.

APEX Field Notes

Search This Blog

Tuesday, July 1, 2025

How to Use APEX$ID, APEX$I, and APEX$META In ORACLE APEX

Building your very first application with ORACLE APEX