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.
Use the apex
namespace to store global variables and highly used functions in Application Express.
Global variables for this namespace are described in this section.
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.
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.
Displays a confirmation showing a message, pMessage
, and depending on user's choice, submits a page setting request value, pRequest
, or cancels page submit.
pMessage (string) pRequest (string)
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');
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.
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).
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.
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} });
The apex.submit
function submits the current page. This function has 2 signatures, as described below.
This function submits the page using the options specified in pOptions
.
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).
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.
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});
This namespace holds all Dynamic Action functions in Oracle Application Express.
This function resumes execution of a Dynamic Action. Execution of a Dynamic Action can be paused, if the action's Wait for Result
attribute is checked. The Wait for Result
is a Dynamic Action plug-in standard attribute designed for use with Ajax based Dynamic Actions. If a plug-in exposes this attribute, it needs to resume execution by calling this function in the relevant place in the plug-in JavaScript code, otherwise, your action breaks execution of Dynamic Actions.
pCallback
(function) - This is a required parameter that references a callback function available from the this.resumeCallback
property.
pErrorOccurred
(boolean) - This is a required parameter that indicates to the framework whether an error has occurred. If an error has occurred and the action's Stop Execution on Error attribute is checked, execution of the Dynamic Action is stopped.
None
Resume execution of the actions indicating that no error has occurred, for example from a success callback of an Ajax based action.
apex.da.resume( lResumeCallback, false );
Resume execution of the actions indicating that an error has occurred, for example from an error callback of an Ajax based action. If the action's
Stop Execution on Error
attribute is checked, execution of the dynamic action is stopped.
apex.da.resume( lResumeCallback, true );
Use the apex.event
namespace to store all event related functions of Oracle Application Express.
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.
Boolean
pSelector (jQuery selector | jQuery object | DOM Node) pEvent (String) pData (Object)
This is the APEX page item namespace. This namespace holds all single item functions. These functions assume that these are APEX generated page items.
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.
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 |
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 |
---|---|---|---|---|
|
(DOM Node | String) |
Required |
Application Express item name or DOM node. |
This will not be used by itself, rather it is used to access item specific functions and properties, as documented in the proceeding APIs
Adds a value to an Application Express item that supports multiple values.
None.
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 |
---|---|---|---|---|
|
(String) |
Required |
The value to be set. |
In this example, the page item called 'P1_ITEM' will have the value '100' added to the values currently selected.
apex.item( "P1_ITEM" ).addValue('100') ;
Disables the Application Express item value, taking into account the item type, making it unavailable for edit.
None.
None.
In this example, the page item called 'P1_ITEM' will be disabled and unavailable for edit.
apex.item( "P1_ITEM" ).disable() ;
Enables the Application Express item value, taking into account the item type, making it available for edit.
None.
None.
In this example, the page item called 'P1_ITEM' will be enabled and available for edit.
apex.item( "P1_ITEM" ).enable() ;
Returns the current value of an Application Express item on a page, taking into account the current item type. This does not return the item's current value from session state (although that could be the same), rather it will return the value as it is on the current page.
There are 2 related functions to .getValue(). $v( pNd ) which returns an item's value, but in the format it will be posted. This will either be a single value, or if the item supports multiple values, will be a ':' colon separated list of values. There is also the $v2( pNd ) function, which is just a shortcut to .getValue() and returns either a single value, or array of values.
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). |
None.
In this example, the current value of the page item called 'P1_ITEM' will be shown in an alert.
alert( "P1_ITEM value = " + apex.item( "P1_ITEM" ).getValue() );
Hides the Application Express item value, taking into account the item type. When using the .hide() function, it is important to understand the following:
If the item being hidden is rendered on a page using table layout (meaning the page references a page template with Grid Layout Type set to 'HTML Table'), and the call to hide has specified to hide the entire table row (pHideRow = TRUE), then it is assumed that everything pertaining to the item is contained in that row, and the entire row will be hidden.
If the item being hidden is rendered on a page using table layout, and the call to hide has specified not to hide the entire table row (pHideRow = FALSE, or not passed), then the function will attempt to hide the item's label, where the FOR attribute matches the ID of the item.
If the item being hidden is rendered on a page using grid layout (meaning the page references a page template with Grid Layout Type set to either 'Fixed Number of Columns', or 'Variable Number of Columns'), and the item references a Label template that includes a Field Container element with a known ID (so where the Field Container > Before Label and Item attribute includes an HTML element with id="#CURRENT_ITEM_CONTAINER_ID#"), then it is assumed that everything pertaining to the item is contained in the Field Container, and this will be hidden.
None.
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 |
---|---|---|---|---|
|
(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'). |
In this example, the page item called P1_ITEM will be hidden. If P1_ITEM is on a page using grid layout and the item references a Label template that includes a Field Container element with a known ID (as detailed above), then that container element will be hidden. Otherwise just the item and its corresponding label will be hidden.
apex.item( "P1_ITEM" ).hide();
In this example, the page item called P1_ITEM's nearest containing table row (TR) will be hidden (as pHideRow = TRUE). Hiding the entire table row should only be used on a page using table layout. If P1_ITEM is on a page using grid layout, then passing pHideRow = TRUE will not work and could result in adverse consequence for the page layout, where an incorrect table row is wrongly hidden.
apex.item( "P1_ITEM" ).hide(TRUE);
Returns true or false if an Application Express item is empty and will consider any whitespace including a space, a tab or a form-feed, as empty. This will also respect if the item type uses a List of Values, and a 'Null Return Value' has been defined in the List of Values. In that case, the 'Null Return Value' will be used to assert if the item is empty. In this case, the DOM node returned is the nearest ancestor of pNd
that has a node name of pToTag
and optionally a matching class. Also it returns false if pNd
is not found or if there is no pToTag
ancestor.
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. |
None.
In this example, the call to .isEmpty() determines if the page item called 'P1_ITEM' is null, and if so displays an alert.
if( apex.item( "P1_ITEM" ).isEmpty() ) { alert( "P1_ITEM empty!" ); }
Places user focus on the Application Express item, taking into account how specific items are designed to receive focus.
None.
None.
In this example, user focus is set to the page item called 'P1_ITEM'.
apex.item( "P1_ITEM" ).setFocus();
Sets a style for the Application Express item, taking into account how specific items are designed to be styled.
None.
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 |
---|---|---|---|---|
|
(CSS Property Name) |
Required |
The CSS property name that will be set. |
|
|
(CSS Property Value) |
Required |
The value used to set the CSS property. |
In this example, the CSS property 'color' will be set to 'red' for the page item called 'P1_ITEM'.
apex.item( "P1_ITEM" ).setStyle( "color", "red" );
Sets the Application Express item value, taking into account the item type. This function sets the current value of an Application Express item on the page, not the item's current value in session state. It also allows for the caller to suppress the 'change' event for the item being set, if desired.
See the $s( pNd, pValue, pDisplayValue, pSuppressChangeEvent )
function for a shortcut to .setValue()
.
None.
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 |
---|---|---|---|---|
|
(String | Array) |
Required |
The value to be set. For items that support multiple values (for example a 'Shuttle'), an array of string values can be passed to set multiple values at once. |
|
|
(String) |
Optional |
Optional parameter used to set the page item's display value, in the case where the return value is different. For example for the item type "Popup LOV", with the attribute "Input Field" = "Not Enterable, Show Display Value and Store Return Value", this value sets the "Input Field". The value of pValue is then used to set the item's hidden return field. |
|
|
(Boolean) |
Optional |
FALSE |
Pass TRUE to prevent the 'change' event from being triggered, for the item being set. |
In this example, the value of the page item called P1_ITEM will be set to "10". As pSuppressChangeEvent has not been passed, the default behavior of the 'change' event triggering for P1_ITEM will occur.
apex.item( "P1_ITEM" ).setValue( "10" );
In this example P1_ITEM is a "Popup LOV" page item with the attribute "Input Field" = "Not Enterable, Show Display Value and Store Return Value", set to "Input Field". The display value of P1_ITEM will be set to "SALES" and the hidden return value will be set to "10". As 'true' has been passed for the pSuppressChangeEvent parameter, the 'change' event will not trigger for the P1_ITEM item.
apex.item( "P1_ITEM" ).setValue( "10", "SALES", true );
Shows the Application Express item value, taking into account the item type. When using the .show() function, it is important to understand the following:
If the item being shown is rendered on a page using table layout (meaning the page references a page template with Grid Layout Type set to 'HTML Table'), and the call to show has specified to show the entire table row (pShowRow = TRUE), then it is assumed that everything pertaining to the item is contained in that row, and the entire row will be shown.
If the item being shown is rendered on a page using table layout, and the call to show has specified not to show the entire table row (pShowRow = FALSE, or not passed), then the function will attempt to show the item's label, where the FOR attribute matches the ID of the item.
If the item being shown is rendered on a page using grid layout (meaning the page references a page template with Grid Layout Type set to either 'Fixed Number of Columns', or 'Variable Number of Columns'), and the item references a Label template that includes a Field Container element with a known ID (so where the Field Container > Before Label and Item attribute includes an HTML element with id="#CURRENT_ITEM_CONTAINER_ID#"), then it is assumed that everything pertaining to the item is contained in the Field Container, and this will be shown.
None.
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 |
---|---|---|---|---|
|
(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'). |
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);
Use the apex.navigation
namespace to store popup and redirect related functions of Oracle Application Express.
Use the apex.server
namespace to store all AJAX functions to communicate with the server part of Oracle Application Express.
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.
Table 23-10 apex.server.plugin(pAjaxIdentifier,pData,pOptions) Parameters
Parameter | Type | Optional/Required | Description |
---|---|---|---|
|
(String) |
Required |
Use the value returned by the PL/SQL package |
|
{Object} |
Optional |
Object which can optionally be used to send additional values to be sent with the AJAX request. The special attribute |
|
{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:
function( pLoadingIndicator ) { return pLoadingIndicator.prependTo ( apex.jQuery( "td.shuttleControl", gShuttle )) }
See Also: See jQuery documentation of |
Type | Description |
---|---|
{Object} |
Retuns a jqXHR object. See Also: See the jQuery documentation for more details on this object: |
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 ... } } );
This function returns the URL to issue a GET request to the PL/SQL AJAX function which has been defined for a plug-in.
Table 23-12 apex.server.pluginUrl( pAjaxIdentifier, pData) Parameters
Name | Type | Optional/Required | Default | Description |
---|---|---|---|---|
|
(String) |
Required |
Use the value returned by the PL/SQL package |
|
|
{Object} |
Optional |
Object which can optionally be used to set additional values which are included into the URL. The special attribute |
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" } );
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.
Table 23-14 apex.server.process Parameters
Name | Type | Optional/Required | Default | Description |
---|---|---|---|---|
|
(String) |
Required |
Use the value returned by the PL/SQL package |
|
|
{Object} |
Optional |
Object which can optionally be used to send additional values to be sent with the AJAX request. The special attribute |
|
|
{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:
function( pLoadingIndicator ) { return lLoadingIndicator.prependTo ( apex.jQuery( "td.shuttleControl", gShuttle )) }
See Also: See jQuery documentation of See the jQuery documentation for more details on this object: |
Type | Description |
---|---|
{Object} |
Returns a jqXHR object. See the jQuery documentation for more details on this object: |
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 ... } } );
Use the apex.storage
namespace to store storage related functions of Oracle Application Express.
Use the apex.widget
namespace to store all the general purpose widget related functions of Oracle Application Express.
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
None.
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 |
---|---|---|---|---|
|
(DOM Node|String) |
Required |
Application Express page item name or DOM node. |
|
|
(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
|
Table 23-17 Properties for the pOptions parameter
Name | Description |
---|---|
|
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 |
|
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 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 |
|
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 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 |
|
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 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 |
|
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 |
|
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 |
|
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 See the "apex.item( pNd ).addValue( pValue )", for details on how this function should be defined. |
|
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:
|
|
Specify the element to receive focus, when focus is set to the item using the Ensuring the item sets focus correctly means certain item related client-side functionality of Application Express still works, for example when using the 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 |
|
Specify the element to receive style, when style is set to the item using the Note: Even if this property is defined, the default handling still always handles the logic associated with the See the 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 |
|
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. |
|
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 This is used, for example, if the item is a |
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$; } });
This section contains all the miscellaneous, non-namespace APIs of Oracle Application Express, including shortcuts to highly used functions.
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.
(DOM Node | false)
pNd (DOM Node | string ID)
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.
pNd (DOM Node | string ID)
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.
(string|array)
pNd (DOM Node | string ID)
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.
pNd (DOM Node | string ID) pValue (String | Array) pDisplayValue(String) pSuppressChangeEvent(Boolean)
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.
Array (DOM Node | string ID | Array)
Array or first value
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.
pNd (DOM Node | string ID | Array)
Array
If pTest
is empty or false return pDefault
otherwise return pTest
.
(string | Array)
pTest (String | Array) pDefault (String | Array)
Sets a specific style property (pStyle
) to given value (pString
) of a DOM node or DOM node Array (pNd
).
(DOM node | DOM Array)
pNd (DOM node | string ID | DOM node Array ) pStyle (String) pString (String)
Hides a DOM node or array of DOM nodes (pNd
). This also takes into consideration which type of Application Express item is being hidden.
(DOM node | Array)
pNd (DOM node | string ID | DOM node Array )
Shows a DOM node or array of DOM nodes (pNd
). This also takes into consideration which type of Application Express item is being hidden.
(DOM node | Array)
pNd (DOM node | string ID | DOM node Array )
Toggles a DOM node or array of DOM nodes (pNd).
(DOM node | Array)
pNd (DOM node | string ID | Array)
Removes a DOM node or array of DOM nodes.
(DOM Node | Array)
pNd (DOM node | string ID | DOM node Array)
Sets the value (pValue
) of a DOM node or array of DOM nodes (pNd
).
Not applicable.
pNd (DOM node | string ID | DOM node Array) pValue (String)
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
.
(DOM Node | false)
pNd (DOM Node | string ID) String (pToTag) String (pToClass )
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.
Not applicable.
pNd (DOM Node | string ID | Dom node Array) pFunc ['TOGGLE','SHOW','HIDE'] (String )
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.
Not applicable.
pNd (DOM Node | string ID | DON node Array)
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.
Not applicable.
pNd (DOM node | string ID | DOM note Array)
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.
Not applicable.
pNd (DOM node | string ID | DOM node ray)
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
.
(DOM node | DOM Array)
pNd (DOM node | string ID | DOM node Array) pNdArray (DOM node | String | Array)
Shows all sibling DOM nodes of given DOM nodes (pNd
).
(DOM node)
pNd (DOM node | string ID )
Sets a DOM node or array of DOM nodes to a single class name.
Not applicable.
pNd (DOM node | string ID | DOM node Array) pClass (String)
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
.
(DOM node | false)
pNd (DOM Nnde | string ID) pClass (String) pThisClass (String)
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.
(Array)
pClass (String) pNd (DOM node | string ID) pTag (String)
Show all the DOM node children of a DOM node (pNd
) that have a specific class (pClass
) and tag (pTag
).
Not applicable.
pNd (DOM node | string ID) pClass (String) pTag (String)
Show all DOM node children of a DOM node (pNd
).
Not applicable.
pNd (DOM node | string ID)
Hide all DOM node children of a DOM node (pNd
).
Not applicable.
pNd (DOM node | string ID)
Disables or enables an item or array of items based on (pTest
).
Not applicable.
pNd (DOM node | string ID | DOM node array) a (true | false)
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
.
false, Array Array of all items that are empty (false | Array)
pNd (DOM node | string ID | DOM node Array) Sting (pClassFail) Sting (pClass)
Returns an item value as an array. Useful for multiselects and checkboxes.
(Array)
pId (DOM Node | string ID)
Returns an item value as an array. Useful for radio items and check boxes.
(Array)
pId (DOM node | string ID)
Clears the content of an DOM node or array of DOM nodes and hides them.
Not applicable.
pNd (DOM node | string ID | DOM node array)
Returns the DOM nodes of the selected options of a select item (pNd
).
(DOM Array)
pNd (DOM node | string ID)
Returns the values of the selected options of a select item (pNd
).
(DOM Array | String)
pNd (DOM node | string ID)
Given an array (pArray
) return a string with the values of the array delimited with a given delimiter character (pDelim
).
Not applicable.
pArray (pArray) pDelim (String)
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.
(true | false)
pId (DOM Node | String) pSearch (pSearch)
Checks an page item's (pThis
) value against a set of values (pValue
). This function returns true if any value matches.
(true | false)
pThis (DOM node | string ID) pValue (Number | String | Array)
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.
(true | false)
pThis (DOM node | string ID) pThat (DOM node | string ID | DOM node Array ) pValue (Number | String | Array)
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.
(true | false)
pThis (DOM node | string ID) pThat (DOM node | string ID | DOM node Array ) pValue (Number | String | Array)
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.
(true | false)
pThis (DOM node | string ID) pThat (DOM node | string ID | DOM node Array ) pValue (Number | String | Array)
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.
(true | false)
pThis (DOM node | string ID) pThat (DOM node | string ID | DOM node Array ) pValue (Number | String | Array)
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.
(true | false)
pThis (DOM node | string ID) pValue (String) pThat (DOM node | string ID | DOM node Array )
Sets a class attribute of an array of nodes that are selected by class.
(DOM node | DOM node Array)
pNd (DOM node | string ID) pClass (String) pTag (String) pClass2 (String)
Collects the values of form items contained within DOM node (pThis
) of class attribute (pClass
) and nodeName (pTag
) and returns an array.
No applicable.
pThis (DOM node | string ID) pCLass (String) pTag (String)
Returns all form input items contained in a DOM node (pThis
) of a certain type (pType
).
DOM node Array
pNd (DOM node | string ID) pType (String)
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.
Not applicable.
pThis (DOM node | string ID) pCheck (true | fales) pArray (DOM node array)
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.
DOM node Array
pNd (DOM node | String)
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.
Not applicable.
pValue (string) pThat (DOM node | string ID)
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.
(DOM Node)
pThis (DOM Node | string ID) pNd (DOM Nnde | string iD | DOM node Array)
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
).
(DOM node | false)
pNd (DOM node | string ID) pSearch (String) pReplace (String)
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.
(true | fales)
pNd (DOM node | string ID) pSearch (String)
Returns a true or false if a string (pText
) contains a substring (pMatch
).
(true | false)
pText (String) pMatch (String)
Use DOM methods to remove all DOM children of DOM node (pND
).
Not applicable.
pNd (DOM node | string ID)
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: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.
[true | false]
pThis (DOM Node | String)
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).
Not applicable.
pId (DOM node | String) pValue (String)
Adds an onload function (func
) without overwriting any previously specified onload functions.
Not applicable.
pFunction (Javascript Function)
Swaps the form values of two form elements (pThis
,pThat
).
Not applicable.
pThis (DOM Node | String) pThat (DOM Node | String)
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.
Not applicable.
pNd (DOM node | String | Array)
Sets array of form item (pArray
) to sequential number in multiples of (pMultiple
).
Not applicable.
pArray (Array) pMultiple (Number)
Inserts the html element (pTag
) as a child node of a DOM node (pThis
) with the innerHTML set to (pText
).
DOM node
pThis (DOM node | string ID ) pTag (String) pText (String)
Appends a table cell to a table row (pThis
). And sets the content to (pText
).
(DOM node)
pThis (DOM node | string ID) pText (String)
Appends a table cell to a table row (pThis
). And sets the content to (pText
).
DOM node
pThis (DOM node | string ID) pTest (String)
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
.
(DOM node)
pThis (DOM node | string ID) pType (String) pId (String) pName (String) pValue (String)
Takes a DOM node (p_Node
) and makes it a child of DOM node (p_Parent
) and then returns the DOM node (pNode).
(DOM node)
p_This (DOM node | string ID) p_Parent (DOM node | string ID)
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
.
Not applicable.
pThis (DOM node | String) pColor(String)
Give an table row Dom node (pThis
), this function sets the background of all table cells to NULL
.
Not applicable.
pThis (DOM Element | String)
Sets the value of a form item (pNd) to uppercase.
Not applicable.
pNd (DOM Node | String)
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.
Not applicable.
pThis (DOM node | String) pString (String) pTags (String pClass (String)
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.
Not applicable.
p_R p_D
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.
true (if successful)
pNd
Returns the value of cookie name (pName
).
Note:
This function is deprecated. Instead, use: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.
Not applicable.
pName (String)
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.
Not applicable.
pName (String) pValue (String)