apex.item

The apex.item API provides a single interface for item related functionality of Application Express. This API returns an Application Express item object, which can then be used to access item related functions and properties. Item objects can apply to either page items or column items. 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 of the region.

apex.item

This 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.item.create with their overrides.

Parameters

Table 38-11 Parameters for pNd

Name Type Description

pNd

DOM Node | String

Application Express item name or DOM node. This parameter can refer to either a page item or column item.

Returns

Returns the Application Express item object, which is used to access item specific functions. For example getValue, setValue, and so on.

Examples

This will not be used by itself, rather it is used to access item specific functions and properties, as documented in the following APIs

See Also:

"apex.item.create"

addValue

Adds a value to an Application Express item that supports multiple values.

Parameters

Table 38-12 Parameters for addValue

Name Type Description

pValue

String

The value to be added.

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') ;

disable

Disables the Application Express item value, taking into account the item type, making it unavailable for edit.

Parameters

None.

Examples

In this example, the page item called P1_ITEM will be disabled and unavailable for edit.

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

displayValueFor

Returns the display value corresponding to the value given by pValue for the Application Express item. 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.

Parameters

Table 38-13 Parameters displayValueFor

Name Type Description

pValue

String

A valid value for this item.

Returns

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

Example

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

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

enable

Enables the Application Express item value, taking into account the item type, making it available for edit.

Parameters

None.

Examples

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

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

getValidity

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

Parameters

None.

Returns

A ValidityState object as described above.

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 ) {
    alert( "Error: " + item.getValidationMessage() );
}

getValidationMessage

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 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

None.

Returns

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

Example

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

getValue

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.

Parameters

None.

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 'Allow Multi Selection' set to ' Yes' or 'Shuttle' native item types).

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()  );

hide

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.

  • 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.

Parameters

Table 38-14 Parameters for hide

Name Type Description

pHideRow

Boolean

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').

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);

isChanged

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 Changes feature can support their plug-in.

Parameters

None.

Returns

true if the current value has changed and false otherwise.

Examples

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

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

isDisabled

Returns the disabled state of an item

Parameters

None.

Returns

true if the Application Express item is disabled andfalse otherwise.

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

Returns true or false if an 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 defined in the List of Values. In that case, the 'Null Return Value' is used to assert if the item is empty.

Parameters

None.

Returns

true if the Application Express item is empty and false otherwise.

Examples

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()  ) {
  alert( "P1_ITEM empty!" );
}

Item Object Properties

An item object returned from apex.item has the properties given in the following table.

Parameters

Table 38-15 Item Object Properties

Name Description

id

The id property of an Application Express item provides the id of the item DOM element.

node

The node property of an Application Express item provides the DOM element of the item. If the item is invalid then the value is false.

Example

The following code checks if the Application Express 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 );
}

setFocus

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

Parameters

None.

Examples

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

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

setStyle

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

Parameters

Table 38-16 Parameters for setStyle

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

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().

Parameters

Table 38-17 Parameters for setValue

Name Type Description

pValue

String | Array

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.

pDisplayValue

String

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.

pSuppressChangeEvent

Boolean

This parameter is optional. The default if not specified is false. Pass true to prevent thechange 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 );

show

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.

  • 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.

Parameters

Table 38-18 Parameters for show

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 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);

apex.item.create

This function is only for item plug-in developers. It provides a plug-in specific implementation for the item. This is necessary to seamlessly integrate a plug-in item type with the built-in item related client-side functionality of Application Express.

Parameters

Table 38-19 apex.item.create Parameters

Name Type Description

pName

DOM Node|String

Application Express page item name or DOM node. This parameter can refer to either a page item or column item.

pItemImpl

Object

An object with properties that provide any functions needed to customize the Application Express item object behavior. The object returned by apex.item has default implementations for each of its functions that are appropriate for many page items particularly for items that use standard form elements. For each function of apex.item you should check if the default handling is appropriate for your item plug-in. If it isn't you can provide your own implementation of the corresponding function through this pItemImpl object. The default behavior is used for any functions omitted.

pItemImpl can contain any of the following properties:

  • displayValueFor( pValue )

  • enable()

  • getPopupSelector()

  • getValidity()

  • getValue()

  • setValue( pValue, pDisplayValue )

  • disable()

  • show()

  • hide()

  • isChanged()

  • isDisabled()

  • addValue()

  • nullValue()

  • setFocusTo

  • setStyleTo

  • afterModify()

  • loadingIndicator( pLoadingIndicator$ )

Table 38-20 Properties for the pItemImpl parameter

Name Description

displayValueFor( pValue )

Specify a function that returns a string display value that corresponds to the given pValue.

enable()

Specify a function for enabling the item, which overrides the default page item handling. This could be useful for example where the item consists of compound elements which also need enabling, or if the item is based on a widget that already has its own enable method that you want to reuse. Ensuring the item can enable correctly means certain item related client-side functionality of Application Express still works, for example when using the Enable action of a Dynamic Actions, to enable the item.

Note: Even if this function is defined, the default handling always handles the logic associated with the .afterModify() function, so that is outside the scope of what a plug-in developer is concerned with.

See the "enable," for details on how to define this function.

getPopupSelector()

Specify a function that returns a CSS selector that locates the popup used by the item. Any plug-in item type that uses a popup (a div added near the end of the document that is positioned near the input item and floating above it) needs to provide a CSS selector that locates the top level element of the popup. This allows the item type to be used in the Interactive Grid region or any other region that needs to coordinate focus with the popup. The default implementation returns null.

In addition the top level popup element must be focusable (have attribute tabindex = -1).

For best behavior of a popup in the Interactive Grid. The popup should:

  • have a way of taking focus

  • close on escape when it has focus

  • close when the element it is attached to looses focus

  • return focus to the element that opened the popup when it closes

  • manage its tab stops so they cycle in the popup or return to the element that opened the popup at the ends

getValidity()

Specify a function that returns a validity object. The returned object must at a minimum have the Boolean valid property. It may include any of the properties defined for the HTML5 ValidityState object. The default implementation returns the validity object of the item element if there is one otherwise it returns { valid: true }.

See the"getValidity" or details on how to define this function.

getValue()

Specify a function for getting the item's value, which overrides the default page item handling. Ensuring the item returns its value correctly means certain item related client-side functionality of Application Express still works, for example in Dynamic Actions to evaluate a When condition on the item, or when calling the JavaScript function $v to get the item's value.

See "getValue," for details on how to define this function.

setValue( pValue, pDisplayValue )

Specify a function for setting the item's value, which overrides the default page item handling. Ensuring the item can set its value correctly means certain item related client-side functionality of Application Express still works, for example when using the Set Value action of a Dynamic Action to set the item's value, or when calling the JavaScript function $s to set the item's value.

Note: Even if this function is defined, the default handling always handles the logic associated with the .afterModify() function and the pSuppressChangeEvent parameter, so that is outside the scope of what a plug-in developer is concerned with.

See the "setValue," for details on how to define this function.

disable()

Specify a function for disabling the item, which overrides the default page item handling. This could be useful for example where the item consists of compound elements which also need disabling, or if the item is based on a widget that already has its own disable method that you want to reuse. Ensuring the item can disable correctly means certain item related client-side functionality of Application Express still works, for example when using the Disable action of a Dynamic Action to disable the item.

Note: Even if this function is defined, the default handling always handles the logic associated with the .afterModify() function, so that is outside the scope of what a plug-in developer is concerned with.

See the "disable," for details on how to define this function.

show()

Specify a function for showing the item, which overrides the default page item handling. This is useful for example where the item consists of compound elements which also need showing, or if the item is based on a widget that already has its own show method that you want to reuse. Ensuring the item can show correctly means certain item related client-side functionality of Application Express still works, for example when using the Show action of a Dynamic Action, to show the item.

See the "show," for details on how to define this function.

hide()

Specify a function for hiding the item, which overrides the default page item handling. This could be useful for example where the item consists of compound elements which also needs hiding, or if the item is based on a widget that already has its own hide method that you want to reuse. Ensuring the item can hide correctly means certain item related client-side functionality of Application Express still works, for example when using the Hide action of a Dynamic Action, to hide the item.

See the "hide," for details on how this function should be defined.

isChanged()

Specify a function that returns true if the current value of the item has changed and false otherwise. This function allows the Warn on Unsaved Changes feature to work. The default implementation uses built-in functionality of HTML form elements to detect changes. If this function does not work correctly then changes to the plug-in item type value will not be detect and the user will not be warned when they leave the page.

See the "isChanged" for details on how this function should be defined.

isDisabled()

Specify a function that returns true if the item is disabled and false otherwise.

addValue()

Specify a function for adding a value to the item, where the item supports multiple values. Currently there is no client-side functionality of Application Express dependent on this. There is also no default page item handling.

Note: Even if this function is defined, the default handling always handles the logic associated with the .afterModify() function, so that is outside the scope of what a plug-in developer is concerned with.

See the "addValue," for details on how this function should be defined.

nullValue

Specify a value that to be used to determine if the item is null. This is used when the item supports definition of a List of Values, where a developer can define a Null Return Value for the item and where the default item handling needs to know this in order to assert if the item is null or empty. This can be done by following these steps:

  1. From the Render function in the plug-in definition, emit the value stored in p_item.lov_null_value as part of the item initialization JavaScript code that fires when the page loads. For example:

    /* Assumes that you have some JavaScript function called 'com_your_company_your_item' that accepts 2 parameters, the first being the name of the item and the second being an object storing properties (say pOptions) required by the item's client side code. */
    apex_javascript.add_onload_code (
        p_code => 'com_your_company_your_item('||
                   apex_javascript.add_value(
                       apex_plugin_util.page_item_names_to_jquery(p_item.name)||', {'||
                           apex_javascript.add_attribute('lovNullValue', p_item.lov_null_value, false, false)||
                   '});' );
  2. Then, in the implementation of com_your_company_your_item( pName, pOptions ) you have the value defined for the specific item's Null Return Value in the pOptions.lovNullValue property. This can then be used in your call to apex.widget.initPageItem, to set the nullValue property.

    Ensuring the nullValue property is set means certain item related client-side functionality of Application Express still works, for example, in Dynamic Actions to correctly evaluate an is null or is not null when condition on the item, or when calling the JavaScript function apex.item( pNd ).isEmpty() to determine if the item is null.

    See the "isEmpty," for further details of this API.

setFocusTo

Specify the element to receive focus, when focus is set to the item using the apex.item( pNd ).setFocus() API. This can be defined as either a jQuery selector, jQuery or DOM object which identifies the DOM element, or a function that returns a jQuery object referencing the element. This can be useful when the item consists of compound elements, and you do not want focus to go to the element that has an ID matching the item name, which is the default behavior. For example, the native item type Popup LOV when the attribute Input Field is set to Not enterable, Show Display Value and Store Return Value renders a disabled input field as the main element with an ID matching the item name and a popup selection icon next to the input. In this case, because you do not want focus to go to the disabled input, use the setFocusTo item property and set that to the popup selection icon.

Ensuring the item sets focus correctly means certain item related client-side functionality of Application Express still works, for example when using the Set Focus action of a Dynamic Action to set focus to the item, when users follow the Go to Error link that displays in a validation error message to go straight to the associated item, or when the item is the first item on a page and the developer has the page level attribute Cursor Focus set to First item on page.

See the "setFocus," for further details of this API.

setStyleTo

Specify the element to receive style, when style is set to the item using the apex.item( pNd ).setStyle() API. This can be defined as either a jQuery selector, jQuery- or DOM object which identifies the DOM element(s), or a function that returns a jQuery object referencing the element(s). This is useful when the item consists of compound elements, and you do not want style to be set to the element or just the element, that has an ID matching the item name which is the default behavior. Ensuring the item sets style correctly means certain item related client-side functionality of Application Express still works, for example when using the Set Style action of a Dynamic Action to add style to the item.

Note: Even if this property is defined, the default handling still always handles the logic associated with the .afterModify() function, so that is outside the scope of what a plug-in developer is concerned with.

See the apex.item( pNd ).setStyle() documentation, for further details of this API.

afterModify()

Specify a function that is called after an item is modified. This is useful, for example as some frameworks such as jQuery Mobile need to be notified if widgets are modified, for example their value has been set, or they have been disabled in order to keep both the native and enhanced controls in sync. This callback provides the hook to do so.

loadingIndicator( pLoadingIndicator$ )

Specify a function that normalizes how the item's loading indicator is displayed during a partial page refresh of the item. This function must pass the pLoadingIndicator$ parameter as the first parameter, which contains a jQuery object with a reference to the DOM element for the loading indicator. The function then adds this loading indicator to the appropriate DOM element on the page for the item, and also returns the jQuery object reference to the loading indicator, such that the framework has a reference to it, so it can remove it once the call is complete.

This is used, for example, if the item is a Cascading LOV and the Cascading LOV Parent Item changes, or when setting the item's value by using one of the server-side Dynamic Actions such as Set Value - SQL Statement.

Example

The following example shows a call to apex.item.create( pNd, pItemImpl ) with all the available callbacks and properties passed. It is unlikely that any plug-in needs to supply every callback and property. This is just to illustrate the syntax.

apex.item.create( "P100_COMPANY_NAME", {
     displayValueFor: function( pValue ) {
        var lDisplayValue;
        // code to determine the display value for pValue
        return lDisplayValue;
    },
     enable: function() {
         // code that enables the item type
     },
     getPopupSelector: function() {
         return "<some CSS selector>";
    },
     getValidity: function() {
         var lValidity = { valid: true };
         if ( /* item is not valid */ ) {
             lValidity.valid = false;
         }
         return lValidity;
     },
     getValue: function() {
         var lValue;
         // code to determine lValue based on the item type.
         return lValue;
     },
     setValue: function( pValue, pDisplayValue ) {
        // code that sets pValue and pDisplayValue (if required), for the item type
     },
     disable: function() {
        // code that disables the item type
     },
     show: function() {
         // code that shows the item type
     },
     hide: function() {
         // code that hides the item type
     },
     isChanged: function() {
         var lChanged;
         // code to determine if the value has changed
         return lChanged;
     },
     addValue: function( pValue ) {
         // code that adds pValue to the values already in the item type
     },
     nullValue: "<null return value for the item>",
     setFocusTo: $( "<some jQuery selector>" ),
     setStyleTo: $( "<some jQuery selector>" ),
     afterModify: function(){
         // code to always fire after the item has been modified (value set, enabled, etc.)
     },
     loadingIndicator: function( pLoadingIndicator$ ){
         // code to add the loading indicator in the best place for the item
         return pLoadingIndicator$;
     }
});