This is the APEX page item namespace. This namespace holds all single item functions. These functions assume that these are APEX generated page items.
Topics:
The apex.item API provides a single interface for item related functionality of Application Express. The API returns an Application Express item object, which can then be used to access item related functions and properties.
Plug-in developers can override much of the behavior defined in the apex.item namespace, by calling apex.widget.initPageItem with their overrides. See the documentation on "apex.widget.initPageItem( pName, pOptions) " for more details.
Return Values
Table 23-1 describes the return values for this function.
Table 23-1 Return Values for apex.item( pNd )
| Type | Description |
|---|---|
|
(Object) |
Returns the Application Express item object, which is used to access item specific functions. For example |
Parameters
Table 23-2 describes the parameters available for this function.
Table 23-2 Parameters for apex.item( pNd )
| Name | Type | Optional/ Required | Default | Description |
|---|---|---|---|---|
|
|
(DOM Node | String) |
Required |
Application Express item name or DOM node. |
Examples
This will not be used by itself, rather it is used to access item specific functions and properties, as documented in the proceeding APIs
Adds a value to an Application Express item that supports multiple values.
Return Values
None.
Parameters
Table 23-3 describes parameters available for this function.
Table 23-3 Parameters for apex.item( pNd ).addValue( pValue )
| Name | Type | Optional/ Required | Default | Description |
|---|---|---|---|---|
|
|
(String) |
Required |
The value to be set. |
Examples
In this example, the page item called 'P1_ITEM' will have the value '100' added to the values currently selected.
apex.item( "P1_ITEM" ).addValue('100') ;
Disables the Application Express item value, taking into account the item type, making it unavailable for edit.
Return Values
None.
Parameters
None.
Examples
In this example, the page item called 'P1_ITEM' will be disabled and unavailable for edit.
apex.item( "P1_ITEM" ).disable() ;
Enables the Application Express item value, taking into account the item type, making it available for edit.
Return Values
None.
Parameters
None.
Examples
In this example, the page item called 'P1_ITEM' will be enabled and available for edit.
apex.item( "P1_ITEM" ).enable() ;
Returns the current value of an Application Express item on a page, taking into account the current item type. This does not return the item's current value from session state (although that could be the same), rather it will return the value as it is on the current page.
There are 2 related functions to .getValue(). $v( pNd ) which returns an item's value, but in the format it will be posted. This will either be a single value, or if the item supports multiple values, will be a ':' colon separated list of values. There is also the $v2( pNd ) function, which is just a shortcut to .getValue() and returns either a single value, or array of values.
Return Values
Table 23-4 describes the return values for this function.
Table 23-4 Return Values for apex.item( pNd ).getValue()
| Name | Description |
|---|---|
|
(String | Array) |
Returns either a single string value or array of string values if the item supports multiple values (for example the 'Select List' with attribute 'Allow Multi Selection' set to ' Yes' or 'Shuttle' native item types). |
Parameters
None.
Examples
In this example, the current value of the page item called 'P1_ITEM' will be shown in an alert.
alert( "P1_ITEM value = " + apex.item( "P1_ITEM" ).getValue() );
Hides the Application Express item value, taking into account the item type. 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.
Return Values
None.
Parameters
Table 23-5 describes the parameters available for this function.
Table 23-5 Parameters for apex.item( pDN ).hide( pHideRow )
| Name | Type | Optional/ Required | Default | Description |
|---|---|---|---|---|
|
|
(String | Array) |
Optional |
FALSE |
If TRUE, hides the nearest containing table row (TR). 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'). |
Examples
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();
In this example, the page item called P1_ITEM's nearest containing table row (TR) will be hidden (as pHideRow = TRUE). Hiding the entire table row should only be used on a page using table layout. If P1_ITEM is on a page using grid layout, then passing pHideRow = TRUE will not work and could result in adverse consequence for the page layout, where an incorrect table row is wrongly hidden.
apex.item( "P1_ITEM" ).hide(TRUE);
Returns true or false if an Application Express item is empty and will consider any whitespace including a space, a tab or a form-feed, as empty. This will also respect 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' will be used to assert if the item is empty. In this case, the DOM node returned is the nearest ancestor of pNd that has a node name of pToTag and optionally a matching class. Also it returns false if pNd is not found or if there is no pToTag ancestor.
Return Values
Table 23-6 describes the return values for this function.
Table 23-6 Parameters for apex.item( pNd ).isEmpty()
| Type | Description |
|---|---|
|
(Boolean) |
Returns true or false if an Application Express item is empty. |
Parameters
None.
Examples
In this example, the call to .isEmpty() determines if the page item called 'P1_ITEM' is null, and if so displays an alert.
if( apex.item( "P1_ITEM" ).isEmpty() ) {
alert( "P1_ITEM empty!" );
}
Places user focus on the Application Express item, taking into account how specific items are designed to receive focus.
Return Values
None.
Parameters
None.
Examples
In this example, user focus is set to the page item called 'P1_ITEM'.
apex.item( "P1_ITEM" ).setFocus();
Sets a style for the Application Express item, taking into account how specific items are designed to be styled.
Return Values
None.
Parameters
Table 23-7 describes the parameters available for this function.
Table 23-7 Parameters for apex.item( pNd ).setStyle( pPropertyName, pPropertyValue )
| Name | Type | Optional/ Required | Default | Description |
|---|---|---|---|---|
|
|
(CSS Property Name) |
Required |
The CSS property name that will be set. |
|
|
|
(CSS Property Value) |
Required |
The value used to set the CSS property. |
Examples
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" );
Sets the Application Express item value, taking into account the item type. This function sets the current value of an Application Express item on the page, not the item's current value in session state. It also allows for the caller to suppress the 'change' event for the item being set, if desired.
See the $s( pNd, pValue, pDisplayValue, pSuppressChangeEvent ) function for a shortcut to .setValue().
Return Values
None.
Parameters
Table 23-8 describes the parameters available for this function.
Table 23-8 Parameters for apex.item (pNd ).setValue( pValue, pDisplayValue, pSuppressChangeEvent)
| Name | Type | Optional/ Required | Default | Description |
|---|---|---|---|---|
|
|
(String | Array) |
Required |
The value to be 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. |
|
|
|
(String) |
Optional |
Optional parameter used to set the page item's display value, in the case where the return value is different. For example for the item type "Popup LOV", with the attribute "Input Field" = "Not Enterable, Show Display Value and Store Return Value", this value sets the "Input Field". The value of pValue is then used to set the item's hidden return field. |
|
|
|
(Boolean) |
Optional |
FALSE |
Pass TRUE to prevent the 'change' event from being triggered, for the item being set. |
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 the attribute "Input Field" = "Not Enterable, Show Display Value and Store Return Value", set to "Input Field". The display value of P1_ITEM will be set to "SALES" and the hidden return value will be set to "10". As '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 );
Shows the Application Express item value, taking into account the item type. 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.
Return Values
None.
Parameters
Table 23-9 describes the parameters for this function.
Table 23-9 Parameters for apex.item ( pNd ).show( pShowRow )
| Name | Type | Optional/ Required | Default | Description |
|---|---|---|---|---|
|
|
(String | Array) |
Optional |
FALSE |
If TRUE, shows the nearest containing table row (TR). 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'). |
Examples
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();
In this example, the page item called P1_ITEM's nearest containing table row (TR) will be shown (as pShowRow = TRUE). Showing the entire table row should only be used on a page using table layout. If P1_ITEM is on a page using grid layout, then passing pShowRow = TRUE will not work and could result in adverse consequence for the page layout, where an incorrect table row is wrongly shown.
apex.item( "P1_ITEM" ).show(TRUE);