Parameters:
Name | Type | Description |
---|---|---|
Text |
string | string to split into an array of chunks no bigger than 8000 chars. |
Returns:
- Type
- string | Array.<string>
Example
This example gets around the 32k size limit by sending text from text area item P1_TEXTAREA as the F01 array. A server process needs to loop over the apex_application.g_f01 array.
apex.gPageContext$.on( "apexpagesubmit", function() {
var $ = apex.jQuery,
form$ = $( "#wwvFlowForm" ),
f1 = apex.server.chunk( $v( "P1_TEXT" ) );
if ( !Array.isArray( f1 ) ) {
f1 = [f1];
}
f1.forEach( function( v ) {
form$.append( "<input type='hidden' name='f01' value='" + v + "'>" );
});
$s( "P1_TEXT", " " );
} );
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 object that contains the following attributes:
Properties
|
|||||||||||||||||
callback |
function |
<optional> |
A no argument function to be executed once script is loaded. |
Returns:
- 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 ... );
} );
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 Oracle APEX 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:
The following properties are treated as special: Properties
|
||||||||||||||||||||||||||||||||
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 https://docs.jquery.com/ The following Oracle APEX specific options are supported: Properties
|
Returns:
done
method is called
if the Ajax request completes successfully. This is called in the same cases and with the same arguments as
the success
callback function in pOptions
.
The promise fail
method is called if the Ajax request completes with an error
including internally detected Oracle APEX errors.
This is called in the same cases and with the same arguments 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.
In addition the promise fail
method can be be called
with textStatus
of "superseded" or "abort" depending on
queuing options. If the apex.event:apexbeforerefresh event cancels the request
the textStatus
is "cancel".
For an error response from the APEX server the textStatus
is "APEX"
and there may be more info in the errorThrown
argument.
- Type
- Promise
Examples
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( data ) {
// do something here
}
} );
See also the examples for apex.server.process because handling the response is the same for both the callback function and promise cases.
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:
- 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"
} );
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 Oracle APEX 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:
The following properties are treated special: Properties
|
||||||||||||||||||||||||||||||||
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 https://docs.jquery.com/ The following Oracle APEX specific options are supported: Properties
|
Returns:
done
method is called
if the Ajax request completes successfully. This is called in the same cases and with the same arguments as
the success
callback function in pOptions
.
The promise fail
method is called if the Ajax request completes with an error
including internally detected Oracle APEX errors.
This is called in the same cases and with the same arguments 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.
In addition the promise fail
method can be be called
with textStatus
of "superseded" or "abort" depending on
queuing options. If the apex.event:apexbeforerefresh event cancels the request
the textStatus
is "cancel".
For an error response from the APEX server the textStatus
is "APEX"
and there may be more info in the errorThrown
argument.
- Type
- Promise
Examples
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 data
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( data ) {
// do something here
},
error: function( jqXHR, textStatus, errorThrown ) {
// handle error
}
} );
This example is similar to the previous one except that the response is handled using the returned promise and the page items are given as an array.
var result = apex.server.process( "MY_PROCESS", {
x01: "test",
pageItems: ["P1_DEPTNO","P1_EMPNO"]
} );
result.done( function( data ) {
// do something here
} ).fail(function( jqXHR, textStatus, errorThrown ) {
// handle error
} ).always( function() {
// code that needs to run for both success and failure cases
} );
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:
- 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"
} );