Pre-General Availability: 2018-5-8

Namespace: server

QuickNav

Functions

apex.server

The apex.server namespace contains all Ajax functions to communicate with the Oracle Application Express server.

Functions

(static) ajaxUrl(pDataopt, pOptionsopt) → {string}

Returns the URL to issue a GET request to the wwv_flow.ajax function.

TODO this function and apex.server.url are under consideration for being merged in some way.

Parameters:
Name Type Attributes Description
pData Object <optional>
 Object which is being passed as the p_json parameter The special attribute "pageItems" which can be of type jQuery selector, jQuery-, 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 wwv_flow.ajax procedure provides. For example you can set the scalar parameters p_request, x01 - x10 and the arrays f01 - f20
pOptions Object <optional>
 todo
Returns:
The URL to issue a GET request.
Type
string
Example

todo

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

(static) chunk(Text) → {string|Array.<string>}

Given a text string break it up in to an array of strings no greater than 8000 chars each if needed. If the original text is less than 8000 chars return it.
Parameters:
Name Type Description
Text string string to split into an array of chunks no bigger than 8000 chars.
Returns:
The input text string if less than 8000 chars or an array of the split up input text.
Type
string | Array.<string>

(static) loadScript(pOptions, callbackopt) → {*}

Load JavaScript files asynchronously using RequireJS require or jQuery getScript. It is rare that an APEX app needs to dynamically load JavaScript but if it does it should use this rather than getScript. The reason is that RequreJS may or may not be on a page. If it is and libraries that are RequireJS aware are loaded they will give an error because they expect to be loaded by a call to require. If RequireJS is not on the page then require cannot be used.

Parameters:
Name Type Attributes Description
pOptions Object An objects that contains the following attributes:
Properties
Name Type Attributes Description
path string The location of the JavaScript file to load.
requirejs boolean <optional>
 Whether to use requirejs to load this file. The default is false.
global string <optional>
 The global name introduced by this file. The existing one is overwritten. Leave this option empty if the file is generated by RequireJS optimizer.
callback function <optional>
 A no argument function to be executed once script is loaded.
Returns:
If getScript is used then the return value is a jqXHR style promise. Otherwise there is no return value.
Type
*
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 its own namespace "myModule".

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

The following example loads a concatenated libraries file 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 ... );
} );

(static) plugin(pAjaxIdentifieropt, pDataopt, pOptionsopt) → {Promise}

This function calls the PL/SQL Ajax function that has been defined for a plug-in. This function is a wrapper around the jQuery.ajax function and 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:

  • Provide the pAjaxIdentifier as the first argument
  • Provide information about the region(s) including the ajaxIdentifier in the pData object structure. See pData description for details.
Parameters:
Name Type Attributes 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. 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>
    }, ...]
}

The following properties are treated special:

Properties
Name Type Attributes Description
pageItems string | jQuery | Element | Array.<string> <optional>
 Identifies the page or column items that will be included in the request. It can be a jQuery selector, jQuery object, Element, 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 - x20 string <optional>
 These properties are moved out of the p_json object and sent as x01 - x20 scalar parameters.
f01 - f20 string | Array <optional>
 These properties are moved out of the p_json object and sent as f01 - f20 array parameters.
pOptions Object <optional>

An object that is used to set additional options to control the Ajax call including before and after processing. 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. See {link http://docs.jquery.com/}

The following Application Express specific options are supported:

Properties
Name Type Attributes Description
refreshObject jQuery | Element | string <optional>
 A jQuery selector string, jQuery object, or Element that identifies the DOM element that the apex.event:apexbeforerefresh and apex.event:apexafterrefresh events are triggered on. If this option is not supplied these events are not triggered.
refreshObjectData Object | Array <optional>
 Only applies if the refreshObject option is given. Specifies extra data that is passed in the apex.event:apexbeforerefresh and apex.event:apexafterrefresh events 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 <optional>
 A no argument function that is called after the apex.event:apexbeforerefresh event has fired and before the actual Ajax call is made. This function can be used to clear the DOM or any other state maintained by the Element or component for which this Ajax request is being made.
loadingIndicator string | jQuery | Element | function <optional>
 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 object or Element. The loadingIndicator can also be a function that receives the loading indicator as a jQuery object, which it can use as is or modify or replace and attach to the DOM where appropriate. The function must return a reference to the jQuery loading indicator. For example: 
function( pLoadingIndicator ) {
    return pLoadingIndicator.prependTo(
        apex.jQuery( "td.shuttleControl", gShuttle) );
}
loadingIndicatorPosition string <optional>
 One of the following 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 <optional>
 An object specifying the name of a queue and queue action. For example: 
{
    name: "updateList",
    action: "replace"
}

If no queue option is given the request is made right away without regard to any previous requests.

The name property specifies the name of the queue to add this request to.

The action property can be one of "wait" (the default), "replace", "lazyWrite".

  • 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: This action 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 jQuery | Element <optional>
 The target element (DOM element or jQuery Selector) that this request pertains to. This is used to get session state context from the enclosing region. This option must be provided if pageItems property of pData contains any column items.
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.
Type
Promise
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.

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

(static) pluginUrl(pAjaxIdentifier, pDataopt) → {string}

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

Parameters:
Name Type Attributes 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>
 Optional object that is used to set additional values which are included into the URL. The special property 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:
The URL to issue a GET request.
Type
string
Example

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

(static) process(pName, pDataopt, pOptionsopt) → {Promise}

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

Parameters:
Name Type Attributes 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. Data for specific regions can be sent in the following format: 
{
    "regions": [ {
       "id": <region-id-or-static-id>,
       <any other data specific to the region plug-in>
    }, ...]
}

The following properties are treated special:

Properties
Name Type Attributes Description
pageItems string | jQuery | Element | Array.<string> <optional>
 Identifies the page or column items that will be included in the request. It can be a jQuery selector, jQuery object, Element, 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 - x20 string <optional>
 These properties are moved out of the p_json object and sent as x01 - x20 scalar parameters.
f01 - f20 string | Array <optional>
 These properties are moved out of the p_json object and sent as f01 - f20 array parameters.
pOptions Object <optional>

An object that is used to set additional options to control the Ajax call including before and after processing. 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. See http://docs.jquery.com/

The following Application Express specific options are supported:

Properties
Name Type Attributes Description
refreshObject jQuery | Element | string <optional>
 A jQuery selector string, jQuery object, or Element that identifies the DOM element that the apex.event:apexbeforerefresh and apex.event:apexafterrefresh events are triggered on. If this option is not supplied these events are not triggered.
refreshObjectData Object | Array <optional>
 Only applies if the refreshObject option is given. Specifies extra data that is passed in the apex.event:apexbeforerefresh and apex.event:apexafterrefresh events 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 <optional>
 A no argument function that is called after the apex.event:apexbeforerefresh event has fired and before the actual Ajax call is made. This function can be used to clear the DOM or any other state maintained by the Element or component for which this Ajax request is being made.
loadingIndicator string | jQuery | Element | function <optional>
 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 object or Element. The loadingIndicator can also be a function that receives the loading indicator as a jQuery object, which it can use as is or modify or replace and attach to the DOM where appropriate. The function must return a reference to the jQuery loading indicator. For example: 
function( pLoadingIndicator ) {
    return pLoadingIndicator.prependTo(
        apex.jQuery( "td.shuttleControl", gShuttle) );
}
loadingIndicatorPosition string <optional>
 One of the following 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 <optional>
 An object specifying the name of a queue and queue action. For example: 
{
    name: "updateList",
    action: "replace"
}

If no queue option is given the request is made right away without regard to any previous requests.

The name property specifies the name of the queue to add this request to.

The action property can be one of "wait" (the default), "replace", "lazyWrite".

  • 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: This action 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 jQuery | Element <optional>
 The target element (DOM element or jQuery Selector) that this request pertains to. This is used to get session state context from the enclosing region. This option must be provided if pageItems property of pData contains any column items.
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.
Type
Promise
Example

This example demonstrates an Ajax call to 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. 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
    }
} );

(static) url(pDataopt, pPageopt) → {string}

This function returns a URL to issue a GET request to the current page or page specified in pPage.

Parameters:
Name Type Attributes Description
pData Object <optional>
 Optional object that is used to set additional values which are included into the URL. The special property 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>
 The ID of the page to issue a GET request for. The default is the current page.
Returns:
The URL to issue a GET request.
Type
string
Example

This example gets 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"
} );