Skip Headers
Oracle® Application Express API Reference
Release 4.2 for Oracle Database 12c

E17963-06
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 next page
Next
PDF · Mobi · ePub

1 APEX_APPLICATION

The APEX_APPLICATION package is a PL/SQL package that implements the Oracle Application Express rendering engine. You can use this package to take advantage of many global variables. Table 1-1 describes the global variables available in the APEX_APPLICATION package.

Table 1-1 Global Variables Available in APEX_APPLICATION

Global Variable Description

G_USER

Specifies the currently logged in user.

G_FLOW_ID

Specifies the ID of the currently running application.

G_FLOW_STEP_ID

Specifies the ID of the currently running page.

G_FLOW_OWNER

Specifies the schema to parse for the currently running application.

G_REQUEST

Specifies the value of the request variable most recently passed to or set within the show or accept modules.

G_BROWSER_LANGUAGE

Refers to the web browser's current language preference.

G_DEBUG

Refers to whether debugging is currently switched on or off. Valid values for the DEBUG flag are 'Yes' or 'No'. Turning debug on shows details about application processing.

G_HOME_LINK

Refers to the home page of an application. The Application Express engine redirects to this location if no page is given and if no alternative page is dictated by the authentication scheme's logic.

G_LOGIN_URL

Used to display a link to a login page for users that are not currently logged in.

G_IMAGE_PREFIX

Refers to the virtual path the web server uses to point to the images directory distributed with Oracle Application Express.

G_FLOW_SCHEMA_OWNER

Refers to the owner of the Application Express schema.

G_PRINTER_FRIENDLY

Refers to whether the Application Express engine is running in print view mode. This setting can be referenced in conditions to eliminate elements not desired in a printed document from a page.

G_PROXY_SERVER

Refers to the application attribute 'Proxy Server'.

G_SYSDATE

Refers to the current date on the database server. this uses the DATE DATATYPE.

G_PUBLIC_USER

Refers to the Oracle schema used to connect to the database through the database access descriptor (DAD).

G_GLOBAL_NOTIFICATION

Specifies the application's global notification attribute.


Topics:


Referencing Arrays

Items are typically HTML form elements such as text fields, select lists, and check boxes. When you create a new form item using a wizard, the wizard uses a standard naming format. The naming format provides a handle so you can retrieve the value of the item later on.

To create your own items, you can access them after a page is submitted by referencing APEX_APPLICATION.G_F01 to APEX_APPLICATION.G_F50 arrays. You can create your own HTML form fields by providing the input parameters using the format F01, F02, F03 and so on. You can create up to 50 input parameters ranging from F01 to F50, for example:

<INPUT TYPE="text" NAME="F01" SIZE="32" MAXLENGTH="32" VALUE="some value">
 
<TEXTAREA NAME="F02" ROWS=4 COLS=90 WRAP="VIRTUAL">this is the example of a text area.</TEXTAREA>
 
<SELECT NAME="F03" SIZE="1">
<OPTION VALUE="abc">abc
<OPTION VALUE="123">123
</SELECT> 

Because the F01 to F50 input items are declared as PL/SQL arrays, you can have multiple items named the same value. For example:

<INPUT TYPE="text" NAME="F01" SIZE="32" MAXLENGTH="32" VALUE="array element 1">
<INPUT TYPE="text" NAME="F01" SIZE="32" MAXLENGTH="32" VALUE="array element 2">
<INPUT TYPE="text" NAME="F01" SIZE="32" MAXLENGTH="32" VALUE="array element 3">

Note that following PL/SQL code produces the same HTML as show in the previous example.

FOR i IN 1..3 LOOP
APEX_ITEM.TEXT(P_IDX        => 1,
   p_value      =>'array element '||i ,
   p_size       =>32,
   p_maxlength  =>32);
END LOOP;

Referencing Values Within an On Submit Process

You can reference the values posted by an HTML form using the PL/SQL variable APEX_APPLICATION.G_F01 to APEX_APPLICATION.G_F50. Because this element is an array, you can reference values directly, for example:

FOR i IN 1..APEX_APPLICATION.G_F01.COUNT LOOP 
    htp.p('element '||I||' has a value of '||APEX_APPLICATION.G_F01(i)); 
END LOOP;

Note that check boxes displayed using APEX_ITEM.CHECKBOX only contain values in the APEX_APPLICATION arrays for those rows which are checked. Unlike other items (TEXT, TEXTAREA, and DATE_POPUP) which can contain an entry in the corresponding APEX_APPLICATION array for every row submitted, a check box only has an entry in the APEX_APPLICATION array if it is selected.


Converting an Array to a Single Value

You can also use Oracle Application Express public utility functions to convert an array into a single value. The resulting string value is a colon-separated list of the array element values. For example:

htp.p(APEX_UTIL.TABLE_TO_STRING(APEX_APPLICATION.G_F01));

This function enables you to reference G_F01 to G_F50 values in an application process that performs actions on data. The following sample process demonstrates how values are inserted into a table:

INSERT INTO my_table (my_column) VALUES 
APEX_UTIL.TABLE_TO_STRING(APEX_APPLICATION.G_F01)

HELP Procedure

This function outputs page and item level help text as formatted HTML. You can also use it to customize how help information is displayed in your application.

Syntax

APEX_APPLICATION.HELP (
    p_request        IN VARCHAR2 DEFAULT NULL,
    p_flow_id        IN VARCHAR2 DEFAULT NULL,
    p_flow_step_id   IN VARCHAR2 DEFAULT NULL,
    p_show_item_help IN VARCHAR2 DEFAULT 'YES',
    p_show_regions   IN VARCHAR2 DEFAULT 'YES',
    p_before_page_html     IN VARCHAR2 DEFAULT '<p>',
    p_after_page_html      IN VARCHAR2 DEFAULT NULL,
    p_before_region_html   IN VARCHAR2 DEFAULT NULL,
    p_after_region_html    IN VARCHAR2 DEFAULT '</td></tr></table></p>',
    p_before_prompt_html   IN VARCHAR2 DEFAULT '<p><b>',
    p_after_prompt_html    IN VARCHAR2 DEFAULT '</b></p>:&nbsp;',
    p_before_item_html     IN VARCHAR2 DEFAULT NULL,
    p_after_item_html      IN VARCHAR2 DEFAULT NULL);

Parameters

Table 1-2 describes the parameters available in the HELP procedure.

Table 1-2 HELP Parameters

Parameter Description

p_request

Not used.

p_flow_id

The application ID that contains the page or item level help you want to output.

p_flow_step_id

The page ID that contains the page or item level help you want to display.

p_show_item_help

Flag to determine if item level help is output. If this parameter is supplied, the value must be either 'YES' or 'NO', if not the default value is 'YES'.

p_show_regions

Flag to determine if region headers are output (for regions containing page items). If this parameter is supplied, the value must be either 'YES' or 'NO', if not the default value is 'YES'.

p_before_page_html

Use this parameter to include HTML between the page level help text and item level help text.

p_after_page_html

Use this parameter to include HTML at the bottom of the output, after all other help.

p_before_region_html

Use this parameter to include HTML before every region section. Note this parameter is ignored if p_show_regions is set to 'NO'.

p_after_region_html

Use this parameter to include HTML after every region section. Note this parameter is ignored if p_show_regions is set to 'NO'.

p_before_prompt_html

Use this parameter to include HTML before every item label for item level help. Note this parameter is ignored if p_show_item_help is set to 'NO'.

p_after_prompt_html

Use this parameter to include HTML after every item label for item level help. Note this parameter is ignored if p_show_item_help is set to 'NO'.

p_before_item_html

Use this parameter to include HTML before every item help text for item level help. Note this parameter is ignored if p_show_item_help is set to 'NO'.

p_after_item_html

Use this parameter to include HTML after every item help text for item level help. Note this parameter is ignored if p_show_item_help is set to 'NO'.


Example

The following example shows how to use the APEX_APPLICATION.HELP procedure to customize how help information is displayed.

In this example, the p_flow_step_id parameter is set to :REQUEST, which means that a page ID specified in the REQUEST section of the URL controls which page's help information to display (see note after example for full details on how this can be achieved).

Also, the help display has been customized so that the region sub-header now has a different color (through the p_before_region_html parameter) and also the ':' has been removed that appeared by default after every item prompt (through the p_after_prompt_html parameter).

APEX_APPLICATION.HELP(
    p_flow_id => :APP_ID,
    p_flow_step_id => :REQUEST,
    p_before_region_html => '<p><br/><table bgcolor="#A3BED8" width="100%"><tr><td><b>',
    p_after_prompt_html  => '</b></p>&nbsp;&nbsp;');

To implement this type of call in your application, you can do the following:

  1. Create a page that will be your application help page.

  2. Create a region of type 'PL/SQL Dynamic Content' and add the APEX_APPLICATION.HELP call as PL/SQL Source.

  3. Then you can add a 'Navigation Bar' link to this page, ensuring that the REQUEST value set in the link is &APP_PAGE_ID.


STOP_APEX_ENGINE Procedure

This procedure signals the Application Express engine to stop further processing and immediately exit to avoid adding additional HTML code to the HTTP buffer.

Note:

This procedure raises the exception apex_application.e_stop_apex_engine internally. You must raise that exception again, if you use a WHEN OTHERS exception handler.

Syntax

APEX_APPLICATION.STOP_APEX_ENGINE

Parameters

None

Example 1

This example tells the browser to redirect to http://apex.oracle.com/ and immediately stops further processing.

owa_util.redirect_url('http://apex.oracle.com');
apex_application.stop_apex_engine;

Example 2

This example also tells the browser to redirect to http://apex.oracle.com/ and immediately stops further processing. But, this time the code also contains a WHEN OTHERS exception handler which deals with the apex_application.e_stop_apex_engine used by apex_application.stop_apex_engine.

begin
    ... code which can raise an exception ...
    owa_util.redirect_url('http://apex.oracle.com');
    apex_application.stop_apex_engine;
exception
    when apex_application.e_stop_apex_engine then
        raise; -- raise again the stop Application Express engine exception
    when others then
        ...; -- code to handle the exception
end;