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

 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

1. 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.

2. 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.

3. 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.

1. Create a Static Content Region.

2. Use the following HTML expression:

{loop ["SEP"] :P1_PRODUCTS/}

    <p>Product #{APEX$I} - Record ID: {APEX$ID}</p>

{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.

1. Use the following HTML expression:

{loop ["SEP"] :P1_RECORDS/}

    <p>Record ID: {APEX$ID}</p>

    <p>Index: {APEX$I}</p>

    <p>State: {APEX$META.state}</p>

    <p>Valid: {APEX$META.valid}</p>

    <p>Selected: {APEX$META.selected}</p>

    <p>Errors: {APEX$META.errorMessage}</p>

{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.

1. Use the following HTML expression:

{loop ["SEP"] :P1_RECORDS/}

    <div style="background-color: {if APEX$META.selected = 'Y'}#FFEB3B{elsif APEX$META.errorMessage != ''}#FFCDD2{else}#FFFFFF{/if}">

        <p>Record ID: {APEX$ID}</p>

        <p>Index: {APEX$I}</p>

        <p>State: {APEX$META.state}</p>

        <p>Valid: {APEX$META.valid}</p>

    </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:

<div style="background-color: #FFEB3B;">

    <p>Record ID: 101</p>

    <p>Index: 1</p>

    <p>State: I</p>

    <p>Valid: Y</p>

</div>

<div style="background-color: #FFCDD2;">

    <p>Record ID: 102</p>

    <p>Index: 2</p>

    <p>State: U</p>

    <p>Valid: N</p>

</div>

<div style="background-color: #FFFFFF;">

    <p>Record ID: 103</p>

    <p>Index: 3</p>

    <p>State: D</p>

    <p>Valid: Y</p>

</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.

1. Use the following HTML expression:

{loop ["SEP"] :P1_AGGREGATES/}

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

        <p><strong>{APEX$META.agg} Aggregation:</strong> {APEX$ID} - {APEX$I}</p>

    {else}

        <p>Record ID: {APEX$ID} - Index: {APEX$I}</p>

    {/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:

<strong>SUM Aggregation:</strong> 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.

How to Use APEX$ITEM and APEX$I Within Loop Directives in Oracle APEX

Introduction
In Oracle APEX, Loop Directives provide a dynamic way to render HTML blocks for each row in a SQL query result. When customizing report templates—especially for Classic Reports and Card Reports—APEX offers special built-in variables like APEX$ITEM and APEX$I that can be used within {loop} and {endloop} blocks. These variables enhance the flexibility of your templates by allowing item-level referencing and row-specific behaviors. By learning how to use APEX$ITEM and APEX$I, developers can create interactive, cleanly structured, and efficient user interfaces with custom logic and formatting for each record.

In Oracle APEX, when you're working with custom templates—particularly in Card Reports or Classic Reports—you can use Loop Directives to repeat content for each row returned by a SQL query. Within these loop blocks, APEX provides built-in substitution variables that enhance the template’s flexibility. Two of the most commonly used are APEX$ITEM and APEX$I.

APEX$ITEM is used to reference the value of a specific column in the SQL query result. For example, if your SQL query includes a column named EMPLOYEE_NAME, you can access it inside your template like this: #APEX$ITEM.EMPLOYEE_NAME#. This renders the value of EMPLOYEE_NAME for each row.

APEX$I is a built-in loop index variable that returns the current row’s index in the iteration. It starts at 1 for the first record and increments for each row. This is useful when you need to generate dynamic IDs or CSS class names that are unique per record. For example, to create a unique ID for each card element, you can use: id="card_#APEX$I#".

To implement this in a Loop Directive, you would use the following structure inside your report’s HTML Expression or Template Text:

{loop}
  <div id="card_#APEX$I#" class="employee-card">
    <h3>#APEX$ITEM.EMPLOYEE_NAME#</h3>
    <p>Department: #APEX$ITEM.DEPARTMENT#</p>
    <p>Email: #APEX$ITEM.EMAIL#</p>
  </div>
{endloop}

Here, {loop} starts the iteration for each row, and {endloop} ends it. Between these tags, you can place any HTML structure and reference your columns dynamically using APEX$ITEM. The APEX$I is especially helpful for debugging, alternating styles (like zebra stripes), or uniquely identifying DOM elements for use with JavaScript or CSS.

Using these directives and variables together, you can build rich, data-driven layouts that are scalable and maintainable. It's a clean and powerful way to separate your presentation logic from your SQL data source while giving you full control over how each record is rendered.

Example

In Oracle APEX, when working with loop directives, two special data substitutions — APEX$ITEM and APEX$I — are available to make your loop content even more dynamic and flexible.

• APEX$ITEM: This is the value of the current item in the loop.

• APEX$I: This is the 1-based index of the current item in the list, which represents the position of the item in the iteration.

These substitutions can be used to manipulate and display dynamic data more effectively. You can use APEX$ITEM for accessing individual items and APEX$I for tracking the position within the loop, such as for adding dynamic numbering, styles, or labels.

Step 1: Basic Understanding of the Loop Syntax

A typical loop directive with APEX$ITEM and APEX$I would look something like this:

{loop [SEP] NAME/}

    <!-- Displaying each item -->

    Item #{APEX$I}: {APEX$ITEM}

{endloop/}

• {loop [SEP] NAME/}: Starts the loop over a collection named NAME, with a separator SEP between items.

• {APEX$I}: Displays the 1-based index (position) of the current item in the loop.

• {APEX$ITEM}: Displays the actual value of the current item in the loop.

• {endloop/}: Ends the loop.

Step 2: Example 1 — Displaying a List with Index and Value

Scenario:

You have a list of items such as product names and you want to display them in a numbered list with their respective positions.

Steps:

1. Create a Page Item or Collection: Assume you have a page item :P1_PRODUCT_LIST containing the list of product names:

• Product A

• Product B

• Product C

2. Create a Static Content Region.

3. Use the following HTML expression:

{loop [", "] :P1_PRODUCT_LIST/}

    <p>Item #{APEX$I}: {APEX$ITEM}</p>

{endloop/}

Explanation:

• The :P1_PRODUCT_LIST contains the list of product names.

• The {APEX$I} represents the index of the current item in the list (1, 2, 3, etc.).

• The {APEX$ITEM} represents the value of the current item (e.g., "Product A").

Expected Output:

Item #1: Product A

Item #2: Product B

Item #3: Product C

Step 3: Example 2 — Styling Items Based on Index Using APEX$I

Scenario:

You want to apply different styles to each item based on its position. For instance, the first item should be bold, the second should be italic, and the rest should have a normal style.

Steps:

1. Use the following HTML expression in the Static Content Region:

{loop [", "] :P1_PRODUCT_LIST/}

    {if APEX$I = 1}

        <p style="font-weight: bold;">Item #{APEX$I}: {APEX$ITEM}</p>

    {elsif APEX$I = 2}

        <p style="font-style: italic;">Item #{APEX$I}: {APEX$ITEM}</p>

    {else}

        <p>Item #{APEX$I}: {APEX$ITEM}</p>

    {/if}

{endloop/}

Explanation:

• The loop will iterate over the items in :P1_PRODUCT_LIST.

• APEX$I is used to check the position of the current item.

• Depending on the value of APEX$I, different styles are applied:

• Bold for the first item (APEX$I = 1).

• Italic for the second item (APEX$I = 2).

• Normal style for all other items.

Expected Output:

Item #1: Product A (in bold)

Item #2: Product B (in italic)

Item #3: Product C (normal style)

Step 4: Example 3 — Generating a List with Custom Separator Using APEX$ITEM

Scenario:

You want to display the list of products in a single line, separated by a custom separator (e.g., a hyphen -), but without adding the separator at the end.

Steps:

1. Create a Static Content Region.

2. Use the following HTML expression:

{loop [" - "] :P1_PRODUCT_LIST/}

    {APEX$ITEM}

{endloop/}

Explanation:

• The loop will iterate through the items in :P1_PRODUCT_LIST.

• [" - "] is the separator that will be inserted between each item, but it won't be added after the last item.

• {APEX$ITEM} will display the value of the current item in the list.

Expected Output:

Product A - Product B - Product C

Step 5: Example 4 — Displaying a Product List with Item Numbers and Values

Scenario:

You want to display each product in the list with its corresponding item number and product value.

Steps:

1. Create a Static Content Region.

2. Use the following HTML expression:

{loop [", "] :P1_PRODUCT_LIST/}

    <p>Item #{APEX$I}: {APEX$ITEM}</p>

{endloop/}

Explanation:

• {APEX$I} will output the item index (e.g., 1, 2, 3).

• {APEX$ITEM} will output the corresponding product name (e.g., "Product A", "Product B", etc.).

Expected Output:

Item #1: Product A

Item #2: Product B

Item #3: Product C

Step 6: Example 5 — Using Loops to Create a Table with Index and Item Values

Scenario:

You want to display a list of products in an HTML table format, with a column for the item number and a column for the item value.

Steps:

1. Use the following HTML expression:

<table border="1">

    <thead>

        <tr>

            <th>Item Number</th>

            <th>Product Name</th>

        </tr>

    </thead>

    <tbody>

        {loop [", "] :P1_PRODUCT_LIST/}

            <tr>

                <td>{APEX$I}</td>

                <td>{APEX$ITEM}</td>

            </tr>

        {endloop/}

    </tbody>

</table>

Explanation:

• The loop iterates over the :P1_PRODUCT_LIST page item.

• {APEX$I} is used to display the 1-based index (item number).

• {APEX$ITEM} is used to display the actual product name.

Expected Output:

<table border="1">

    <thead>

        <tr>

            <th>Item Number</th>

            <th>Product Name</th>

        </tr>

    </thead>

    <tbody>

        <tr>

            <td>1</td>

            <td>Product A</td>

        </tr>

        <tr>

            <td>2</td>

            <td>Product B</td>

        </tr>

        <tr>

            <td>3</td>

            <td>Product C</td>

        </tr>

    </tbody>

</table>

• APEX$ITEM allows you to access the value of the current item in the loop.

• APEX$I provides the 1-based index of the current item, which can be used for dynamic numbering, conditional formatting, and more.

These features are essential when you need to display or manipulate dynamic data within a loop, providing you with the flexibility to create sophisticated user interfaces with ease.

Conclusion

Using APEX$ITEM and APEX$I within Loop Directives opens the door to advanced customization and interactivity in Oracle APEX reports. Whether you're building interactive card displays, applying row-based logic, or generating unique identifiers for UI components, these built-in variables provide the control needed for polished, user-friendly applications. Mastering them enables APEX developers to move beyond static templates and deliver smart, scalable report layouts that meet both design and functional requirements.