Skip to Main Content

# Interface: item

## QuickNav

## item

The item interface is used to access methods and properties of an Oracle APEX item including item plug-ins. You get access to the item interface for a page or column item with the apex.item function.

An item interface can apply to either a page item or column item. Page items are items on the page backed by session state in any region. Column items are created by region types such as Interactive Grid that support editable columns. The state of a column item, including its value, changes according to the editing context (active record) of the region and is typically backed by data in an Oracle APEX model.

Plug-in developers can define the behavior of their item by calling apex.item.create.

### Properties

#### element :jQuery

The jQuery object for this item element. If the item doesn't exist then it is the empty jQuery object $(). This is primarily for plug-in developers.

##### Type:

- jQuery

##### Example

Get option element after initialization.

    var value = apex.item( "P1_ITEM" ).element;

#### id :string|false

The id of the DOM element of the item. If the item doesn't exist, and is not a column within a trigger action context, then the value is false.

##### Type:

- string | false

##### Example

Get option id after initialization.

    var value = apex.item( "P1_ITEM" ).id;

#### item_type :string

A string that identifies the type of the item.

##### Type:

- string

##### Example

Get option item_type after initialization.

    var value = apex.item( "P1_ITEM" ).item_type;

#### node :Element|false

The DOM element that best represents the value of the Oracle APEX item. If the item doesn't exist then the value is false.

##### Type:

- Element | false

##### Example

The following code checks if the Oracle APEX item P1_OPTIONAL_ITEM exists before setting its value. Use code similar to this if there is a possibility of the item not existing.

    var item = apex.item( "P1_OPTIONAL_ITEM" );
    if ( item.node ) {
        item.setValue( newValue );
    }

#### value :string|Array

A shorthand for getting and setting page item values. This autogenerated property is based on item#getValue and item#setValue.

Note that you can pass other parameters using item#setValue such as `pDisplayValue` and `pSuppressChange`, which is not possible via `.value`.

Note: this is not supported for getting and setting column values within a trigger action context.

##### Type:

- string | Array

Since:
  - 21.2

##### Examples

Getting a page item value:

    var empno = apex.item( "P1_EMPNO" ).getValue();
    // is equivalent to:
    var empno = apex.item( "P1_EMPNO" ).value;
    // is equivalent to:
    var empno = apex.items.P1_EMPNO.value;

Setting a page item value:

    apex.item( "P1_EMPNO" ).setValue( "100" );
    // is equivalent to:
    apex.item( "P1_EMPNO" ).value = "100";
    // is equivalent to:
    apex.items.P1_EMPNO.value = "100";

### Methods

#### addValue(pValue, pDisplayValueopt)

Adds the given value to the current list of values of an item that supports multiple values. Not all multivalued items support this method.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pValue` | string |  | The value to be added.
`pDisplayValue` | string | <optional> | The display value, only if different from pValue and can't be determined by the item itself. Not all multivalued items that support addValue will support this parameter.

##### Example

In this example, the page item called P1_ITEM will have the value 100 added to the current list of values.

    apex.item( "P1_ITEM" ).addValue( "100" );

#### disable()

Disables the Oracle APEX item, making it unavailable for editing. Not all items support being disabled. This only applies to items that can be edited. See also item#enable.

##### Example

In this example, the page item named P1_ITEM will be disabled and unavailable for editing.

    apex.item( "P1_ITEM" ).disable();

#### displayValueFor(pValue, pState) → {string}

Returns the display value corresponding to the value given by pValue for the Oracle APEX item. This method is intended for items that have both a value and display value, such as select lists.

If the item type does not have a display value distinct from the value then `pValue` is returned; meaning that the value is the display value. For item types that have a display value but don't have access to all possible values and display values then this function only works when `pValue` is the current value of the item. For the native items, this only applies to item type Popup LOV. For item types such as select lists that have access to all their values, if `pValue` is not a valid value then `pValue` is returned.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pValue` | string | Array | The value to return the corresponding display value. For items which support multiple values such as a 'Shuttle' or 'Select List' with attribute 'Allow Multi Selection' set to 'Yes', `pValue` may be passed as an array of values. The return value is always a string with multiple values separated by a comma and space (", ").
`pState` | object | Optional parameter used when items are associated with a model column to provide state information about the item value. Most item types don't use this parameter. It is mostly useful to item types that include markup in the returned display value. ###### Properties
Name | Type | Description
--- | --- | ---
`readonly` | boolean | If true the column value is readonly.
`disabled` | boolean | If true the column value is disabled.

Since:
  - 5.1

##### Returns:

The string display value corresponding to the given `pValue` as described above.

Type
  string

##### Example

This example gets a display value from a select list item called P1_ITEM and displays it in an alert.

    apex.message.alert( "The correct answer is: " + apex.item( "P1_ITEM" ).displayValueFor( "APPLES" ) );

#### enable()

Enables the Oracle APEX item value that has been disabled, making it available for editing. Not all items support being disabled. This only applies to items that can be edited. See also item#disable.

##### Example

In this example, the page item called P1_ITEM will be enabled and available for edit.

    apex.item( "P1_ITEM" ).enable();

#### getMultiValueStorage() → {object|null}

Returns the storage object of a multivalued item. This object has the properties `type` and `separator`.

Valid values for `type` are "separated" or "json-array". See `storageType` in apex.item.create for more information.

The property `separator` is only available when `type` is "separated". See `separator` in apex.item.create for more information.

The function returns null when the storage type is not applicable (as it is for items that don't support multiple values).

Since:
  - 24.1

##### Returns:

object describing storage of multiple values.

Type
  object | null

##### Example

The following example creates a multivalued item and calls "getMultiValueStorage" function.

    apex.item.create( "P1_ITEM", {
       storageType: "separated",
       separator: "~"
    } );

    const multiValueStorage = apex.item( "P1_ITEM" ).getMultiValueStorage(); // returns { type: "separated", separator: "~" }

#### getSeparator() → {string|null}

Returns the separator used by a multivalued item. It returns null when the separator is not applicable (as it is for items that don't support multiple values) or cannot be customized, in which case the default of ":" is used. See also item#getMultiValueStorage.

Since:
  - 24.1

##### Returns:

separator character used to separate multiple values. The separator is set when item is created.

Type
  string | null

##### Example

The following example creates a multivalued item and calls "getSeparator" function.

    apex.item.create( "P1_ITEM", {
       storageType: "separated",
       separator: "~"
    } );

    const separator = apex.item( "P1_ITEM" ).getSeparator(); // returns "~"

#### getValidationMessage(pLabelopt) → {string}

Return a validation message if the Oracle APEX item is not valid and empty string otherwise.

The message comes from the element's validationMessage property. An APEX extension allows specifying a custom message, which overrides the element's validationMessage, by adding a custom attribute named data-valid-message. If the item has this attribute then its value is returned if the item is not valid. As the name implies, the text of the message should describe what is expected of valid input, rather than what went wrong.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pLabel` | string | <optional> | Optional label to use in the message if the message contains a #LABEL# placeholder. This parameter is not often needed because in general the label for an item can be determined automatically.

Since:
  - 5.1

##### Returns:

A validation message, if the item is not valid and empty string otherwise.

Type
  string

##### Example

See the example for item#getValidity for an example of this function.

#### getValidity() → {object}

Return a ValidityState object as defined by the HTML5 constraint validation API for the Oracle APEX item. If a plug-in item implements its own validation then the object may not contain all the fields defined by HTML5. At a minimum it must have the valid property. If the item doesn't support HTML5 validation then it is assumed to be valid.

This function does not actually validate the item value. For many item types the browser can do the validation automatically if you add HTML5 constraint attributes such as pattern. Validation can be done using the HTML5 constraint validation API.

Developers rarely have a need to call this function. It is used internally by the client side validation feature. Item plug-in developers should ensure this function works with their plug-in.

Since:
  - 5.1

##### Returns:

A ValidityState object as described above.

Type
  object

##### Example

The following example displays a message in an alert dialog if the item called P1_ITEM is not valid.

    var item = apex.item( "P1_ITEM" );
    if ( !item.getValidity().valid ) {
        apex.message.alert( "Error: " + item.getValidationMessage() );
    }

#### getValue() → {string|Array}

Returns the current value of an Oracle APEX item. The initial value of a page item comes from session state when the server renders the page. The initial value of a column item comes from the corresponding field value of the active record of the Oracle APEX model. This function always returns the current value of the item, which may have been changed by the user or with the item#setValue method since it was initialized.

There are two shorthand functions related to `getValue`. The $v function that returns an item's value as a string. This will either be a single value, or if the item supports multiple values, will be a ':' colon separated list of values. Note this does not make use of the configurable separator or storage type for multivalued items. The $v2 function, which is just a shortcut to getValue and returns either a single value, or an array of values. See also item#setValue.

##### Returns:

Returns either a single string value or array of string values if the item supports multiple values (for example the 'Select List' with attribute 'Multiple Values : Type' not equal to 'No' or 'Shuttle' native item types).

Type
  string | Array

##### Example

In this example, the current value of the page item called P1_ITEM will be shown in an alert.

    apex.message.alert( "P1_ITEM value = " + apex.item( "P1_ITEM" ).getValue() );

#### hasDisplayValue() → {boolean}

Returns true or false if an Oracle APEX item has any currently displayed value e.g. the placeholder is shown. Note: This is not concerned with the true item value (that is the job of isEmpty()), this is more about whether there is currently anything displayed within the item. It is absolutely recommended to implement this interface for LOV-based item plug-ins, to ensure accurate results are returned when null values are used.

Since:
  - 22.1

##### Returns:

true if the Oracle APEX item has any displayed value.

Type
  boolean

##### Example

In this example, the call to .hasDisplayValue() determines if the page item called P1_ITEM has any display value, and if so displays an alert.

    if ( apex.item( "P1_ITEM" ).hasDisplayValue() ) {
        apex.message.alert( "P1_ITEM has a display value!" );
    }

#### hide(pHideRowopt)

Hides the Oracle APEX item. When using the hide function, it is important to understand the following:

- If the item being hidden is rendered on a page using table layout (meaning the page references a page template with Grid Layout Type set to 'HTML Table'), and the call to hide has specified to hide the entire table row (`pHideRow` = true), then it is assumed that everything pertaining to the item is contained in that row, and the entire row will be hidden.
- If the item being hidden is rendered on a page using table layout, and the call to hide has specified not to hide the entire table row (`pHideRow` = false, or not passed), then the function will attempt to hide the item's label, where the `for` attribute matches the `id` of the item.
- If the item being hidden is rendered on a page using grid layout (meaning the page references a page template with Grid Layout Type set to either 'Fixed Number of Columns', or 'Variable Number of Columns'), and the item references a Label template that includes a Field Container element with a known `id` (so where the Field Container > Before Label and Item attribute includes an HTML element with id="#CURRENT_ITEM_CONTAINER_ID#"), then it is assumed that everything pertaining to the item is contained in the Field Container, and this will be hidden.
- If the item is a column item then just the column value is hidden. The exact behavior depends on the type of region. For example in Interactive Grid just the cell content is hidden not the whole column.

See also item#show.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pHideRow` | boolean | <optional> | This parameter is deprecated. This parameter is optional. The default value is false. If true, hides the nearest containing table row (TR). This parameter is not supported for column items. Its behavior is undefined. Only applicable when item is on a page using table layout (meaning the page references a page template with Grid Layout Type set to 'HTML Table').

##### Example

In this example, the page item called P1_ITEM will be hidden. If P1_ITEM is on a page using grid layout and the item references a Label template that includes a Field Container element with a known ID (as detailed above), then that container element will be hidden. Otherwise just the item and its corresponding label will be hidden.

    apex.item( "P1_ITEM" ).hide();

#### isChanged() → {boolean}

Determine if the value of this item has changed since it was first initialized. Return true if the current value of the Oracle APEX item has changed and false otherwise. Developers rarely have a need to call this function. It is used internally by the Warn on Unsaved Changes feature. Item Plug-in developers should ensure this function works so that the Warn on Unsaved Changes feature can support their plug-in.

Since:
  - 5.1

##### Returns:

true if the item value has changed and false otherwise.

Type
  boolean

##### Example

The following example determines if the value of item P1_ITEM has been changed.

    if ( apex.item( "P1_ITEM" ).isChanged() ) {
        // do something
    }

#### isDisabled() → {boolean}

Returns the disabled state of an item.

Since:
  - 5.1

##### Returns:

true if the item is disabled and false otherwise.

Type
  boolean

##### Example

This example gets the value of an item, but only if it is not disabled.

    var value = null;
    if ( !apex.item( "P1_ITEM" ).isDisabled() ) {
        value = apex.item( "P1_ITEM" ).getValue();
    }

#### isEmpty() → {boolean}

Returns true or false if an Oracle APEX item is empty and considers any item value consisting of only whitespace including space, tab, or form-feed, as empty. This also respects if the item type uses a List of Values, and a 'Null Return Value' has been defined in the List of Values. In that case, the 'Null Return Value' is used to assert if the item is empty. If you really want to know if something is displayed inside the item, you should use hasDisplayValue().

##### Returns:

true if the Oracle APEX item is empty and false otherwise.

Type
  boolean

##### Example

In this example, the call to .isEmpty() determines if the page item called P1_ITEM is empty, and if so displays an alert.

    if ( apex.item( "P1_ITEM" ).isEmpty() ) {
        apex.message.alert( "P1_ITEM empty!" );
    }

#### isReady() → {boolean}

Returns true if the item is fully ready to use and false otherwise. This function is only applicable to items that take extra time to load. For example items that are implemented by libraries that load asynchronously including JET or other libraries that use RequireJS. For most items this will always return true. In addition, it is only useful for code that runs as, or soon after, the page loads. It is not needed in code called from dynamic actions because all dynamic action page load processing waits until after all items are loaded.

See also item#whenReady and the `delayLoading` property of apex.item.create.

Since:
  - 21.2

##### Returns:

Type
  boolean

##### Example

This example checks that a delayLoading item is ready before getting its value and uses a default string if it is not ready.

    var value = "waiting...",
        theItem = apex.item( "P1_DATE1" );
    if ( theItem.isReady() ) {
        value = theItem.getValue();
    }

#### refresh()

Call to refresh the item. What it means for an item to be refreshed depends on the item. Not all items support refresh. Typically, an item such as a select list that has a list of options will refresh the available options from the server. In most cases it is not necessary to call this method directly because the declarative Cascading LOV Parent Items takes care of it automatically.

##### Example

The following example will cause the P1_ITEM select list page item to fetch its options from the server.

    apex.item( "P1_ITEM" ).refresh();

#### removeValue(pValueopt)

Removes the given value from the current list of values of an item that supports multiple values. Not all multivalued items support this method.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pValue` | string | <optional> | The value to be removed. The behavior when no value is given is item specific. For example, it may remove the currently selected or focused item or items or may do nothing at all.

##### Example

In this example, the page item called P1_ITEM will have the value 100 removed from the current list of values.

    apex.item( "P1_ITEM" ).removeValue( "100" );

#### setFocus()

Places user focus on the Oracle APEX item, taking into account how specific items are designed to receive focus.

##### Example

In this example, user focus is set to the page item named P1_ITEM.

    apex.item( "P1_ITEM" ).setFocus();

#### setStyle(pPropertyName, pPropertyValue)

Sets a style for the Oracle APEX item, taking into account how specific items are designed to be styled.

Note: Using setStyle is not a best practice. It is better to add or remove CSS classes and use CSS rules to control the style of items. Also keep in mind that the exact markup of native and plug-in items can change from one release to the next.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pPropertyName` | string | The CSS property name that will be set.
`pPropertyValue` | string | The value used to set the CSS property.

##### Example

In this example, the CSS property color will be set to red for the page item called P1_ITEM.

    apex.item( "P1_ITEM" ).setStyle( "color", "red" );

#### setValue(pValue, pDisplayValueopt, pSuppressChangeEventopt)

Sets the Oracle APEX item value. This function sets the current value of the item. For page items the session state is not affected until the page is submitted (or the item is explicitly saved to the server using ajax or a dynamic action). For column items the region such as Interactive Grid takes care of writing the value back to the Oracle APEX model when appropriate.

Normally a change event is explicitly triggered on the item node when the value is set. This allows cascading LOV functionality and dynamic action change events to work. The caller may suppress the change event for the item being set, if needed. The change event should be suppressed when the value is set while processing a change event triggered on the same item, to prevent an infinite loop. The grid widget relies on the change event to update the model. If you suppress the change event on a column item you may need to call the grid#setActiveRecordValue method.

There is a shorthand function for setValue $s. See also item#getValue.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pValue` | string | Array.<string> |  | The value to set. For items that support multiple values (for example a 'Shuttle'), an array of string values can be passed to set multiple values at once.
`pDisplayValue` | string | <optional> | The display value, only if different from pValue and can't be determined by the item itself. For example, for the item type Popup LOV when the display value and return value are different, this parameter sets the display value while the `pValue` parameter sets the hidden return value.
`pSuppressChangeEvent` | boolean | <optional> | Pass true to prevent the change event from being triggered for the item being set. The default is false.

##### Examples

In this example, the value of the page item called P1_ITEM will be set to 10. As `pSuppressChangeEvent` has not been passed, the default behavior of the `change` event triggering for P1_ITEM will occur.

    apex.item( "P1_ITEM" ).setValue( "10" );

In this example, P1_ITEM is a Popup LOV page item with distinct display and return values. The display value of P1_ITEM will be set to SALES, and the hidden return value will be set to 10. Because true has been passed for the `pSuppressChangeEvent` parameter, the `change` event will not trigger for the P1_ITEM item.

    apex.item( "P1_ITEM" ).setValue( "10", "SALES", true );

This example shows how to suppress the change event when there is no display value.

    apex.item( "P1_ITEM" ).setValue( "10", null, true );

#### show(pShowRowopt)

Shows the Oracle APEX item. When using the show function, it is important to understand the following:

- If the item being shown is rendered on a page using table layout (meaning the page references a page template with Grid Layout Type set to 'HTML Table'), and the call to show has specified to show the entire table row (`pShowRow` = true), then it is assumed that everything pertaining to the item is contained in that row, and the entire row will be shown.
- If the item being shown is rendered on a page using table layout, and the call to show has specified not to show the entire table row (`pShowRow` = false, or not passed), then the function will attempt to show the item's label, where the `for` attribute matches the `id` of the item.
- If the item being shown is rendered on a page using grid layout (meaning the page references a page template with Grid Layout Type set to either 'Fixed Number of Columns', or 'Variable Number of Columns'), and the item references a Label template that includes a Field Container element with a known `id` (so where the Field Container > Before Label and Item attribute includes an HTML element with id="#CURRENT_ITEM_CONTAINER_ID#"), then it is assumed that everything pertaining to the item is contained in the Field Container, and this will be shown.
- If the item is a column item then just the column value is shown. The exact behavior depends on the type of region. For example, in Interactive Grid just the cell content is shown not the whole column.

See also item#hide.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pShowRow` | boolean | <optional> | This parameter is deprecated. This parameter is optional. The default if not specified is false. If true, shows the nearest containing table row (TR). This parameter is not supported for column items. Its behavior is undefined. Only applicable when item is on a page using table layout (meaning the page references a page template with Grid Layout Type set to 'HTML Table').

##### Example

In this example, the page item called P1_ITEM will be shown. If P1_ITEM is on a page using grid layout and the item references a Label template that includes a Field Container element with a known ID (as detailed above), then that container element will be shown. Otherwise just the item and its corresponding label will be shown.

    apex.item( "P1_ITEM" ).show();

#### whenReady() → {Promise}

Returns a promise that is resolved when the item is fully ready to use. This function is only applicable to items that take extra time to load. For example items that are implemented by libraries that load asynchronously including JET or other libraries that use RequireJS. Items that are not delay loaded do not have this method. In addition, it is only useful for code that runs as, or soon after, the page loads. It is not needed in code called from dynamic actions because all dynamic action page load processing waits until after all items are loaded.

See also item#isReady and the `delayLoading` property of apex.item.create.

Since:
  - 21.2

##### Returns:

Type
  Promise

##### Example

This example sets the value of an item after it is loaded.

    var theItem = apex.item( "P1_ITEM" );
    theItem.whenReady().then( function() {
        theItem.setValue( "Some Value" );
    } );