3 Application Builder Concepts

How the Application Express Engine Renders and Processes Pages

The Application Express engine dynamically renders and processes pages based on data stored in Oracle database tables. To view a rendered version of your application, you request it from the Application Express engine. When you run an application, the Application Express engine relies on two processes:

• Show Page is the page rendering process. It assembles all the page attributes (including regions, items, and buttons) into a viewable HTML page.

• Accept Page performs page processing. It performs any computations, validations, processes, and branching.

When you request a page using a URL, the engine is running Show Page. When you submit a page, the Application Express engine is running Accept Page or performing page processing during which it saves the submitted values in the session cache and then performs any computations, validations, or processes.

Understanding Conditional Rendering and Processing

A condition is a small unit of logic that helps you control the display of regions, items, buttons, and tabs as well as the execution of processes, computations, and validations. For example, when you apply a condition to a button, the rendering engine evaluates the condition during the rendering (or Show Page) process. Whether the condition passes or fails determines if the page control (such as a button) displays.

You specify a condition by selecting a condition type. You can select a condition type when you first create the control or component, or by editing the control or component and making a selection from the Condition Type attribute. Depending upon the Condition Type you select, you enter the appropriate values in the Expressions fields. The condition evaluates to true or false based on the values you enter in the Expression fields.

To view a complete list of all available conditions for a given component or control, click the arrow to the right of the Condition Type list. Shortcuts to common selections appear directly beneath the list. If your condition requires an expression, enter it in the appropriate field.

The following sections offer examples of some commonly used condition types.

3,100,203

SELECT 1 FROM employees WHERE department_id = :P101_DEPTNO

NVL(:MY_ITEM,'NO') = 'YES'

Verifying User Identity

Authentication is the process of establishing users' identities before they can access an application. Authentication may require a user to enter a user name and password, or may involve the use of a digital certificate or a secure key.

Oracle Application Express supports modular authentication, making it easy to switch authentication methods when needed. You can establish a user's identity by selecting from a number of built-in authentication methods, or by using a wizard to create your own custom authentication approach.

Controlling Access to Controls and Components

While conditions control the rendering and processing of specific controls or components on a page, authorization schemes control user access. Authorization is a broad term for controlling access to resources based on user privileges.

Authorization schemes extend the security of your application's authentication scheme. You can specify an authorization scheme for an entire application, a page, or a specific page control such as a region, item, or button. For example, you could use an authorization scheme to selectively determine which tabs, regions, or navigation bar entries a user sees.

What Is a Session?

A session is a logical construct that establishes persistence (or stateful behavior) across page views. Each session is assigned a unique identifier. The Application Express engine uses this identifier (or session ID) to store and retrieve an application's working set of data (or session state) before and after each page view.

Because sessions are entirely independent of one another, any number of sessions can exist in the database at the same time. Also, because sessions persist in the database until purged by an administrator, a user can return to an old session and continue running an application long after first launching it. A user can also run multiple instances of an application simultaneously in different browser sessions.

Sessions are logically and physically distinct from Oracle database sessions used to service page requests. A user runs an application in a single Oracle Application Express session from log in to log out with a typical duration measured in minutes or hours. Each page requested during that session results in the Application Express engine creating or reusing an Oracle database session to access database resources. Often these database sessions last just a fraction of a second.

Understanding Session IDs

The Application Express engine establishes the identity (or anonymity) of the user for each page request and the session ID to fetch session state from the database. The most visible location of the session ID is in the URL for a page request. The session ID displays as the third parameter in the URL, for example:

http://apex.oracle.com/pls/apex/f?p=4350:1:220883407765693447

In this example, the session ID is 220883407765693447.

Another visible location is in the page's HTML POST data and indirectly in the contents of a session cookie. This cookie is sent by the Application Express engine during authentication and is maintained for the life of the application (or browser) session.

Oracle Application Express assigns new session IDs during authentication processing, records the authenticated user's identity with the session ID, and continually checks the session ID in each page request's URL or POST data with the session cookie and the session record in the database. These checks provide users with flexibility and security.

While the session ID is the key to session state, the session cookie (where applicable) and the session record safeguard the integrity of the session ID and the authentication status of the user.

Viewing Session State

The behavior of an Oracle Application Express application is usually driven by values in session state. For example, a button may display conditionally based on the value of an item session state. You can view the session state for a page by clicking Session on the Developer toolbar.

Referencing Session State

Referencing the value of an item is one of the most common examples of referencing session state. An item can be a field, a text area, a password, a select list, or a check box. Table 3-2 describes the supported syntax for referencing item values.

Setting Session State

When a user submits a page, the Application Express engine automatically stores values typed into fields (items) in session state. For example, suppose you have an application containing two pages. The first page of the application contains a form in which a user can enter a phone number. You defined this form by creating an item named P2_PhoneNo. On the second page, you want to display the information the user enters in the form.

When the page is submitted, Oracle Application Express captures the value entered in the phone number field and stores the value for future use. The phone number entered by the user can then be retrieved from session state by referencing the item associated with the field on the page.

Clearing Session State

As you develop your applications, you may find it useful to clear the cached value for specific items, all items on a page, all pages in an application, or the current user session. Clearing a cached value resets the value to null. The topics that follow offer specific examples of clearing session state.

Topics in this section include:

• Clearing Cache by Item

• Clearing Cache by Page

• Clearing Cache for an Entire Application

• Clearing Cache for the Current User Session

f?p=100:5:&APP_SESSION.::NO:MY_ITEM

f?p=100:5:&APP_SESSION.::NO:THE_EMPNO,THE_DEPTNO

f?p=6000:6003:&APP_SESSION.::NO:RP,6004,6014 

f?p=6000:6003:&APP_SESSION.::NO:6003:MY_ITEM:1234 

f?p=6000:6004:&APP_SESSION.::NO:6003:MY_ITEM1,MY_ITEM2,MY_ITEM3:1234,,5678 

f?p=App:Page:Session::NO:APP

f?p=6000:6004:12507785108488427528::NO:SESSION

About Bind Variable Syntax

You can use bind variables syntax anywhere in Application Express where you are using SQL or PL/SQL to reference session state of a specified item. For example:

SELECT * FROM employees WHERE last_name like '%' || :SEARCH_STRING || '%'

In this example, the search string is a page item. If the region type is defined as SQL Query, you can reference the value using standard SQL bind variable syntax. Using bind variables ensures that parsed representations of SQL queries are reused by the database, optimizing memory usage by the server.

When using bind variable syntax, remember the following rules:

• Bind variable names must correspond to an item name.

• Bind variable names are not case-sensitive.

• Bind variable names cannot be longer than 30 characters (that is, they must be a valid Oracle identifier).

  Although page item and application item names can be up to 255 characters, if you intend to use an application item within SQL using bind variable syntax, the item name must be 30 characters or less.

:MY_ITEM

SELECT last_name, job_id, salary
FROM employees
WHERE department_id = :THE_DEPTNO

IF :P1_JOB IS NOT NULL THEN
  INSERT INTO employees (employee_id, first_name, job_id) 
  VALUES (:P1_EMP_ID, :P1_NAME, :P1_JOB)
end if;

Understanding the URL that Displays for a Page

The URL that displays for each page indicates the location of Oracle Application Express and identifies the address of Oracle Application Express, the application ID, page number, and session ID. For example:

http://apex.oracle.com/pls/apex/f?p=4350:1:220883407765693447

This example indicates:

• apex.oracle.com is the URL of the server

• pls is the indicator to use the mod_plsql cartridge

• apex is the database access descriptor (DAD) name. The DAD describes how HTTP Server connects to the database server so that it can fulfill an HTTP request. The default value is apex.

• f?p= is a prefix used by Oracle Application Express

• 4350 is the application being called

• 1 is the page within the application to be displayed

• 220883407765693447 is the session number

Using f?p Syntax to Link Pages

You can create links between pages in your application using the following syntax:

f?p=App:Page:Session:Request:Debug:ClearCache:itemNames:itemValues:PrinterFriendly

Table 3-3 describes the arguments you can pass when using f?p syntax.

\123,45\

V('PRINTER_FRIENDLY')

Although it is important to understand how f?p syntax works, you rarely have to construct this syntax yourself. Application Builder includes many wizards that automatically create these references for you. The following sections describe specific instances that utilize f?p syntax to link pages.

Calling a Page Using an Application and Page Alias

Application and page aliases must consist of valid Oracle identifiers, cannot contain any whitespace, and are not case-sensitive. The following example calls a page using an application and a page alias from within an application. It runs the page home of the application myapp and uses the current session ID.

f?p=myapp:home:&APP_SESSION.

Application aliases must be unique within a workspace. If an application in a different workspace has the same application alias, use the &c argument to specify the workspace name. For example:

f?p=common_alias:home:&APP_SESSION.&c=WORKSPACE_A

Calling a Page from a Button URL

When you create a button, you can specify a URL to redirect to when the user clicks the button. This example runs page 6001 of application 6000 and uses the current session ID.

f?p=6000:6001:&APP_SESSION.

Note that this is only one approach to using a button. This method bypasses page submission and acts as a hyperlink on the page. Another method is to submit the page first. In that approach, clicking the button submits the page for processing, allowing forms to be submitted and session state to be saved.

Facilitating Bookmarks by Using Zero as the Session ID

If the pages within an application are public and do not require authentication, you make it easier for application users to bookmark pages by using zero as the session ID.

Application pages that do not require authentication can be accessed with "f?p" URLs where the session ID is zero (that is, the single digit 0). When you request a page by either entering the URL in the browser or by clicking on a link having 0 for the session ID, the Application Express engine assigns a new session ID and sends a session cookie containing this new session ID to your browser. As you navigate through the application's public pages, you will see that all generated links to public pages will contain 0 for the session ID and all branches to public pages will have new URLs that use 0 as the visible session ID. Behind the scenes, however, the Application Express engine actually uses the session ID in the cookie as the actual session ID to locate session state.

This feature is useful when you want to hide the actual session ID. By hiding the session ID, you enable users to bookmark pages without needing to include the session ID in the bookmark link. As an added benefit, using zero as the session ID also keeps the actual session ID hidden from search engines.

In order to use zero as the session ID in your application, you have to generate at least one link having a zero session ID. The use of this first link starts the zero session ID mechanism. One approach would be to provide a single static link with a zero session ID on the application home page. For example, where you might normally code the link to page 2 as f?p=&APP_ID.:2:&APP_SESSION, you would code f?p=&APP_ID.:2:0.

Using Substitution Strings

You can use substitution strings in Application Builder in the following ways:

• Include a substitution string within a template to reference component values

• Reference page or application items using &ITEM. syntax

• Use built-in substitution strings to achieve a specific type of functionality

Special substitution strings available within a template are denoted by the number symbol (#). For example:

#ABC#

To reference page or application items using substitution variables:

1. Precede the item name with an ampersand (&).

2. Append a period (.) to the item name.

For example, you would refer to an application item named F101_X in an HTML region, a region title, an item label, or in any of numerous other contexts in which static text is used, for example:

&F101_X.

Notice the required trailing period. When the page is rendered, Application Express engine replaces value the substitution string with the value of item F101_X.

About Built-in Substitution Strings

Application Builder supports a number of built-in substitution strings. You may need to reference these values to achieve specific types of functionality.

The following sections describe these substitution strings, when to use them, and what supported syntax is currently available. Note that bind variable :USER has special meaning within the database. Also, the term Direct PL/SQL refers to PL/SQL that can be used in stored database objects such as procedures and functions.

Topics in this section include:

• APP_ALIAS

• APP_ID

• APP_IMAGES

• APP_PAGE_ID

• APP_SESSION

• APP_UNIQUE_PAGE_ID

• APP_USER

• AUTHENTICATED_URL_PREFIX

• BROWSER_LANGUAGE

• CURRENT_PARENT_TAB_TEXT

• DEBUG

• HOME_LINK

• LOGIN_URL

• IMAGE_PREFIX

• Application Express SCHEMA OWNER

• PRINTER_FRIENDLY

• LOGOUT_URL

• PROXY_SERVER

• PUBLIC_URL_PREFIX

• REQUEST

• SQLERRM

• SYSDATE_YYYYMMDD

• WORKSPACE_IMAGES

f?p=ABC:1:&APP_SESSION.

Click me to go to page 1 <a href="f?p=&APP_ALIAS.:1:&APP_SESSION."> of the current application</a>

f?p=&APP_ID.:40:&APP_SESSION.

f?p=&APP_ID.:&APP_PAGE_ID.:&APP_SESSION.

SELECT 'f?p=100:1:'||:APP_SESSION||':'||:APP_UNIQUE_PAGE_ID||
    ':::P1_EMPNO:'||employee_id,
   first_name,
    job_id
FROM employees

f?p=100:1:&APP_SESSION.::&DEBUG

APEX_APPLICATION.G_FLOW_SCHEMA_OWNER

APEX_APPLICATION.G_PROXY_SERVER

f?p=100:1:&APP_SESSION.:GO

IF V ('REQUEST') = 'GO' THEN
   htp.p('hello');
END IF;

#SQLERRM#