5 Working with Application Pages

Available Navigation Bar Controls and Buttons

A navigation bar appears directly beneath the breadcrumb trail.

Available controls on the page navigation bar include:

• Page. Displays the current page number. To view another page, enter the page number in the Page field and click Go.

• Previous and Next. These buttons resemble less than (<) and greater than (>) signs. Click these buttons to move to the previous or next page.

• View. Controls the current page view. To view alternative reports, make a selection from the list and click Go. See "Using the View List on the Page Definition".

The following buttons appear to the right of the navigation bar:

• Run. Submits the current page to the Application Express engine to render viewable HTML. See "Running a Page or Application".

• Copy. Creates a copy of the current page. You specify a page number and page name.

• Delete. Deletes the current page.

• Create. Links to a wizard for creating a page. See "Creating a Page from the Page Definition".

About the Action Bar

The Run Page, Shared Components, Comment, Lock, Export Page, and Find icons display on the Action bar.

About Page Rendering, Page Processing, and Shared Components

Every Page Definition is divided into three sections:

• Page Rendering. Page rendering is the process of generating a page from the database. The Page Rendering section lists user interface controls and logic that execute when a page is rendered. See "About Page Rendering".

• Page Processing. Page processing occurs once a page is submitted. Typically a page is submitted when a user clicks a button. The Page Processing section lists logic controls (such as computations and processes) that are evaluated and executed when the page is processed. See "About Page Processing".

• Shared Components. The Shared Components section lists common components that can be used by one or more pages within an application. See "About Shared Components".

Page

Page attributes control specific characteristics of a page such as the page name, display attributes such as the page title and the associated page template, header text, and the selected authorization scheme to name just a few. You access page attributes from the Page Definition.

Regions

A region is a area on a page that serves as a container for content. Each page can have any number of regions. The content of a region is determined by the region source. For example, a region may contain a report based on a SQL query you define, or it may contain static HTML.

You control the appearance of a region through a specific region template. You can use regions to group page controls (such as items or buttons). You can also create simple regions that do not generate additional HTML, or create elaborate regions that frame content within HTML tables or images.

Buttons

As you design your application, you can use buttons to direct users to a specific page or URL, or to enable users to submit a page. When you submit a page, the Application Express engine posts or processes information. A button can be implemented as an HTML button, an image, or by using a template. Buttons can be placed in predefined region template positions or among items in a form.

Items

Items are HTML form elements such as text fields, select lists, and check boxes with an associated session state. Item attributes affect the display and behavior of items on a page. For example, these attributes can impact where a label displays, how large an item will be, and whether the item will display next to, or below the previous item.

There are two categories of items: page items and application items. Page-level items are placed on a page and have associated user interface properties, such as Display As, Label, and Label Template. Application-level items are not associated with a page and therefore have no user interface properties. An application item can be used as a global variable.

Computations

Computations are units of logic used to assign session state to items. You can use computations to assign a value to an identified item when a page is submitted or displayed.

Application-level computations assign a value to an item each time a page is rendered. A page-level computation assigns a value to an identified item when a page is displayed or submitted (rendered and processed).

Processes

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 a page is rendered, to execute some type of logic (for example, using PL/SQL), or to make a call to the rendering engine. Typically a process performs an action. A process may be hand coded PL/SQL, or the invocation of a predefined process.

Computations

Computations are units of logic used to assign session state to items and are executed at the time the page is processed.

Validations

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

Processes

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

Branches

Branches enable you to create logic controls that determine how the user navigates through the application.

Tabs

Tabs are an effective way to navigate between pages of an application. Application Builder includes two types of tabs: standard tabs and parent tabs.

An application having only one level of tabs uses a standard tab set. A standard tab set is associated with a specific page. You can use standard tabs to link users to other pages within your application. A parent tab set functions as a container to hold a group of standard tabs. Parent tabs give users another level of navigation and context (or sense of place) within the application.

Lists 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). Once created, an LOV can then be referenced by one or more page items.

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

Breadcrumbs

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

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 control when and how the list entry displays. You control the display of the list and the appearance of all list entries by linking the list to a template.

Theme

A theme is a named collection of templates that defines the application user interface. Each theme contains templates for every type of application component and page control, including individual pages, regions, reports, lists, labels, menus, buttons, and list of values.

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 lists of values. Groups of templates are organized into named collections called themes.

Security

You can provide security for your application by specifying an authorization scheme. Authorization is a broad term for controlling access to resources based on user privileges.

Navigation Bar

Use a navigation bar to link users to various pages within an application. Typically a navigation bar is used to enable users to log in, 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, display sequence, and target location (a URL or page).

Creating a Page Computation

A page computation assigns a value to an identified item when a page is displayed or submitted (rendered and processed).You create a page computation by running the Create Page Computation Wizard. For each computation, specify the item for which you are creating the computation and a computation type.

To create a page computation:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".

2. Under Computations, click the Create icon.

3. For Item Location, select where the computation will execute and click Next. Location options include:

   • Item on this Page

   • Item on Another Page

   • Application Level Item

4. For Item, select the item and computation point at which you would like to perform the computation:

   1. Compute Item - Select the item the computation will update.

   2. Sequence - Select the order of evaluation.

   3. Computation Point - Select the point at which the computation executes. The computation point On New Instance executes the computation when a new session (or instance) is generated.

   4. Computation Type - Select the method of computation you want to create.

   5. Click Next.

5. In Computation, enter a computation that corresponds to the selected computation type and click Next.

6. On Condition, you can choose to make the computation conditional. To make a computation conditional, make a selection from the Condition Type list and enter text in the expression fields.

7. Click Create.

Understanding Computation Points and Computation Syntax

A good example of using computations can be illustrated by a page containing form fields for entering phone numbers. In this example, the phone number is stored in one database column; however, the data entry form breaks the phone number into three components: area code, prefix, and line number. In this example, the page items are called P10_AREA_CODE, P10_PREFIX, and P10_LINE_NUMBER.

Next, suppose you need to combine the values stored in these items into a single string. You could accomplish this by using an After Submit computation and store the combined values in an item called P10_PHONE_NUMBER.

To create a computation to store the combined values of P10_AREA_CODE, P10_PREFIX, and P10_LINE_NUMBER in new items:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".

2. Create a item named P10_PHONE_NUMBER to store the combined values of P10_AREA_CODE, P10_PREFIX, and P10_LINE_NUMBER. See "Differences Between Page Items and Application Items".

3. Under Computations, click the Create icon.

4. For Item Location, select Item on this Page and click Next.

5. For Computation, select P10_PHONE_NUMBER.

6. For Sequence, select the order of evaluation.

7. For Computation, you have the option of creating one of the following computation types:

   1. Static Assignment:

      • For Computation Type, select Static Assignment and click Next.

      • Enter the following computation:

        (&P10_AREA_CODE.) &P10_PREFIX.-&P10_LINE_NUMBER.
        

      • Click Next.

   2. PL/SQL Function Body:

      • For Computation Type, select PL/SQL Function Body and click Next.

      • Enter the following computation:

        DECLARE
        l_return_value  VARCHAR2(300) DEFAULT NULL;
        BEGIN
            l_return_value :=
        '('||:P10_AREA_CODE||')'||:P10_PREFIX||'-'||:P10_LINE_NUMBER;
        RETURN l_return_value;
        END;
        

      • Click Next.

   3. SQL Query:

      • For Computation Type, select SQL Query and click Next.

      • Enter the following computation:

        SELECT '('||:P10_AREA_CODE||')'||:P10_PREFIX||'-'||:P10_LINE_NUMBER FROM DUAL
        

      • Click Next.

   4. PLSQL Expression:

      • For Computation Type, select PLSQL Expression and click Next.

      • Enter the following computation:

        '('||:P10_AREA_CODE||')'||:P10_PREFIX||'-'||:P10_LINE_NUMBER
        

      • Click Next.

8. Click Create.

Editing Page Computation Attributes

Once you create a computation, you can edit it on the Edit Page Computation page.

To edit a page computation:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".

2. Under Computations, select the computation name.

   The Edit Page Computation page appears.

3. Edit the appropriate attributes.

4. Click Apply Changes.

Creating a Validation

To create a validation:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".

2. Under Validations in Page Processing, click the Create icon.

   The Create Validation Wizard appears.

3. Select a validation level:

   • Item level validations are specific to a single item.

   • Page level validations do not apply to any single item, but apply to an entire page.

4. If you selected Item level validation, select the item to be validated and click Next.

5. Select a validation method as described in Table 5-1.

   Table 5-1 Validation Methods

   Validation Method	Descriptions
   SQL	Compares item values to data in the database. For example, you can use a SQL validation to verify whether a last name typed into a field exists in the database. In the following Exists SQL validation, the field is named P1_LAST_NAME and the table is named customers. SELECT 1 FROM customers WHERE last_name = :P1_LAST_NAME
   PL/SQL	Useful if you need complex logic to validate entered data. For example, suppose you need to create a validation for an address form that requires the user to enter a province if the address is not in the United States. You could create the validation as a Function Returning Boolean, using the following PL/SQL: BEGIN IF :P1_COUNTRY = 'US' AND :P1_PROVINCE IS NULL THEN RETURN FALSE; ELSE RETURN TRUE; END IF; END; You could also create the same validation implemented as a PL/SQL Expression as follows: NOT (:P1_COUNTRY='US' AND :P1_PROVINCE IS NULL);
   Item Level Null	Checks if an item's value in session state is null. For example, you could validate that the user enters a value in a field by creating an item validation and then selecting the validation method Item Not Null.
   Item String Comparison	Compares the value of an item to a specific string. There are several string comparison validations that compare the value of an item to a literal string. For example, you select the validation type Item in Expression 1 is contained in Expression 2 to validate a user entry in a field against a list of values you provide. In Expression 1, enter the name of the item you want to validate without a colon. For example: P1_VALUE In Expression 2, enter a string of values you want to validate against. For example: ABC/DEF/GHI
   Regular Expression	Regular expressions provide a method to describe text patterns. Use a Regular Expression validation to perform data validation. For example, you could use the following regular expression validation to verify that a string of entered data always consists of groups of six numbers separated by commas and followed by a comma: ^([[:digit:]]{6},)+$ This regular expression would find the following entries valid: 123456,654321, 123456, 123456,123456,654321, However, the following would not be valid: 123456,12345 12345

   
   

6. For SQL, PL/SQL, and Item String Comparison validations, select the type of validation you want to create and click Next.

7. Specify the sequence and validation name and click Next.

8. Depending upon the validation method, enter the validation or message text that displays if the validation fails. Click Next.

9. Define conditions that apply to this validation and click Create.

Defining How Validation Error Messages Display

You can choose to have validation error messages display inline (that is, on the page where the validation is performed) or on a separate error page.

To define how a validation error message displays:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".

2. Under Validations, select the appropriate validation.

   The attributes page for the validation appears.

3. Scroll down to Error Message.

4. In Error Message, enter your error message text.

5. From Error message display location, select a display location.

   This attribute identifies where a validation error message displays. Validation error messages can display on an error page or inline within the existing page. Inline error messages can display in a notification area (defined as part of the page template) or within the field label.

   To create a hard error that stops all processing (including validations), you must display the error on an error page.

6. If you select Inline with Field or Inline with Field and in Notification, you must associate an item with the error message. To associate an item with the error message, select the item from the Associated Item list.

7. Click Apply Changes.

Processing Validations Conditionally

You can control when and if a validation is performed under Conditions.

To create a condition for an existing validation:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".

2. Under Validations, select the appropriate validation.

   The attributes page for the validation appears.

3. Scroll down to Conditions.

4. To have a validation performed when a user clicks a particular button, make a selection from the When Button Pressed list.

5. Make a selection from the Condition Type list.

6. Depending upon the selected Condition Type, enter values in the Expression attributes. The validation will be rendered or processed if the specified condition is met.

7. Click Apply Changes.

Creating a Page Process

You create a process by running the Create Process Wizard. During the wizard, you define a process name, specify a sequence and the point at which the process will execute, and select a process category. You can change nearly all of these attributes on the Edit Page Process page.

To create a process:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".

2. Under Processes, click the Create icon.

3. Select a category. Table 5-2 describes available page process categories.

   Table 5-2 Process Categories

   Process Category	Description
   Data Manipulation	Data Manipulation process types are frequently used by wizards to support data manipulation language (DML) actions. Application Builder supports the following declarative data manipulation processes: Select Automatic Row Fetch and Automatic Row Processing (DML) to create an automatic data manipulation language (DML) process. Use Multi Row Update and Multi Row Delete with tabular forms. Use Add Rows to Tabular Form with a tabular form.
   Close Popup Window	Applies to processes running within a popup window. Upon execution, this process type closes the current popup window.
   Form Pagination	Implements pagination through the detail records associated with a master detail form. Most often used in master detail forms (such as in the Master Detail Wizard), this process checks the master table to determine which set of detail records you are in and determines what the next detail record should be. See Also: "Creating a Master Detail Form"
   On Demand	Creates an application-level process that can only be executed when called from a specific page. When you create this process type at the page-level, you are creating reference to an existing application-level process. See Also: "About On Demand Application Processes"
   PL/SQL	Runs the PL/SQL you provide. Use this process type to execute a block of PL/SQL entered directly into the process or to simply call an existing API.
   Reset Pagination	In Report regions, resets pagination back to the first result set. The Application Express engine keeps track of where the user is within a given result set. This process category returns the user to the beginning result set. In other words, this category resets the counters associated with the report region to return the first part of the result set the next time the result set displays.
   Session State	Sets the values of existing session state items to null. Select this process type to clear the cache for applications, sessions, or items and to clear existing user preferences. See Also: "Managing Session State Values" and "Managing User Preferences" in Oracle Application Express Administration Guide
   Web Services	Implements a Web Service as a process on a page. Running the process submits a request to the service provider. See Also: "Invoking a Web Service as a Process"

   
   

4. Follow the on-screen instructions.

Editing Process Attributes

Once you create a process, you can control when the process executes and what the process does by editing attributes on the Edit Page Process page.

To edit an existing page process:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".

2. Select the process name.

   The Edit Page Process page appears.

Defining a Branch Point and Action

When you click a standard tab in an application, the Application Express engine sets session state, executes computations, and then links you to the target page. It does not run any processes or explicitly defined branches. In cases where the page is submitted without clicking a tab, the Application Express engine explicitly defines branches to direct users to a subsequent page.

You can control when a branch executes by making a selection from the Branch Point list. Available options include:

• On Submit: Before Computation - Branching occurs before computations, validations, or processing. Use this option for buttons that do not need to invoke any processing (for example, a Cancel button).

• On Submit: Before Validation - Branching occurs after computations, but before validations or processing. If a validation fails, page processing stops, a rollback is issued, and the page displays the error. Because of this default behavior, you do not need to create branches to accommodate validations. However, you may want to branch based on the result of a computation (for example, to a previous branch point).

• On Submit: Before Processing - Branching occurs after computations and validations, but before processing. Use this option to branch based on a validated session state, but before performing any page processing.

• On Submit: After Processing - Branching occurs after computations, validations, and processing. This option branches to a URL or page after performing computations, validations, and processing. When using this option, remember to sequence your branches if you have multiple branches for a given branch point.

• On Load: Before Header - Branching occurs before a page is rendered. This option displays another page instead of the current page or redirects the user to another URL or procedure.

Depending upon the Branch Type you select, you can specify the following additional information in the Action attributes:

• The page number of the page to which you want to branch

• PL/SQL procedure which ultimately renders a branch target page

• A URL address

Branching Conditionally

Like other controls, branches can be made conditional. To create a conditional branch, make a selection from the Condition Type list, and enter text in the expression fields to implement the condition type you choose.

Name

Use these attributes to define general attributes for the current page such as a page name, an optional alphanumeric alias, and associated page groups. Table 5-3 describes these attributes.

f?p=100:home

Display Attributes

Use these attributes to define general display attributes for the current page such as the selected page template, standard tab set, title, and cursor focus. Table 5-4 describes these attributes.

Header and Footer

Use these attributes to define page header, body header, body footer, and page footer text. Table 5-5 describes these attributes.

HTML Header

Use HTML Header to replace the #HEAD# substitution string in the page template header. The values entered here are inserted after the HTML <HEAD> tag. Common uses of these attributes:

• Code page-specific inline cascading style classes

• Add additional style sheets for a specific page

• Code page-specific JavaScript

• Code page-specific meta tag page refresh

For Include Standard CSS and JavaScript, select Yes to suppress the inclusion of cascading style sheet (CSS) and JavaScript files in the HTML Header. Because suppressing the display of these files breaks typical applications, enabling this attribute is only recommended for advanced developers.

HTML Body Attributes

Use this attribute to add events when the page is being loaded, such as calls to JavaScript. In the Page HTML Body attribute, enter JavaScript or text to be substituted for your page template's #ONLOAD# substitution string. To use this feature, your page template must include the #ONLOAD# substitution string.

You can use the Page HTML Body attribute to write into the contents of the opening <body> tag. A typical page template might use #ONLOAD# within the opening <body> tag as shown in the following example:

<html>
<head>
...
</head>
<body #ONLOAD# >

Security

Use these attributes to specify an authorization scheme and authentication requirements for the current page. Table 5-6 describes these attributes.

autocomplete="off"

Duplicate Submission

Use the Allow duplicate page submissions list to specify whether users may process a page multiple times in a row. Set this attribute to No to prevent duplicate page submissions from being processed multiple times.

Examples of duplicate page submissions include:

• A user clicks the Submit button multiple times.

• You create a branch of type Branch to Page, and the user clicks the browser reload button.

In On duplicate page submissions go to this URL, enter a URL. Use this field if you set Allow duplicate page submissions to No. If you select No and a user attempts to submit the same page twice, Oracle Application Express displays an error message and a link to the URL you specify.]

Cache

Use these attributes to enable caching for the current page. Enabling page caching can improve application's performance and works well for static pages. Table 5-7 describes these attributes.

Configuration

Select a build option for this page. You can use build options to enable or disable functionality. Most application attributes have a build option attribute. Do not specify a build option for the current page unless you plan to exclude the page in certain configurations.

Build options have two possible values: INCLUDE and EXCLUDE. If you specify an attribute as being included, then the Application Express engine considers it part of the application definition at run time. Conversely, if you specify an attribute as being excluded, then the Application Express engine treats it as if it did not exist.

On Error Text

Use this attribute to specify the error text that displays in the #NOTIFICATION_MESSAGE# template substitution string in the event an error occurs on the page.

Help

Use this attribute to enter Help text for the current page.

Help text is displayed using a help system that you must develop. To show the Help for a specific page, call the APEX_APPLICATION.HELP procedure from a page that you create for displaying Help text. For example, you could use a navigation bar icon similar to:

f?p=4000:4600:&APP_SESSION.::&DEBUG::LAST_STEP:&APP_PAGE_ID.

Page-level help supports shortcuts using the following syntax:

"SHORTCUT_NAME"

Comments

Use this attribute to record comments about the current page. These comments never display when the application is running.

Using the Shared Components Icon

You can also access the Shared Components page by clicking the Shared Components icon on the Action bar. The Action bar resembles a small mechanical gear and displays beneath the Utilities tab in the upper right corner of most pages in Application Builder.

Application

The following section describes the links under Application.

Logic

The following section describes the links under Logic.

Security

The following section describes the links under Security.

Globalization

The following section describes the links under Globalization.

Navigation

The following section describes the links under Navigation.

User Interface

The following section describes the links under User Interface.

Reports

The following section describes the links under Reports.

Files

The following section describes the links under Files.

Exporting Shared Components from the Export Page

To export shared components from the Shared Components page:

1. Navigate to the Export page:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. On the Application home page, click Export/Import.

   4. On the Export/Import page, click Export and click Next.

2. On the Tasks list, click Component Export.

   The Component Export page appears. See "Exporting Application Components".

Exporting Shared Components from the Shared Components Page

To export shared components from the Shared Components page:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Application home page, click Shared Components.

   The Shared Components page appears.

5. On the Tasks list, click Export Application Components.

   The Component Export page appears. See "Exporting Application Components".

Running an On Demand Process from a Page Request

You can have a page request run an On Demand process by using the following syntax:

f?p=application_id:page_id:session:APPLICATION_PROCESS=process_id

Where:

• application_id is the application ID or alphanumeric alias

• page_id is the page number or alphanumeric alias

• session is the session ID

• APPLICATION_PROCESS=process_id is the keyword APPLICATION_PROCESS= followed by either the process ID or an alphanumeric name of an application-level process having a Process Point of On Demand

When you use this syntax, the Application Express engine recognizes the request and processes it using the following rules:

• The page number in the URL can be any page number or alias. A page number or alias is required in the request only as a syntactic placeholder because no specific page is accessed for this type of request.

• The process authorization scheme, the application's authorization scheme, and the process conditions are supported.

• Session state (that is, item names and values) may be set in the URL, but clear cache options are ignored.

• Any failures of authentication, authorization, or process conditions do not result in visible error messages or other indicators of such failures and most often result in a blank page being displayed.

• Specifying the process by name locates the first process with the specified (case-preserved) name.

About the Application Process Page

Once you create an application process, it appears on the Application Processes page. You control how the page displays by making a selection from the View list. Available options include:

• Icons (the default) displays each process as a large icon. To edit a process, click the appropriate icon.

• Details displays each application process as a line in a report. To edit a process, click the name.

Utilization

Click Utilization to display the Application Process Utilization page. This page displays application processes used in the current application.

History

Click History to display the Application Process History page. This page displays a history of recently changed application processes by date.

About Application Computations that Execute On New Instance

Typically an application computation runs at the same point across multiple pages in an application. The exception is computations having a Computation Point of On New Instance. This type of computation only runs when a user first accesses your application. This type of computation is useful when you need to only retrieve information once within a user's session (for example, to retrieve a user's job title).

About the Application Computations Page

Once you create an application computation, it appears on the Application Computations page. You control how the page displays by making a selection from the View list. Available options include:

• Icons (the default) displays each computation as a large icon. To edit an computation, click the appropriate icon.

• Details displays each application process as a line in a report. To edit a computation process, click the name.