Skip Headers
Oracle® Application Express API Reference
Release 4.2

E35127-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to current chapter
Up
Go to next page
Next
PDF · Mobi · ePub

23 JavaScript APIs

This section describes JavaScript functions and objects included with Oracle Application Express and available on every page. You can use these functions and objects to provide client-side functionality, such as showing and hiding page elements, or making XML HTTP Asynchronous JavaScript and XML (AJAX) requests.

Note:

Legacy JavaScript. Work has commenced in attempting to reduce the overall size of JavaScript that is loaded by Application Express when rendering a page. JavaScript functions that are no longer served on every page are gradually being moved to a legacy JavaScript file, which can be found in /i/libraries/apex/legacy.js.

When developing applications, a developer has the option to either include, or not include the legacy JavaScript functions. This is achieved by using the Include Legacy JavaScript property on the User Interface Attributes page under the application's Shared Components.

Existing applications are migrated with this option enabled, for backward compatibility. To not include this legacy file, you need to go through the functions listed in the legacy file, and search your application and associated JavaScript files for any references to those files. If you are happy that there are no references to these functions, you can switch off including the legacy file and benefit from the slightly smaller library.

When developing new applications, the legacy file is included by default in all applications that use a Desktop User Interface Type. New applications that use a jQuery Mobile Smartphone User Interface Type do not include this file.

For both new and existing application development, Oracle recommends that you do not continue to use any of the functions in legacy.js, to reduce your dependency to this legacy JavaScript.

Topics:


apex namespace

Use the apex namespace to store global variables and highly used functions in Application Express.

Global Variables

  • apex.gPageContext$ - Application Express variable that stores the current page context. The current page context is different depending on whether the page is a Desktop, or jQuery Mobile page. For Desktop, this is set to the document level. For jQuery Mobile, where pages are actually represented as DIV elements in the Browser DOM and multiple page DIVs can be loaded in the Browser DOM at one time, this is set to the DIV element representing the current page.

    This is used to set the context for your jQuery selectors, to ensure that the selector is executing within the context of the correct page.

    For example:

    jQuery( ".my_class", apex.gPageContext$ );
    

    This selects all elements with a CSS class of my_class, in the context of the current page.

Topics:


apex.confirm

The apex.confirm function displays a confirmation and depending on the user's choice either submits the page, or cancels a page submit. This function has 2 signatures, as described below.

Topics:

apex.confirm(pMessage, pRequest)

Displays a confirmation showing a message, pMessage, and depending on user's choice, submits a page setting request value, pRequest, or cancels page submit.

Parameters

pMessage (string)
pRequest (string)

Example

This example shows a confirmation dialog with the text 'Delete Department'. If the user chooses to proceed with the delete, the current page is submitted with a REQUEST value of 'DELETE'

apex.confirm('Delete Department', 'DELETE');

apex.confirm(pMessage, pOptions)

Displays a confirmation showing a message (pMessage) and depending on user's choice, submits a page setting request values specified by (pOptions) or cancels page submit.

Parameters

pMessage (string)
pOptions (Object)
where pOptions can contain the following properties:
submitIfEnter - If you only want to confirm when the ENTER key has been pressed, call apex.confirm in the event callback and pass the event object as this parameter.
request - The request value to set (defaults to null)
set - Object conatining name/value pairs of items to be set on the page prior to submission(defaults to null).
showWait - Flag to control if a 'Wait Indicator' icon is displayed, which can be useful when running long page operations (Defaults to false).

Return Values

Boolean - If the submitIfEnter option is specified, a boolean value is returned. True is returned if the ENTER key was not pressed and false if the ENTER key was pressed. If submitIfEnter is not been specified, nothing is returned.

Example

This example shows a confirmation message with the 'Save Department?' text. If the user chooses to proceed with the save, the page is submitted with a REQUEST value of 'SAVE' and 2 page item values are set, P1_DEPTNO to 10 and P1_EMPNO to 5433.

apex.confirm("Save Department?", {
  request:"SAVE",
  set:{"P1_DEPTNO":10, "P1_EMPNO":5433}
  });

apex.submit

The apex.submit function submits the current page. This function has 2 signatures, as described below.

Topics:

apex.submit(pOptions)

This function submits the page using the options specified in pOptions.

Parameters

pOptions (Object)
where pOptions can contain the following properties:
submitIfEnter - If you only want to submit when the ENTER key has been pressed, call apex.submit in the event callback and pass the event object as this parameter.
request - The request value to set (defaults to null)
set - Object conatining name/value pairs of items to be set on the page prior to submission(defaults to null).
showWait - Flag to control if a 'Wait Indicator' icon is displayed, which can be useful when running long page operations (Defaults to false).

Return Values

Boolean - If the submitIfEnter option is specified, a boolean value is returned. True is returned if the ENTER key was not pressed and false if the ENTER key was pressed. If submitIfEnter is not been specified, nothing is returned.

Example

This example submits the page with a REQUEST value of 'DELETE' and 2 page item values are set, P1_DEPTNO to 10 and P1_EMPNO to 5433. During submit a wait icon is displayed as visual indicator for the user as well.

apex.submit({
  request:"DELETE",
  set:{"P1_DEPTNO":10, "P1_EMPNO":5433});

apex.submit(pRequest)

This function submits the page setting the Application Express Request value pRequest.

Parameters

pRequest (String)

Example

Submits the current page with a REQUEST value of 'DELETE'.

apex.submit( 'DELETE' );

apex.event namespace

Use the apex.event namespace to store all event related functions of Oracle Application Express.

Topics:


apex.event.trigger(pSelector,pEvent,pData)

Given a jQuery selector, jQuery object or DOM Node the specified pEvent is triggered. pEvent can be a browser event like "click" or "change" but also a custom event like "slidechange". This function should only be used to trigger events that are handled by the dynamic action framework. Otherwise, custom events registered by plug-ins installed in your application or any event that is already exposed in dynamic actions can be compromised.

Return Value

Boolean

Parameters

pSelector (jQuery selector | jQuery object | DOM Node)
pEvent (String)
pData (Object)

apex.item namespace

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:


apex.item( pNd )

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, "Return Values for apex.item( pNd )" 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 getValue, setValue, and so on.


Parameters

Table 23-2, "Parameters for apex.item( pNd )" describes the parameters available for this function.

Table 23-2 Parameters for apex.item( pNd )

Name Type Optional/Required Default Description

pNd

(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


apex.item( pNd ).addValue( pValue )

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

Return Values

None.

Parameters

Table 23-3, "Parameters for apex.item( pNd ).addValue( pValue )" describes parameters available for this function.

Table 23-3 Parameters for apex.item( pNd ).addValue( pValue )

Name Type Optional/Required Default Description

pValue

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

apex.item( pNd ).disable()

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

apex.item( pNd ).enable()

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

apex.item( pNd ).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.

Return Values

Table 23-4, "Return Values for apex.item( pNd ).getValue()" 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()  );

apex.item( pNd ).hide( pHideRow)

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, "Parameters for apex.item( pDN ).hide( pHideRow )" describes the parameters available for this function.

Table 23-5 Parameters for apex.item( pDN ).hide( pHideRow )

Name Type Optional/Required Default Description

pHideRow

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

apex.item( pNd ).isEmpty()

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, "Parameters for apex.item( pNd ).isEmpty()" 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!" );
}

apex.item( pNd ).setFocus()

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

apex.item( pNd ).setStyle( pPropertyName, pPropertyValue )

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, "Parameters for apex.item( pNd ).setStyle( pPropertyName, pPropertyValue )" describes the parameters available for this function.

Table 23-7 Parameters for apex.item( pNd ).setStyle( pPropertyName, pPropertyValue )

Name Type Optional/Required Default Description

pPropertyName

(CSS Property Name)

Required

 

The CSS property name that will be set.

pPropertyValue

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

apex.item( pNd ).setValue(pValue, pDisplayValue, pSuppressChangeEvent)

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, "Parameters for apex.item (pNd ).setValue( pValue, pDisplayValue, pSuppressChangeEvent)" 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

pValue

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

pDisplayValue

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

pSuppressChangeEvent

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

apex.item( pNd ).show( pShowRow )

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, "Parameters for apex.item ( pNd ).show( pShowRow )" describes the parameters for this function.

Table 23-9 Parameters for apex.item ( pNd ).show( pShowRow )

Name Type Optional/Required Default Description

pShowRow

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

apex.navigation namespace

Use the apex.navigation namespace to store popup and redirect related functions of Oracle Application Express.

Topics:


apex.navigation.popup.close(pThat,pValue)

Sets the value of the item in the parent window (pThat), with (pValue) and then closes the popup window.

Return Value

Not applicable.

Parameters

pValue (string)
pThat (DOM node | string ID)

apex.server namespace

Use the apex.server namespace to store all AJAX functions to communicate with the server part of Oracle Application Express.

Topics:


apex.server.plugin(pAjaxIdentifier,pData,pOptions)

This function calls the PL/SQL AJAX function which has been defined for a plug-in. This function is a wrapper of the jQuery.ajax function and supports all the settings the jQuery function provides, with additional Application Express specific features.

Parameters

Table 23-10 apex.server.plugin(pAjaxIdentifier,pData,pOptions) Parameters

Parameter Type Optional/Required Description

pAjaxIdentifier

(String)

Required

Use the value returned by the PL/SQL package apex_plugin.get_ajax_identifier to identify your plug-in.

pData

{Object}

Optional

Object which can optionally be used to send additional values to be sent with the AJAX request. The special attribute pageItems which can be of type jQuery selector, jQuery or DOM object or array of item names identifies the page items which should be included in the URL. But you can also set additional parameters that the wwv_flow.show procedure provides (for example you can set the scalar parameters x01 - x10 and the arrays f01 - f20).

pOptions

{Object}

Optional

Object which can optionally be used to set additional options used by the AJAX.

It supports the following optional Application Express specific attributes:

refreshObject - jQuery selector, jQuery- or DOM object which identifies the DOM element for which the apexbeforerefresh and apexafterrefresh events are fired.

refreshObjectData - Specify data that is internally passed by the apexbeforerefresh and apexafterrefresh event triggering code, so that any handlers defined for these events can access this data. In Dynamic Actions defined for the Before Refresh or After Refresh events, this can be accessed from JavaScript via the this.data property. For custom jQuery event handlers, this can be accessed via the pData parameter of the event handler.

clear - JavaScript function used to clear the DOM after the apexbeforerefresh event has fired and before the actual AJAX call is triggered.

loadingIndicator - jQuery selector, jQuery- or DOM object which identifies the DOM element where the loading indicator should be displayed next to it. loadingIndicator can also be a function which gets the loading Indicator as jQuery object and has to return the jQuery reference to the created loading indicator. For example:

function( pLoadingIndicator ) {
    return pLoadingIndicator.prependTo ( apex.jQuery( "td.shuttleControl", gShuttle ))
}

loadingIndicatorPosition - 4 options to define the position of the loading indicator displayed. Only considered if the value passed to loadingIndicator is not a function.

  • before: Displays before the DOM element(s) defined by loadingIndicator.

  • after: Displays after the DOM element(s) defined by loadingIndicator.

  • prepend: Displays inside at the beginning of the DOM element(s) defined by loadingIndicator.

  • append: Displays inside at the end of the DOM element(s) defined by loadingIndicator.

See Also: See jQuery documentation of jQuery.ajax for all other available attributes. The attribute dataType is defaulted to json.

http://docs.jquery.com/


Return Values

Table 23-11 Return Value

Type Description

{Object}

Retuns a jqXHR object.

See Also: See the jQuery documentation for more details on this object:

http://docs.jquery.com/


Example

This call to apex.server.plugin sets the scalar value x01 to test (which can be accessed from PL/SQL using apex_application.g_x01) and sets the page item's P1_DEPTNO and P1_EMPNO values in session state (using jQuery selector syntax). The P1_MY_LIST item is used as the element for which the apexbeforerefresh and apexafterrefresh events are fired. P1_MY_LIST is used as the element for which to display the loading indicator next to. The success callback is stubbed out and is used for developers to add their own code that fires when the call successfully returns.

The pData parameter to the success callback will contain any response sent from the call.

apex.server.plugin ( lAjaxIdentifier, {
    x01: "test",
    pageItems: "#P1_DEPTNO,#P1_EMPNO"
    }, {
    refreshObject:     "#P1_MY_LIST",
    loadingIndicator:  "#P1_MY_LIST",
    success: function( pData ) { ... do something here ... }
    } );

apex.server.pluginUrl( pAjaxIdentifier, pData )

This function returns the URL to issue a GET request to the PL/SQL AJAX function which has been defined for a plug-in.

Parameters

Table 23-12 apex.server.pluginUrl( pAjaxIdentifier, pData) Parameters

Name Type Optional/Required Default Description

pAjaxIdentifier

(String)

Required

 

Use the value returned by the PL/SQL package apex_plugin.get_ajax_identifier to identify your plug-in.

pData

{Object}

Optional

 

Object which can optionally be used to set additional values which are included into the URL. The special attribute pageItems which can be of type jQuery selector, jQuery or DOM object or array of item names identifies the page items which are included in the URL. You can also set additional parameters that the wwv_flow.show procedure provides (for example you can set the scalar parameters x01 - x10 and the arrays f01 - f20).


Return Value

Table 23-13 Return Value

Type Description

(String)

The URL to issue the GET request.


Example

This call to apex.server.pluginUrl returns a URL to issue a GET request to the PL/SQL AJAX function which has been defined for a plug-in, where the URL sets the scalar value x01 to test (which can be accessed from PL/SQL using apex_application.g_x01) and will also set the page item's P1_DEPTNO and P1_EMPNO values in session state (using jQuery selector syntax).

var lUrl;
lUrl = apex.server.pluginUrl ( pAjaxIdentifier, {
  x01: "test",
  pageItems: "#P1_DEPTNO,#P1_EMPNO" } );

apex.server.process( pAjaxIdentifier, pData, pOptions )

This function calls a PL/SQL on-demand process defined on page or application level. This function is a wrapper of the jQuery.ajax function and supports all the setting the jQuery function provides but provides additional Application Express features.

Parameters

Table 23-14 apex.server.process Parameters

Name Type Optional/Required Default Description

pAjaxIdentifier

(String)

Required

 

Use the value returned by the PL/SQL package apex_plugin.get_ajax_identifier to identify your plug-in.

pData

{Object}

Optional

 

Object which can optionally be used to send additional values to be sent with the AJAX request. The special attribute pageItems which can be of type jQuery selector, jQuery or DOM object or array of item names identifies the page items which are included in the URL. You can also set additional parameters that the wwv_flow.show procedure provides (for example you can set the scalar parameters x01 - x10 and the arrays f01 - f20).

pOptions

{Object}

Optional

 

Object which can optionally be used to set additional options used by the AJAX.

It supports the following optional Application Express specific attributes:

refreshObject - jQuery selector, jQuery- or DOM object which identifies the DOM element for which the apexbeforerefresh and apexafterrefresh events are fired.

refreshObjectData - Specify data that is internally passed by the apexbeforerefresh and apexafterrefresh event triggering code, so that any handlers defined for these events can access this data. In Dynamic Actions defined on the Before Refresh or After Refresh events, this can be accessed from JavaScript via the this.data property. For custom jQuery event handlers, this can be accessed via the pData parameter of the event handler.

clear - JavaScript function used to clear the DOM after the apexbeforerefresh event has fired and before the actual AJAX call is triggered.

loadingIndicator - jQuery selector, jQuery- or DOM object which identifies the DOM element where the loading indicator should be displayed next to it. loadingIndicator can also be a function which gets the loading Indicator as jQuery object and has to return the jQuery reference to the created loading indicator. For example:

function( pLoadingIndicator ) {
  return lLoadingIndicator.prependTo ( apex.jQuery(
"td.shuttleControl", gShuttle ))
}

loadingIndicatorPosition - 4 options to define the position of the loading indicator displayed. Only considered if the value passed to loadingIndicator is not a function.

before: Displays before the DOM element(s) defined by loadingIndicator

after: Displays after the DOM element(s) defined by loadingIndicator

prepend: Displays inside at the beginning of the DOM element(s) defined by loadingIndicator

append: Displays inside at the end of the DOM element(s) defined by loadingIndicator

See Also: See jQuery documentation of jQuery.ajax for all other available attributes. The attribute dataType is defaulted to json.

See the jQuery documentation for more details on this object:

http://docs.jquery.com/


Return Values

Table 23-15 Return Value

Type Description

{Object}

Returns a jqXHR object.

See the jQuery documentation for more details on this object:

http://docs.jquery.com/


Example

This call to apex.server.process calls an on-demand process called MY_PROCESS and sets the scalar value x01 to test (which can be accessed from PL/SQL using apex_application.g_x01) and sets the page item's P1_DEPTNO and P1_EMPNO values in session state (using jQuery selector syntax). The success callback is stubbed out so that developers can add their own code that fires when the call successfully returns.

Note: The pData parameter to the success callback contains any response sent from the call.

apex.server.process ( "MY_PROCESS", {
  x01: "test",
  pageItems: "#P1_DEPTNO,#P1_EMPNO"
  }, {
 success: function( pData ) { ... do something here ... }
  } );

apex.storage namespace

Use the apex.storage namespace to store storage related functions of Oracle Application Express.

Topics:


apex.storage.getCookie(pName)

Returns the value of cookie name (pName).

Return Value

Not applicable.

Parameters

pName (String)

apex.storage.setCookie(pName,pValue)

Sets a cookie (pName) to a specified value (pValue).

Return Value

Not applicable.

Parameters

pName (String)
pValue (String)

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)

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, "Parameters for apex.widget.initPageItem( pName, pOptions )" describes the available parameters for this function.

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

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, "Properties for the pOptions parameter" 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:

  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 "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$;
    }
});

Miscellaneous Javascript APIs

This section contains all the miscellaneous, non-namespace APIs of Oracle Application Express, including shortcuts to highly used functions.

Topics:


$x(pNd)

Given a DOM node or string ID (pNd), this function returns a DOM node if the element is on the page, or returns false if it is not.

Return Value

(DOM Node | false)

Parameters

pNd (DOM Node | string ID)

$v(pNd)

Given a DOM node or string ID (pNd), this function returns the value of an Application Express item in the same format as it would be posted.

Parameters

pNd (DOM Node | string ID)

$v2(pNd)

Given a DOM node or string ID (pNd), this function returns the value of an Application Express item as a string or an array. If the page item type can contain multiple values like a shuttle, checkboxes or a multi select list an array is returned, otherwise a string.

Return Value

(string|array)

Parameters

pNd (DOM Node | string ID)

$s(pNd, pValue, pDisplayValue, pSuppressChangeEvent)

Given a DOM node or string ID (pNd), this function sets the Application Express item value taking into account the item type. The pDisplayValue is optional. If used for a page item of type "Popup LOV" where the attribute "Input Field" = "Not Enterable, Show Display Value and Store Return Value", it sets the "Input Field". The value of pValue is stored in the hidden return field. The pSuppressChangeEvent parameter is optional. Passing either FALSE or not passing this parameter value results in a change event firing for the item being set. Pass TRUE to prevent the change event from firing for the item being set.

Parameters

pNd (DOM Node | string ID)
pValue  (String | Array)
pDisplayValue(String)
pSuppressChangeEvent(Boolean)

$u_Narray(pNd)

Given a DOM node or string ID or an array (pNd), this function returns a single value, if an pNd is an array but only has one element the value of that element is returned otherwise the array is returned. Used for creating DOM based functionality that can accept a single or multiple DOM nodes.

Return Value

Array (DOM Node | string ID | Array)

Parameters

Array or first value

$u_Carray(pNd)

Given a DOM node or string ID or an array (pNd), this function returns an array. Used for creating DOM based functionality that can accept a single or multiple DOM nodes.

Return Value

pNd (DOM Node | string ID | Array)

Parameters

Array

$nvl(pTest, pDefault)

If pTest is empty or false return pDefault otherwise return pTest.

Return Value

(string | Array)

Parameters

pTest  (String | Array)
pDefault (String | Array)

$x_Style(pNd, pStyle, pString)

Sets a specific style property (pStyle) to given value (pString) of a DOM node or DOM node Array (pNd).

Return Value

(DOM node | DOM Array)

Parameters

pNd (DOM node | string ID | DOM node Array )
pStyle (String)
pString (String)

$x_Hide(pNd)

Hides a DOM node or array of DOM nodes (pNd). This also takes into consideration which type of Application Express item is being hidden.

Return Value

(DOM node | Array)

Parameters

pNd (DOM node | string ID | DOM node Array )

$x_Show(pNd)

Shows a DOM node or array of DOM nodes (pNd). This also takes into consideration which type of Application Express item is being hidden.

Return Value

(DOM node | Array)

Parameters

pNd (DOM node | string ID | DOM node Array )

$x_Toggle(pNd)

Toggles a DOM node or array of DOM nodes (pNd).

Return Value

(DOM node | Array)

Parameters

pNd (DOM node | string ID | Array)

$x_Remove(pNd)

Removes a DOM node or array of DOM nodes.

Return Value

(DOM Node | Array)

Parameters

pNd (DOM node | string ID | DOM node Array)

$x_Value(pNd,pValue)

Sets the value (pValue) of a DOM node or array of DOM nodes (pNd).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node Array)
pValue (String)

$x_UpTill(pNd, pToTag)

Starting from a DOM node (pNd), this function cascades up the DOM tree until the tag of node name (pToTag) is found. If the optional pToClass is present, the ancestor node must have a node name that equals pToTag and the class must equal pToClass.

Return Value

(DOM Node | false)

Parameters

pNd  (DOM Node | string ID) 
String (pToTag) 
String (pToClass ) 

$x_ItemRow(pNd,pFunc)

Given DOM node or array of DOM nodes, this function (shows, hides, or toggles) the entire row that contains the DOM node or array of DOM nodes. This is most useful when using Page Items. This function only works in table layouts since it explicitly looks for a containing tr element.

Return Value

Not applicable.

Parameters

pNd (DOM Node | string ID | Dom node Array) 
pFunc ['TOGGLE','SHOW','HIDE'] (String )

$x_HideItemRow(pNd)

Given a page item name, this function hides the entire row that holds the item. In most cases, this is the item and its label. This function only works in table layouts since it explicitly looks for a containing tr element.

Return Value

Not applicable.

Parameters

pNd (DOM Node | string ID | DON node Array)

$x_ShowItemRow(pNd)

Given a page item name, this function shows the entire row that holds the item. In most cases, this is the item and its label. This function only works in table layouts since it explicitly looks for a containing tr element.

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM note Array)

$x_ToggleItemRow(pNd)

Given a page item name (pNd), this function toggles the entire row that holds the item. In most cases, this is the item and its label. This function only works in table layouts since it explicitly looks for a containing tr element.

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node ray)

$x_HideAllExcept(pNd,pNdArray)

Hides all DOM nodes referenced in pNdArray and then shows the DOM node referenced by pNd. This is most useful when pNd is also a node in pNdArray.

Return Value

(DOM node | DOM Array)

Parameters

pNd (DOM node | string ID | DOM node Array) 
pNdArray (DOM node | String | Array)

$x_HideSiblings(pNd)

Hides all sibling nodes of given pNd.

Return Value

(DOM node)

Parameters

pNd (DOM node | string ID )

$x_ShowSiblings(pNd)

Shows all sibling DOM nodes of given DOM nodes (pNd).

Return Value

(DOM node)

Parameters

pNd (DOM node | string ID )

$x_Class(pNd,pClass)

Sets a DOM node or array of DOM nodes to a single class name.

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node Array)
pClass (String)

$x_SetSiblingsClass(pNd, pClass, pNdClass)

Sets the class (pClass) of all DOM node siblings of a node (pNd). If pNdClass is not null the class of pNd is set to pNdClass.

Return Value

(DOM node | false)

Parameters

pNd (DOM Nnde | string ID)
pClass (String)
pThisClass (String)

$x_ByClass(pClass, pNd, pTag)

Returns an array of DOM nodes by a given class name (pClass). If the pNd parameter is provided, then the returned elements are all children of that DOM node. Including the pTag parameter further narrows the list to just return nodes of that tag type.

Return Value

(Array)

Parameters

pClass (String)
pNd  (DOM node | string ID)
pTag (String)

$x_ShowAllByClass(pNd, pClass, pTag)

Show all the DOM node children of a DOM node (pNd) that have a specific class (pClass) and tag (pTag).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID)
pClass (String)
pTag (String)

$x_ShowChildren(pNd)

Show all DOM node children of a DOM node (pNd).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID)

$x_HideChildren(pNd)

Hide all DOM node children of a DOM node (pNd).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID)

$x_disableItem(pNd, pTest)

Disables or enables an item or array of items based on (pTest).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node array)
a (true | false)

$f_get_emptys(pNd, pClassFail, pClass)

Checks an item or an array of items to see if any are empty, set the class of all items that are empty to pClassFail, set the class of all items that are not empty to pClass.

Return Value

false, Array  Array of all items that are empty (false | Array)

Parameters

pNd (DOM node | string ID | DOM node Array)
Sting (pClassFail)
Sting (pClass)

$v_Array(pNd)

Returns an item value as an array. Useful for multiselects and checkboxes.

Return Value

(Array)

Parameters

pId (DOM Node | string ID)

$f_ReturnChecked(pNd)

Returns an item value as an array. Useful for radio items and check boxes.

Return Value

(Array)

Parameters

pId (DOM node | string ID)

$d_ClearAndHide(pNd)

Clears the content of an DOM node or array of DOM nodes and hides them.

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID | DOM node array)

$f_SelectedOptions(pNd)

Returns the DOM nodes of the selected options of a select item (pNd).

Return Value

(DOM Array)

Parameters

pNd (DOM node | string ID)

$f_SelectValue(pNd)

Returns the values of the selected options of a select item (pNd).

Return Value

(DOM Array | String)

Parameters

pNd (DOM node | string ID)

$u_ArrayToString(pArray, pDelim)

Given an array (pArray) return a string with the values of the array delimited with a given delimiter character (pDelim).

Return Value

Not applicable.

Parameters

pArray (pArray)
pDelim (String)

$x_CheckImageSrc(pId,pSearch)

Checks an image (pId) source attribute for a substring (pSearch). The function returns true if a substring (pSearch) is found. It returns false if a substring (pSearch) is not found.

Return Value

(true | false)

Parameters

pId (DOM Node | String)
pSearch (pSearch)

$v_CheckValueAgainst(pThis, pValue)

Checks an page item's (pThis) value against a set of values (pValue). This function returns true if any value matches.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pValue (Number | String | Array)

$f_Hide_On_Value_Item(pThis, pThat, pValue)

Checks page item's (pThis) value against a value (pValue). If it matches, a DOM node (pThat) is set to hidden. If it does not match, then the DOM node (pThat) is set to visible.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pThat  (DOM node | string ID | DOM node Array )
pValue (Number | String | Array)

$f_Show_On_Value_Item(pThis, pThat, pValue)

Checks page item's (pThis) value against a value (pValue). If it matches, a DOM node (pThat) is set to visible. If it does not match, then the DOM node (pThat) is set to hidden.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pThat  (DOM node | string ID | DOM node Array )
pValue (Number | String | Array)

$f_Hide_On_Value_Item_Row(pThis, pThat, pValue)

Checks the value (pValue) of an item (pThis). If it matches, this function hides the table row that holds (pThat). If it does not match, then the table row is shown.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pThat  (DOM node | string ID | DOM node Array )
pValue (Number | String | Array)

$f_Show_On_Value_Item_Row(pThis, pThat, pValue)

Checks the value (pValue) of an item (pThis). If it matches, this function shows the table row that holds (pThat). If it does not match, then the table row is hidden.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pThat  (DOM node | string ID | DOM node Array )
pValue (Number | String | Array)

$f_DisableOnValue(pThis, pValue, pThat)

Checks the value (pValue) of an item (pThis). If it matches, this function disables the item or array of items (pThat). If it does not match, then the item is enabled.

Return Value

(true | false)

Parameters

pThis (DOM node | string ID)
pValue (String)
pThat  (DOM node | string ID | DOM node Array )

$x_ClassByClass(pNd, pClass, pTag, pClass2)

Sets a class attribute of an array of nodes that are selected by class.

Return Value

(DOM node | DOM node Array)

Parameters

pNd (DOM node | string ID)
pClass (String)
pTag (String)
pClass2 (String)

$f_ValuesToArray(pThis, pClass, pTag)

Collects the values of form items contained within DOM node (pThis) of class attribute (pClass) and nodeName (pTag) and returns an array.

Return Value

No applicable.

Parameters

pThis (DOM node | string ID)
pCLass (String)
pTag (String)

$x_FormItems(pNd, pType)

Returns all form input items contained in a DOM node (pThis) of a certain type (pType).

Return Value

DOM node Array

Parameters

pNd (DOM node | string ID)
pType (String)

$f_CheckAll(pThis, pCheck, pArray)

Check or uncheck (pCheck) all check boxes contained within a DOM node (pThis). If an array of checkboxes DOM nodes (pArray) is provided, use that array for affected check boxes.

Return Value

Not applicable.

Parameters

pThis (DOM node | string ID)
pCheck (true | fales)
pArray (DOM node array)

$f_CheckFirstColumn(pNd)

This function sets all checkboxes located in the first column of a table based on the checked state of the calling check box (pNd), useful for tabular forms.

Return Value

DOM node Array

Parameters

pNd (DOM node | String)

$v_PopupReturn(pValue, pThat) [Deprecated]

Sets the value of the item in the parent window (pThat), with (pValue) and then closes the popup window.

Note:

This function is deprecated. Instead, use:

apex.navigation.popup.close(pThat,pValue)

For existing applications, the old function is still available, because of the application including the 'Legacy JavaScript' file (legacy.js). For details on how to control the inclusion of this file, see "About Database Applications" in Oracle Application Express Application Builder User's Guide.

Return Value

Not applicable.

Parameters

pValue (string)
pThat (DOM node | string ID)

$x_ToggleWithImage(pThis,pNd)

Given an image element (pThis) and a DOM node (pNd), this function toggles the display of the DOM node (pNd). The src attribute of the image element (pThis) is rewritten. The image src has any plus substrings replaced with minus substrings or minus substrings are replaced with plus substrings.

Return Value

(DOM Node)

Parameters

pThis (DOM Node | string ID)
pNd (DOM Nnde | string iD | DOM node Array)

$x_SwitchImageSrc(pNd, pSearch, pReplace)

Checks an image (pId) src attribute for a substring (pSearch). If a substring is found, this function replaces the image entire src attribute with (pReplace).

Return Value

(DOM node | false)

Parameters

pNd (DOM node | string ID)
pSearch (String)
pReplace (String)

$x_CheckImageSrc(pNd, pSearch)

Checks an image (pNd) source attribute for a substring (pSearch). The function returns true if a substring (pSearch) is found. It returns false if a substring (pSearch) is not found.

Return Value

(true | fales)

Parameters

pNd  (DOM node | string ID)
pSearch (String)

$u_SubString(pText,pMatch)

Returns a true or false if a string (pText) contains a substring (pMatch).

Return Value

(true | false)

Parameters

pText (String) 
pMatch (String)

html_RemoveAllChildren(pNd)

Use DOM methods to remove all DOM children of DOM node (pND).

Return Value

Not applicable.

Parameters

pNd (DOM node | string ID) 

$v_IsEmpty(pThis) [Deprecated]

Returns true or false if a form element is empty, this considers any whitespace including a space, a tab, a form-feed, as empty. This also considers any null value that has been specified on the item.

Note:

This function is deprecated. Instead, use:

apex.item( pNd ).isEmpty()

For existing applications, the old function is still available, because of the application including the 'Legacy JavaScript' file (legacy.js). For details on how to control the inclusion of this file, see "About Database Applications" in Oracle Application Express Application Builder User's Guide.

Return Value

[true | false]

Parameters

pThis (DOM Node | String)

html_SetSelectValue(pId,pValue)

Sets the value (pValue) of a select item (pId). If the value is not found, this functions selects the first option (usually the NULL selection).

Return Value

Not applicable.

Parameters

pId (DOM node | String)
pValue (String)

addLoadEvent(pFunction)

Adds an onload function (func) without overwriting any previously specified onload functions.

Return Value

Not applicable.

Parameters

pFunction (Javascript Function)

$f_Swap(pThis,pThat)

Swaps the form values of two form elements (pThis,pThat).

Return Value

Not applicable.

Parameters

pThis (DOM Node | String)
pThat (DOM Node | String)

submitEnter(pNd,e) [Deprecated]

Submits a page when ENTER is pressed in a text field, setting the request value to the ID of a DOM node (pNd).

Usage is onkeypress="submitEnter(this,event)"

Note:

This function is deprecated. Instead, use:

apex.submit( { submitIfEnter : event })

See apex.submit for further details on how to use the 'submitIfEnter' pOptions property.For existing applications, the old function is still available, because of the application including the 'Legacy JavaScript' file (legacy.js). For details on how to control the inclusion of this file, see "About Database Applications" in Oracle Application Express Application Builder User's Guide.

Return Value

Not applicable.

Parameters

pNd (DOM node | String | Array)

$f_SetValueSequence(pArray,pMultiple)

Sets array of form item (pArray) to sequential number in multiples of (pMultiple).

Return Value

Not applicable.

Parameters

pArray (Array) 
pMultiple (Number)

$dom_AddTag(pThis, pTag, pText)

Inserts the html element (pTag) as a child node of a DOM node (pThis) with the innerHTML set to (pText).

Return Value

DOM node

Parameters

pThis (DOM node | string ID ) 
pTag (String)
pText (String)

$tr_AddTD(pThis,pText)

Appends a table cell to a table row (pThis). And sets the content to (pText).

Return Value

(DOM node)

Parameters

pThis (DOM node | string ID)
pText (String)

$tr_AddTH(pThis,pText)

Appends a table cell to a table row (pThis). And sets the content to (pText).

Return Value

DOM node

Parameters

pThis (DOM node | string ID)
pTest (String)

$dom_AddInput(pThis,pType,pId,pName,pValue)

Inserts the html form input element (pType) as a child node of a DOM node (pThis) with an id (pId) and name (pName) value set to pValue.

Return Value

(DOM node)

Parameters

pThis (DOM node | string ID)
pType (String)
pId (String)
pName (String)
pValue (String)

$dom_MakeParent(p_Node,p_Parent)

Takes a DOM node (p_Node) and makes it a child of DOM node (p_Parent) and then returns the DOM node (pNode).

Return Value

(DOM node)

Parameters

p_This (DOM node | string ID)
p_Parent (DOM node | string ID)

$x_RowHighlight(pThis, pColor)

Give an table row DOM element (pThis), this function sets the background of all table cells to a color (pColor). A global variable gCurrentRow is set to pThis.

Return Value

Not applicable.

Parameters

pThis (DOM node | String)
pColor(String)

$x_RowHighlightOff(pThis)

Give an table row Dom node (pThis), this function sets the background of all table cells to NULL.

Return Value

Not applicable.

Parameters

pThis (DOM Element | String)

$v_Upper(pNd)

Sets the value of a form item (pNd) to uppercase.

Return Value

Not applicable.

Parameters

pNd (DOM Node | String)

$d_Find(pThis,pString,pTags,pClass)

Hides child nodes of a Dom node (pThis) where the child node's inner HTML matches any instance of pString. To narrow the child nodes searched by specifying a tag name (pTag) or a class name (pClass). Note that the child node is set to a block level element when set to visible.

Return Value

Not applicable.

Parameters

pThis (DOM node | String)
pString (String)
pTags (String 
pClass (String)

setReturn(p_R,p_D) [Deprecated]

Sets DOM items in the global variables returnInput (p_R) and returnDisplay (p_D) for use in populating items from popups.

Note:

This function is deprecated and due to very limited value there is no alternative.

For existing applications, the old function is still available, because of the application including the 'Legacy JavaScript' file (legacy.js). For details on how to control the inclusion of this file, see "About Database Applications" in Oracle Application Express Application Builder User's Guide.

Return Value

Not applicable.

Parameters

p_R
p_D

$f_First_field(pNd)

Places the user focus on a form item (pNd). If pNd is not found then this function places focus on the first found user editable field.

Return Value

true (if successful)

Parameters

pNd

GetCookie (pName) [Deprecated]

Returns the value of cookie name (pName).

Note:

This function is deprecated. Instead, use:

apex.storage.getCookie(pName)

For existing applications, the old function is still available, because of the application including the 'Legacy JavaScript' file (legacy.js). For details on how to control the inclusion of this file, see "About Database Applications" in Oracle Application Express Application Builder User's Guide.

Return Value

Not applicable.

Parameters

pName (String)

SetCookie (pName,pValue) [Deprecated]

Sets a cookie (pName) to a specified value (pValue).

Note:

This function is deprecated. Instead, use:

apex.storage.setCookie(pName,pValue)

For existing applications, the old function is still available, because of the application including the 'Legacy JavaScript' file (legacy.js). For details on how to control the inclusion of this file, see "About Database Applications" in Oracle Application Express Application Builder User's Guide.

Return Value

Not applicable.

Parameters

pName (String)
pValue (String)