The APEX_JAVASCRIPT
package provides utility functions for adding dynamic JavaScript code to HTTP output. This package is usually used for plug-in development.
Topics:
This function returns the attribute and the attribute's escaped text surrounded by double quotes.
Note:
This function does not escape HTML tags. It only prevents HTML tags from breaking the JavaScript object attribute assignment. To prevent XSS (cross site scripting) attacks, you must also callSYS.HTF.ESCAPE_SC
to prevent embedded JavaScript code from being executed when you inject the string into the HTML page.APEX_JAVASCRIPT.ADD_ATTRIBUTE ( p_name IN VARCHAR2, p_value IN VARCHAR2, p_omit_null IN BOOLEAN:=TRUE, p_add_comma IN BOOLEAN:=TRUE) RETURN VARCHAR2;
Table 9-1 describes the parameters available in the ADD_ATTRIBUTE
function signature 1.
Table 9-1 ADD_ATTRIBUTE Signature 1 Parameters
Parameter | Description |
---|---|
|
Name of the JavaScript object attribute. |
|
Text to be assigned to the JavaScript object attribute. |
|
If set to TRUE and |
|
If set to TRUE, a trailing comma is added when a value is returned. |
Adds a call to the addEmployee
JavaScript function and passes in a JavaScript object with different attribute values. The output of this call will look like:
addEmployee( {"FirstName":"John", "LastName":"Doe", "Salary":2531.29, "Birthday":new Date(1970,1,15,0,0,0), "isSalesman":true });
As the last attribute you should use the parameter combination FALSE (p_omit_null
), FALSE (p_add_comma
) so that the last attribute is always generated. This avoids that you have to check for the other parameters if a trailing comma should be added or not.
apex_javascript.add_onload_code ( 'addEmployee('|| '{'|| apex_javascript.add_attribute('FirstName', sys.htf.escape_sc(l_first_name))|| apex_javascript.add_attribute('LastName', sys.htf.escape_sc(l_last_name))|| apex_javascript.add_attribute('Salary', l_salary)|| apex_javascript.add_attribute('Birthday', l_birthday)|| apex_javascript.add_attribute('isSalesman', l_is_salesman, false, false)|| '});' );
This function returns the attribute and the attribute's number.
APEX_JAVASCRIPT.ADD_ATTRIBUTE ( p_name IN VARCHAR2, p_value IN NUMBER, p_omit_null IN BOOLEAN:=TRUE, p_add_comma IN BOOLEAN:=TRUE) RETURN VARCHAR2;
Table 9-2 describes the parameters available in the ADD_ATTRIBUTE
function signature 2.
Table 9-2 ADD_ATTRIBUTE Signature 2 Parameters
Parameter | Description |
---|---|
|
Name of the JavaScript object attribute. |
|
Number which should be assigned to the JavaScript object attribute. |
|
If set to TRUE and |
|
If set to TRUE, a trailing comma is added when a value is returned. |
See example for ADD_ATTRIBUTE Function Signature 1.
This function returns the attribute and a JavaScript boolean of true, false, or null.
APEX_JAVASCRIPT.ADD_ATTRIBUTE ( p_name IN VARCHAR2, p_value IN BOLLEAN, p_omit_null IN BOOLEAN:=TRUE, p_add_comma IN BOOLEAN:=TRUE) RETURN VARCHAR2;
Table 9-3 describes the parameters available in the ADD_ATTRIBUTE
function signature 3.
Table 9-3 ADD_ATTRIBUTE Signature 3 Parameters
Parameter | Description |
---|---|
|
Name of the JavaScript object attribute. |
|
Boolean assigned to the JavaScript object attribute. |
|
If |
|
If set to TRUE a trailing comma is added when a value is returned. |
See example for ADD_ATTRIBUTE Function Signature 1
This function returns the attribute and the attribute's date. If p_value is null the value null is returned.
APEX_JAVASCRIPT.ADD_ATTRIBUTE ( p_name IN VARCHAR2, p_value IN DATE, p_omit_null IN BOOLEAN:=TRUE, p_add_comma IN BOOLEAN:=TRUE) RETURN VARCHAR2;
Table 9-4 describes the parameters available in the ADD_ATTRIBUTE
function signature 4.
Table 9-4 ADD_ATTRIBUTE SIgnature 4 Parameters
Parameter | Description |
---|---|
|
Name of the JavaScript object attribute. |
|
Date assigned to the JavaScript object attribute. |
|
If |
|
If set to TRUE a trailing comma is added when a value is returned. |
See example for ADD_ATTRIBUTE Function Signature 1
This procedure adds a code snippet that is included inline into the HTML output. For example, you can use this procedure to add new functions or global variable declarations. If you want to execute code you should use ADD_ONLOAD_CODE Procedure.
APEX_JAVASCRIPT.ADD_INLINE_CODE ( p_code IN VARCHAR2, p_key IN VARCHAR2 DEFAULT NULL);
Table 9-5 describes the parameters available in the ADD_INLINE_CODE
procedure.
Table 9-5 ADD_INLINE_CODE Parameters
Parameter | Description |
---|---|
|
JavaScript code snippet. For example: |
|
Identifier for the code snippet. If specified and a code snippet with the same name has already been added the new code snippet will be ignored. If |
The following example includes the JavaScript function initMySuperWidget
in the HTML output. If the plug-in is used multiple times on the page and the add_inline_code
is called multiple times, it is added once to the HTML output because all calls have the same value for p_key
.
apex_javascript.add_inline_code ( p_code => 'function initMySuperWidget(){'||chr(10)|| ' // do something'||chr(10)|| '};', p_key => 'my_super_widget_function' );
This procedure adds the script tag to load a JavaScript library. If a library has been added it will not be added a second time.
APEX_JAVASCRIPT.ADD_LIBRARY ( p_name IN VARCHAR2, p_directory IN VARCHAR2 DEFAULT wwv_flow.g_image_prefix||'javascript/', p_version IN VARCHAR2 DEFAULT c_apex_version, p_skip_extension IN BOOLEAN DEFAULT FALSE);
Table 9-6 describes the parameters available in the ADD_LIBRARY
procedure.
Table 9-6 ADD_LIBRARY Parameters
Parameter | Description |
---|---|
|
Name of the JavaScript file. Must not use |
|
Must have a trailing slash. |
|
Version identifier. It is recommended, but is optional, to add this to the library name. |
|
If TRUE the extension |
The following example includes the JavaScript library file my_library.1.2.min.js
in the directory specified by p_plugin.file_prefix
. This is the recommended syntax when you include your own JavaScript files in a plug-in.
apex_javascript.add_library ( p_name => 'mylibrary.1.2.min' p_directory => p_plugin.file_prefix, p_version => null );
This procedure adds a javascript code snippet to the HTML output which is executed by the onload event. If an entry with the same key exists it will be ignored. If p_key
is NULL the snippet will always be added.
APEX_JAVASCRIPT.ADD_ONLOAD_CODE ( p_code IN VARCHAR2, p_key IN VARCHAR2 DEFAULT NULL);
Table 9-7 describes the parameters available in the ADD_ONLOAD_CODE
procedure.
Table 9-7 ADD_ONLOAD_CODE Parameters
Parameter | Description |
---|---|
|
Javascript code snippet to be executed during the onload event. |
|
Any name to identify the specified code snippet. If specified, the code snippet is added if there has been no other call with the same |
Adds the JavaScript call initMySuperWidget()
to the onload buffer. If the plug-in is used multiple times on the page and the add_onload_code
is called multiple times, it is added once to the HTML output because all calls have the same value for p_key
apex_javascript.add_onload_code ( p_code => 'initMySuperWidget();' p_key => 'my_super_widget' );
This function returns the escaped text surrounded by double quotes. For example, this string could be returned "That\'s a test"
.
Note:
This function does not escape HTML tags. It only prevents HTML tags from breaking the JavaScript object attribute assignment. To prevent XSS (cross site scripting) attacks, you must also callSYS.HTF.ESCAPE_SC
to prevent embedded JavaScript code from being executed when you inject the string into the HTML page.APEX_JAVASCRIPT.ADD_VALUE ( p_value IN VARCHAR2, p_add_comma IN BOOLEAN :=TRUE) RETURN VARCHAR2;
Table 9-8 describes the parameters available in the ADD_VALUE
signature 1 function.
Table 9-8 ADD_VALUE Signature 1 Parameters
Parameter | Description |
---|---|
|
Text to be escaped and wrapped by double quotes. |
|
If |
This example adds some JavaScript code to the onload buffer. The value of p_item.attribute_01
is first escaped with htf.escape_sc
to prevent XSS attacks and then assigned to the JavaScript variable lTest
by calling apex_javascript.add_value
. Add_value
takes care of properly escaping the value and wrapping it into double quotes. Because commas are not wanted, p_add_comma
is set to FALSE.
apex_javascript.add_onload_code ( 'var lTest = '||apex_javascript.add_value(sys.htf.escape_sc(p_item.attribute_01), FALSE)||';'||chr(10)|| 'showMessage(lTest);' );
This function returns p_value
as JavaScript number, if p_value
is NULL the value null is returned.
APEX_JAVASCRIPT.ADD_VALUE ( p_value IN NUMBER, p_add_comma IN BOOLEAN :=TRUE) RETURN VARCHAR2;
Table 9-8 describes the parameters available in the ADD_VALUE
signature 2 function.
Table 9-9 ADD_VALUE Signature 2 Parameters
Parameter | Description |
---|---|
|
Number which should be returned as JavaScript number. |
|
If |
See example for ADD_VALUE Function Signature 1 .
This function returns p_value
as JavaScript boolean. If p_value
is NULL the value null is returned.
APEX_JAVASCRIPT.ADD_VALUE ( p_value IN BOOLEAN, p_add_comma IN BOOLEAN :=TRUE) RETURN VARCHAR2;
Table 9-10 describes the parameters available in the ADD_VALUE
signature 3 function.
Table 9-10 ADD_VALUE Signature 3 Parameters
Parameter | Description |
---|---|
|
Boolean which should be returned as JavaScript boolean. |
|
If |
See example for ADD_VALUE Function Signature 1 .
This function returns p_value
as JavaScript date object, if p_value
is NULL the value null is returned.
APEX_JAVASCRIPT.ADD_VALUE ( p_value IN NUMBER, p_add_comma IN BOOLEAN :=TRUE) RETURN VARCHAR2;
Table 9-11 describes the parameters available in the ADD_VALUE
signature 4 function.
Table 9-11 ADD_VALUE Signature 4 Parameters
Parameter | Description |
---|---|
|
Date which should be returned as JavaScript date object. |
|
If |
See example for ADD_VALUE Function Signature 1 .
This function escapes a text to be used in JavaScript. This function makes the following replacements:
Table 9-12 Table of Replacement Values
Replacement | After replacement |
---|---|
\ |
\\ |
/ |
\/ |
" |
\u0022 |
' |
\u0027 |
tab |
\t |
chr(10) |
\n |
Note:
This function does not escape HTML tags. It only prevents HTML tags from breaking the JavaScript object attribute assignment. To prevent XSS (cross site scripting) attacks, you must also callSYS.HTF.ESCAPE_SC
to prevent embedded JavaScript code from being executed when you inject the string into the HTML page.APEX_JAVASCRIPT.ESCAPE ( p_text IN VARCHAR2) RETURN VARCHAR2;
Table 9-13 describes the parameters available in the ESCAPE
function.
Adds some JavaScript code to the onload buffer. The value of p_item.attribute_01 is first escaped with htf.escape_sc to prevent XSS attacks and then escaped with apex_javascript.escape to prevent that special characters like a quote break the JavaScript code.
apex_javascript.add_onload_code ( 'var lTest = "'||apex_javascript.escape(sys.htf.escape_sc(p_item.attribute_01))||'";'||chr(10)|| 'showMessage(lTest);' );