Using apex.item in Oracle APEX to Get and Set Item Values

Managing page items is something you'll do constantly when building Oracle APEX applications. Whether you're reading user input, updating fields dynamically, or controlling form behavior, you need a reliable way to interact with page items. That's exactly what the apex.item API provides.

In this tutorial, I'll show you how to use apex.item to get and set values, work with different item types, and handle common scenarios you'll encounter. By the end, you'll be comfortable manipulating page item values in your APEX applications.

Understanding apex.item

The apex.item API is your primary tool for interacting with page items through JavaScript. It works with all APEX item types, from simple text fields to complex components like shuttles and select lists. What makes it powerful is that it understands APEX's item structure, unlike plain JavaScript or jQuery which might miss important details.

When you use apex.item, APEX handles the heavy lifting. It knows whether your item is a checkbox, a date picker, or a radio group, and it interacts with each one correctly. This saves you from writing conditional code for different item types.

The Syntax of apex.item

Before we dive into examples, let's understand the basic syntax. The apex.item function takes one parameter: the item name. You don't include the hash symbol that you might use in CSS selectors.

For getting values, the syntax is:

apex.item('ITEM_NAME').getValue()

For setting values, the syntax is:

apex.item('ITEM_NAME').setValue(value, displayValue, suppressChangeEvent)

The setValue method accepts three parameters. The first parameter is the value you want to set (required). The second parameter is the display value for items that show one thing but save another, like select lists (optional). The third parameter is a boolean that controls whether the change event fires (optional, defaults to false).

Now that you understand the syntax, let's look at practical examples.

Getting Item Values in Oracle APEX using apex.item

Let's start with the most basic operation, reading a value from a page item. Here's how you do it:

var employeeName = apex.item('P1_EMPLOYEE_NAME').getValue();
console.log('Employee Name: ' + employeeName);

This code gets the value from the item P1_EMPLOYEE_NAME. The getValue() method returns the current value as a string. You can then use this value in calculations, validations, or send it to the server through Ajax calls.

For items that can have multiple values, like a shuttle or multi-select list, you'll get an array:

var selectedDepartments = apex.item('P1_DEPARTMENTS').getValue();
console.log(selectedDepartments);

if (selectedDepartments.length > 0) {
    console.log('First department: ' + selectedDepartments[0]);
    console.log('Total selected: ' + selectedDepartments.length);
}

This is important to remember. Single-value items return strings, multi-value items return arrays. I've debugged many issues that boiled down to not checking which type I was working with. Always consider what kind of item you're working with before processing the value.

Setting Item Values in Oracle APEX using apex.item

Setting values is just as straightforward. Use the setValue() method with the value you want to assign:

apex.item('P1_SALARY').setValue('50000');

This sets the salary field to 50000. But here's something crucial: when you use setValue(), APEX triggers the change event automatically by default. This means any Dynamic Actions listening for changes will fire, cascading LOVs will refresh, and validations will run. It's as if the user typed the value themselves.

For multi-value items, pass an array:

apex.item('P1_SKILLS').setValue(['JAVA', 'PYTHON', 'SQL']);

This sets the shuttle or multi-select list to have three selected values. The array should contain the return values of the items you want selected.

Sometimes you want to set a value without triggering events. Maybe you're initializing the page or preventing infinite loops in your Dynamic Actions. Use the suppress parameter:

apex.item('P1_TOTAL').setValue('1500', null, true);

That third parameter (true) suppresses the change event. The middle parameter is null here because we're not setting a display value. When you suppress the event, APEX updates the item silently without notifying any listeners.

Working with Display and Return Values

Some APEX items have two values: what the user sees (display value) and what gets saved (return value). Select lists and popup LOVs work this way. You can set both at once:

apex.item('P1_EMPLOYEE').setValue('100', 'John Smith');

Here, '100' is the employee ID that gets saved, and 'John Smith' is what appears on screen. This is particularly useful when you're populating items from Ajax calls where you already know both values.

Let me give you a real-world scenario. Suppose you're building a form where selecting a customer should populate their email address. First, create an Ajax Callback process named GET_CUSTOMER_EMAIL in your APEX page:

DECLARE
    l_email VARCHAR2(100);
BEGIN
    SELECT email
    INTO l_email
    FROM customers
    WHERE customer_id = apex_application.g_x01;
    
    apex_json.open_object;
    apex_json.write('email', l_email);
    apex_json.close_object;
EXCEPTION
    WHEN NO_DATA_FOUND THEN
        apex_json.open_object;
        apex_json.write('email', '');
        apex_json.close_object;
END;

This PL/SQL process receives the customer ID through apex_application.g_x01, looks up the email address, and returns it as JSON. Now you can call this process and set the email field with the JavaScript code:

apex.server.process('GET_CUSTOMER_EMAIL', {
    x01: apex.item('P1_CUSTOMER_ID').getValue()
}, {
    success: function(data) {
        apex.item('P1_EMAIL').setValue(data.email);
    }
});

This gets the selected customer ID using getValue(), sends it to the server, and when the response comes back, it sets the email field using setValue(). The change event will fire, so if you have validations or other Dynamic Actions on the email field, they'll execute automatically.

Practical Examples of Getting and Setting Values in APEX

Let me show you some common patterns I use in my projects. Here's how you might calculate a total based on quantity and price:

var quantity = apex.item('P1_QUANTITY').getValue();
var price = apex.item('P1_PRICE').getValue();

// Convert strings to numbers for calculation
var total = parseFloat(quantity) * parseFloat(price);

// Set the total, rounded to 2 decimal places
apex.item('P1_TOTAL').setValue(total.toFixed(2));

Remember that getValue() always returns a string, even for number fields. You need to convert it to a number before doing math. I use parseFloat() for decimal numbers and parseInt() for whole numbers.

Here's another common scenario, copying values from one item to another:

var billingAddress = apex.item('P1_BILLING_ADDRESS').getValue();
var billingCity = apex.item('P1_BILLING_CITY').getValue();
var billingZip = apex.item('P1_BILLING_ZIP').getValue();

apex.item('P1_SHIPPING_ADDRESS').setValue(billingAddress);
apex.item('P1_SHIPPING_CITY').setValue(billingCity);
apex.item('P1_SHIPPING_ZIP').setValue(billingZip);

This copies billing address information to shipping address fields when a user indicates they're the same. Each setValue() call triggers change events, so any dependent items or validations will update accordingly.

Building Complex Validations

You can combine getting and setting values to create sophisticated validations. Here's an example that ensures a discount percentage doesn't exceed the maximum allowed:

var discount = parseFloat(apex.item('P1_DISCOUNT_PERCENT').getValue());
var maxDiscount = 25;

if (discount > maxDiscount) {
    apex.message.showErrors([{
        type: 'error',
        message: 'Discount cannot exceed ' + maxDiscount + '%',
        location: 'inline',
        pageItem: 'P1_DISCOUNT_PERCENT'
    }]);
    
    // Reset to maximum allowed
    apex.item('P1_DISCOUNT_PERCENT').setValue(maxDiscount.toString());
    return false;
}

This gets the discount value, checks if it exceeds the maximum, shows an error if it does, and resets it to the maximum allowed value. The validation happens instantly as users interact with the form.

Tips from My Experience

After working with apex.item on numerous projects, I've picked up some habits that save time and prevent bugs. Always use apex.item instead of direct jQuery or JavaScript DOM manipulation. It might seem like overkill for simple text fields, but when your text field becomes a date picker or autocomplete later, your code keeps working without changes.

When you're setting values from Ajax callbacks, consider whether you want the change event to fire. If you're initializing multiple fields, suppress the events until the last field to avoid triggering cascading updates multiple times:

apex.item('P1_FIELD1').setValue(value1, null, true);
apex.item('P1_FIELD2').setValue(value2, null, true);
apex.item('P1_FIELD3').setValue(value3); // Let this one trigger events

Also, remember that getValue() returns a string for single-value items. If you're comparing values, be careful with type coercion:

var status = apex.item('P1_STATUS').getValue();

// Good: string comparison
if (status === 'ACTIVE') {
    // Do something
}

// Be careful with numbers
var count = apex.item('P1_COUNT').getValue();
if (parseInt(count) > 0) { // Convert to number first
    // Do something
}

Bringing It All Together

The apex.item API is your gateway to creating dynamic, interactive Oracle APEX applications. You've learned the syntax for getting and setting values, how to work with single and multi-value items, handle display and return values separately, and control when change events fire. These are the building blocks you'll use in almost every APEX application you build.