Application Builder Concepts in APEX

Application Builder Concepts

This section provides basic conceptual information about Application Builder. Use Application Builder to assemble an HTML interface (or application) on top of database objects such as tables and procedures. Each application is a collection of pages linked together using tabs, buttons, or hypertext links.
This section contains the following topics:

• What Is a Page?
  
• Understanding Page Processing and Page Rendering
  
• Understanding Session State Management
  
• Managing Session State Values
  
• Understanding URL Syntax
  
• Understanding Substitution Strings
  

See Also:

"Using Application Builder" and "Building an Application"

What Is a Page?

A page is the basic building block of an application. When you build an application in Application Builder, you create pages that contain user interface elements, such as tabs, lists, buttons, items, and regions.
You add controls to a page on the Page Definition.
To view the Page Definition of an existing page:

1. Navigate to the Workspace home page.
   
2. Click the Application Builder icon.
   
3. Select an application.
   
4. Select a page.
   The Page Definition appears and is divided into three main sections:
   
   • Page Rendering lists user interface controls and logic that are executed when a page is rendered. Page Rendering is the process of generating a page from the database. See "About Page Rendering".
     
   • Page Processing lists logic controls (such as computations and processes) that are evaluated and executed when the page is processed. See "About Page Processing".
     
   • Shared Components lists common components that can be used by one or more pages within an application. See "About Shared Components".
     

See Also:

"About the Page Definition" and "Editing a Page Definition"

Understanding Page Processing and Page Rendering

When you create an application in Application Builder, you link pages together using tabs, buttons, or hypertext links. Each page can have buttons and items and can include application logic. You can branch from one page to the next using conditional navigation, perform calculations and validations, and display reports, calendars, and charts. You can generate reports, charts, and forms using built-in wizards, static HTML, or deliver more custom rendering with PL/SQL programming.
Topics in this section include:

• How the Application Express Engine Renders and Processes Pages
  
• Understanding Conditional Rendering and Processing
  
• Verifying User Identity
  
• Controlling Access to Controls and Components
  

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.

Note:

Whether you use the Expression fields depends upon the selected condition type. Some condition types do not require values in either field, others require a value only for Expression 1, and other condition types require values in both fields. Although these fields are labeled "Expression 1" and "Expression 2", the values for a given condition type do not necessarily conform to any formal definition of the term expression. They are simply text values appropriate for the selected condition type.

Description of the illustration condition.gif

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.

See Also:

Appendix A, "Available Conditions" for a detailed listing of available condition types

Current Page in Expression 1

Current page in Expression 1 evaluates to true if the current page number is contained within the comma-delimited list of pages in Expression 1. For example:

3,100,203

If the current page is 100, then this condition evaluates to true and the condition passes.

Exists

Exists (SQL query returns at least one row) is expressed as a SQL query. If the query returns at least one row, then the condition evaluates as true. For example:

SELECT 1 FROM employees WHERE department_id = :P101_DEPTNO

This example references item P101_DEPTNO as a bind variable. You can use bind variables within application processes and SQL query regions to reference item session state. If one or more employees are in the department identified by the value of P101_DEPTNO, then the condition evaluates as true.

See Also:

"About Bind Variable Syntax"

PL/SQL Expression

Use PL/SQL Expression to specify an expression in valid PL/SQL syntax that evaluates to true or false. For example:

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

If the value of :MY_ITEM is Yes, as in the previous example, then the condition evaluates as true. If the value of :MY_ITEM is No, then the condition evaluates as false.

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.

See Also:

"Establishing User Identity Through Authentication" for more information

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.

See Also:

"Providing Security Through Authorization"

Understanding Session State Management

HTTP, the protocol over which HTML pages are most often delivered, is a stateless protocol. A Web browser is only connected to the server for as long as it takes to download a complete page. In addition, each page request is treated by the server as an independent event, unrelated to any page requests that happened previously or may occur in the future. This means that to access form values entered on one page on a subsequent page, some form of session state management needs to occur. Typically, when a user enters values into a form on one page, those values are not accessible on later pages. Oracle Application Express transparently maintains session state and provides developers with the ability to get and set session state values from any page in the application.
Topics in this section include:

• What Is a Session?
  
• Understanding Session IDs
  
• Referencing Session State
  

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.

See Also:

"Viewing Active Sessions"

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.

See Also:

"Understanding the URL that Displays for a Page"

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.

Description of the illustration d_toolbar.gif

See Also:

"About the Developer Toolbar"

About the Session State Page

The Session State page provides valuable information about the session in which the application is currently running. To locate a specific page, enter the page number in the page field and click Go. Table 3-1 describes the various types of information available on the Session State page.

Table 3-1 Information Available on the Session State Page

Heading	Description
Application	Identifies the application name, session ID, current user, workspace ID, and browser language.
Page Items	Identify attributes of the page item, including the application and page numbers, item name, how the item displays (hidden, popup, button, display only HTML), the item value in session state, and status. The Status column indicates the status of the session state. Available values include: I - Inserted U - Updated R - Reset
Application Items	Application items are items that do not reside on a page. Application items are session state variables without the associated user interface properties. See Also: "Understanding Application-Level Items" and "Understanding Substitution Strings" for information about referencing item values
Session State	Summarizes session state for the current session. Lists applicable application IDs, page numbers, item names, display type, item values, and display labels.

See Also:

"Managing Session State Values"

Managing Session State Values

When building interactive, data-driven Web applications, the ability to access and manage session state values is critical. In Oracle Application Express, session state is automatically managed for every page and easily referenced in static HTML or logic controls such as processes or validations.
Topics in this section include:

• Referencing Session State
  
• Setting Session State
  
• Clearing Session State
  
• About Bind Variable Syntax
  

See Also:

"Items" and "Referencing Item Values"

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.

Table 3-2 Syntax for Referencing Item Values

Type	Syntax	Description
SQL	:MY_ITEM	Standard bind variable syntax for items whose names are no longer than 30 characters. Use this syntax for references within a SQL query and within PL/SQL.
PL/SQL	V('MY_ITEM')	PL/SQL syntax referencing the item value using the V function. See Also: "Oracle Application Express APIs"
PL/SQL	NV('MY_NUMERIC_ITEM')	Standard PL/SQL syntax referencing the numeric item value using the NV function. See Also: "Oracle Application Express APIs"
Static text (exact)	&MY_ITEM.	Static text. Exact substitution.

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
  

Clearing Cache by Item

Clearing cache for a single item resets the value of the item to null. For example, you might use this approach to make sure a specific item's value is null when a page is prepared for rendering.
The following example uses standard f?p syntax to clear the cache for an item. This example calls page 5 of application 100. Placing MY_ITEM in the ClearCache position of the f?p syntax resets the value of MY_ITEM to NULL.

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

The following example resets the value of the items THE_EMPNO and THE_DEPTNO.

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

Clearing Cache by Page

Caching application items provides an effective way to maintain session state. However, there are occasions when you may want to clear the cache for all items on a page. For example, suppose you needed to clear all fields on a page when a user clicks a link that creates a new order. By clearing the cache for an entire page, you set the value of all items on the page to null.

Clearing Session Cache for Two Pages While Resetting Pagination

This example clears the session cache for two pages and resets pagination.

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

This example:

• Runs page 6003 of application 6000 and uses the current session ID
  
• Indicates to not show debug information (NO)
  
• Clears all values maintained by the current session's cache for items of pages 6004 and 6014
  
• Resets region pagination (RP) on page 6003 (the requested page)
  

See Also:

"Controlling Report Pagination"

Clearing Session Cache on a Page and Passing an Item Value

This example shows how to implement an update form. It clears existing information and sets the item's value (typically a primary key).

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

This example:

• Runs page 6003 of application 6000 and uses the current session ID
  
• Indicates to not show debug information (NO)
  
• Clears all values maintained by the current session's cache for items on page 6003
  
• Sets the session state of an item called MY_ITEM to the value 1234
  

Clearing Session Cache on a Page and Passing Values to Multiple Items

This example is similar to the previous example, except it passes values to multiple items.

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

This example:

• Runs page 6004 of application 6000 and uses the current session ID
  
• Clears the current session's cache for items on page 6003
  
• Indicates debug information should be hidden (NO)
  
• Sets the value of MY_ITEM1 to 1234, sets the value of MY_ITEM2 to null (indicated by the comma used as placeholder), and sets the value of MY_ITEM3 to 5678
  

Clearing Cache for an Entire Application

You can clear an application's cache by using f?p syntax and creating a Clear Cache argument using the keyword APP. For example:

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

Note:

Resetting the cache for an entire application does not restore the application to a completely reset state. For example, if an application includes on-new instance computations or on-new instance processes, the Application Express engine runs these computations and processes when the application session is created. Then, it processes the clear cache request and displays the requested page. To reset an application completely without a session ID (if no cookie is used to track the session ID), you must request it using a URL without a session ID, or by calling APEX_APPLICATION.CLEAR_APP_CACHE from another application. If the session ID is tracked using a cookie, you will need to logout to reset the state.

Clearing Cache for the Current User Session

Another approach to clearing an application's cache is to create a Clear Cache argument using the keyword SESSION. For example:

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.
  

Using Bind Variables in Regions Based on a SQL Query or LOV

If your region type is defined as a SQL Query, SQL Query (plsql function body returning SQL query), or list of values (LOV), you can reference session state using the following syntax:

:MY_ITEM

One common way to do this is to incorporate a session state variable in a WHERE clause. The following example shows how to bind the value of the item THE_DEPTNO into a region defined from a SQL Query.

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

See Also:

"Understanding Regions" for information about creating regions

Using Bind Variables in PL/SQL Procedures

For region types defined as a PL/SQL Procedure, regions are constructed using PL/SQL anonymous block syntax. In other words, the beginning and ending keywords are used to enclose the PL/SQL block. For example:

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;

In this example, the values of the employee_id, first_name, and job_id are populated by the values of P1_EMP_ID, P1_NAME, and P1_JOB.

Understanding URL Syntax

The URL that displays for each page identifies the location of Oracle Application Express, the address of Oracle Application Express, the application ID, the page number, and the session ID.
The application ID is a unique number that identifies each application. Similarly, the page number uniquely identifies each page. Applications and pages may also have alphanumeric aliases. Application aliases are unique within a workspace and page aliases are unique within each application. When you run an application, the Application Express engine generates a session number that serves as a key to the user's session state.
Topics in this section include:

• Understanding the URL that Displays for a Page
  
• Using f?p Syntax to Link Pages
  
• Calling a Page Using an Application and Page Alias
  
• Calling a Page from a Button URL
  
• Facilitating Bookmarks by Using Zero as the Session ID
  

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
  

See Also:

"About Publishing the Application URL"

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.

Table 3-3 f?p Syntax Arguments

Syntax	Description
App	Indicates an application ID or alphanumeric alias.
Page	Indicates a page number or alphanumeric alias.
Session	Identifies a session ID. You can reference a session ID to create hypertext links to other pages that maintain the same session state by passing the session number. You can reference the session ID using the syntax: Short substitution string: &SESSION. PL/SQL: V('SESSION') Bind variable: :APP_SESSION
Request	Sets the value of REQUEST. Each application button sets the value of REQUEST to the name of the button. This enables accept processing to reference the name of the button when a user clicks it. You can reference REQUEST using the syntax: Substitution string: &REQUEST. PL/SQL: V('REQUEST') Bind variable: :REQUEST
Debug	Displays application processing details. Valid values for the DEBUG flag are YES or NO. Setting this flag to YES displays details about application processing. You can reference the Debug flag using the following syntax: Short substitution string: &DEBUG. PL/SQL: V('DEBUG') Bind variable: :DEBUG See Also: "Debugging an Application"
ClearCache	Clears the cache. This sets the value of items to null. To clear cached items on a single page, specify the numeric page number. To clear cached items on multiple pages, use a comma-separated list of page numbers. Clearing a page's cache also resets any stateful processes on the page. Individual or comma-separated values can also include collection names to be reset or the keyword RP, which resets region pagination on the requested page. The keyword APP clears cache for all pages and all application-level items in the current application and removes sort preferences for the current user. The keyword SESSION achieves the same result as the APP keyword, but clears items associated with all applications that have been used in the current session. See Also: "Clearing Session State"
itemNames	Comma-delimited list of item names used to set session state with a URL.
itemValues	List of item values used to set session state within a URL. Item values cannot include colons, but can contain commas if enclosed with backslashes. To pass a comma in an item value, enclose the characters with backslashes. For example: \123,45\
PrinterFriendly	Determines if the page is being rendered in printer friendly mode. If PrinterFriendly is set to Yes, then the page is rendered in printer friendly mode. The value of PrinterFriendly can be used in rendering conditions to remove elements such as regions from the page to optimize printed output. You can reference the printer friendly preference by using the following syntax: V('PRINTER_FRIENDLY') When referenced, the Application Express engine will not display tabs or navigation bars, and all items will be displayed as text and not as form elements.

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.

See Also:

"Creating Buttons" and "APP_SESSION"

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.

Understanding Substitution Strings

You can use substitution strings within a page template or region source to replace a character string with another value. As you design your application and enable users to edit items, you use substitution strings to pass information.
Topics in this section include:

• Using Substitution Strings
  
• About Built-in Substitution Strings
  

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.

Determining Substitution String Usage within a Given Template

You can determine what template-specific substitution strings are supported in which templates by viewing the template definition. See "Editing Templates".

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
  

See Also:

• "Substitutions" for information about defining static substitution strings as an application attribute
  
• "Establishing User Identity Through Authentication" for information about authentication
  

APP_ALIAS

APP_ALIAS is an alphanumeric name for the current application. APP_ALIAS is different from the APP_ID in that the APP_ID must be unique over all workspaces and all applications hosted in one database. In contrast, APP_ALIAS must be unique within a workspace. For example, by using the same APP_ALIAS you can create the application, ABC, in two different workspaces. You can use APP_ALIAS almost anywhere APP_ID can be used. For example, f?p syntax can use an APP_ALIAS or an application ID as demonstrated in this example:

f?p=ABC:1:&APP_SESSION.

This example runs application ABC, page 1 using the current session.
Table 3-4 describes the supported syntax for referencing APP_ALIAS.

Table 3-4 APP_ALIAS Syntax

Reference Type	Syntax
Bind variable	:APP_ALIAS
PL/SQL	V('APP_ALIAS')
Substitution string	&APP_ALIAS.

The following is an HTML example:

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

APP_ID

APP_ID identifies the application ID of the currently executing application. Table 3-5 describes the supported syntax for referencing APP_ID.

Table 3-5 APP_ID Syntax

Reference Type	Syntax
Bind variable	:APP_ID
Direct PL/SQL	APEX_APPLICATION.G_FLOW_ID (A NUMBER)
PL/SQL	NV('APP_ID')
Substitution string	&APP_ID.

The following is an example of a substitution string reference:

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

APP_IMAGES

Use this substitution string to reference uploaded images, JavaScript, and cascading style sheets that are specific to a given application and are not shared over many applications. If you upload a file and make it specific to an application, then you must use this substitution string, or bind variable. Table 3-6 describes the supported syntax for referencing APP_IMAGES.

Table 3-6 APP_IMAGES Syntax

Reference Type	Syntax
Bind variable	:APP_IMAGES
Direct PL/SQL	Not available.
PL/SQL	V('APP_IMAGES')
Substitution string	&APP_IMAGES.
Template substitution	#APP_IMAGES#

See Also:

"IMAGE_PREFIX", "WORKSPACE_IMAGES", and "Managing Images"

APP_PAGE_ID

APP_PAGE_ID is the current application ID. For example, if your application was on page 3, then the result would be 3. Using this syntax is useful when writing application components that need to work generically in multiple applications. Table 3-7 describes the supported syntax for referencing APP_PAGE_ID.

Table 3-7 APP_PAGE_ID Syntax

Reference Type	Syntax
Bind variable	:APP_PAGE_ID
PL/SQL	:APP_PAGE_ID
PL/SQL and Direct PL	NV('APP_PAGE_ID')
Substitution string	&APP_PAGE_ID.

The following is an example of a substitution string reference:

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

APP_SESSION

APP_SESSION is one of the most commonly used built-in substitution strings. You can use this substitution string to create hypertext links between application pages that maintain a session state by passing the session number. Note that you can also use the substitution string SESSION in place of APP_SESSION. Table 3-8 describes the supported syntax for referencing APP_SESSION.

Table 3-8 APP_SESSION Syntax

Reference Type	Syntax
Bind variable	:APP_SESSION
PL/SQL	V('APP_SESSION')
Short PL/SQL	V('SESSION')
Substitution string	&APP_SESSION.

Consider the following examples:

• From within an HTML region:
  

  <a href="f?p=100:5:&APP_SESSION.">click me</a> 
  
  

• Using PL/SQL:
  

  htf.anchor('f?p=100:5:'||V('APP_SESSION'),'click me');
  
  

• Using a SQL query:
  

  SELECT htf.anchor('f?p=100:5:'||:APP_SESSION,'clickme') FROM DUAL;
  
  

APP_UNIQUE_PAGE_ID

APP_UNIQUE_PAGE_ID is an integer generated from an Oracle sequence which is unique for each page view. This number is used by applications to prevent duplicate page submissions and can be used for other purposes. For example, if you want to make a unique URL to avoid browser caching issues, you can embed this number in the request or debug column in calls to the f procedure. Table 3-9 describes the supported syntax for referencing APP_UNIQUE_PAGE_ID.

Table 3-9 APP_UNIQUE_PAGE_ID Syntax

Reference Type	Syntax
Bind variable	:APP_UNIQUE_PAGE_ID
PL/SQL	V('APP_UNIQUE_PAGE_ID')
Substitution string	&APP_UNIQUE_PAGE_ID.

The following is an HTML example:

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

Note the use of the APP_UNIQUE_PAGE_ID in the request column. This makes this URL unique and may avoid excessive browser caching problems.

APP_USER

APP_USER is the current user running the application. Depending upon your authentication model, the value of the user is set differently. If the application is running using database authentication, then the value of the user is the same as the database pseudo column USER. If the application uses an authentication scheme that requires the user to authenticate, the value of APP_USER is set by the authentication scheme, usually to the user name used during authentication. Table 3-10 describes the supported syntax for referencing APP_USER.

Table 3-10 APP_USER Syntax

Reference Type	Syntax
Bind variable	:APP_USER
PL/SQL	V('APP_USER')
Substitution string	&APP_USER.

Consider the following examples:

• From within an HTML region:
  

  Hello you are logged in as &APP_USER.
  
  

• Using PL/SQL:
  

  htp.p('Hello you are logged in as'||V('APP_USER')); 
  
  

• As a bind variable:
  

  SELECT * FROM some_table WHERE user_id = :APP_USER
  
  

  See Also:

  "Authentication" for information about the Public User attribute

AUTHENTICATED_URL_PREFIX

This application-level attribute identifies a valid authenticated prefix (that is, a logged in URL prefix). You can use a relative path or a full path beginning with http. This item is useful if your application can be run in both authenticated (logged in) and public (not logged in) modes. You can use AUTHENTICATED_URL_PREFIX to construct a link to an authenticated page. This item is most useful when using basic database authentication because changes to the URL can require authentication. Table 3-11 describes the supported syntax for referencing AUTHENTICATED_URL_PREFIX.

Table 3-11 AUTHENTICATED_URL_PREFIX Syntax

Reference Type	Syntax
Bind variable	:AUTHENTICATED_URL_PREFIX
PL/SQL	V('AUTHENTICATED_URL_PREFIX')
Substitution string	&AUTHENTICATED_URL_PREFIX.

BROWSER_LANGUAGE

BROWSER_LANGUAGE refers to the Web browser's current language preference. Table 3-12 describes the supported syntax for referencing BROWSER_LANGUAGE.

Table 3-12 BROWSER_LANGUAGE Syntax

Reference Type	Syntax
Bind variable	:BROWSER_LANGUAGE
Direct PL/SQL	APEX_APPLICATION.G_BROWSER_LANGUAGE
PL/SQL	V('BROWSER_LANGUAGE')
Substitution string	:BROWSER_LANGUAGE.
Substitution string	&BROWSER_LANGUAGE.

CURRENT_PARENT_TAB_TEXT

CURRENT_PARENT_TAB_TEXT is most useful in page templates, but is only relevant for applications that use two-level tabs (that is, parent and standard tabs). Use this string to reference the parent tab label. This substitution string enables you to repeat the currently selected parent tab within the page template. Table 3-13 describes the supported syntax for referencing CURRENT_PARENT_TAB_TEXT.

Table 3-13 CURRENT_PARENT_TAB_TEXT Syntax

Reference Type	Syntax
Bind variable	Not Available.
Substitution string	&CURRENT_PARENT_TAB_TEXT.

DEBUG

Valid values for the DEBUG flag are Yes or No. Turning debug on shows details about application processing. If you write your own custom code, you may want to generate debug information only if the debug mode is set to Yes. Table 3-14 describes the supported syntax for referencing DEBUG.

Table 3-14 DEBUG Syntax

Reference Type	Syntax
Bind variable	:DEBUG
Direct PL/SQL	APEX_APPLICATION.G_DEBUG
PL/SQL	V('DEBUG')
Substitution string	&DEBUG.

The following is an example of a substitution string reference that preserves the current value of DEBUG:

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

HOME_LINK

HOME_LINK is the home page of an application. The Application Express engine will redirect to this location if no page is given and if no alternative page is dictated by the authentication scheme's logic. You define the Home Link on the Application Attributes page.
Table 3-15 describes the supported syntax for referencing HOME_LINK.

Table 3-15 HOME_LINK Syntax

Reference Type	Syntax
Direct PL/SQL	APEX_APPLICATION.G_HOME_LINK
PL/SQL	V('HOME_LINK')
Template Reference	#HOME_LINK#
Substitution String	&HOME_LINK.

See Also:

"Authentication" for information about the Home Link attribute

LOGIN_URL

Use LOGIN_URL to display a link to a login page for users that are not currently logged in. Table 3-16 describes the supported syntax for LOGIN_URL.

See Also:

"Authentication" and "About the Security Attributes Page"

Table 3-16 LOGIN_URL Syntax

Reference Type	Syntax
Bind variable	:LOGIN_URL
Direct PL/SQL	APEX_APPLICATION.G_LOGIN_URL
PL/SQL	V('LOGIN_URL')
Substitution string	&LOGIN_URL.
Template Substitution	#LOGIN_URL#

IMAGE_PREFIX

The value of IMAGE_PREFIX determines the virtual path the Web server uses to point to the images directory distributed with Oracle Application Express. If you want to reference uploaded images, use WORKSPACE_IMAGES and APP_IMAGES. Table 3-17 describes the supported syntax for referencing IMAGE_PREFIX.

See Also:

"APP_IMAGES","WORKSPACE_IMAGES", and "Configuring the Application Definition"

Table 3-17 IMAGE_PREFIX Syntax

Reference Type	Syntax
Bind variable	:IMAGE_PREFIX
Direct PL/SQL	APEX_APPLICATION.G_IMAGE_PREFIX
PL/SQL	V('IMAGE_PREFIX')
Substitution string	&IMAGE_PREFIX.
Template Substitution	#IMAGE_PREFIX#

Application Express SCHEMA OWNER

If you are generating calls to applications from within your PL/SQL code, you may need to reference the owner of the Oracle Application Express schema. The following describes the correct syntax for a direct PL/SQL reference:

APEX_APPLICATION.G_FLOW_SCHEMA_OWNER

You may also use #FLOW_OWNER# to reference this value in SQL queries and PL/SQL (for example, in a region or a process).

PRINTER_FRIENDLY

The value of PRINTER_FRIENDLY determines if 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. Table 3-18 describes the supported syntax for referencing PRINTER_FRIENDLY.

Table 3-18 PRINTER_FRIENDLY Syntax

Reference Type	Syntax
Direct PL/SQL	APEX_APPLICATION.G_PRINTER_FRIENDLY (VARCHAR2 DATATYPE)
PL/SQL	V('PRINTER_FRIENDLY')
Substitution string	&PRINTER_FRIENDLY.

LOGOUT_URL

LOGOUT_URL is an application-level attribute used to identify the logout URL. This is a URL that navigates the user to a logout page or optionally directly logs out a user. To create a logout navigation bar entry, add a trailing period to &LOGOUT_URL (&LOGOUT_URL.). If you are coding a page template, use #LOGOUT_URL#. Table 3-19 describes the supported syntax for referencing LOGOUT_URL.

Table 3-19 LOGOUT_URL Syntax

Reference Type	Syntax
Bind variable	:LOGOUT_URL
PL/SQL	V('LOGOUT_URL')
Substitution string	&LOGOUT_URL.
Template substitution	#LOGOUT_URL#

PROXY_SERVER

PROXY_SERVER is an application attribute. The attribute may be used by regions whose source comes from a URL. The following is the correct syntax for a direct PL/SQL reference used when you are writing PL/SQL to access remote Web servers from within the database (for example, when using the utl_http package shipped with the database).

APEX_APPLICATION.G_PROXY_SERVER

PUBLIC_URL_PREFIX

PUBLIC_URL_PREFIX is an application-level attribute that identifies a URL to toggle out of a logged in mode to a public view. Table 3-20 describes the supported syntax for referencing PUBLIC_URL_PREFIX.

Table 3-20 PUBLIC_URL_PREFIX Syntax

Reference Type	Syntax
Bind variable	:PUBLIC_URL_PREFIX
PL/SQL	V('PUBLIC_URL_PREFIX')
Substitution string	&PUBLIC_URL_PREFIX.
Template substitution	#PUBLIC_URL_PREFIX#

REQUEST

Each application button sets the value of REQUEST to the name of the button or to the request value attribute associated with the button. This enables accept processing to reference the name of the button when a user clicks it. In the f?p syntax, REQUEST may be set using the fourth argument.

Referencing the Value of REQUEST

REQUEST is typically referenced during Accept processing (that is, the processing that occurs when you post a page). Table 3-21 describes the supported syntax for referencing REQUEST.

Table 3-21 REQUEST Syntax

Reference Type	Syntax
Bind variable	:REQUEST
Direct PL/SQL	APEX_APPLICATION.G_REQUEST
PL/SQL	V('REQUEST')
Substitution string	&REQUEST &REQUEST. (exact syntax match)

Scope and Value of REQUEST for Posted Pages

When you post a page, you initiate Accept processing. Accept processing consists of computations, validations, processes, and branches. The value of REQUEST is available during each phase of the Accept processing. Once an application branches to a different page then REQUEST is set to NULL.
The value of REQUEST is the name of the button the user clicks, or the name of the tab the user selects. For example, suppose you have a button with a name of CHANGE, and a label Apply Change. When a user clicks the button, the value of REQUEST will be CHANGE.

About the When Button Pressed Attribute

Validations, processes, and branches have a When Button Pressed attribute. This attribute displays as a select list and contains the names of buttons that exist on the current page. If you make a selection from When Button Pressed, you associate the button's REQUEST value with the validation, process, or branch.
When you use a button to submit a page, the REQUEST value is passed to the page. The Accept processing logic evaluates each validation, process, and branch that uses a When Button Pressed attribute to determine whether the component should run (or fire). When one of these components runs, do not assume that a user actually clicked the associated button and caused the page to be submitted. Keep in mind, that another button using the same request value may have submitted the page. Similarly, JavaScript on the page can also submit the page and pass in a request value.

Referencing REQUEST Using Declarative Conditions

It is common to reference REQUEST using conditions. For example, you may want to reset pagination when a user clicks Go on a report page. You can reset pagination by creating an on-submit page process. The page process can be made conditional using the condition Request = Expression 1.
To conditionalize an on-submit page process:

1. Under Condition, select the condition type Request = Expression 1.
   
2. In Expression 1, enter GO.
   

Using REQUEST for Show Processing

You can also use REQUEST for Show processing when navigating to a page using f?p syntax. For example:

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

Remember that the fourth argument in the f?p syntax is REQUEST. This example goes to application 100, page 1 for the current session, and sets the value of REQUEST to GO. Any process or region can reference the value of REQUEST using Show processing.
The following is a similar example using PL/SQL:

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

Note that htp.p('hello') is a call to a PL/SQL Web Toolkit package to print out the specified text string.

See Also:

• Oracle Database Advanced Application Developer's Guide for information about developing Web applications with PL/SQL
  
• Oracle Database PL/SQL Packages and Types Reference for information about htp packages
  

SQLERRM

SQLERRM is a template substitution only available in the Applications Region Error Message. The following describes the correct syntax for a region template substitution reference:

#SQLERRM#

SYSDATE_YYYYMMDD

SYSDATE_YYYYMMDD represents the current date on the database server, with the YYYYMMDD format mask applied. You may use this value instead of repeated calls to the SYSDATE() function. The following list describes the supported syntax for referencing SYSDATE_YYYYMMDD.

• Bind variable
  

  :SYSDATE_YYYYMMDD
  
  

• PL/SQL
  

  V('SYSDATE_YYYYMMDD')
  
  

• Direct PL/SQL
  

  APEX_APPLICATION.G_SYSDATE (DATE DATATYPE)
  
  

Table 3-22 SYSDATE_YYYYMMDD Syntax

Reference Type	Syntax
Bind variable	:SYSDATE_YYYYMMDD
Direct PL/SQL	APEX_APPLICATION.G_SYSDATE (DATE DATATYPE)
PL/SQL	V('SYSDATE_YYYYMMDD')

WORKSPACE_IMAGES

Use this substitution string to reference uploaded images, JavaScript, and cascading style sheets that are shared over many applications within a workspace. Table 3-23 describes the supported syntax for referencing WORKSPACE_IMAGES.

Table 3-23 WORKSPACE_IMAGES Syntax

Reference Type	Syntax
Bind variable	:WORKSPACE_IMAGES
Direct PL/SQL	Not available
PL/SQL	V('WORKSPACE_IMAGES')
Substitution string	&WORKSPACE_IMAGES.
Template substitution	#WORKSPACE_IMAGES#