Interface: item

The id of the DOM element of the item. If the item doesn't exist then the value is false.

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

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

Adds the given value to the current list of values of an Oracle Application Express item that supports multiple values.

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

Disables the Oracle Application Express 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.

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

Returns the display value corresponding to the value given by pValue for the Oracle Application Express 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, with the attribute Input Field = "Not Enterable, Show Display Value and Store Return Value". 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.

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

Enables the Oracle Application Express 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.

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

Return a validation message if the Oracle Application Express 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.

Return a ValidityState object as defined by the HTML5 constraint validation API for the Oracle Application Express 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.

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

Returns the current value of an Oracle Application Express 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 Application Express 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 in the string format it will be sent to the server. This will either be a single value, or if the item supports multiple values, will be a ':' colon separated list of values. 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.

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

Hides the Oracle Application Express 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.

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

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

Determine if the value of this item has changed since it was first initialized. Return true if the current value of the Oracle Application Express 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.

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

Returns the disabled state of an item.

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

Returns true or false if an Oracle Application Express 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 ( apex.item( "P1_ITEM" ).isEmpty() ) {
    apex.message.alert( "P1_ITEM empty!" );
}

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

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

Sets a style for the Oracle Application Express 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.

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

Sets the Oracle Application Express 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 Application Express 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.

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

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

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

Shows the Oracle Application Express 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.

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

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