Pre-General Availability: 2018-3-9
QuickNav
Properties
- id
- node
Methods
- addValue
- disable
- displayValueFor
- enable
- getValidationMessage
- getValidity
- getValue
- hide
- isChanged
- isDisabled
- isEmpty
- setFocus
- setStyle
- setValue
- show
item
The item interface is used to access methods and properties of an Application Express item.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 Application Express model.
Plug-in developers can define the behavior of their item by calling apex.item.create.
Properties
(static) id :string|false
The id of the DOM element of the item. If the item doesn't exist then the value is false.
Type:
- string|false
(static) node :Element|false
The DOM element that best represents the value of the Application Express item. If the item doesn't existthen the value is false.
Type:
- Element|false
Example
The following code checks if the Application Express itemP1_OPTIONAL_ITEM exists before setting its value. Use code similar to thisif there is a possibility of the item not existing.
var item = apex.item( "P1_OPTIONAL_ITEM" );if ( item.node ) { item.setValue( newValue );}Methods
(static) addValue(pValue)
Adds the given value to the current list of values of an Application Express item that supports multiplevalues.
Parameters:
| Name | Type | Description |
|---|---|---|
pValue | string | The value to be added. |
Example
In this example, the page item called P1_ITEM will have the value 100 added to the valuescurrently selected.
apex.item( "P1_ITEM" ).addValue("100");(static) disable()
Disables the 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.
Example
In this example, the page item named P1_ITEM will be disabled and unavailable for edit.
apex.item( "P1_ITEM" ).disable();(static) displayValueFor(pValue) → {string}
Returns the display value corresponding to the value given by pValue for the 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 accessto 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.
Parameters:
| Name | Type | Description |
|---|---|---|
pValue | string | The value to return the corresponding display value. |
- 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 displaysit in an alert.
apex.message.alert( "The correct answer is: " + apex.item( "P1_ITEM" ).displayValueFor( "APPLES" ) );(static) enable()
Enables the 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.
Example
In this example, the page item called P1_ITEM will be enabled and available for edit.
apex.item( "P1_ITEM" ).enable();(static) getValidationMessage() → {string}
Return a validation message if the Application Express item is not valid and empty string otherwise.
The message comes from the element's validationMessage property. An APEX extension allows specifying acustom message, which overrides the element's validationMessage, by adding a custom attribute nameddata-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 thanwhat went wrong.
- 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.
(static) getValidity() → {object}
Return a ValidityState object as defined by the HTML5 constraint validation API for theApplication Express item. If a plug-in item implements its own validation then the object may not containall the fields defined by HTML5. At a minimum it must have the valid property. If the item doesn't supportHTML5 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 thevalidation automatically if you add HTML5 constraint attributes such as pattern. Validation can be doneusing the HTML5 constraint validation API.
Developers rarely have a need to call this function. It is used internally by the client side validationfeature. 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() );}(static) getValue() → {string|Array}
Returns the current value of an Application Express item. The initial value of a page item comes fromsession state when the server renders the page. The initial value of a column item comes from thecorresponding field value of the active record of the Application Express model. This functionalways returns the current value of the item, which may have been changed by the user or with the item.setValuemethod since it was initialized.
There are two shorthand functions related to getValue. The $v function that returns an item's value in the string formatit will be posted. This will either be a single value, or if the item supports multiple values, will bea ':' colon separated list of values. The $v2 function, which is just a shortcutto 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 itemsupports multiple values (for example the 'Select List' with attribute 'Allow Multi Selection' set to ' Yes'or 'Shuttle' native item types).
- Type
- string|Array
(static) hide(pHideRow)
Hides the 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 pagetemplate with Grid Layout Type set to 'HTML Table'), and the call to hide has specified to hide the entiretable row (pHideRow = true), then it is assumed that everything pertaining to the item is contained in thatrow, 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 specifiednot to hide the entire table row (pHideRow = false, or not passed), then the function will attempt to hidethe 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 pagetemplate 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 thiswill be hidden.
- If the item is a column item then just the column value is hidden. The exact behavior depends on thetype of region. For example in Interactive Grid just the cell content is hidden not the whole column.
See also item.show.
Parameters:
| Name | Type | Description |
|---|---|---|
pHideRow | boolean | This parameter is optional. The default value is false. If true, hides thenearest 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 thepage 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 aField 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) willbe hidden (as pHideRow = true). Hiding the entire table row should only be used on a page usingtable layout. If P1_ITEM is on a page using grid layout, then passing pHideRow = true will not work andcould result in adverse consequence for the page layout, where an incorrect table row is wrongly hidden.
apex.item( "P1_ITEM" ).hide( true );(static) isChanged() → {boolean}
Determine if the value of this item has changed since it was first initialized.Return true if the current value of the 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 Changesfeature 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}(static) 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();}(static) isEmpty() → {boolean}
Returns true or false if an Application Express item is empty and considers any item value consisting ofonly 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 defined in the Listof Values. In that case, the 'Null Return Value' is used to assert if the item is empty.
Returns:
true if the Application Express item is empty and false otherwise.
- Type
- boolean
Example
In this example, the call to .isEmpty() determines if the page item calledP1_ITEM is empty, and if so displays an alert.
if ( apex.item( "P1_ITEM" ).isEmpty() ) { apex.message.alert( "P1_ITEM empty!" );}(static) setFocus()
Places user focus on the Application Express 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();(static) setStyle(pPropertyName, pPropertyValue)
Sets a style for the Application Express item, taking into account how specific items aredesigned to be styled.
Note:
Using setStyle is not a best practice. It is better to add or remove CSS classes and use CSS rules tocontrol the style of items. Also keep in mind that the exact markup of native and plug-in items canchange 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" );(static) setValue(pValue, pDisplayValueopt, pSuppressChangeEventopt)
Sets the Application Express item value. This function sets the current value of theitem. For page items the session state is not affected until the page is submitted (or the itemis explicitly saved to the server using ajax or a dynamic action). For column items the regionsuch as Interactive Grid takes care of writing the value back to the Application Express modelwhen appropriate.
Normally a change event is explicitly triggered on the item node when the value is set. This allowscascading 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 besuppressed when the value is set while processing a change event triggered on the same item to preventan infinite loop.
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, with the attribute Input Field = 'Not Enterable, Show Display Value and Store Return Value', this value sets the Input Field display value. The value of pValue is used to set the item's hidden return field. |
pSuppressChangeEvent | boolean | <optional> | Pass true to prevent the change event from being triggered for the item being set. The default is false. |
(static) show(pShowRow)
Shows the 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 pagetemplate with Grid Layout Type set to 'HTML Table'), and the call to show has specified to show the entiretable row (pShowRow = true), then it is assumed that everything pertaining to the item is contained in thatrow, 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 specifiednot to show the entire table row (pShowRow = false, or not passed), then the function will attempt to showthe 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 pagetemplate 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 withid="#CURRENT_ITEM_CONTAINER_ID#"), then it is assumed that everything pertaining to the item is containedin 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 thetype of region. For example in Interactive Grid just the cell content is shown not the whole column.
See also item.hide.
Parameters:
| Name | Type | Description |
|---|---|---|
pShowRow | boolean | 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'). |
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 FieldContainer 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 resultin adverse consequence for the page layout, where an incorrect table row is wrongly shown.
apex.item( "P1_ITEM" ).show( true );