Skip Headers
Oracle® Application Express API Reference
Release 4.2

E35127-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to current chapter
Up
Go to next page
Next
PDF · Mobi · ePub

13 APEX_JAVASCRIPT

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:


ADD_3RD_PARTY_LIBRARY_FILE Procedure

This procedure adds the script tag to load a 3rd party javascript library file and also takes into account the specified Content Delivery Network for the application. Supported libraries include: jQuery, jQueryUI, and jQuery Mobile.

Syntax

add_3rd_party_library_file ( 
    p_library in varchar2, 
    p_file_name in varchar2, 
    p_directory in varchar2 default null, 
    p_version in varchar2 default null ); 

Parameters

Table 13-1 describes the parameters available for the ADD_3RD_PARTY_LIBRARY_FILE procedure.

Table 13-1 ADD_3RD_PARTY_LIBRARY_FILE Parameters

Parameters Description

p_library

Use one of the c_library_* constants

p_file_name

Specifies the file name without version, .min and .js

p_directory

Directory where the file p_file_name is located (optional)

p_version

If no value is provided then the same version Application Express ships is used (optional)


Example

This example loads the JavaScript file of the Draggable feature of jQuery UI.

apex_javascript.add_3rd_party_library_file (
     p_library   =>apex_javascript.c_library_jquery_ui,
     p_file_name => 'jquery.ui.draggable' )

ADD_ATTRIBUTE Function Signature 1

This function returns the attribute and the attribute's escaped text surrounded by double quotation marks.

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 call SYS.HTF.ESCAPE_SC to prevent embedded JavaScript code from being executed when you inject the string into the HTML page.

Syntax

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;

Parameters

Table 13-2 describes the parameters available in the ADD_ATTRIBUTE function signature 1.

Table 13-2 ADD_ATTRIBUTE Signature 1 Parameters

Parameter Description

p_name

Name of the JavaScript object attribute.

p_value

Text to be assigned to the JavaScript object attribute.

p_omit_null

If set to TRUE and p_value is empty, returns NULL.

p_add_comma

If set to TRUE, a trailing comma is added when a value is returned.


Example

Adds a call to the addEmployee JavaScript function and passes in a JavaScript object with different attribute values. The output of this call looks 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)||
        '});' );

ADD_ATTRIBUTE Function Signature 2

This function returns the attribute and the attribute's number.

Syntax

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;

Parameters

Table 13-3 describes the parameters available in the ADD_ATTRIBUTE function signature 2.

Table 13-3 ADD_ATTRIBUTE Signature 2 Parameters

Parameter Description

p_name

Name of the JavaScript object attribute.

p_value

Number which should be assigned to the JavaScript object attribute.

p_omit_null

If set to TRUE and p_value is empty, returns NULL.

p_add_comma

If set to TRUE, a trailing comma is added when a value is returned.


Example

See example for ADD_ATTRIBUTE Function Signature 1.


ADD_ATTRIBUTE Function Signature 3

This function returns the attribute and a JavaScript boolean of true, false, or null.

Syntax

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;

Parameters

Table 13-4 describes the parameters available in the ADD_ATTRIBUTE function signature 3.

Table 13-4 ADD_ATTRIBUTE Signature 3 Parameters

Parameter Description

p_name

Name of the JavaScript object attribute.

p_value

Boolean assigned to the JavaScript object attribute.

p_omit_null

If p_omit_null is TRUE and p_value is NULL the function returns NULL.

p_add_comma

If set to TRUE a trailing comma is added when a value is returned.


Example

See example for ADD_ATTRIBUTE Function Signature 1


ADD_ATTRIBUTE Function Signature 4

This function returns the attribute and the attribute's date. If p_value is null the value null is returned.

Syntax

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;

Parameters

Table 13-5 describes the parameters available in the ADD_ATTRIBUTE function signature 4.

Table 13-5 ADD_ATTRIBUTE SIgnature 4 Parameters

Parameter Description

p_name

Name of the JavaScript object attribute.

p_value

Date assigned to the JavaScript object attribute.

p_omit_null

If p_omit_null is TRUE and p_value is NULL the function returns NULL.

p_add_comma

If set to TRUE a trailing comma is added when a value is returned.


Example

See example for ADD_ATTRIBUTE Function Signature 1


ADD_INLINE_CODE Procedure

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.

Syntax

APEX_JAVASCRIPT.ADD_INLINE_CODE (
    p_code       IN VARCHAR2,
    p_key        IN VARCHAR2 DEFAULT NULL);

Parameters

Table 13-6 describes the parameters available in the ADD_INLINE_CODE procedure.

Table 13-6 ADD_INLINE_CODE Parameters

Parameter Description

p_code

JavaScript code snippet. For example: $s('P1_TEST',123);

p_key

Identifier for the code snippet. If specified and a code snippet with the same name has already been added, the new code snippet is ignored. If p_key is NULL the snippet is always added.


Example

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

ADD_LIBRARY Procedure

This procedure adds the script tag to load a JavaScript library. If a library has been added, it is not added a second time.

Syntax

APEX_JAVASCRIPT.ADD_LIBRARY (
    p_name                   IN VARCHAR2,
    p_directory              IN VARCHAR2,
    p_version                IN VARCHAR2 DEFAULT NULL,
    p_check_to_add_minified  IN BOOLEAN DEFAULT FALSE,
    p_skip_extension         IN BOOLEAN  DEFAULT FALSE,
    p_ie_condition           IN VARCHAR2 DEFAULT NULL,
    p_key                    IN VARCHAR2 DEFAULT NULL);

Parameters

Table 13-7 describes the parameters available in the ADD_LIBRARY procedure.

Table 13-7 ADD_LIBRARY Parameters

Parameter Description

p_name

Name of the JavaScript file. Must not use .js when specifying.

p_directory

Directory where JavaScript library is loaded. Must have a trailing slash.

p_version

Version identifier.

p_check_to_add_minified

If TRUE, the procedure tests if it is appropriate to add .min extension and add it if appropriate. This is added if an application is not running in DEBUG mode, and omitted when in DEBUG mode.

p_skip_extension

If TRUE the extension .js is NOT added.

p_ie_condition

Condition which is used as Internet Explorer condition.

p_key

Name used to indicate if the library has already been loaded. If not specified, defaults to p_directory||p_name||p_version.


Example

The following example includes the JavaScript library file named my_library.1.2.min.js (if the application is not running in DEBUG mode), or my_library.1.2.js (if the application is running in DEBUG mode), from the directory specified by p_plugin.file_prefix. The addition of the .min extension if the application is not running in DEBUG mode is carried out because p_check_to_add_minified is set to true. Since p_skip_extension is not specified, this defaults to .js. Also, since p_key is not specified, the key defaults to p_plugin.file_prefix||mylibrary.1.2.

apex_javascript.add_library (
    p_name                  => 'mylibrary.1.2',
    p_directory             => p_plugin.file_prefix,
    p_check_to_add_minified => true );

ADD_ONLOAD_CODE Procedure

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 is ignored. If p_key is NULL the snippet is always added.

Syntax

APEX_JAVASCRIPT.ADD_ONLOAD_CODE (
    p_code           IN VARCHAR2,
    p_key            IN VARCHAR2 DEFAULT NULL);

Parameters

Table 13-8 describes the parameters available in the ADD_ONLOAD_CODE procedure.

Table 13-8 ADD_ONLOAD_CODE Parameters

Parameter Description

p_code

Javascript code snippet to be executed during the onload event.

p_key

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 p_key. If p_key is NULL the code snippet is always added.


Example

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

ADD_VALUE Function Signature 1

This function returns the escaped text surrounded by double quotation marks. 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 call SYS.HTF.ESCAPE_SC to prevent embedded JavaScript code from being executed when you inject the string into the HTML page.

Syntax

APEX_JAVASCRIPT.ADD_VALUE (
    p_value          IN VARCHAR2,
    p_add_comma      IN BOOLEAN :=TRUE)
RETURN VARCHAR2;

Parameters

Table 13-9 describes the parameters available in the ADD_VALUE signature 1 function.

Table 13-9 ADD_VALUE Signature 1 Parameters

Parameter Description

p_value

Text to be escaped and wrapped by double quotation marks.

p_add_comma

If p_add_comma is TRUE a trailing comma is added.


Example

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 with double quotation marks. 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);' );

ADD_VALUE Function Signature 2

This function returns p_value as JavaScript number, if p_value is NULL the value null is returned.

Syntax

APEX_JAVASCRIPT.ADD_VALUE (
    p_value          IN NUMBER,
    p_add_comma      IN BOOLEAN :=TRUE)
RETURN VARCHAR2;

Parameters

Table 13-9 describes the parameters available in the ADD_VALUE signature 2 function.

Table 13-10 ADD_VALUE Signature 2 Parameters

Parameter Description

p_value

Number which should be returned as JavaScript number.

p_add_comma

If p_add_comma is TRUE a trailing comma is added. Default is TRUE.


Example

See example for ADD_VALUE Function Signature 1 .


ADD_VALUE Function Signature 3

This function returns p_value as JavaScript boolean. If p_value is NULL the value null is returned.

Syntax

APEX_JAVASCRIPT.ADD_VALUE (
    p_value          IN BOOLEAN,
    p_add_comma      IN BOOLEAN :=TRUE)
RETURN VARCHAR2;

Parameters

Table 13-11 describes the parameters available in the ADD_VALUE signature 3 function.

Table 13-11 ADD_VALUE Signature 3 Parameters

Parameter Description

p_value

Boolean which should be returned as JavaScript boolean.

p_add_comma

If p_add_comma is TRUE a trailing comma is added. Default is TRUE.


Example

See example for ADD_VALUE Function Signature 1 .


ADD_VALUE Function Signature 4

This function returns p_value as JavaScript date object, if p_value is NULL the value null is returned.

Syntax

APEX_JAVASCRIPT.ADD_VALUE (
    p_value          IN NUMBER,
    p_add_comma      IN BOOLEAN :=TRUE)
RETURN VARCHAR2;

Parameters

Table 13-12 describes the parameters available in the ADD_VALUE signature 4 function.

Table 13-12 ADD_VALUE Signature 4 Parameters

Parameter Description

p_value

Date which should be returned as JavaScript date object.

p_add_comma

If p_add_comma is TRUE a trailing comma is added. Default is TRUE.


Example

See example for ADD_VALUE Function Signature 1 .


Escape Function

This function escapes text to be used in JavaScript. This function makes the following replacements:

Table 13-13 Table of Replacement Values

Replacement After replacement

<

\u003c

>

\u003e

\

\\

/

\/

"

\u0022

'

\u0027

tab

\t

chr(10)

\n


Note:

This function prevents HTML tags from breaking the JavaScript object attribute assignment and also escapes the HTML tags '<' and '>'. It does not escape other HTML tags, therefore to be sure to prevent XSS (cross site scripting) attacks, you must also call SYS.HTF.ESCAPE_SC to prevent embedded JavaScript code from being executed when you inject the string into the HTML page.

Syntax

APEX_JAVASCRIPT.ESCAPE (
    p_text  IN VARCHAR2)
RETURN VARCHAR2;

Parameters

Table 13-14 describes the parameters available in the ESCAPE function.

Table 13-14 ESCAPE Parameters

Parameter Description

p_text

Text to be escaped.


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 escaped with apex_javascript.escape to prevent that special characters like a quotation mark 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);' );