APEX Field Notes: 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/}

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:

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

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

{loop [", "] :P1_PRODUCT_LIST/}

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

Use the following HTML expression in the Static Content Region:

{loop [", "] :P1_PRODUCT_LIST/}

{if APEX$I = 1}

{elsif APEX$I = 2}

{else}

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

Create a Static Content Region.
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:

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

{loop [", "] :P1_PRODUCT_LIST/}

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

Use the following HTML expression:

<thead>

<tr>

<th>Item Number</th>

<th>Product Name</th>

</tr>

</thead>

<tbody>

{loop [", "] :P1_PRODUCT_LIST/}

<tr>

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

<thead>

<tr>

<th>Item Number</th>

<th>Product Name</th>

</tr>

</thead>

<tbody>

<tr>

<td>Product A</td>

</tr>

<tr>

<td>Product B</td>

</tr>

<tr>

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

APEX Field Notes

Search This Blog

Tuesday, July 1, 2025

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

Building your very first application with ORACLE APEX