31.11 apex.server namespace

The apex.server namespace stores all Ajax functions to communicate with the server part of Oracle Application Express.

31.11.1 apex.server.loadScript

This API is used to asynchronously load other JavaScript libraries that has Asynchronous Module Definition (AMD), and if RequireJS library is already loaded on the page.

Syntax

apex.server.loadScript( pConfig, callback )

Parameters

Table 31-56 apex.server.loadScript

Name Type Description

pConfig

object

JSON objects contains the following attributes:

  • “path” - {String} the location of the file.

  • “requirejs” - {Boolean} whether to use requirejs to load this file.

  • “global” - {String} the global name introduced by this files and the existing one is overwritten. Leave this option empty if the file is generated by RequireJS optimizer.

callback

object

Function to be executed once script is loaded.

Returns

Returns a function.

Examples

The following example loads a regular library that does not need RequireJS:

 apex.server.loadScript ({
    "path": "./library_1.js"
 }, function() {
    console.log( 'library_1 is ready.' );
 });

The following example loads a library that requires RequireJS and creates own namespace: "myModule":

 apex.server.loadScript ({
    "path": "./library_2.js",
    "requirejs": true,
    "global": "myModule"
 }, function() {
    console.log( myModule );
 });

The following example loads a concatenated libraries generated by RequireJS Optimizer, assuming requireJS is already on the page:

 apex.server.loadScript ({
    "path": "./library_all.js",
    "requirejs": true
 }, function() {
    console.log( myModule_1, myModule_2 ... );
 });

31.11.2 apex.server.plugin

This function calls the PL/SQL Ajax function that has been defined for a plug-in. This function is a wrapper of the jQuery.ajax function that supports a subset of the jQuery.ajax options plus additional Application Express specific options.

The plug-in PL/SQL Ajax function is identified using the value returned by the PL/SQL package apex_plugin.get_ajax_identifier. There are two ways to provide the plug-in Ajax identifier:

  1. Provide the pAjaxIdentifier as the first argument

  2. Provide information about the region(s) including the ajaxIdentifier in the pData object structure. See pData description for details.

Syntax

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

Parameters

Table 31-57 apex.server.plugin

Name Type Description

pAjaxIdentifier

String

Optional. The plug-in ajax identifier. If not given then pData must include a regions array that includes a region with property ajaxIdentifier.

pData

Object

Optional object containing data to send to the server in the Ajax request. The Object is serialized as JSON and sent to the server in parameter p_json. See below pData special properties table for a list of properties that are treated special.

Data for specific regions can be sent in the following format:

    {
        "regions": [ {
           "id": <region-id-or-static-id>,
           "ajaxIdentifier": <ajaxIdentifier>,
            <any other data specific to the region plug-in>
       }, ...
       ]
    }

pOptions

Object

Optional object that is used to set additional options to control the Ajax call including before and after processing.

See below pOptions properties table for a list of Application Express specific options.

See jQuery documentation of jQuery.ajax for these supported options: accepts, dataType, beforeSend, contents, converters, dataFilter, headers, complete, statusCode, error, success.

The dataType option defaults to json.

The async option is deprecated and will be removed in a future release.

http://docs.jquery.com/

Table 31-58 pData special properties

Name Type Description

pageItems

String | jQuery | DOM element | Array

Identifies the page or column items that will be included in the request. It can be a jQuery selector, jQuery or DOM object or array of item names. These items will be made available in session state on the server. If pageItems contains column items then pOptions should include the target property so that the region session state context can be determined.

x01 - x10

String

These properties are moved out of the p_json object and sent as x01 - x10 scalar parameters.

f01 - f20

String | Array

These properties are moved out of the p_json object and sent as f01 - f20 array parameters.

Table 31-59 pOptions properties

Name Type Description

refreshObject

String | jQuery | DOM element

jQuery selector, jQuery or DOM object which identifies the DOM element on which the apexbeforerefresh and apexafterrefresh events are triggered. If this option is not supplied these events are not triggered.

refreshObjectData

Object | Array

Only applies if refreshObject option is given. Specify data that is 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 using the this.data property. For custom jQuery event handlers, this can be accessed through the pData parameter of the event handler.

clear

Function

JavaScript function used to clear the DOM after the apexbeforerefresh event is triggered and before the actual Ajax call is made.

loadingIndicator

String | jQuery | DOM object | Function

Identifies the element(s) that will have a loading indicator (progress spinner) displayed next to it during the Ajax call. The element can be specified with a jQuery selector, jQuery or DOM object. 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

String

Six options to define the position of the loading indicator displayed. Only considered if the value passed toloadingIndicator 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.

  • centered: Displays in the center of the DOM element defined by loadingIndicator.

  • page: Displays in the center of the page.

queue

Object

Object specifying the name of a queue and queue action. The name property specifies the name of the queue to add the request to.

The action property can be one of the following:

  • "wait" This action is the default and is used to send requests one after the other. When the action is wait the request is added to the named queue. If there are no other requests in that queue in progress or waiting then this request is executed. Otherwise it waits on the named queue until the ones before it are complete.

  • "replace" Action replace is used when this current request makes any previous requests on the named queue in progress or waiting obsolete or invalid. This current request aborts any in progress request and clears out any waiting requests on the named queue and then is executed. Waiting requests are rejected with status "superseded".

  • "lazyWrite" This action is used to throttle requests to the server to persist data. This should only be used to persist non critical data such as user interface settings or state. Use when the data may change frequently and only the last data values need to be saved. For example this is useful for persisting splitter position, or tree expansion and focus state etc.

The queue name is unique for each data unit. For example if you were saving the position of two different splitters use a unique name for each one so that latest update to one doesn't overwrite a previous lazy write of the other. When using lazyWrite Queue the refreshObject, clear, loadingIndicator, and loadingIndicatorPosition are most likely not useful because nothing is being loaded or refreshed.

It is possible to mix requests with wait and replace actions on the same queue. The lazyWrite action should not be used with a queue name that is also used with wait and replace actions.

target

String | DOM element

Target element (DOM element or jQuery Selector) that this request pertains to. This is used to get session state context from the enclosing region.

Returns

Returns a promise object. The promise done method is called if the Ajax request completes successfully. This is called in the same cases as the success callback function in pOptions. The promise fail method is called if the Ajax request completes with an error including internally detected Application Express errors. This is called in the same cases as the error callback function in pOptions. The promise also has an always method that is called after done and error. The promise is returned even when queue options are used. The promise is not a jqXHR object but does have an abort method. The abort method does not work for requests that use any queue options.

Example

This example demonstrates a 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 value for lAjaxIdentifier must be set to the value returned by the server PL/SQL API apex_plugin.get_ajax_identifier.

The pData parameter to the success callback will contain any response returned by the plug-in PL/SQL Ajax function.

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

31.11.3 apex.server.pluginUrl

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

Parameters

Table 31-60 apex.server.pluginUrl

Name Type Description

pAjaxIdentifier

String

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

pData

Object

Optional object that is 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 apex.show procedure provides (for example you can set the scalar parameters x01 - x10 and the arrays f01 - f20).

Returns

Returns a string that is 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). The value for lAjaxIdentifier must be set to the value returned by the server PL/SQL API apex_plugin.get_ajax_identifier.

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

31.11.4 apex.server.process

This function calls a PL/SQL on-demand (Ajax callback) process defined on page or application level. This function is a wrapper of the jQuery.ajax function that supports a subset of the jQuery.ajax options plus additional Application Express specific options.

Syntax

apex.server.process( pName, pData, pOptions ) → Promise

Parameters

Table 31-61 apex.server.process

Name Type Description

pName

String

The name of the PL/SQL on-demand page or application process to call.

pData

Object

Optional object containing data to send to the server in the Ajax request. The Object is serialized as JSON and sent to the server in parameter p_json. See below pData table for a list of properties that are treated special.

Data for specific regions can be sent in the following format:

    {
        "regions": [ {
            "id": <region-id-or-static-id>,
            "ajaxIdentifier": <ajaxIdentifier>,
            <any other data specific to the region plug-in>
        }, ...
        ]
    }

pOptions

Object

Optional object that is used to set additional options to control the Ajax call including before and after processing. See pOptions table below for a list of Application Express specific options.

See jQuery documentation of jQuery.ajax for these supported options: accepts, dataType, beforeSend, contents, converters, dataFilter, headers, complete, statusCode, error, success. The dataType option defaults to json.

The async option is deprecated and will be removed in a future release.

Table 31-62 pData special properties

Name Type Description

pageItems

String | jQuery | DOM element | Array

Identifies the page or column items that will be included in the request. It can be a jQuery selector, jQuery or DOM object or array of item names. These items will be made available in session state on the server. If pageItems contains column items then pOptions should include the target property so that the region session state context can be determined.

x01 - x10

String

These properties are moved out of the p_json object and sent as x01 - x10 scalar parameters.

f01 - f20

String | Array

These properties are moved out of the p_json object and sent as f01 - f20 array parameters.

Table 31-63 pOptions properties

Name Type Description

refreshObject

String | jQuery | DOM element

jQuery selector, jQuery or DOM object which identifies the DOM element on which the apexbeforerefresh and apexafterrefresh events are triggered. If this option is not supplied these events are not triggered.

refreshObjectData

Object | Array

Only applies if refreshObject option is given. Specify data that is 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 using the this.data property. For custom jQuery event handlers, this can be accessed through the pData parameter of the event handler.

clear

Function

JavaScript function used to clear the DOM after the apexbeforerefresh event is triggered and before the actual Ajax call is made.

loadingIndicator

String | jQuery | DOM object | Function

Identifies the element(s) that will have a loading indicator (progress spinner) displayed next to it during the Ajax call. The element can be specified with a jQuery selector, jQuery or DOM object. 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

String

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

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

  • centered: Displays in the center of the DOM element defined by loadingIndicator

  • page: Displays in the center of the page.

queue

Object

Object specifying the name of a queue and queue action. The name property specifies the name of the queue to add the request to.

The action property can be one of the following:

  • "wait" This action is the default and is used to send requests one after the other. When the action is wait the request is added to the named queue. If there are no other requests in that queue in progress or waiting then this request is executed. Otherwise it waits on the named queue until the ones before it are complete.

  • "replace" Action replace is used when this current request makes any previous requests on the named queue in progress or waiting obsolete or invalid. This current request aborts any in progress request and clears out any waiting requests on the named queue and then is executed. Waiting requests are rejected with status "superseded".

  • "lazyWrite" This action is used to throttle requests to the server to persist data. This should only be used to persist non critical data such as user interface settings or state. Use when the data may change frequently and only the last data values need to be saved. For example this is useful for persisting splitter position, or tree expansion and focus state etc.

The queue name is unique for each data unit. For example if you were saving the position of two different splitters use a unique name for each one so that latest update to one doesn't overwrite a previous lazy write of the other. When using lazyWrite Queue the refreshObject, clear, loadingIndicator, and loadingIndicatorPosition are most likely not useful because nothing is being loaded or refreshed.

It is possible to mix requests with wait and replace actions on the same queue. The lazyWrite action should not be used with a queue name that is also used with wait and replace actions.

target

String | DOM element

Target element (DOM element or jQuery Selector) that this request pertains to. This is used to get session state context from the enclosing region.

Returns

A promise object is returned. The promise done method is called if the Ajax request completes successfully. This is called in the same cases as the success callback function in pOptions. The promise fail method is called if the Ajax request completes with an error including internally detected Application Express errors. This is called in the same cases as the error callback function in pOptions. The promise also has an always method that is called after done and error. The promise is returned even when queue options are used. The promise is not a jqXHR object but does have an abort method. The abort method does not work for requests that use any queue options.

Example

This example demonstrates a 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 the response returned from on-demand process.

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

31.11.5 apex.server.url

This function returns the URL to issue a GET request to the current page.

Parameters

Table 31-64 apex.server.url

Name Type Optional/Required Description

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 apex.show procedure provides (for example you can set the scalar parameters x01 - x10 and the arrays f01 - f20).

pPage

String

Optional

Page ID of the current page, which can be optionally used to set the page ID in the URL being returned.

Returns

Returns the string URL to issue the GET request.

Example

This example demonstrates a call to apex.server.url. Returns a URL to issue a GET request to the DELETE function which has been defined for this page, 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).

apex.server.url ({
    p_request: "DELETE",
    x01: "test",
    pageItems: "#P1_DEPTNO,#P1_EMPNO" });