Skip Headers

Oracle® HTML DB User's Guide
Release 1.5

Part Number B10992-01
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
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

6 Application Builder Concepts

This section provides basic conceptual information about Application Builder. Application Builder is the core component within Oracle HTML DB that enables you to build database centric Web applications.

This section contains the following topics:


See Also:


About Page Rendering and Page Processing

In Oracle HTML DB you use Application Builder to build dynamically rendered applications. An application is a collection of database-driven Web pages. You can 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, 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.

What is a Page?

A page is the basic building block of an application. When you build an application in Application Builder you can include a number of common user interface elements, including standard tabs, navigation bar icons, buttons, items, and regions. Figure 6-1 illustrates the use of some of these elements.

Figure 6-1 Sample Application

Description of sampl_app.gif follows
Description of the illustration sampl_app.gif

You can view all the elements that make up a page by accessing the Page Definition.

To view the Page Definition for an existing page:

  1. Click the Build icon.

  2. From the Available Applications list, select an application and click Go.

    The list of pages appears at the bottom of the page.

  3. To edit a specific page, enter the page ID in the Edit Page field and click Go, or click the page name.

    The Page Definition appears. (See Figure 6-2.)

    Figure 6-2 Page Definition

    Description of pg_def.gif follows
    Description of the illustration pg_def.gif

    By default, the Page Definition is divided into three sections:

    • Page Rendering

    • Page Processing

    • Shared Components

    The left section, Page Rendering, lists page level attributes as well as any UI controls and logic that is executed at the time the page is rendered. The middle section, Page Processing, lists the logic controls (such as computations and processes) that are evaluated and executed when the page is processed. The far right section, Shared Components, lists common components that display on every page within an application.

    The following list briefly describes Page Rendering components:

    • Page. Defines page level attributes such as the page name, title and template.

    • Regions. Defines regions. A region is an area of a page that uses a specific template to generate HTML content. Each page can have any number of regions. You can use regions to group other controls, such as buttons and items, together. You can create simple regions that do not generate additional HTML, or create elaborate regions that frame content within HTML tables or images. The HTML DB engine displays regions in sequence within columns. You can choose whether a region displays conditionally.

    • Buttons. Lists the buttons on the current page. Buttons are used to submit a page. When you submit a page, the HTML DB engine processes it, or redirects users to another page without any processing. Buttons can be implemented as an HTML button, an image, or by using a template.

    • Items. Lists the items grouped by region. Items are HTML form elements such as text fields, select lists and check boxes with an associated session state.

    • Computations. Lists the computations that are executed at the time the page is rendered. Computations are units of logic used to assign session state to items.

    • Processes. Lists the processes that are executed at the time the page is rendered. Processes are logic controls used to execute data manipulation language (DML) or PL/SQL. For example, you can use a process to populate session state at the time the page is rendered.

    The following list describes Page Processing components:

    • Computations. Lists the computations that are executed at the time the page is processed. Computations are units of logic used to assign session state to items.

    • Validations. Enables you to create logic controls to verify whether user input is valid. For example, a validation can check whether a value has been typed into a mandatory field.

    • Processes. Lists the processes that are executed after the page is submitted. Processes are logic controls used to execute data manipulation language (DML) or PL/SQL.

    • Branching. Enables you to create logic controls that determine how the user navigates through the application.


See Also:


How Application Builder Uses Templates

The HTML DB engine constructs the look and feel of each page using templates. Templates contains contain HTML and variables that are substituted with dynamic values at runtime. Using templates, the HTML DB engine dynamically renders pages from data stored in tables. You can specify a template for each page. If you do not specify a template, the HTML DB engine uses the default application level template. Application Builder also includes templates for regions, rows, lists, reports, labels, menus, list of values, and buttons.

The use of templates offers a number of advantages:

  • Templates can be shared by multiple components

  • A single change to a template will affect all components using that template at once

The separation of the user interface definition from data access and application logic ensures that the application and user interface can be built concurrently by different people. The following sections describe the different types of templates available in Oracle HTML DB.

Page Templates

Each page is rendered using a page template. Every application has a default page template which applies to all pages in the application, unless you specify a different template.

Page templates control the appearance of navigation bars, parent tabs, and standard tabs. To change an application's default page template, select Edit Attributes from the Application Builder home page. An asterisk (*) indicates that a template in another application subscribes to (or is using) this template. Page templates are divided into component areas. Each area supports specific substitution strings.

Region Templates

Region templates control the appearance of regions. For example, you could use a region template to place a box around some content. Region templates can also be used to control the placement of buttons and region titles. An asterisk (*) indicates that a template in another application subscribes to (or is using) this template.

List Templates

List templates control the appearance of lists. For example, you could create a list to add a list of icons on a home page or third level tabs, or to include a progress indicator. An asterisk (*) indicates that a template in another application subscribes to (or is using) this template.

Report Templates

Report templates control the format of database queries. These templates format the results of reports. An asterisk (*) indicates that a template in another application subscribes to (or is using) this template.

Label Templates

Label templates control the appearance of item labels. For example, you could use label templates to determine how required field labels display. An asterisk (*) indicates that a template in another application subscribes to (or is using) this template.

Menu Templates

Menu templates control the display of menus. You select a menu template when you create a region. For example, menu templates can be used to create breadcrumb style navigation links. An asterisk (*) indicates that a template in another application subscribes to (or is using) this template.

Popup List of Values Templates

Popup List of Values templates control the appearance of popup list of values (or items having the type POPUP LOV). You can create as many popup LOVs as you want, but you can only specify one popup LOV template for each application.

How Page Processing and Page Rendering Work

The HTML DB engine dynamically renders and process pages based on data stored in database tables. To view a rendered version of your application, you run or submit it to the HTML DB engine. When you run an application, the HTML DB engine relies on two processes:

When you call a page using a URL, the HTML DB engine is running the Show page or page rendering process. When you submit a page, the HTML DB engine saves the submitted values in the session cache and then performs any computations, validations, or processes.

Understanding Shared Components

Shared components are common components that display on every page within an application. Examples of shared components include:

  • Parent and standard tabs

  • Navigation bars

  • List of values

  • Menus

  • Lists

  • Templates

About Standard Tabs and Parent Tabs

Application Builder includes two different types of tabs:

  • Standard tabs

  • Parent tabs

An application having only one level of tabs uses standard tabs. An application having two levels of tabs uses a parent and standard tabs. A standard tab set is associated with a specific page and page ID. You can use standard tabs to link users to a specific page.

Parent tabs give users another level of navigation. Parent tabs function as a container to hold a group of standard tabs. You can use parent tabs to link users to a specific URL associated with a specific page. When the target page appears, it displays its own standard tab set.


See Also:

"Creating Tab Sets" for more information on creating standard and parent tabs

About Navigation Bars

Use navigation bars to link users to various pages within an application. Typically navigation bars are used to enable users to log in and log out or link to help text. The location of a navigation bar depends upon the associated page template. A navigation bar icon enables you to display a link from an image or text. When you create a navigation bar icon you can specify an image name, text, a display sequence, and a target location (an URL or page).


See Also:

"Creating a Navigation Bar" for more information on creating navigation bars

About List of Values

A list of values (LOV) is a static or dynamic definition used to display a specific type of page item, such as a radio group, check box, or select list. LOVs can be static (that is, based on a set of predefined display and return values) or dynamic (based on SQL queries that select values from tables).

You define LOVs at the application level by running the LOV Wizard and adding them to the Named List of Values repository.


See Also:

"Creating LOVs"

About Menus

A menu is a hierarchical list of links that is rendered using a template. For example, you can display menus as a list of links or as a breadcrumb path.


See Also:

"Creating Menus" for more information on creating menus

About Lists

A list is a collection of links that is rendered using a template. For each list entry, you specify display text, a target URL, and other attributes that can control when and how the list entry displays. You control the display of the list by linking it to a template. This template controls the appearance of all list entries.


See Also:

"Creating Lists" for more information on creating lists

About Templates

Templates control the look and feel of the pages in your application. As you create your application you specify templates for pages, regions, reports, lists, labels, menus, buttons, and popup list of values.


See Also:

"Working with Templates" for more information on viewing, creating, and editing templates

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 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 whether the component (such as a button) displays.

You specify a condition by selecting a condition type when you create the component (that is, the region, item, button, or tab) or by making a selection from the component's conditional display attribute. (See Figure 6-3 .) The condition evaluates to true or false based on the values you enter in the Expression fields.

Figure 6-3 Conditional Display Attribute

Description of condition.gif follows
Description of the illustration condition.gif

To view a complete listing of all available conditions for a given component, click the view icon to the right of the Conditional Display Type list. Shortcuts to common selections appear directly beneath the Type list. If your condition requires an expression, type it in the appropriate field.

The sections that follow offer examples of some commonly used condition types.

Current Page In Expression 1

Current page = Expression 1 evaluates to true if the current page matches the page ID listed in the Expression 1 field. For example:

100,101,102

If the current page is 100, 101, or 102, 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 emp WHERE deptno = :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 Variables" for more information

PLSQL Expression

Use PLSQL 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, then the condition evaluates as true. Otherwise it evaluates as false.


See Also:

Appendix A, "Available Conditions " for a detailed listing of all conditional types available in Oracle HTML DB

Using Build Options to Control Configuration

Build options enable you to conditionally display specific functionality within an application. Using build options you can control which features of an application are turned on for each application deployment. If you specify a build option at the application level, you do not need to specify it for each attribute (for example, each page, branch, button, item, or tab).

Build options have two possible values: INCLUDE and EXCLUDE. If you specify an attribute as being included, then the HTML DB engine considers it part of the application definition at runtime. Reversely, if you specify an attribute as being excluded then the HTML DB engine treats it as if it does not exist.


See Also:

"Editing Application Attributes" and "Editing Page Attributes" for more information on specifying build options

Creating Build Options

Before you can specify a build option, you must create it.

To create a build option:

  1. Click the Build icon.

  2. When Application Builder appears, select the Builds tab.

  3. To create a new build option, click Create.

  4. Follow the on-screen instructions.

Viewing Build Option Reports

Oracle HTML DB includes a report detailing build option utilization in the current application.

To view a report of build option utilization:

  1. Click the Build icon.

  2. When Application Builder appears, select the Builds tab.

  3. Click Navigate in the left navigation pane and then select Build Opt Utilization.

  4. Make a selection from the Build Options list and click Go.

Verifying User Identity

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

Oracle HTML DB supports authentication. 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 Components

While conditions control the rendering and processing of specific components on a page, authorizations control user access to specific components. Authorization is a broad term for controlling access to resources based on predefined 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 specific component such as a region, item, or button. For example, you could use an authorization scheme to selectively determine which tabs, regions, or navigations bars a users sees.

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 have 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 HTML DB transparently maintains session state and provides developers with the ability to get and set session state values from any page in the application.

A session is a logical construct that establishes persistence (or stateful behavior) across page views. Each session is assigned a unique identifier within the Oracle HTML DB installation. The HTML DB 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. Since 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.

Oracle HTML DB sessions are logically and physically distinct from the Oracle database sessions used to service page requests. A user runs an application in a single Oracle HTML DB 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 HTML DB engine creating or reusing an Oracle database session to access database resources. Each of these sessions lasts just a fraction of a second.

Understanding Session IDs

The HTML DB engine establishes the identity (or anonymity) of the user for each page request and the session ID in order to fetch session state from the database. The most visible location of the session ID is in the URL for a page request. Another visible location is in the page's HTML POST structures or in a session cookie sent by the HTML DB engine during authentication and maintained for the life of the application (or browser) session.

Oracle HTML DB 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 both 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 HTML DB 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.

Figure 6-4 Developer Toolbar

Description of d_toolbar.gif follows
Description of the illustration d_toolbar.gif

The Session State page provides valuable information about the page. Table 6-1 describes the various types of information available on the Session State page.

Table 6-1 Information Available on the Session State Page

Heading Description
Application, Page, Session Identifies the application name, page ID, and session ID.
Page Items Identify attributes of the page, including the item name, how the item displays (hidden, popup, button, display only HTML), the state or session ID, 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: "Using Substitution Strings" for more information on referencing item values

Application Environment Identifies the session ID, current user, security ID, and browser language.
Session State Indicates the user's entire session state. The section at the top indicates the state for the current page.


See Also:

"Using the Developer Toolbar" for more information about the Developer toolbar

Managing Session State Values

When building interactive, data driven Web applications, the ability to access and manage session state values with ease is critical. In Oracle HTML DB, 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:


See Also:

"About Items" and "Referencing Item Values" for more information

Referencing Session State

Referencing the value of an item is one of the most common examples of referencing session state. In Oracle HTML DB, an item can be a field, a text area, a password, a select list, or checkbox. Table 6-2 describes the supported syntax for referencing item values.

Table 6-2 Syntax for Referencing Item Values

Type Syntax Description
SQL :MY_ITEM Standard bind variable syntax for items no longer than 30 bytes. 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 HTML DB APIs"

PL/SQL nv('MY_NUMERIC_ITEM') Standard PL/SQL syntax referencing the numeric item value using the nv function.

See Also: "Oracle HTML DB APIs"

Static Text &MY_IITEM Static text.
Static Text (exact) &MY_IITEM. Static text. Exact Substitution.

Setting Session State

When a user submits a page in Oracle HTML DB, the HTML DB 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 have 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 HTML DB captures the value typed in the phone number field and stores the value for future use. The phone number typed 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.

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:&SESSION.::NO::MY_ITEM:

The following example resets the value of the items THE_EMPNO andTHE_DEPTNO.

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

Clearing Cache by Page

Caching application items provides a very 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 page when a user clicks a link the creates a new order. By clearing 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:&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)

Clearing Session Cache on a Page and Passing an Item Value

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

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

Specifically this example:

  • Runs page 6003 of application 6000 and use 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 one except it passes values to multiple items.

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

Specifically this example:

  • Runs page 6004 of application 6000 and use 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 commas used as placeholder), and set the value of MY_ITEM3 to 5678

Clearing Cache for an Entire Application

You can also clear application cache by using f?p syntax by creating a REQUEST argument using the keyword APP using the following syntax:

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


Note:

Resetting the cache for an entire application does not actually restore the application to a completely reset state. For example, if an application includes on-new instance computations or on-new instance processes, the HTML DB engine runs these computations and processes when the application session is created. Then, it processes the clear cache request and displays the requested page.

The only way to reset the application completely is to request it using a URL without a session ID, or by calling HTMLDB_APPLICATION.CLEAR_APP_CACHE from another application. If the session ID is set using a cookie, you will need to logout in order to reset the state.


Clearing Cache for the Current User Session

You can also clear application cache by using f?p syntax. Create a REQUEST argument using the keyword SESSION. For example:

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

About Bind Variables

You can use bind variables within an application process or SQL query to reference session state of a specified item. For example:

SELECT * FROM emp WHERE 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 application items can be up to 255 characters, if you intend to use an application items 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 syntax:

:MY_ITEM

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

SELECT ename, job, sal
FROM emp
WHERE deptno = :THE_DEPTNO


See Also:

Creating Regions for more information on creating different types of 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 are added automatically around the PL/SQL. For example:

INSERT INTO emp (empno, ename, job) 
VALUES (:P1_empno, :P1_name, :P1_job);

In this example, the values of the empno, ename, and job are populated by the values of P1_empno, P1_name, and P1_job.

Understanding URL Syntax

Each application has a number (called an application ID) or alphanumeric alias which uniquely identifies it. Similarly, each page also has a unique number (called a page ID) or an alphanumeric alias. When you run an application, the HTML DB engine generates a session number that serves as a key to the user's session state.

The URL that displays for each page indicates the location of Oracle HTML DB and identifies the application ID, page ID, and session ID. For example:

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

This example indicates that:

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 6-3 describes the possible arguments you can pass when using f?p syntax.

Table 6-3 f?p Syntax Arguments

Syntax Description
App Indicates an application ID or alphanumeric alias.
Page Indicates a page ID 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

ClearCache Clears cache. Clearing cache for a single item simply sets the value of the item to null. To clear cached items, use a comma delimited list of page numbers. Comma delimited lists can also contain collections to be reset or the keyword RP, which resets region pagination on the requested page.
itemNames Comma delimited list of item names used to set session state with an URL.
itemValues Comma delimited list of item values used to set session state with an URL.
PrinterFriendly Identifies the printer friendly preference of YES or NO (default). You can use this item when preparing a page view with minimal graphics and a layout suitable for printing. You can reference the printer friendly preference by using the syntax:
v('PRINTER_FRIENDLY')

When referenced, the HTML DB 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. Oracle HTML DB includes many wizards that automatically create these references for you. The sections that follow describe a number of specific instances that utilize f?p syntax to link pages.

Calling a Page Using an Application and Page Alias

The following example calls a page using an application and a page alias from within an Oracle HTML DB application. It runs the page home of the application myapp and uses the current session ID.

f?p=myapp:home:&SESSION.

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:&SESSION.

Using 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 will need to use substitution strings in order to pass information.

You can use substitution strings in Oracle HTML DB in the following ways.

Substitution strings used within a template contains the pound symbol (#). For example:

#ABC#

Substitution strings created at the application level do not display, but are used as variable to maintain session state. You can define page items as an attribute of a page. You can use this type of session state substitution at the application or page level. For example:

&MY_ITEM.

Built-in Substitution Strings

Application Builder supports a number of built-in substitution strings. You may need to reference these values in order to achieve specific types of functionality. Built-in substitution strings available in Oracle HTML DB include:

The sections that follow describe these substitution strings, when to use them, and what supported syntax is currently available. Note that no short syntax exists for SESSION or USER since both are Oracle reserved words.

Topics in this section include:


See Also:


APP_SESSION

APP_SESSION is one of the most commonly used built-in substitution string. You can use this substitution string to create hypertext links between application pages that maintain a session state by passing the session number. Table 6-4 describes the supported syntax for referencing APP_SESSION.

Table 6-4 APP_SESSION Syntax

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

Consider the following examples:

  • From within an HTML Region:

    <a href="f?p=100:5:&SESSION.">click me</a> 
    
    
  • Using PL/SQL:

    htf.anchor('f?p=100:5:'||v('SESSION'),'click me');
    
    
  • Using a SQL query:

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

APP_USER

The APP_USER is the current user running the application. Depending upon your authentication model, the value of the user 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. Table 6-5 describes the supported syntax for referencing APP_USER.

Table 6-5 APP_USER Syntax

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

Consider the following examples:

  • From within an HTML Region:

    Hello you are logged in as &USER.
    
    
  • Using PL/SQL:

    htp.p('Hello you are logged in as'||v('USER')); 
    
    
  • As a bind variable:

    SELECT * FROM some_table WHERE user_id = :app_user
    
    

IMAGE_PREFIX

The Image Prefix attribute is defined on the Edit Application Attributes page. By default the image prefix is "/i/". Use this prefix when referencing images distributed with Oracle HTML DB. If you wish to reference uploaded images, use WORKSPACE_IMAGES and APP_IMAGES. Table 6-6 describes the supported syntax for referencing IMAGE_PREFIX.


See Also:

"Editing Application Attributes" for more information on application attributes

Table 6-6 IMAGE_PREFIX Syntax

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

WORKSPACE_IMAGES

The workspace images prefix is derived from the IMAGE_PREFIX (see "IMAGE_PREFIX"). Workspace images differ from application images in that workspace images are not specific to a given application and can be shared among multiple applications. Table 6-7 describes the supported syntax for referencing WORKSPACE_IMAGES.

Table 6-7 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#

APP_IMAGES

The application images prefix is derived from the IMAGE_PREFIX (see previous section). Oracle HTML DB stores uploaded images in the database. Workspace images are specific to a given application and are not shared over many applications. If you uploaded an image and make it specific to an application, then you must use this substitution string, or bind prefix. Table 6-8 describes the supported syntax for referencing APP_IMAGES.

Table 6-8 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#

BROWSER_LANGUAGE

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

Table 6-9 BROWSER_LANGUAGE Syntax

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

PRINTER_FRIENDLY

The value of PRINTER_FRIENDLY determines whether the HTML DB 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 6-10 describes the supported syntax for referencing PRINTER_FRIENDLY.

Table 6-10 PRINTER_FRIENDLY Syntax

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

HOME_LINK

HOME_LINK is the home page of an application. The HTML DB engine will redirect to location if no page is given. Table 6-11 describes the supported syntax for referencing HOME_LINK.

Table 6-11 HOME_LINK Syntax

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

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).

HTMLDB_APPLICATION.G_PROXY_SERVER

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. 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 6-12 describes the supported syntax for referencing REQUEST.

Table 6-12 REQUEST Syntax

Reference Type Syntax
Bind variable :REQUEST
Direct PL/SQL HTMLDB_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 Oracle HTML DB 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 of "Apply Change." When a user clicks the button the value of REQUEST will be CHANGE.

Referencing REQUEST Using Declarative Conditions

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

To create an on-submit page process:

  1. Under Conditional Display, 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:&SESSION.:GO

Remember that the fourth argument is 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 in order to print out the specified text string.


See Also:


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:

    HTMLDB_APPLICATION.G_SYSDATE (DATE DATATYPE)
    
    

Table 6-13 SYSDATE_YYYYMMDD Syntax

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

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 wish to generate debug information only if the debug mode is set to YES. Table 6-14 describes the supported syntax for referencing DEBUG.

Table 6-14 DEBUG Syntax

Reference Type Syntax
Bind variable :DEBUG
Direct PL/SQL HTMLDB_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:&SESSION.::&DEBUG

APP_ID

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

Table 6-15 APP_ID Syntax

Reference Type Syntax
Bind variable :APP_ID
Direct PL/SQL HTMLDB_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:&SESSION.

APP_PAGE_ID

APP_PAGE_ID is the current application Page 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 6-16 describes the supported syntax for referencing APP_PAGE_ID.

Table 6-16 APP_PAGE_ID Syntax

Reference Type Syntax
Bind variable :APP_PAGE_ID
Direct PL/SQL HTMLDB_APPLICATION.G_FLOW_STEP_ID (A NUMBER)
Direct PL/SQL :APP_PAGE_ID
PL/SQL 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.:&SESSION.

APP 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 schema. The following describes the correct syntax for direct PL/SQL reference:

HTMLDB_APPLICATION.G_FLOW_SCHEMA_OWNER

SQLERRM

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

#SQLERRM#

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 since changes to the URL can require authentication. Table 6-17 describes the supported syntax for referencing AUTHENTICATED_URL_PREFIX.

Table 6-17 AUTHENTICATED_URL_PREFIX Syntax

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

LOGOUT_URL

LOGOUT_URL is 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 a user out. To create a logout navigation bar icon, use &LOGOUT_URL for the navigation bar link. If you are coding a page template use #LOGOUT_URL#. Table 6-18 describes the supported syntax for referencing LOGOUT_URL.

Table 6-18 LOGOUT_URL Syntax

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

PUBLIC_URL_PREFIX

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

Table 6-19 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#

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 6-20 describes the supported syntax for referencing CURRENT_PARENT_TAB_TEXT.

Table 6-20 CURRENT_PARENT_TAB_TEXT Syntax

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

APP_ALIAS

APP_ALIAS is alphanumeric name for the current application. APP_ALIAS is different from the APP_ID in that the APP_ID must be unique over all companies and all applications hosted in one database. In contrast, APP_ALIAS must be unique within a workspace. Using the same APP_ALIAS you can create an application called ABC in two workspaces. You can use APP_ALIAS almost anywhere a 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:&SESSION.

This example runs application ABC, page 1 using the current session.

Table 6-21 describes the supported syntax for referencing APP_ALIAS.

Table 6-21 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:&SESSION."> of the current application</a>

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 wish 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 6-22 describes the supported syntax for referencing APP_UNIQUE_PAGE_ID.

Table 6-22 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:'||empno,
   ename,
    job
FROM emp

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.