apex.widget namespace

Use the apex.widget namespace to store all the general purpose widget related functions of Oracle Application Express.

Topics:

apex.widget.initPageItem( pName, pOptions)

apex.widget.initPageItem( pName, pOptions)

Given the Application Express page item name or the DOM node, different callbacks and properties can be registered for a page item. This is necessary to seamlessly integrate a plug-in item type with the built-in page item related client-side functionality of Application Express.

For more information about implementing plug-ins, see "Implementing Plug-ins" in Oracle Application Express Application Builder User's Guide:

For samples authored by Oracle, see the plug-in repository, on OTN:

http://apex.oracle.com/plugins

Return Values

None.

Parameters

Table 23-16 describes the available parameters for this function.

Table 23-16 Parameters for apex.widget.initPageItem( pName, pOptions )

Name Type Optional/ Required Default Description

Name	Type	Optional/ Required	Default	Description
`pName`	(DOM Node\|String)	Required		Application Express page item name or DOM node.
`pOptions`	(Object)	Required (individual properties are optional)		Supports many properties to specify callbacks and certain item-specific values. Specifying any of these properties will override the default behavior of Application Express for that particular property. See Table 23-17 for `pOption` property details. `pOptions` can contain one of the following properties: `getValue()` `setValue( pValue, pDisplayValue )` `enable()` `disable()` `show()` `hide()` `addValue()` `nullValue()` `setFocusTo` `setStyleTo` `afterModify()` `loadingIndicator( pLoadingIndicator$ )`

pName

(DOM Node|String)

Required

Application Express page item name or DOM node.

pOptions

(Object)

Required (individual properties are optional)

Supports many properties to specify callbacks and certain item-specific values. Specifying any of these properties will override the default behavior of Application Express for that particular property.

See Table 23-17 for pOption property details.

pOptions can contain one of the following properties:

getValue()
setValue( pValue, pDisplayValue )
enable()
disable()
show()
hide()
addValue()
nullValue()
setFocusTo
setStyleTo
afterModify()
loadingIndicator( pLoadingIndicator$ )

Table 23-17 Properties for the pOptions parameter

Name	Description
`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 "apex.item( pNd ).getValue()", for details on how to define this function. Note: You should first check if the default handling of Application Express works for the item, because in that case you do not need to specify this. You can check by calling `apex.item( pNd ).getValue();` to see if that returns the item value correctly.
`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 "apex.item( pNd ).setValue(pValue, pDisplayValue, pSuppressChangeEvent)", for details on how to define this function. Note: You should first check if the default handling of Application Express works for the item, because in that case you do not need to specify this. You can check by calling `apex.item( pNd ).setValue( pValue );` to see if that sets the item value correctly.
`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 "apex.item( pNd ).enable()", for details on how to define this function. Note: You should first check if the default handling of Application Express works for the item, because in that case you do not need to specify this. You can check by calling `apex.item( pNd ).enable();` to see if that enables the item satisfactorily.
`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 "apex.item( pNd ).disable()", for details on how to define this function. Note: You should first check if the default handling of Application Express works for the item, because in that case you do not need to specify this. You can check by calling `apex.item( pNd ).disable();` to see if that disables the item satisfactorily.
`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 "apex.item( pNd ).show( pShowRow )", for details on how to define this function. Note: You should first check if the default handling of Application Express works for the item, because in that case you do not need to specify this. You can check by calling `apex.item( pNd ).show();` to see if that shows the item satisfactorily.
`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 "apex.item( pNd ).hide( pHideRow)", for details on how this function should be defined. Note: You should first check if the default handling of Application Express works for the item, because in that case you do not need to specify this. You can check by calling `apex.item( pNd ).hide();` to see if that hides the item satisfactorily.
`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 "apex.item( pNd ).addValue( pValue )", 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: 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)\|\| '});' ); 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 "apex.item( pNd ).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 "apex.item( pNd ).setFocus()", for further details of this API. Note: You should first check if the default handling of Application Express works for the item, because in that case you do not need to specify this. You can check this by adding the item as the first item on a page, where the page has the page attribute `Cursor Focus` set to `First item on page`, and then running the page. The item receives focus.
`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. Note: You should first check if the default handling of Application Express works for the item, because in that case you do not need to specify this. You can check by calling `apex.item( pNd ).setStyle( pPropertyName, pPropertyValue );` to see if the item correctly sets the style.
`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`.

Examples

The following example shows a call to apex.widget.initPageItem with all the available callbacks and properties passed.

apex.widget.initPageItem( "P100_COMPANY_NAME", {
    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
    },
    enable:     function() {
        // code that enables 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
    },
    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$;
    }
});