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