Oracle® Database

Application Express User's Guide

Release 3.0

B32471-02

June 2007

Oracle Database Application Express User's Guide, Release 3.0

B32471-02

Copyright © 2003, 2007, Oracle. All rights reserved.

Primary Author:  Terri Winters, Anne Romano

Contributors:  Marco Adelfio, Carl Backstrom, Christina Cho, Michael Hichwa, Christopher Jones, Joel Kallman, Sharon Kennedy, Syme Kutz, Sergio Leunissen, Kris Rice, Marc Sewtz, Scott Spadafore, Scott Spendolini, Jason Straub, Simon Watt, and Steve Fogel

The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.

If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.

Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.

Contents

Preface

- Topic Overview

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

What's New in Oracle Application Express

- Oracle Application Express Release 3.0 New Features

Part I Getting Started with Oracle Application Express

1 Quick Start

- What is Oracle Application Express?

- About Oracle Application Express Architecture

- Understanding Application Express User Roles

- Logging In to Oracle Application Express

- About Browser Requirements

- Configuring Your Oracle Application Express Environment

- Logging In to Oracle Application Express as a Developer

- About the Workspace Home Page

- Navigation Alternatives

- Using Online Help

2 Running a Demonstration Application

- Installing a Demonstration Application

- Running an Installed Demonstration Application

- Running an Application from Demonstration Applications

- Running an Application from the Application Home Page

- Understanding Sample Application

- About the Home Page

- About the Customers Page

- About the Products Page

- About the Orders Page

- About the Charts Page

- About the Admin Page

- Viewing Pages in Printer Friendly Mode

- Modifying a Demonstration Application

- About the Developer Toolbar

- Editing a Demonstration Application

- Viewing Underlying Database Objects

- Viewing the Database Object Dependencies Report

- Viewing Database Objects in Object Browser

Part II Application Development

3 Application Builder Concepts

- What Is a Page?

- Understanding Page Processing and Page Rendering

- How the Application Express Engine Renders and Processes Pages

- Understanding Conditional Rendering and Processing

- Verifying User Identity

- Controlling Access to Controls and Components

- Understanding Session State Management

- What Is a Session?

- Understanding Session IDs

- Viewing Session State

- Managing Session State Values

- Referencing Session State

- Setting Session State

- Clearing Session State

- About Bind Variable Syntax

- Understanding URL Syntax

- 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 Substitution Strings

- Using Substitution Strings

- About Built-in Substitution Strings

4 Using Application Builder

- Accessing Application Builder

- About the Application Builder Home Page

- Configuring Developer Preferences

- About the Application Home Page

- About the Action Bar

- About Application Attributes

- Configuring the Application Definition

- Configuring Security Attributes

- Configuring Globalization Attributes

- About the Page Definition

- Accessing a Page Definition

- Understanding the Page Definition

- Using the View List on the Page Definition

- Accessing the View List on the Page Definition

- About Page Events

- About Database Object Dependencies

- About History

- About Export

- About Groups

- About Referenced

- Editing a Page Definition

- About the Edit All Icon

- About the Copy or Create Icons

- Reordering Page Components

- About Page Rendering

- About Page Processing

- About Shared Components

- Understanding Page Computations

- Understanding Validations

- Understanding Page Processes

- Understanding Branches

- Editing Page Attributes

- Accessing Page Attributes

- About the Page Attributes Page

- About the Developer Toolbar

- Working with Shared Components

- Accessing the Shared Components Page

- About the Shared Components Page

- About Exporting Shared Components

- Accessing Reports on Shared Components

- Understanding Application Processes

- About On Demand Application Processes

- Application Process Example

- Creating an Application Process

- Accessing Application Processes Reports

- Understanding Application Computations

- About Application Computations

- Creating an Application Computation

- Accessing the Application Computation History Report

- Viewing Application Reports

- Accessing Application Reports

- Shared Components Reports

- Page Components Reports

- Activity Reports

- Cross Application Reports

5 Building an Application

- Creating an Application

- About Creating an Application Using a Wizard

- About the Create Application Wizard

- About the Create Application from Spreadsheet Wizard

- About Demonstration Applications

- Copying an Application

- Deleting an Application

- Managing Pages in an Application

- About Creating Pages

- Creating a Page from the Application Home Page

- Creating a Page from the Page Definition

- Creating a Page from the Developer Toolbar

- Copying a Page

- Running a Page or Application

- Grouping Pages

- Locking and Unlocking a Page

- Deleting a Page

- Adding Application Comments

- Creating an Application Comment

- Viewing the Application Comments Report

- Adding Developer Comments

- Adding Developer Comments to an Application or Page

- Viewing and Editing Developer Comments

- Deleting Developer Comments

- About the Developer Comments Report

- Creating Reports

- Creating a Report Using a Wizard

- Editing Report Attributes

- Altering Report Layout Using Column Attributes

- Controlling Report Pagination

- Enabling Column Sorting

- Adding a Download Link to a Report

- Exporting a Report as an XML File or a CSV File

- Creating a Column Link

- Defining an Updatable Column

- Defining a Column as a List of Values

- Controlling When Columns Display

- Controlling Column Breaks

- Printing Report Regions

- Creating Forms

- Creating a Form Using a Wizard

- Creating a Tabular Form

- Creating a Master Detail Form

- Creating a Form Manually

- Validating User Input in Forms

- Creating Calendars

- About Creating Calendars

- Creating a New Calendar

- Editing a Calendar Title

- Editing Calendar Attributes

- Upgrading a Calendar Created in a Previous Releases

- Converting an Easy Calendar to a SQL Calendar

- Creating Charts

- About Supported Chart Types

- About Creating SQL Queries for Charts

- Creating an HTML Chart

- Creating a SVG Chart

- Creating a Flash Chart

- Editing Chart Attributes

- Using Custom XML with Flash Charts

- Enabling Asynchronous Updates

- Displaying SVG Charts in Other Languages

- Creating Buttons

- About the Buttons Section of the Page Definition

- Creating a Button Using a Wizard

- Creating Multiple Buttons

- Editing Buttons

- Understanding the Relationship Between Button Names and REQUEST

- About Branching with Buttons

- Displaying Buttons Conditionally

- Understanding Page-Level Items

- Differences Between Page Items and Application Items

- About the Items Section of the Page Definition

- Creating Page-Level Items

- Editing Page-Level Items

- Using the Drag and Drop Layout Page

- Referencing Item Values

- Displaying Conditional or Read-Only Page Items

- Working with a Multiple Select List Item

- Populating an Alternative Date Picker Format for an Application

- Populating an Alternative Date Picker Format for a Specific Item

- Understanding Application-Level Items

- Creating an Application-level Item

- Accessing Application Item History

- Editing Application-level Item Attributes

- Creating Lists of Values

- Creating a Named LOV at the Application Level

- About Static LOVs

- Editing an Existing LOV

- Referencing Session State Within an LOV

- Referencing a Null Value in an Item Based on an LOV

- Accessing LOV Reports

- Creating Dependent Select Lists

- Using Shortcuts

- About Shortcut Types

- Defining Shortcuts

- Editing Existing Shortcuts

- Accessing Shortcut Reports

- Using the Find Icon

- About the Find Icon

- About the Item Finder

- Using the Page Finder

- Using the Query Finder

- Using the Table Finder

- Using the PL/SQL Finder

- Using the Images Finder

- Using the CSS Finder

- Controlling Access to Applications, Pages, and Page Components

- How the Access Control List Works

- Creating an Access Control List

- Selecting an Application Mode and Adding Users

- Controlling Access for Pages and Page Components

- Incorporating JavaScript into an Application

- Referencing Items Using JavaScript

- Incorporating JavaScript Functions

- Calling JavaScript from a Button

- Creating a Help Page

- Creating a Help Page and Region

- Defining Help Text

- Creating a Help Navigation Bar Entry

6 Adding Navigation

- Creating Tabs

- About Template Support

- About the Tabs Section of the Page Definition

- Using the Reorder Tabs Icon

- About the Tabs Page

- How to Create a Tab

- Editing Tabs

- Accessing Tab Reports

- Creating Lists

- How To Create a List

- Adding a List to a Page

- Editing a List

- Editing Multiple List Entries Simultaneously

- Accessing List Reports

- Creating Breadcrumbs

- About Breadcrumbs

- How to Create Breadcrumbs

- Editing Breadcrumbs

- Reparenting Breadcrumb Entries

- Accessing Breadcrumb Reports

- Creating Trees

- How To Create a Tree

- Editing a Tree

- Accessing Tree Reports

- Creating a Navigation Bar Entry

- About Navigation Bars

- How to Create a Navigation Bar Entry

- Editing a Navigation Bar Entry

- Editing Multiple Navigation Bar Entries Simultaneously

- Using the Reorder Navigation Bar Entries Icon

- Accessing Navigation Bar Entry Reports

- Controlling Navigation Using Branches

7 Controlling Page Layout and User Interface

- Understanding Page Layout in Oracle Application Express

- Displaying Components on Every Page of an Application

- Understanding Regions

- About the Regions Section of the Page Definition

- Using the Reorder Regions Icon

- Editing Region Attributes

- Creating a Region

- About Region Types

- Copying a Region

- Creating a Multiple Column Layout

- Creating Regions in Multiple Columns

- Creating a Multiple Column Page Template

- How Item Attributes Affect Page Layout

- Incorporating Content from Other Web Sites

- Managing Themes

- Accessing the Themes Page

- Changing the Default Templates in a Theme

- Creating a New Theme

- Switching the Active Theme

- Copying a Theme

- Deleting a Theme

- About Exporting and Importing Themes

- Changing a Theme Identification Number

- Viewing Theme Reports

- Customizing Templates

- About Cascading Style Sheets

- Selecting a Default Page Template

- Creating a New Template

- Viewing Template Reports

- Editing Templates

- Breadcrumb Templates

- Button Templates

- Calendar Templates

- Label Templates

- List Templates

- Page Templates

- Popup LOV Templates

- Region Templates

- Report Templates

- Optimizing a Page for Printing

- Selecting a Printer Friendly Template for an Application

- Using f?p Syntax to Toggle to Printer Friendly Mode

- Using Custom Cascading Style Sheets

- Uploading Cascading Style Sheets

- Referencing an Uploaded Cascading Style Sheet in the Page Template

- Managing Images

- Uploading Images

- Referencing Images

- Editing Image Attributes

- Deleting an Image

- Managing Static Files

- Uploading Static Files

- Editing an Uploaded File

- Downloading an Uploaded File

- Deleting an Uploaded File

- Rendering HTML Using Custom PL/SQL

8 Understanding Application Administration

- Understanding Administrator Roles

- About the Application Administration Page

- Accessing the Application Administration Page

- Resetting Your Password from Application Administration

- Viewing the Application Express Product Information Page

- About the Manage Services Page

- Accessing the Manage Services Page

- Managing Session State and User Preferences

- Managing Session State

- Managing User Preferences

- Managing Cached Regions and Pages

- Purging Cached Regions

- Purging Cached Pages

- Managing Workspace Preferences

- Disabling PL/SQL Program Unit Editing for a Workspace

- Enabling Login Controls for a Workspace

- Managing Application Models

- Deleting an Application Model

- Managing Demonstration Applications

- Leveraging Application Builder Defaults

- About Application Builder Defaults

- Configuring Application Builder Defaults

- Viewing the Workspace Overview Report

- Viewing Workspace Summary Report

- Viewing Available Storage Space

- Terminating a Workspace Service

- Requesting a Database Schema

- Requesting Additional Storage

- Viewing Schema Reports

- Managing Log Files

- Purging the Developer Activity Log

- Purging the External Click Count Log

- Managing Application Express Users

- Creating New User Accounts

- Editing Existing User Accounts

- Deleting or Locking User Accounts

- Changing an End User Password

- Using Groups to Manage Application Express Users

- Monitoring Activity within a Workspace

- Viewing Developer Activity and Application Change Information

- Viewing Application Changes by Developer

- Viewing Application Changes by Day

- Viewing Active Sessions

9 Managing User Interface Defaults

- Viewing Tables or Views Utilizing User Interface Defaults

- Creating to User Interface Defaults

- Viewing the UI Defaults Report in Object Browser

- Editing Column Attributes

- About the Column Definition

- About List of Values

- About the Database Column Definition Report

- Comparing User Interface Defaults Across Applications

- About Exporting and Importing User Interface Defaults

10 Debugging an Application

- About Tuning Performance

- Reviewing Session State

- Accessing Debug Mode

- Enabling SQL Tracing and Using TKPROF

- Monitoring Application and Page Resource Use

- Viewing Reports

- Debugging Problematic SQL Queries

- Removing Controls and Components to Isolate a Problem

11 Managing Application Security

- About Cross-Site Scripting Protection

- Protecting HTML Regions and Other Static Areas

- Protecting Dynamic Output

- Protecting Report Regions

- Protecting Form Items

- Enabling Network Services in Oracle Database 11g

- Understanding Session State Protection

- How Session State Protection Works

- Enabling Session State Protection

- Configuring Session State Protection

- Understanding the Security Risks of File Upload Tables

- Establishing User Identity Through Authentication

- Understanding How Authentication Works

- Determining Whether to Include Authentication

- About Preconfigured Authentication Schemes

- Creating an Authentication Scheme

- Using the Authentication Scheme Repository

- Viewing the Current Authentication Scheme for an Application

- Changing the Current Authentication Scheme for an Application

- Viewing Authentication Scheme Utilization

- About Creating an Authentication Scheme from Scratch

- Providing Security Through Authorization

- How Authorization Schemes Work

- Creating an Authorization Scheme

- Attaching an Authorization Scheme to an Application, Page, or Components

- Viewing Authorization Reports

12 Deploying an Application

- About the Oracle Application Express Application Development Life Cycle

- System Development Life Cycle Methodologies to Consider

- Understanding the Packaging Process

- Deployment Options to Consider

- Deciding Whether to Copy a Workspace

- Deciding Whether to Copy a Database

- About the Application ID

- Deciding to Install a New HTTP Server

- How to Move an Application to Another Development Instance

- About Managing Database Objects

- How to Create a Packaged Application

- How a Packaged Application Simplifies Deployment

- Creating a Packaged Application

- Adding Installation Scripts for an Image, Cascading Style Sheet, or Static File

- Adding an Access Control List to a Packaged Application

- Installing Supporting Objects

- Deleting Supporting Objects Scripts, Messages, and Installation Options

- Upgrading a Packaged Application

- Deinstalling Supporting Objects

- Viewing an Install Summary

- Exporting an Application and Related Files

- Exporting an Application

- Exporting Workspace Users

- Exporting Application Components

- Exporting a Page in an Application

- Exporting Cascading Style Sheets

- Exporting Images

- Exporting Static Files

- Exporting Script Files

- Exporting Themes

- Exporting User Interface Defaults

- Importing Export Files

- Importing an Application or Page

- Importing Cascading Style Sheets

- Importing Static Files

- Importing Images

- Importing Themes

- Importing User Interface Defaults

- Installing Export Files

- Accessing the Export Repository

- Installing an Application Export from the Export Repository

- Installing Other Files from the Export Repository

- Deleting Files from the Export Repository

- Installing Export Files from SQL*Plus

- About Publishing the Application URL

- Using Build Options to Control Configuration

- Creating Build Options

- Managing Build Options

- Exporting Build Options or Build Option Status

- Viewing the Build Option Utilization Report

13 Advanced Programming Techniques

- About DML Lockings

- Accessing Data with Database Links

- Sending Email from an Application

- About Configuring Oracle Application Express to Send Email

- Sending Email from an Application

- Using Collections

- About the APEX_COLLECTION API

- Creating a Collection

- Truncating a Collection

- Accessing a Collection

- Deleting a Collection

- Adding Members to a Collection

- Updating Collection Members

- Deleting Collection Members

- Determining Collection Status

- Merging Collections

- Managing Collections

- Clearing Collection Session State

- Creating Custom Activity Reports Using APEX_ACTIVITY_LOG

- Running Background PL/SQL

- Understanding the APEX_PLSQL_JOB Package

- About System Status Updates

- Using a Process to Implement Background PL/SQL

- Implementing Web Services

- Understanding Web Service References

- Working with SSL Enabled Web Services

- Creating a Web Service Reference Based on a WSDL

- Using the Web Service Reference Repository

- Testing a Web Service Reference Created from a WSDL

- Testing a Web Service Reference Created Manually

- Creating an Input Form and Report on a Web Service

- Creating a Form on a Web Service

- Invoking a Web Service as a Process

- Editing a Web Service Process

- Viewing a Web Service Reference History

14 Managing Application Globalization

- About Translating an Application and Globalization Support

- About Language Identification

- Rules for Translating Applications Built in Application Builder

- How Translated Applications Are Rendered

- About Translatable Components

- Specifying the Primary Language for an Application

- Using Format Masks for Items

- Translating Applications for Multibyte Languages

- Understanding the Translation Process

- Step 1: Map the Target Language

- Step 2: Seed and Export Text to a Translation File

- Step 3: Translate the XLIFF File

- Step 4: Upload and Apply a Translated XLIFF Document and Publish the Application

- Manually Editing a Translation

- Translating Messages

- Translating Messages Used in PL/SQL Procedures

- Translating Messages Used Internally by Application Express

- Translating Data That Supports List of Values

- Defining a Dynamic Translation

- APEX_LANG.LANG API

- About Supported Globalization Codes

15 Oracle Application Express APIs

- APEX_UTIL

- CHANGE_CURRENT_USER_PW Procedure

- CACHE_GET_DATE_OF_PAGE_CACHE Procedure

- CACHE_GET_DATE_OF_REGION_CACHE Procedure

- CACHE_PURGE_BY_APPLICATION Procedure

- CACHE_PURGE_BY_PAGE Procedure

- CACHE_PURGE_STALE Procedure

- CHANGE_PASSWORD_ON_FIRST_USE Function

- CLEAR_APP_CACHE Procedure

- CLEAR_PAGE_CACHE Procedure

- CLEAR_USER_CACHE Procedure

- COUNT_CLICK Procedure

- COUNT_STALE_REGIONS Function

- CREATE_USER Procedure

- CREATE_USER_GROUP Procedure

- CURRENT_USER_IN_GROUP Function

- EDIT_USER Procedure

- END_USER_ACCOUNT_DAYS_LEFT Function

- EXPIRE_END_USER_ACCOUNT Procedure

- EXPIRE_WORKSPACE_ACCOUNT Procedure

- EXPORT_USERS Procedure

- FETCH_APP_ITEM Function

- FETCH_USER Procedure

- FIND_SECURITY_GROUP_ID Function

- FIND_WORKSPACE Function

- GET_ACCOUNT_LOCKED_STATUS Function

- GET_ATTRIBUTE Function

- GET_AUTHENTICATION_RESULT Function

- GET_CURRENT_USER_ID Function

- GET_DEFAULT_SCHEMA Function

- GET_EMAIL Function

- GET_FILE Procedure

- GET_FILE_ID Function

- GET_FIRST_NAME Function

- GET_GROUPS_USER_BELONGS_TO Function

- GET_GROUP_ID Function

- GET_GROUP_NAME Function

- GET_LAST_NAME Function

- GET_USERNAME Function

- GET_NUMERIC_SESSION_STATE Function

- GET_PREFERENCE Function

- GET_SESSION_STATE Function

- GET_USER_ID Function

- GET_USER_ROLES Function

- IS_LOGIN_PASSWORD_VALID Function

- IS_USERNAME_UNIQUE Function

- KEYVAL_NUM Function

- KEYVAL_VC2 Function

- LOCK_ACCOUNT Procedure

- PASSWORD_FIRST_USE_OCCURRED Function

- PREPARE_URL Function

- PUBLIC_CHECK_AUTHORIZATION Function

- PURGE_REGIONS_BY_APP Procedure

- PURGE_REGIONS_BY_ID Procedure

- PURGE_REGIONS_BY_NAME Procedure

- PURGE_REGIONS_BY_PAGE Procedure

- PURGE_STALE_REGIONS Procedure

- REMOVE_PREFERENCE Procedure

- REMOVE_SORT_PREFERENCES Procedure

- REMOVE_USER Procedure

- RESET_AUTHORIZATIONS Procedure

- RESET_PW Procedure

- SAVEKEY_NUM Function

- SAVEKEY_VC2 Function

- SET_ATTRIBUTE Procedure

- SET_AUTHENTICATION_RESULT Procedure

- SET_CUSTOM_AUTH_STATUS Procedure

- SET_EMAIL Procedure

- SET_FIRST_NAME Procedure

- SET_LAST_NAME Procedure

- SET_PREFERENCE Procedure

- SET_SESSION_STATE Procedure

- SET_USERNAME Procedure

- STRING_TO_TABLE Function

- TABLE_TO_STRING Function

- UNEXPIRE_END_USER_ACCOUNT Procedure

- UNEXPIRE_WORKSPACE_ACCOUNT Procedure

- UNLOCK_ACCOUNT Procedure

- URL_ENCODE Function

- WORKSPACE_ACCOUNT_DAYS_LEFT Function

- APEX_MAIL

- SEND Procedure

- PUSH_QUEUE Procedure

- APEX_ITEM

- CHECKBOX Function

- DATE_POPUP Function

- DISPLAY_AND_SAVE Function

- HIDDEN Function

- MD5_CHECKSUM Function

- MD5_HIDDEN Function

- MULTI_ROW_UPDATE Procedure

- POPUP_FROM_LOV Function

- POPUP_FROM_QUERY Function

- POPUPKEY_FROM_LOV Function

- POPUPKEY_FROM_QUERY Function

- RADIOGROUP Function

- SELECT_LIST Function

- SELECT_LIST_FROM_LOV Function

- SELECT_LIST_FROM_LOV_XL Function

- SELECT_LIST_FROM_QUERY Function

- SELECT_LIST_FROM_QUERY_XL Function

- TEXTAREA Function

- TEXT Function

- TEXT_FROM_LOV Function

- TEXT_FROM_LOV_QUERY Function

- APEX_APPLICATION

- Referencing Arrays

- Referencing Values Within an On Submit Process

- Converting an Array to a Single Value

- APEX_CUSTOM_AUTH

- APPLICATION_PAGE_ITEM_EXISTS Function

- CURRENT_PAGE_IS_PUBLIC Function

- DEFINE_USER_SESSION Procedure

- GET_COOKIE_PROPS Procedure

- GET_LDAP_PROPS Procedure

- GET_NEXT_SESSION_ID Function

- GET_SESSION_ID_FROM_COOKIE Function

- GET_USERNAME Function

- GET_SECURITY_GROUP_ID Function

- GET_SESSION_ID Function

- GET_USER Function

- IS_SESSION_VALID Function

- LOGIN Procedure

- LOGOUT Procedure

- POST_LOGIN Procedure

- SESSION_ID_EXISTS Function

- SET_USER Procedure

- SET_SESSION_ID Procedure

- SET_SESSION_ID_TO_NEXT_VALUE Procedure

- APEX_LDAP

- AUTHENTICATE Function

- IS_MEMBER Function

- MEMBER_OF Function

- MEMBER_OF2 Function

- GET_USER_ATTRIBUTES Procedure

- GET_ALL_USER_ATTRIBUTES Procedure

Part III Database Tools

16 Managing Database Objects with Object Browser

- About Object Browser

- Accessing Object Browser

- Searching For and Browsing Database Objects

- Searching For and Selecting Database Objects

- Hiding the Object Selection Pane

- Using the Find Tables Icon

- About Creating New Database Objects

- Managing Tables

- Creating a Table

- Browsing a Table

- Editing a Table

- Dropping a Table

- Managing Views

- Creating a View

- Browsing a View

- Editing a View

- Compiling a View

- Dropping a View

- Managing Indexes

- Creating an Index

- Browsing an Index

- Dropping an Index

- Managing Sequences

- Creating a Sequence

- Browsing a Sequence

- Dropping a Sequence

- Managing Types

- Creating a Type

- Browsing a Type

- Dropping a Type

- Managing Packages

- Creating a Package

- Viewing a Package

- Editing a Package

- Compiling a Package

- Downloading a Package

- Dropping a Package

- Managing Procedures

- Creating a Procedure

- Browsing a Procedure

- Editing a Procedure

- Compiling a Procedure

- Downloading a Procedure

- Dropping a Procedure

- Managing Functions

- Creating a Function

- Browsing a Function

- Editing a Function

- Compiling a Function

- Downloading a Function

- Dropping a Function

- Managing Triggers

- Creating Triggers

- Browsing a Trigger

- Editing a Trigger

- Compiling a Trigger

- Downloading a Trigger

- Dropping a Trigger

- Managing Database Links

- Creating a Database Link

- Browsing a Database Link

- Dropping a Database Link

- Managing Materialized Views

- Creating a Materialized View

- Browsing a Materialized View

- Dropping a Materialized View

- Managing Synonyms

- Creating Synonyms

- Viewing a Synonym

- Dropping a Synonym

17 Building Queries with Query Builder

- About Query Builder

- Accessing Query Builder

- Understanding the Query Building Process

- Using the Object Selection Pane

- Searching and Filtering Objects

- Hiding the Object Selection Pane

- Selecting Objects

- About Supported Column Types

- Adding an Object to the Design Pane

- Removing or Hiding Objects in the Design Pane

- Specifying Query Conditions

- Creating Relationships Between Objects

- About Join Conditions

- Joining Objects Manually

- Joining Objects Automatically

- Working with Saved Queries

- Saving a Query

- Editing a Saved Query

- Deleting a Saved Query

- Viewing Generated SQL

- Viewing Query Results

18 Using SQL Scripts

- What is SQL Scripts?

- Accessing SQL Scripts

- About the SQL Scripts Page

- Creating a SQL Script

- Creating a SQL Script in the Script Editor

- Uploading a SQL Script

- Using the Script Editor

- Editing an Existing Script

- Searching and Replacing Text or Regular Expressions

- Summary of Script Editor Controls

- Deleting a SQL Script

- Deleting Scripts from the SQL Scripts Page

- Deleting a Script in the Script Editor

- Copying a SQL Script

- Executing a SQL Script

- Executing a SQL Script in the Script Editor

- Executing a SQL Script from the SQL Scripts Page

- About the Run Script Page

- Viewing SQL Script Results

- Viewing Results from the SQL Scripts Page

- About the Results Page

- Exporting and Importing SQL Scripts

- Copying Scripts to an Export Script

- Importing Scripts from an Export Script

- Viewing Script and Result Quotas

19 Using SQL Commands

- What is SQL Commands?

- Accessing SQL Commands

- About the SQL Commands Home Page

- Using the Command Editor

- Running a SQL Command

- About Transactions in SQL Commands

- About Unsupported SQL*Plus Commands

- About Command Termination

- Using Bind Variables

- Saving a SQL Command

- Copying a Command

- Using Saved Commands

- Accessing Saved Commands

- About the Saved SQL Pane

- Using SQL Command History

- Accessing a Command from Command History

- About the History Pane

- Viewing Results

- Accessing the Results Pane

- About the Results Pane

- Using Explain Plan

- Viewing an Explain Plan

- About Explain Plan Pane

20 Using Application Express Utilities

- About Importing, Exporting, Loading, and Unloading Data

- Choosing the Right Import/Export/Load/Unload Option

- Loading and Unloading Data from the Database

- Accessing the Data Load/Unload Page

- Loading Data

- Unloading Data

- Using Text Data Load Repository

- Generating DDL

- Viewing Object Reports

- Table Reports

- Security Reports

- PL/SQL Reports

- Exception Reports

- All Object Reports

- Using the Recycle Bin to View and Restore Dropped Objects

- Managing Objects in the Recycle Bin

- Emptying the Recycle Bin Without Viewing the Objects

- Reviewing Application Express Views

- Comparing Schemas

- Monitoring the Database

- Sessions

- About System Statistics

- About Top SQL

- About Long Operations

- Viewing Database Details

21 Migrating Applications

- About Application Migration

- Preparation Checklist for Migrating Applications

- How to Migrate Your Applications

- Step 1: Export Microsoft Access Metadata

- Step 2: Migrate the Microsoft Access Database to Oracle

- Step 3: Create an Oracle Application Express Workspace

- Step 4: Create a Migration Project

- About the Project Page

- Step 5: Review Your Retrieved Objects

- Reviewing Retrieved Tables

- Reviewing Retrieved Queries

- Reviewing Retrieved Forms

- Reviewing Retrieved Reports

- Reviewing Database, Module, and Pages Information

- Step 6: Generate the Oracle Application Express Application

- Managing Your Migration Projects

Part IV Administration

22 Managing an Oracle Application Express Hosted Service

- What Is an Oracle Application Express Administrator?

- Logging in to Oracle Application Express Administration Services

- Managing Service

- Creating a Site-Specific Tasks List

- Managing Log Entries

- Managing Session State

- Managing Mail

- Viewing Installed Translations

- Managing Environment Settings

- Disabling PL/SQL Program Unit Editing for an Instance

- Disabling the Creation of Demonstration Applications in a New Workspace

- Configuring SQL Workshop

- Enabling Database Monitoring

- Configuring Security Settings

- Configuring Email Settings

- Configuring Wallet Information

- Configuring Report Printing

- Configuring Workspace Size Options for Requests

- Managing Login and System Messages

- Managing Schemas

- Determining the Application Express Engine Schema

- Understanding Oracle Default Schema Restrictions

- Creating Workspaces

- About Workspace Provisioning

- Specifying a Provisioning Mode

- Creating a Workspace Manually

- Managing Workspace to Schema Assignments

- Managing Workspace Requests

- Viewing a Pending Workspace Request on the Notifications List

- Viewing Requests from the Workspace Requests Page

- Approving or Declining a Pending Workspace Request

- Changing the Status of an Existing Workspace Request

- Deleting a Workspace Request

- Managing Change Requests

- Viewing a Pending Change Request from the Notifications List

- Viewing a Change Request from the Workspace Utilization Report

- Viewing Requests from the Change Requests Page

- Approving or Declining a Pending Change Request

- Managing Users in an Oracle Application Express Instance

- Creating New User Accounts

- Editing an Existing User Account

- Deleting User Accounts

- Managing Existing Workspaces

- Viewing Existing Workspaces

- Viewing Workspace Details

- Viewing Workspace Database Privileges

- About Deleting Inactive Workspaces

- Removing a Workspace

- Locking a Workspace

- Exporting and Importing a Workspace

- Managing Applications

- Viewing Application Attributes

- Changing Application Build Status Set During Deployment

- Viewing the Parse As Schemas Report

- Monitoring Activity Across a Development Instance

A Available Conditions

B Privileges Granted to PUBLIC

- Packages

- Procedures

- Functions

- Tables

- Views

Index

Preface

Oracle Database Application Express User's Guide describes how to use the Oracle Application Express development environment to build and deploy database-centric Web applications. Oracle Application Express turns a single Oracle database into a shared service by enabling multiple workgroups to build and access applications as if they were running in separate databases.

This preface contains these topics:

- Topic Overview

- Audience

- Documentation Accessibility

- Related Documents

- Conventions

Topic Overview

This document contains the following chapters:

Title

Description

What's New in Oracle Application Express

Describes new features available in this release of Oracle Application Express.

Quick Start

Offers a quick introduction to using the Oracle Application Express.

Running a Demonstration Application

Describes how to run and modify the demonstration applications that install with Application Builder.

Application Builder Concepts

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.

Using Application Builder

Provides important background information about using Application Builder to build dynamically rendered applications.

Building an Application

Describes how to use Application Builder to build an application and application components.

Adding Navigation

Describes how to implement navigation in your application using different types of navigation controls, including navigation bar entries, tabs, breadcrumbs, lists, and trees.

Controlling Page Layout and User Interface

Describes different approaches to customizing an application's user interface and page layout including customizing regions, editing item attributes, customizing templates, and incorporating cascading style sheets and images.

Understanding Application Administration

Explains the tasks and reports available to workspace administrators, including managing application services, session state, user preferences, log files, application models, Application Express end users, application development activity, and explains how to send email from an application.

Managing User Interface Defaults

Describes how to use user interface defaults to assign default user interface properties to a table, column, or view.

Debugging an Application

Describes approaches to debugging your Application Builder application, including viewing Debug Mode, enabling SQL tracing, viewing page reports, and how to manually remove a control or a component to isolate a problem.

Managing Application Security

Describes how to provide security for an Application Builder application by utilizing cross-site scripting protection, session state protection, authentication, and authorization.

Deploying an Application

Explains how to package an application built within Application Builder.

Advanced Programming Techniques

Provides information about advanced programming techniques including establishing database links, using collections, running background SQL, utilizing Web services, and managing user preferences.

Managing Application Globalization

Explains how to translate an application built-in Application Builder.

Oracle Application Express APIs

Describes the APIs available in Oracle Application Express.

Managing Database Objects with Object Browser

Describes how to use Object Browser to browse, create, and edit objects in an Oracle Application Express database.

Building Queries with Query Builder

Explains how to use Query Builder's graphical user interface to search and filter database objects, select objects and columns, create relationships between objects, view formatted query results, and save queries.

Using SQL Scripts

Provides information on how to use SQL Scripts to create, edit, view, run, and delete script files.

Using SQL Commands

Explains on how to use SQL Commands to create, edit, view, run, and delete SQL commands.

Using Application Express Utilities

Describes how to use Application Express Utilities to load and unload data from the database, generate DDL, view object reports, and restore dropped database objects.

Migrating Applications

Describes how to migrate a Microsoft Access application and generate an Oracle Application Express application.

Managing an Oracle Application Express Hosted Service

Describes how to administer and managing an entire Oracle Application Express instance using the Oracle Application Express Administration Services application.

Audience

Oracle Database Application Express User's Guide is intended for application developers who are building database-centric Web applications using Oracle Application Express. The guide describes how to use the Oracle Application Express development environment to build, debug, manage, and deploy applications.

To use this guide, you need to have a general understanding of relational database concepts as well as an understanding of the operating system environment under which you are running Oracle Application Express.

See Also:
Oracle Database 2 Day + Application Express Developer's Guide

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at

http://www.oracle.com/accessibility/

Accessibility of Code Examples in Documentation

Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

TTY Access to Oracle Support Services

Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services within the United States of America 24 hours a day, seven days a week. For TTY support, call 800.446.2398.

Related Documents

For more information, see these Oracle resources:

- Oracle Database Application Express Release Notes

- Oracle Database Application Express Installation Guide

- Oracle Database 2 Day + Application Express Developer's Guide

- Oracle Database Application Express Advanced Tutorials

- Oracle Database Concepts

- Oracle Database Advanced Application Developer's Guide

- Oracle Database Administrator's Guide

- Oracle Database SQL Language Reference

- SQL*Plus User's Guide and Reference

For information about Oracle error messages, see Oracle Database Error Messages. Oracle error message documentation is available only in HTML. If you have access to the Oracle Database Documentation Library, you can browse the error messages by range. Once you find the specific range, use your browser's "find in page" feature to locate the specific message. When connected to the Internet, you can search for a specific error message using the error message search feature of the Oracle online documentation.

Many books in the documentation set use the sample schemas of the seed database, which is installed by default when you install Oracle. Refer to Oracle Database Sample Schemas for information on how these schemas were created and how you can use them yourself

Printed documentation is available for sale in the Oracle Store at

http://oraclestore.oracle.com/

To download free release notes, installation documentation, white papers, or other collateral, please visit the Oracle Technology Network (OTN). You must register online before using OTN; registration is free and can be done at

http://www.oracle.com/technology/membership/

If you already have a user name and password for OTN, then you can go directly to the documentation section of the OTN Web site at

http://www.oracle.com/technology/documentation/

Conventions

The following text conventions are used in this document:

Convention

Meaning

boldface

Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace

Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

What's New in Oracle Application Express

This section describes new features available in Oracle Application Express Release 3.0 and points you to additional information.

Oracle Application Express Release 3.0 New Features

New features in Oracle Application Express, release 3.0 include:

- PDF Printing.

You can now include the ability to print a report by exporting a report region to PDF. When editing a report region, there is a new tab called Print Attributes. You can also define report queries and print attributes for report regions as Shared Components, making them accessible to all pages within an application. See "Printing Report Regions".

- Microsoft Access Migration.

Application Migration enables you to migrate a Microsoft Access application and generate an Oracle Application Express application. The migration process involves the following steps:

- Use the Exporter tool to export metadata from Microsoft Access.

- Use Oracle Migration Workbench to migrate a Microsoft Access database to Oracle.

- Create an Oracle Application Express workspace and then a migration project.

- Validate and update the retrieved objects.

- Generate an Oracle Application Express application.

See "Migrating Applications".

- Flash Charts.

Oracle Application Express includes support for 18 different types of Flash charts. You can create Flash charts when creating a new page or by defining a Chart region. This release also includes a utility that enables you to convert existing Scalable Vector Graphics (SVG) charts to Flash. See "Creating Charts".

- Drag and Drop Item Layout.

The Items section of Page Definition includes a new Drag and Drop icon. You can use this icon to access a new Drag and Drop Layout page. The Drag and Drop Layout page enables you to interactively reorder items within a given region, change select item attributes, create new items, and delete existing items. See "Using the Drag and Drop Layout Page".

- Improved Web Services.

Oracle Application Express now supports more loosely defined Web services types and document styles. Both of these enhancements enable support for Web services created with JDeveloper and Oracle BPEL synchronous processes. You can now interact with Web services over a Secure Sockets Layer (SSL) and work with Web services that require basic authentication. Finally, this release also enables you to manually create a Web service reference even if the Application Express engine cannot correctly parse a WSDL document. See "Implementing Web Services".

- New Item Types.

Release 3.0 contains the following new item types:

- Shuttle - A multiple select list that includes two boxes containing lists

- New Text areas - HTML Editor Minimal and HTML Editor Standard

- New Popup List of Values - Popup Color Picker

- Date Picker (use item format mask)

See "About Item Types" and "Populating an Alternative Date Picker Format for a Specific Item".

- Calendar Enhancement.

When you create a Calendar, you now get a Monthly, Weekly and Daily view. Application users can quickly toggle between these display modes with the click of a button. See "Creating Calendars".

- Supporting Objects Enhancement.

The Supporting Objects feature, introduced in Oracle Application Express 2.2, now includes the ability to define upgrade scripts. You can use the Upgrade page to define scripts to upgrade database objects, images, and seed data when upgrading an existing application. See "Upgrading a Packaged Application".

- Page and Region Caching.

You can improve your application's performance by taking advantage of page and region caching. In release 3.0, new Cache attributes have been added to the Page Attributes and Region Definition pages. Page caching works well for static pages and region caching is a good choice for regions such as lists that do not have any conditions or regions containing HTML text. See "Cache" and "Utilizing Region Caching".

- Item Finder Enhancements.

In release 3.0, the Item Finder features two new tabs: CSS and Images. Use the CSS tab to identify cascading style sheets that are available to any Application Express application regardless of theme. Use the Images tab to view a gallery of available art. See"Using the CSS Finder" and "Using the Images Finder".

Additionally, the Find Table icon has been added to Object Browser and SQL Commands within SQL Workshop. You can use this icon to quickly view tables and columns within the current schema. See "Using the Find Tables Icon" and "About the SQL Commands Home Page".

- Application and Schema Comparison.

New application and schema comparison capabilities enable you to identify differences between two selected applications, or between objects in two different schemas. To access the new Application Comparison utility, navigate to Application Reports and click Cross Application. See "Viewing Application Reports". To generate a schema comparison, navigate to Utilities and click Schema Comparison. See "Comparing Schemas".

- Friendly URL Syntax to Facilitate Bookmarks.

By specifying zero as the session ID, you can now make it easier for application users to bookmark pages within an application. This features makes all public page links consistent, making them easier to bookmark. See "Facilitating Bookmarks by Using Zero as the Session ID".

- New Password and Account Controls.

You can now specify rules for password expiration, mandate strong passwords (that is, specify the minimum number of and type of characters), require that users change their passwords on first use, and lock accounts.

You configure account login controls and password policies across a development instance in Oracle Application Express Administration Services. See "Configuring Security Settings". You specify controls for a specific account under Account Controls on the Edit User page. See "Managing Application Express Users".

- Improved Workspace Management.

This release also includes a number of workspace management enhancements. For users requesting new workspaces or requesting additional storage, you can control what sizes display. See "Configuring Workspace Size Options for Requests".

You can also request an email of your workspace names. See "Finding Your Workspace Name". Finally, you can view a log of login attempts. See "Monitoring Activity Across a Development Instance".

Part I

Getting Started with Oracle Application Express

Part I provides an introduction to Oracle Application Express. These chapters introduce you to basic Oracle Application Express concepts.

Part I contains the following chapters:

- Chapter 1, "Quick Start"

- Chapter 2, "Running a Demonstration Application"

1 Quick Start

This section offers a quick introduction to using Oracle Application Express. It is assumed you have already completed the installation process.

This section contains the following topics:

- What is Oracle Application Express?

- About Oracle Application Express Architecture

- Understanding Application Express User Roles

- Logging In to Oracle Application Express

- About the Workspace Home Page

- Navigation Alternatives

- Using Online Help

See Also:
Oracle Database 2 Day + Application Express Developer's Guide

What is Oracle Application Express?

What is Oracle Application Express? Oracle Application Express is a hosted declarative development environment for developing and deploying database-centric Web applications. Thanks to built-in features such as user interface themes, navigational controls, form handlers, and flexible reports, Oracle Application Express accelerates the application development process.

The Application Express engine renders applications in real time from data stored in database tables. When you create or extend an application, Oracle Application Express creates or modifies metadata stored in database tables. When the application is run, the Application Express engine then reads the metadata and displays the application.

To provide stateful behavior within an application, Oracle Application Express transparently manages session state in the database. Application developers can get and set session state using simple substitutions as well as standard SQL bind variable syntax.

The sections that follow describe key features of Oracle Application Express.

Reporting

With Oracle Application Express, you can quickly generate HTML reports that display the results of SQL queries. You can also download and print reports in HTML, PDF, RTF (compatible with Microsoft Word), and XLS (compatible with Microsoft Excel) formats.

You can declaratively link reports together to provide drill-down reporting and use bind variables to pass information from session state to a report. Reports support declarative column heading sorting, control breaks, sums, and pagination. Report sorting and pagination can use Partial Page Refresh (PPR) technology to avoid refreshing the entire page. You can also add declarative links to a report to download the report data to CSV or XML formats. Plus, you can customize the report appearance using templates. See "About Bind Variable Syntax" and "Creating Reports".

Forms

Using wizards, you can easily create forms on tables or on a stored procedure. When creating a form on a table, these wizards provide automatic management of insert, update, and delete as well as lost update detection. Once you create a form, you can rearrange form fields (called form items) using a visual representation, enabling you to quickly achieve the layout you want. Form items offer a variety of display options including text fields, text areas, radio groups, select lists, check boxes, date pickers, and popup list of values. See "Creating Forms".

Charting

You can also use wizards to create HTML, SVG, or Flash charts. You can create charts that enable users to drill down from one chart to another chart or report. Charts can also be refreshed using Partial Page Refresh (PPR) technology, avoiding the need to refresh an entire page. You can also configure a chart to refresh at defined intervals. Additionally, you can take advantage of report column templates to add simple HTML bar charts to any report. See "Creating Charts".

Spreadsheet Upload

Use the Create Application from Spreadsheet Wizard to quickly upload spreadsheet data directly into the database. You can choose to store the data in a new database table or add it to an existing database table. Once the data is uploaded, you can quickly create an application. This handy wizard enables you to go from spreadsheet to a shared application in just a few clicks. See "About the Create Application from Spreadsheet Wizard".

Session State Management

Oracle Application Express transparently manages session state (or application context) in the database. Forms automatically save session state, remembering your application context over your session. Referencing session state within SQL and PL/SQL is as simple as using bind variables. For example, consider the following SELECT statement:

SELECT * FROM EMP WHERE EMPNO = :P1_ID

In this example, the value in the item P1_ID is automatically bound when the query is run. You can also reference session state within a static context by prefixing the item name with an ampersand (&) and suffixing it with a period(.), for example:

&P1_NAME.

For management of two dimensional data sets, Oracle Application Express provides a robust collections infrastructure. Best of all, session management is stateless and does not consume any memory. See "Managing Session State Values" and "About Bind Variable Syntax".

User Interface Themes

Oracle Application Express separates presentation (or user interface themes) from the application logic. You can design your application in one theme, change to another supplied theme, or create and use your own custom theme. By separating the application logic (such as queries, processes, and branches) from the HTML rendering, your application can take advantage of new designs and other technological advances without an application rewrite. See "Managing Themes".

Flow Control and Navigation

Every Web application needs navigation and dynamic applications need flow control. Oracle Application Express provides built-in components to simplify the development and maintenance of navigational controls. Navigation is controlled using declarative tabs (one or two levels), breadcrumbs, tree controls, and lists of links. Flow control is performed using declarative branches which can take effect at specific events and under certain conditions. The appearance of navigation controls are managed through templates, making it easy to change from one look to another. See "Adding Navigation" and "Controlling Navigation Using Branches".

Conditionality on All Components

When creating dynamic Web applications, many application components and processing are conditional. In other words, you only show or process certain pieces of information based on the application context, the data, an event, or a privilege. Oracle Application Express enables you to declaratively specify conditionality of all components. This gives you exact control over what users see or do not see on a tab, button, item, list entry, and so. See "Understanding Conditional Rendering and Processing".

External Interfaces and Extensibility

Even though Oracle Application Express provides a robust declarative environment for building applications, you also have the option of developing custom interfaces or controls. For example, if a component does not meet the needs of your environment, you can generate your own custom HTML using PL/SQL. See "Rendering HTML Using Custom PL/SQL". You can also call external services using Web services. See "Implementing Web Services". Oracle Application Express also includes APIs to easily integrate email alerts into an application. See "Sending Email from an Application". Plus, because Oracle Application Express resides in the Oracle database, you can take advantage of inherent database capabilities, including external tables, PL/SQL, database links, gateways, and database Java to extend the functionality of your application.

Security

With Oracle Application Express, you can create public applications that do not require a user log in, or you can create secure applications that require authentication. Oracle Application Express provides a number of built-in authentication schemes including Single Sign On, Database Account Credentials, and an easy-to-use user management system. You can also use custom schemes that interface with just about any authentication service including Microsoft Active Directory and Oracle Applications.

Additionally, you can customize authorization to meet the needs of your environment and apply authorization selectively to an entire application, a page, or a page component. Finally, you can also take advantage of an innovative session state protection feature to prevent URL tampering and built-in features to protect an application form SQL Injection and cross-site scripting (XSS) attacks. See "Managing Application Security".

SQL Workshop Tools

SQL Workshop provides tools to enable you to view and manage database objects from a Web browser. Use SQL Commands to run SQL and PL/SQL statements. See "Using SQL Commands". Query Builder enables you to define queries by dragging and dropping tables and easily create relationships between objects. See "Building Queries with Query Builder". Object Browser provides an easy-to-use graphical user interface for viewing, creating, modifying, browsing, and dropping database objects. See "Managing Database Objects with Object Browser". Finally, you can use SQL Scripts to create, edit, view, run, and delete script files. See "Using SQL Scripts".

Supporting Objects Utility

You can simplify the steps needed to export, install, upgrade, and deinstall an application in another Oracle Application Express instance by creating a packaged application. Using the Supporting Objects utility, you can bundle the application definition with scripts for creating the database objects, seed data, images, cascading style sheets, and JavaScript.

Creating a packaged application provides application users with an installer-like experience and automates the process of importing and installing an application in another development, test, or even production instance. See "How to Create a Packaged Application".

Performance

Oracle Application Express provides application developers and application users with an extremely high level of performance. Because Oracle Application Express resides in the Oracle database, it has minimal impact on network traffic. Plus, Application Builder includes a large number of monitoring reports to enable you to identify and tune application performance. See "Debugging an Application".

Hosted Development

Oracle Application Express enables a single database to host large numbers of users. Users work in a dedicated work area called a workspace. A workspace is a virtual private database that enables multiple users to work within the same Oracle Application Express installation while keeping their objects, data and applications private. This flexible architecture enables a single database instance to manage thousands of applications.

You determine how the process of provisioning (or creating) a workspace works. For example, in email verification provision mode, users request a workspace using a link on the login page. After the workspace request has been granted, users receive an email containing a link that they must click to verify the validity of their email address. Then they receive an email with their login credentials. To see an example of email verification provision mode, go to:

http://apex.oracle.com

See "Configuring Your Oracle Application Express Environment" and "Managing an Oracle Application Express Hosted Service" .

About Oracle Application Express Architecture

Oracle Application Express installs with your Oracle database and is comprised of data in tables and PL/SQL code.

Whether you are running the Oracle Application Express development environment or an application you built using Oracle Application Express, the process is the same. Your browser sends a URL request that is translated into the appropriate Oracle Application Express PL/SQL call. After the database processes the PL/SQL, the results are relayed back to your browser as HTML. This cycle happens each time you either request or submit a page.

The application session state is managed in the database tables within Application Express. It does not use a dedicated database connection. Instead, each request is made through a new database session, consuming minimal CPU resources.

About Oracle HTTP Server (Apache) and the Embedded PL/SQL Gateway

The version of Oracle Database you use determines how the URL is translated:

- Versions prior to Oracle Database 11.1 require Oracle HTTP Server (Apache) with mod_plsql. The following graphic illustrates the three-tier architecture.

- With Oracle Database 11.1 or higher or Oracle Database 10g Express Edition, you can remove Oracle HTTP Server and mod_plsql from the architecture and replace it with the embedded PL/SQL gateway. The following graphic illustrates the two-tier architecture using the embedded PL/SQL gateway.

The embedded PL/SQL gateway provides the Oracle database with a Web server and also the necessary infrastructure to create dynamic applications. The embedded PL/SQL gateway runs in the XML DB HTTP server in the Oracle database and includes the core features of mod_plsql, but does not require the Oracle HTTP Server powered by Apache. Inclusion of the embedded PL/SQL gateway simplifies the architecture and eliminates the middle tier entirely.

About the Application Express Engine

The Application Express engine renders and processes pages. It also performs these tasks:

- session state management

- authentication services

- authorization services

- page flow control

- validations processing

Understanding Application Express User Roles

To access the Oracle Application Express development environment, users log in to a shared work area called a workspace. Users are divided into four primary roles:

- Developers are users who create and edit applications

- Workspace administrators are users who perform administrator tasks specific to a workspace such as managing user accounts, monitoring workspace activity, and viewing log files

- End users have no development privileges and are defined to provide access to applications that do not use an external authentication scheme.

- Oracle Application Express administrators are superusers that manage an entire hosted instance using the Application Express Administration Services application

See Also:
"Understanding Administrator Roles", "Managing Application Express Users" and "Managing an Oracle Application Express Hosted Service"

Logging In to Oracle Application Express

When you log in to Oracle Application Express you log in to a workspace. A workspace is an area within the Oracle Application Express development environment where developers can create applications.

How you log in to Oracle Application Express depends upon whether you have configured your development environment:

- If you have recently installed Oracle Application Express, you need to configure your development environment

- If you are a developer logging into a previously configured development environment, an administrator must grant you access to a workspace

Topics in this section include:

- About Browser Requirements

- Configuring Your Oracle Application Express Environment

- Logging In to Oracle Application Express as a Developer

About Browser Requirements

You open the Oracle Application Express home page in a Web browser. To view or develop Oracle Application Express applications, the Web browser must support Java Script and the HTML 4.0 and CSS 1.0 standards. Ensure also that cookies are enabled. The following browsers meet this requirement:

- Microsoft Internet Explorer 6.0 or higher

- Mozilla Firefox 1.0 or higher

Configuring Your Oracle Application Express Environment

How you set up Oracle Application Express depends upon your user role. If you are a developer accessing a hosted development environment, an administrator must grant you access to a workspace. If you are an Oracle Application Express administrator, you must perform the following steps:

1. Log in to Oracle Application Express Administration Services. Oracle Application Express Administration Services is a separate application for managing an entire Oracle Application Express instance. See "Logging in to Oracle Application Express Administration Services" .

2. Specify a provisioning mode. In Oracle Application Express Administration Services you need to determine how the process of creating (or provisioning) a workspace will work. See "About Workspace Provisioning" and "Specifying a Provisioning Mode".

3. Create a Workspace. A workspace is a virtual private database allowing multiple users to work within the same Oracle Application Express installation while keeping their objects, data and applications private. Each workspace has a unique ID and name. An Oracle Application Express administrator can create a workspace manually or have users submit requests. See "Creating Workspaces" and "Managing Workspace Requests".

4. Log in to a Workspace. Once you create a workspace in Oracle Application Express Administration Services, return to the Oracle Application Express Login page and log in to that workspace. See "Logging In to Oracle Application Express as a Developer".

See Also:
"Managing an Oracle Application Express Hosted Service"

Logging In to Oracle Application Express as a Developer

When you log in to Oracle Application Express, you log in to a workspace. If you are a developer, an administrator must grant you access to a workspace.

Note:
Before users can request a workspace or change their passwords, an Oracle Application Express administrator must configure Oracle Application Express environment preferences.

See Also:
"Managing Environment Settings"

Topics in this section include:

- Requesting a Workspace

- Logging in to a Workspace

- Finding Your Workspace Name

- Resetting Your Password

- Logging Out of a Workspace

Requesting a Workspace

Note:
This section applies only if your Oracle Application Express administrator has configured Oracle Application Express to support workspace requests.

See Also:
"Specifying a Provisioning Mode" and "Configuring Email Settings"

Before you can log in to Oracle Application Express, an administrator must grant you access to a workspace. Each workspace has a unique ID and name.

To request a workspace:

1. In a Web browser, navigate to the Oracle Application Express Login page.
If you do not know the URL for logging in to Application Express, see "Logging in to a Workspace".

The Login page appears.

2. Under Tasks, click Request a Workspace.
The Request Service Wizard appears.

3. Click Next and follow the on-screen instructions.

See Also:
"Creating Workspaces"

Logging in to a Workspace

After an Oracle Application Express administrator approves a workspace request, an e-mail arrives with your login credentials (the workspace name, user name, and password).

Note that if your administrator selected Email Verification as the automated method for handling new workspace requests, you might first receive an email containing a verification link. This step ensures that your email is a valid one before the workspace request is approved.

See Also:
"Specifying a Provisioning Mode" and "Configuring Email Settings"

To log in to Oracle Application Express:

1. In a Web browser, navigate to the Oracle Application Express Login page. By default, Oracle Application Express installs to the following location:

- If your setup uses the embedded PL/SQL gateway, go to:

http://hostname:port/apex

Where:

- hostname is the name of the system where Oracle XML DB HTTP Server is installed.

- port is the port number assigned to Oracle XML DB HTTP Server. In a default installation, this number is 8080. You can find information about your Oracle HTTP Server installation's port number from the following file:

ORACLE_BASE\ORACLE_HOME\install\portlist.ini

However, be aware that if you change a port number, it is not updated in the portlist.ini file, so you can only rely on this file immediately after installation.

- apex is the database access descriptor (DAD) defined in the configuration file.

For users who have upgraded from earlier releases, or who have a custom configuration, this value may be htmldb or something else. Verify your DAD with your Oracle Application Express administrator.

- If your setup uses Oracle HTTP Server (Apache) and mod_plsql, go to:

http://hostname:port/pls/apex

Where:

- hostname is the name of the system where Oracle HTTP Server is installed.

- port is the port number assigned to Oracle HTTP Server. In a default installation, this number is 7777. You can find information about your Oracle HTTP Server installation's port number from either of the following files:

ORACLE_BASE\ORACLE_HOME\install\portlist.ini
ORACLE_BASE\ORACLE_HTTPSERVER_HOME\Apache\Apache\conf\httpd.conf

- pls is the indicator to use the mod_plsql cartridge.

- apex is the database access descriptor (DAD) defined in the mod_plsql configuration file.

For users who have upgraded from earlier releases, or who have a custom configuration, this value may be htmldb or something else. Verify your DAD with your Oracle Application Express administrator.

See Also:
"Managing Oracle Database Port Numbers" in Oracle Database Installation Guide and ORACLE_BASE\ORACLE_HTTPSERVER_HOME\Apache\modplsql\conf\dads.readme for more information on database access descriptors

The Login page appears.

2. Under Login, enter the following:

- In the Workspace field, enter the name of your workspace.

- In the Username field, enter your user name.

- In the Password field, enter your case-sensitive password.

3. Click Login.
Note that, depending on your setup, you might be required to change your password when you log in for the first time.

Finding Your Workspace Name

If you cannot remember your workspace name, you can request a list of all workspace names associated with your email address.

To find your workspace name:

1. On the Login page, click Find My Workspace on the Tasks list.

2. Enter your email address and click Find Workspace.
An email with the list workspace names. is sent to you.

Resetting Your Password

You can reset your password by clicking the Change Password link on the Workspace home page.

To reset your password from the Workspace home page:

1. Log in to Oracle Application Express. See "Logging In to Oracle Application Express".

2. From the Administration list, click Change Password.
The Change Password page appears.

3. In Change Password, enter the following:

- Enter Current Password - Enter your current password.

- Enter New Password - Enter your new password.

- Confirm New Password - Enter your new password again.

4. Click Apply Changes.

See Also:
"Changing an End User Password"

Logging Out of a Workspace

To log out of Oracle Application Express, click the Logout icon in the upper right corner of the window.

About the Workspace Home Page

When you log in to Oracle Application Express, the Workspace home page appears. A workspace is a virtual private database allowing multiple users to work within the same Oracle Application Express installation while keeping their objects, data and applications private.

Your user name and workspace name display in the lower left corner of the page. The following three large icons display in the center of the page:

- Application Builder. Use Application Builder to assemble an HTML interface (or application) on top of database objects such as tables and procedures. See "Application Builder Concepts" and "Using Application Builder".

- SQL Workshop. Use the SQL Workshop to access tools for viewing and managing database objects. Click SQL Workshop to access the following database tools:

- Object Browser. View, create, modify, browse, and drop database objects. Use the PL/SQL editor to edit and compile packages, procedures, functions, and triggers while taking advantage of error reporting. See "Managing Database Objects with Object Browser".

- SQL Commands. Run SQL commands and anonymous PL/SQL, scripts, and saved queries. See "Using SQL Commands".

- SQL Scripts. Use SQL Scripts to create, edit, view, run, and delete script files. You can also upload and download scripts from your local file system. See "Using SQL Scripts".

- Query Builder. Use Query Builder's graphical user interface to search and filter database objects, select objects and columns, create relationships between objects, view formatted query results, and save queries with little or no SQL knowledge. See "Building Queries with Query Builder".

- Utilities. Use Utilities to load and unload data from the database, generate DDL, view object reports, restore dropped database objects, and monitor the database. See "Using Application Express Utilities".

About Administration

An Administration list appears on the right side of the Workspace home page. Use the following links to administer your application development environment:

- Administration links to the Application Administration page. Use this page to perform administrative tasks. See "About the Application Administration Page".

- Manage Services links to the Manage Services page. Use this page to manage session state, log files, preferences, and application models. See "About the Manage Services Page".

- Manage Application Express Users links to the Existing Users page. Use this page to manage existing Application Express users as well as user groups. See "Managing Application Express Users" and "Using Groups to Manage Application Express Users".

- Monitor Activity links to the Monitor Activity page. Use this page to monitor page views and view application changes. See "Monitoring Activity within a Workspace".

- Change Password links to the Change Password page. Use this page to change your workspace password. See "Resetting Your Password".

- About Application Express links to the About Application Express page. This page displays version and configuration information for both Application Express and the Oracle database. See "Viewing the Application Express Product Information Page".

About Migrations

Use the Migrations link to migrate a Microsoft Access application and generate an Oracle Application Express application. See "Migrating Applications".

About Workspace Schemas

The Workspace Schemas list displays beneath the Administration list. It displays the database schemas that are associated with, and therefore accessible to, this workspace.

About Links

The Links list displays on the lower side of the Workspace home page. Use this list to access the following Application Express resources:

- Oracle Technology Network links to the Oracle Application Express section of Oracle Technology Network. Use this page to access additional information and resources about using Oracle Application Express.

- Discussion Forum links to Oracle Application Express Discussion Forum. Use this page as a resource for research as well as for posting your own questions or answering those of other users.

- User's Guide links to an HTML-based online Help system. You can also access online Help by clicking the Help link in the upper right corner of any page in Oracle Application Express. See "About Procedural Online Help".

Navigation Alternatives

This section describes alternative methods for navigating between pages in the Application Express user interface.

Navigating Using Icons or Drop Down Menus

You can move between pages in Oracle Application Express by clicking large graphical icons. When using these icons, you have two navigation options:

- Primary Navigation (drill-down). Click a large icon to drill-down to the appropriate page.

- Secondary Navigation (drop down menus). Click the down arrow on the right side of the icon to view a drop down menu. Select an option from the menu.

Note:
For the purposes of consistency, this document uses the primary navigation path (or drill-down approach) when explaining navigation.

Navigating Using Breadcrumbs

Breadcrumbs (also called locator links) appear at the top of every page within the Oracle Application Express user interface. Each breadcrumb entry indicates where the current page is relative to other pages within the user interface. You can use breadcrumbs to instantly link to a previous page. For example, clicking on Home takes you to the Workspace home page.

Using Online Help

The Application Express user interface features three types of online help: Procedural Online Help, Page-Level Help, and Field-Level Help.

About Procedural Online Help

You can access an HTML-based online Help system by clicking the Help link in the upper right corner of the window.

When you click the Help link, a help topic appears that describes the current page. To view the table of contents of another help set, select it from the list in the upper left side of the window.

You can browse through help topics by:

- Expanding and collapsing the table of contents. To view a topic, simply select it.

- Clicking the breadcrumb links at the top of each help topic.

- Clicking the Previous and Next buttons within a topic. Click these buttons to access the previous and next help topic within the structure of the help set.

The top of the window features a gray bar. Click Back and Forward to return to a previously viewed page. These controls work similarly to the Back and Forward controls in a Web browser.

Click Find to perform a keyword search of the entire help system. When the search field appears, enter a case insensitive query in the field provided and click Find. To search for an exact phrase, enclose the phrase in double quotation marks.

Tip:
With Oracle Database 11g, you must enable network services in order use the Find link. See "Enabling Network Services in Oracle Database 11g"

About Page-Level Help

Many pages with in the Application Express user interface include page-level Help. Page-level Help displays in a text box on the right side of the page and offers a brief description of the page functionality.

About Field-Level Help

Most select lists, check boxes, items, and fields within the Application Express user interface include Field-level Help. Items within the user interface that have Field-level Help have a light gray underline. When Field-level Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark.

Click the item label to display a description in a separate window.

2 Running a Demonstration Application

This section describes how to run the two demonstration applications provided with Oracle Application Express. It also explains how to modify the demonstration application called Sample Application that installs with Application Builder. Running and analyzing how an application works is an effective way to better understand how you can use Application Builder to build your own applications.

Topics:

This section contains the following topics:

- Installing a Demonstration Application

- Running an Installed Demonstration Application

- Understanding Sample Application

- Modifying a Demonstration Application

- Viewing Underlying Database Objects

See Also:
"Next Steps" in Oracle Database 2 Day + Application Express Developer's Guide to learn more about other resources to expand your knowledge of Oracle Application Express

Installing a Demonstration Application

Application Builder includes two demonstration applications you can install. Use these applications to learn more about the different types of functionality you can include in your applications.

To install the demonstration applications:

1. From the Workspace home page, click the down arrow on the right side of the Application Builder icon.

2. From the menu, select Demonstrations.

The Demonstration Applications page appears, displaying the following applications:

- Sample Application offers a working demonstration that highlights basic design concepts.

- Collection Showcase demonstrates shopping cart concepts.

3. To install a demonstration application, locate the application you want to install, and click Install.

4. Follow the on-screen instructions.
The Application home page appears.

5. To run an installed demonstration application, click the Run Application icon.

6. Enter the appropriate login credentials and click Login.

- For Sample Application:

- For User Name, enter either demo or admin.

- For Password, enter the current workspace name in lowercase letters.

- For other demonstration applications, enter your workspace user name and password.

Note:
You can also access the Demonstration Applications page by clicking Create on the Application home page and then selecting Demonstration Application.

See Also:
"About Demonstration Applications" and "Running an Installed Demonstration Application"

Running an Installed Demonstration Application

Once you have installed a demonstration application, you can run it from the Demonstration Applications page or from the Application Builder home page.

Topics in this section include:

- Running an Application from Demonstration Applications

- Running an Application from the Application Home Page

See Also:
"Installing a Demonstration Application" and "Running a Page or Application"

Running an Application from Demonstration Applications

To run a demonstration application from the Demonstration Applications page:

1. From the Workspace home page, click the down arrow on the right side of the Application Builder icon.

2. From the menu, select Demonstrations.
The Demonstration Applications page appears.

3. On the Demonstration Applications page, locate the application you want to run.

4. In the Action column, click Run.

5. Enter the appropriate login credentials and click Login.

- For Sample Application:

- For User Name, enter either demo or admin.

- For Password, enter the current workspace name in lowercase letters.

- For other demonstration applications, enter your workspace user name and password.

Running an Application from the Application Home Page

Once you have installed a demonstration application, you can run it from the Application Builder home page.

To run a demonstration application from the Application Builder home page:

1. Log in to the Workspace home page.

2. Click the Application Builder icon.

3. Click the application to be run.
The Application home page appears.

4. Click the Run Application icon.

5. Enter the appropriate login credentials and click Login.

- For Sample Application:

- For User Name, enter either demo or admin.

- For Password, enter the current workspace name in lowercase letters.

- For other demonstration applications, enter your workspace user name and password.

Understanding Sample Application

This section describes the demonstration application called Sample Application.

Sample Application shows an easy-to-use interface for viewing, updating, and searching order and customer information for electronic and computer products. Users can navigate among the pages using the Home, Customers, Products, Orders, and Charts tabs.

Sample Application demonstrates the following functionality:

- Examples of ways to display summary information, including a dial chart and summary reports

- Reports for viewing, updating, and adding customers, products, and orders

- A Calendar report

- Flash charts available in Oracle Application Express including cluster bar, pie chart, and stacked bar

- Printer friendly mode

The following sections describe specific functionality available on each page.

See Also:
"What Is a Page?"

About the Home Page

The Home page contains four regions:

- My Quota

- My Top Orders

- Sample Application

- Tasks

My Quota demonstrates the use of a Flash Dial Chart. This chart displays a value based on an underlying SQL statement.

Although not demonstrated in this example, you can enable an asynchronous refresh by editing the attributes of any SVG or Flash chart.

My Top Orders is a simple report based on a SQL query. This report displays a subset of the information that appears on the Orders page. Users can link to order details by selecting the Edit icon.

Sample Application is a simple HTML region that displays static text. You can create this type of region to display explanatory information to users.

Tasks contains a list with links to other pages within the application. Links available on the Home page Tasks list include:

- About this Application links to an informational page that describes this application.

- Enter a New Order links to a wizard for creating a new order.

- Add a New Customer links to a form for entering new customer information.

- Add a New Product links to a form for adding new products.

See Also:
"Creating Charts", "Creating a Report Using a Wizard", "Creating a Region", and "Creating Lists"

About the Customers Page

The Customers page enables users to view and edit customer information. The Customers page consists of two main regions:

- Customers

- Top Customers

Customers is an updatable report for tracking customer information. This region is also based on a SQL query. To search for a customer, enter a customer name in the Search field and click Go. To sort by customer name, click the column heading. A Sort icon then appears to the right of the heading Customer Name. To update existing customer information, click the Edit icon.

Top Customers ranks customers by order amount. This report is based on a SQL query that returns top customers based on their orders.

See Also:
"Creating Reports"

About the Products Page

The Products page enables users to view and edit product information. The Products page consists of two main regions:

- Products

- Top 10 Products

Products displays an updatable report for tracking product information. This region is based on a SQL query that uses a custom function for displaying images stored in the database. To sort by product category, click the column heading. A Sort icon appears to the right of the heading. To edit a product description, click the Edit icon. To add a new product, click the Create Product button at the bottom of the page. Users can export the data in the Products report to a spreadsheet by clicking Export to Spreadsheet.

Top 10 Products is also a SQL report. This report outlines the top ten products based on quantities sold.

See Also:
"Creating Reports"

About the Orders Page

The Orders page enables users to view and edit customer orders. The Orders page contains two regions:

- My Orders

- Orders by Day

My Orders is a wizard report that summarizes the current orders in the system. To sort a column, click the column heading. A Sort icon then appears to the right of the column heading. To edit an existing order, click the Edit icon. To add a new order, click the Enter New Order button.

Orders by Day is a Calendar report. This report displays each order on the appropriate date in a calendar. Users can select a calendar entry to view order details.

See Also:
"Creating Calendars" and "Creating Reports"

About the Charts Page

The Charts page illustrates three types of Flash charts available in Application Builder: cluster bar, pie chart, and stacked bar. To view a chart, select it from the list on the left.

See Also:
"Creating Charts"

About the Admin Page

The Admin page displays only if you log in to Sample Application using the user name admin. Sample Application makes use of a custom authentication scheme that stores user names and obfuscated passwords in a table. The Manage Users page enables you to manage additional users.

Note that this custom authentication scheme does not use any user names or passwords associated with Oracle Application Express application developers.

Viewing Pages in Printer Friendly Mode

Clicking Print in the upper left corner of the page displays the current page in Printer Friendly mode. When in Printer Friendly mode, the Application Express engine displays all text within the HTML form fields as text.

To enable your application to display in Printer Friendly mode, you need to create and then specify a Print Mode Page Template on the Edit Definition page.

See Also:
"Optimizing a Page for Printing"

Modifying a Demonstration Application

Once you understand the type of functionality available in a demonstration application, the next step is to learn more about the construction of each page. An efficient way to speed up the learning process is to analyze and deconstruct the pages in the demonstration applications. If you happen to break something, you can quickly delete the demonstration application and install it again. See "Deleting an Application" and "Installing a Demonstration Application".

You edit existing pages in an application, add pages to an application, or create entirely new applications using Application Builder.

Topics in this section include:

- About the Developer Toolbar

- Editing a Demonstration Application

About the Developer Toolbar

The Developer toolbar is a quick way to edit the current application, the current running page, create a new page, control, or component, view session state, or turn edit links on or off.

See Also:
"About the Developer Toolbar"

The Developer toolbar consists of the following links:

- Home links you to the Workspace home page. See "About the Workspace Home Page".

- Application links you to the Application home page. See "Application Builder Concepts".

- Edit Page accesses the Page Definition for the current running page. See "About the Page Definition".

- Create links to a wizard for creating a new page, region, page control (item, button, branch, computation, process, or validation), or a shared control (navigation bar icon, tab, list of values, list, or breadcrumb). See "Building an Application".

- Session links you to session state information for the current page. See "Viewing Session State".

- Activity links you to the Activity reports page. See "Activity Reports".

- Debug toggles the page between Debug and No Debug mode. See "Accessing Debug Mode".

- Show Edit Links toggles between Show Edit Links and Hide Edit Links. Clicking Show Edit Links displays a small orange icon next to each editable object on the page. Each icon is orange and contains a triangle with two rules beneath it. Clicking the link displays another window in which to edit the object.

Editing a Demonstration Application

There are two ways to edit a demonstration application:

- From the Demonstration Applications page, click Edit next to the desired application.

- If you are running an application, click Application on the Developer toolbar.

The Application home page appears. The application ID and application name display at the top of the page.

You can run the current application, edit supporting objects, create shared components, or export and import information by clicking one of the following:

- Run Application submits the pages in the current application to the Application Express engine to render viewable HTML. See "How the Application Express Engine Renders and Processes Pages".

- Supporting Objects links to the Supporting Objects page. See "How to Create a Packaged Application".

- Shared Components links to a list of shared components and user interface controls that can display or be applied on every page within an application. See "Working with Shared Components".

- Export/Import links you to the Export/Import Wizard. Use this wizard to import and export an entire application as well as related files such as cascading style sheets, images, static files, script files, themes, user interface defaults, and workspace users. See "Exporting an Application and Related Files".

The pages that make up the application appear on the Application home page. To access a specific page, simply click it. To search for a specific page, enter a case insensitive query for the page title or page number in the Page field and click Go.

See Also:
"About the Application Home Page" and "About the Page Definition"

Viewing Underlying Database Objects

The Application Express engine renders applications in real time based on data stored in database tables. You can view the database objects for any demonstration application in Object Browser, or by viewing the Application Database Object Dependencies report.

Topics in this section include:

- Viewing the Database Object Dependencies Report

- Viewing Database Objects in Object Browser

Viewing the Database Object Dependencies Report

The Database Object Dependencies report identifies database objects referenced by the current application. Review this report to determine what objects to move when deploying an application.

To view the Database Object Dependencies report:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.
The Application home page appears.

4. On the Tasks list, click Application Reports.

5. Click Shared Components.

6. Under Application, click Database Object Dependencies.

7. Click Compute Dependencies.

8. To view the components that reference a specific database object, select the Reference Count number.

See Also:
"Viewing Application Reports"

Viewing Database Objects in Object Browser

To view the database objects in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Select an object type from the Object list in the upper left corner of the page. For example, to view tables, select Tables.

3. To search for an object name, enter keywords in the search field beneath the Object list.
A list of matching objects appears.

4. To perform a specific task related to the selected object, select the appropriate task button.
For example, to modify a column in the DEMO_CUSTOMERS table:

a. From the Objects list, select Tables.

b. From the Tables list, select DEMO_CUSTOMERS.

c. Click Modify Column.

5. To view additional object details, select a tab beneath the object name. For example, to view the data in the DEMO_CUSTOMERS table:

a. From the Tables list, select DEMO_CUSTOMERS.

b. Select the Data tab.
A report appears that displays the data in the DEMO_CUSTOMERS table appears.

See Also:
"Managing Database Objects with Object Browser"

Part II

Application Development

Part II describes how to use Application Builder to develop database-driven applications.

Part II contains the following chapters:

- Chapter 3, "Application Builder Concepts"

- Chapter 4, "Using Application Builder"

- Chapter 5, "Building an Application"

- Chapter 6, "Adding Navigation"

- Chapter 7, "Controlling Page Layout and User Interface"

- Chapter 8, "Understanding Application Administration"

- Chapter 9, "Managing User Interface Defaults"

- Chapter 10, "Debugging an Application"

- Chapter 11, "Managing Application Security"

- Chapter 12, "Deploying an Application"

- Chapter 11, "Managing Application Security"

- Chapter 13, "Advanced Programming Techniques"

- Chapter 14, "Managing Application Globalization"

- Chapter 15, "Oracle Application Express APIs"

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

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.

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#

See Also:
"APP_IMAGES" and "IMAGE_PREFIX"

4 Using Application Builder

This section provides important background information about using Application Builder to build dynamically rendered applications.

This section contains the following topics:

- Accessing Application Builder

- About the Application Builder Home Page

- About the Application Home Page

- About Application Attributes

- About the Page Definition

- Using the View List on the Page Definition

- Editing a Page Definition

- Editing Page Attributes

- About the Developer Toolbar

- Working with Shared Components

- Understanding Application Processes

- Understanding Application Computations

- Viewing Application Reports

See Also:

- "Quick Start"

- "Application Builder Concepts"

- "Building an Application"

- "Controlling Page Layout and User Interface"

- "Adding Navigation"

Accessing Application Builder

An application is a collection of database-driven Web pages linked together using tabs, buttons, or hypertext links. The pages within an application share a common session state definition and authentication method. Application Builder is the tool you use to build the pages that comprise an application.

To access Application Builder:

1. Log in to Oracle Application Express.
The Workspace home page appears.

2. To view the Application Builder home page you can either:

- Click the Application Builder icon to link to the Application Builder home page.

- Click the down arrow on the right side of the Application Builder icon to view a drop down menu. Then select the appropriate menu option.

Note:
For consistency, this document uses the primary navigation path (or drill-down approach) when explaining navigation.

About the Application Builder Home Page

The Application Builder home page displays all installed applications.

You can customize the appearance of the Application Builder home page using the navigation bar at the top of the page. Available controls include:

- Application. Use the Application field to search for an application. Enter a case insensitive query for the application name or application ID and click Go. To view all applications, leave the field blank and click Go.

- View. Use this control to display information about the applications in your workspace. Make a selection from the list and click Go. Available options include:

- Icons (the default) displays each application as a large icon identified by the application name.

- Details displays each application as a line in a report. Each line includes the application ID, the application name, when the application was last updated, the page count, and who last updated the application.

- Display. Determines how many applications display on the page. To change the display, make a selection from the list and click Go.

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

- Import. Click Import to import an exported application file. See "Importing Export Files"

- Create. Click Create to create a new application or install a demonstration application. See "Installing a Demonstration Application" and "About Creating an Application Using a Wizard".

About the Tasks List

A Tasks list displays on the right side of the Application Builder home page.

The Tasks list contains the following links:

- Application Builder Defaults links to the Manage Application Builder Defaults page. See "Leveraging Application Builder Defaults".

- Developer Preferences links to the Developer Preferences page. See "Configuring Developer Preferences".

- User Interface Defaults links to the User Interface Defaults page. See "Managing User Interface Defaults".

- Export Repository links to the Export Repository page. See "Importing Export Files".

About the Recent List

The Recent list contains links to recently viewed applications.

Configuring Developer Preferences

Many pages in Application Builder include a navigation bar at the top of the page. You can use the controls in the navigation bar to customize the appearance of the page. Most navigation bars include a View and Display list. You can control the default display for both lists on the Developer Preferences page.

To edit developer preferences:

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

2. From the Tasks list, click Developer Preferences.

3. From Set View Mode, select one of the following:

- Icons (the default) displays the items on the page as a large icon.

- Details displays the items on the page as a line in a report.

4. From Report Rows, select the number items to display.

5. Click Apply Changes.

About the Application Home Page

To view a specific application, select the application on the Application Builder home page. The Application home page appears. The application ID and the application name display at the top of the page. To link to the application definition, click application name.

See Also:
"Configuring the Application Definition"

The following large icons appear next:

- Run Application submits the pages in the current application to the Application Express engine to render viewable HTML. See "How the Application Express Engine Renders and Processes Pages".

- Supporting Objects links to the Supporting Objects page. See "How to Create a Packaged Application".

- Shared Components links to a list of shared components and user interface controls that can display or be applied on every page within an application. See "Working with Shared Components".

- Export/Import links you to the Export/Import Wizard. Use this wizard to import and export an entire application as well as related files such as cascading style sheets, images, static files, script files, themes, user interface defaults, and workspace users. "Exporting an Application and Related Files".

About the Navigation Bar and Create Page Button

A navigation bar and the Create Page button display in the center of the Application home page. You can use these controls to search for pages, alter the page view, or create a new page.

The Application home page navigation bar contains the following controls:

- Page. Search for a page number or name by entering a case insensitive keyword or phrase in the Page field and clicking Go. To view all pages in an application, leave the Page field blank and click Go. You control how many pages display by making a selection from the Display list.

- View. By default, each page displays as a large icon. You can change the appearance of the page by making a selection from the View list and clicking Go. See "Understanding Page Display Alternatives".

- Display. Determines how many pages display. To change the number of pages that appear, make a selection from the Display list and click Go.

The Create Page button displays to the right of the navigation bar. Click Create Page to launch a wizard that walks you through creating a new page. See "Managing Pages in an Application".

See Also:
"About the Action Bar"

About the Tasks List

A Tasks list displays on the right side of the Application home page.

The Tasks list contains the following links:

- Delete this Application deletes the current application. See "Deleting an Application".

- Copy this Application creates a copy of the current application. See "Copying an Application".

- Page Groups links to the Page Groups page. Make the pages within your application easier to access by organizing them into page groups. See "Grouping Pages".

- Page Locks links to the Locked Pages page. Locking pages in an application prevents conflicts during application development. See "Locking and Unlocking a Page".

- User Interface Defaults link to the User Interface Defaults page. See"Managing User Interface Defaults".

- Export Repository links to the Export Repository page. See "Installing Export Files".

- Application Reports links to the Application Reports page. Use this page to view reports specific to your application. See "Viewing Application Reports".

Understanding Page Display Alternatives

You can control how the Application home page appears by making a selection from the View list and clicking Go. Available View modes include:

- Icons

- Details

- by Group

- by Type

Icons mode (the default) displays each page as a large icon identified by the page name. To view a page, click the icon.

See Also:
"About the Recent List"

Details mode displays each page as a line in a report. Each line includes the page number, the page name, when the page was last updated, the page type, who updated it, any associated group, and lock status. To view a page, click the page name. Use the Lock icon to prevent conflicts during application development. Click the Run icon to run the associated page and render viewable HTML.

See Also:
"Locking and Unlocking a Page" and "Running a Page or Application"

By Group displays currently defined page groups. You can use page groups to organize and manage the pages within an application. See "Grouping Pages".

By Type separates pages into categories, such as Login, Report, Tabular Form, Dynamic Form, Chart, and so on. The number of pages within each page category displays within a parenthesis to the right of the type name. To view a page, click the page type and then the page.

About the Recent List

The Recent list contains links to recently viewed pages within the current application. This list only appears when viewing the Application home page in Icon mode.

About the Action Bar

The Action bar displays beneath the Utilities tab in the upper right corner of most pages in Application Builder.

This bar contains the icons discussed in the sections that follow. Note that the Run Page icon, Edit Page icon, Developer Comment icon, and Find icon display on numerous pages in Application Builder, including pages for creating and managing shared components. See "Working with Shared Components".

Run Page Icon

The Run Page icon resembles a small, light green traffic light. Click this icon to render viewable HTML of the current page. If no page is selected, clicking this icon runs the first page in the application. When you run a page, the Application Express engine dynamically renders the page based on data stored in the database. See "Running a Page or Application".

Edit Icon

The Edit Page icon resembles a small green piece of paper and pencil. Click this icon to access the Page Definition of the current page. If no page is selected, clicking this icon displays the Page Definition of the first page in the application. See "About the Page Definition".

Shared Components Icon

The Shared Components icon resembles a small mechanical gear. Click this icon to view a list of shared components and user interface controls that can display or be applied on every page within an application. See "Working with Shared Components".

Developer Comment icon

The Developer Comment icon is the shape of a green balloon. Click this icon to record comments about an application, a specific page, or a group of pages. See "Adding Developer Comments".

Find Icon

The Find icon resembles a flashlight. Click this icon to search for items, pages, queries, tables, PL/SQL, images, and cascading style sheets (CSS) within the current application or the schemas associated with the workspace. See "Using the Find Icon".

About Application Attributes

Application attributes apply to an entire application. Once you create an application, the next logical step is to review and possibly update application attributes.

Topics in this section include:

- Configuring the Application Definition

- Configuring Security Attributes

- Configuring Globalization Attributes

See Also:
"How to Create a Packaged Application" for information on using the Supporting Objects utility to create a packaged application

Configuring the Application Definition

You use the attributes on the Edit Definition page to control the application name and availability as well as to define static substitution strings. Additionally, the Edit Definition page displays defined build options, the associated theme, template defaults, and component defaults. Required values are marked with a red asterisk (*).

Topics in this section include:

- Accessing the Edit Definition Page

- About the Edit Definition Page

Accessing the Edit Definition Page

To edit the application definition:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Application, click Application Definition.
The Edit Definition page appears.

Tip:
You can also access the Edit Definition page by clicking the application name at the top of the Application home page.

About Navigation Alternatives

The Edit Definition page is divided into the following sections: Name, Availability, Global Notification, Substitutions, Logo, Build Options, Theme, Template Defaults, and Component Defaults. You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page.

When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

About the Edit Definition Page

The following sections describe the attributes available on the Edit Definition page.

Topics in this section include:

- Name

- Availability

- Global Notifications

- Substitutions

- Logo

- Build Options

- Theme

- Template Defaults

- Component Defaults

Name

Use Name to define basic characteristics of your application, including the application name, an optional alphanumeric alias, and a version number. Table 4-1 describes all Name attributes.

Table 4-1 Application Definition Attributes

Attribute

Description

Name

Provides a short descriptive name for the application to distinguish it from other applications in your development environment.

Application Alias

Assigns an alternate alphanumeric application identifier. You can use this identifier in place of the application ID.For example, suppose you create an alias of myapp for application 105. Using f?p syntax, you could call application 105 as either:

- f?p=105:1

- f?p=myapp:1

See Also: "Using f?p Syntax to Link Pages"

Version

Includes the application's version number on a page. You can also automatically tie the version to the date of last modification using the following format masks:

- YYYY.MM.DD

- MM.DD.YYYY

- DD.MM.YYYY

If your application version uses YYYY.MM.DD, then Application Builder replaces this format mask with the date of last modification of any application attribute.

Image Prefix

Determines the virtual path the Web server uses to point to the images directory distributed with Application Builder. During installation, the virtual path is configured as /i/.

When embedding an image in static text (for example, in page or region headers or footers), you can reference an image using the substitution string #IMAGE_PREFIX#. For example, to reference the image go.gif, you would use the following syntax:

<img src="#IMAGE_PREFIX#go.gif">

See Also: "IMAGE_PREFIX", "Managing Images", and "Referencing Images"

Proxy Server

Use this field to specify a proxy server.

For example, you may require a proxy server when using a region source type of URL. The URL region source embeds the results of the URL (that is, the page returned by navigating to the URL) as the region source. If you use a firewall and the target of a URL is outside the firewall relative to Application Builder, you may need to specify a proxy server.

You can reference values entered into this field from PL/SQL using the PL/SQL package variable APEX_APPLICATION.G_PROXY_SERVER.

Logging

Determines whether or not user activity is recorded in the Oracle Application Express activity log. When set to Yes, every page view is logged, enabling an administrator to monitor user activity for each application.

Disabling logging may be advisable for high volume applications.

Debugging

Controls debug mode for the current application. Available options include:

- Yes enables the application to run in a debug mode.

- No disables the application from running in debug mode.

Running an application in debug mode is useful when an application is under development. However, for a production application, it is a good idea to disable debugging and thus prevent users from viewing application logic.

Parsing Schema

Specifies the schema that all SQL and PL/SQL in the application will be parsed as. You may use the #OWNER# substitution string to reference this value in SQL queries and PL/SQL (for example, in a region or a process).

Exact Substitutions

Determines if exact substitutions are supported. Use exact substitutions. Non-exact substitutions is a deprecated feature.

Exact substitutions use the following sytnax:

&ITEM.

Non-exact substitutions use the following sytnax:

&ITEM

See Also:
"Understanding Substitution Strings" and "Using f?p Syntax to Link Pages"

Availability

Use Availability attributes to manage your application by defining an application status and build status. For example, if you select the status Restricted Access, you can specify which users have access and can run the application. Table 4-2 describes these attributes.

Table 4-2 Application Availability Attributes

Attribute

Description

Status

Specifies whether or not the application is available or unavailable for use. Options include:

- Available - Application is available with no restrictions.

- Available with Edit Links - Application is available for use. For developers, the Developer toolbar displays at the bottom of each page. Requires the developer to be logged in to the Application Builder in the same browser session.

- Available to Developers Only - Application is available to users having developer privileges.

- Restricted Access - Application is available to developers named in the Restrict to comma separated user list.

- Unavailable - Application cannot be run or edited. The message in Message for unavailable application displays when users attempt to access the application.

- Unavailable (Status Shown with PL/SQL) - Application cannot be run or edited.

- Unavailable (Redirect to URL) - Application cannot be run. The user is linked to the URL entered in Message for unavailable application.

See Also: "Controlling Access to Applications, Pages, and Page Components"

Build Status

Identifies the build status of the current application. Options include:

- Run and Build Application - Developers and users can both run and develop the application.

- Run Application Only - Users can only run the application. This option is intended for applications in a production instance.

See Also: "Changing Application Build Status SetDuring Deployment"

Message for unavailable application

Use this attribute in conjunction with Status. If you set Status to Unavailable, Unavailable (Status Shown with PL/SQL), or Unavailable (Redirect to URL), the text you enter in this attribute displays. If you set Status to Available, the text you enter in this attribute does not display.

Restrict to comma separated user list (status must equal Restricted Access)

Use this attribute in conjunction with the Status Restricted Access. If you set Status to Restricted Access, only the users listed in this attribute can run the application. To use this attribute:

1. From the Status list, select Restricted Access.

2. Enter a comma-delimited list of users who can run the application in the field provided.

Global Notifications

You can use the Global Notifications attribute to communicate system status to application users. For example, you can use this attribute to notify users of scheduled downtime, or communicate other messages regarding application availability. If the page templates used in your application contain the #GLOBAL_NOTIFICATION# substitution string, the text entered here will display in that string's place.

To create a global notification:

1. Include the #GLOBAL_NOTIFICATION# substitution string in your page template.

2. Navigate to the Edit Definition page and enter a message in the Global Notifications attribute.

3. Click Apply Changes.

See Also:
"Understanding Substitution Strings" and "Page Templates"

Substitutions

Use these fields to define static substitution strings for your application. You can use static substitution string for phrases or labels that occur in many places within an application. To create a substitution string, enter the string name in the Substitution String column and the string value in the Substitution Value column.

Defining static substitution strings centrally enables you to change text strings in multiple places in your application by making a single change to the Substitution Value defined on this page.

See Also:
"Understanding Substitution Strings"

Logo

Use Logo attributes to define an application logo. An application logo can be text-based or image-based. To use this feature, your page template must include the #LOGO# substitution string.

To define an application logo:

1. For Logo Type, select one of the following:

- Select Image to use an image for the application logo.

- Select Text to use text for the application logo.

2. In Logo, enter the following:

- For an image, enter the complete image name, including the filename extension. For example:

/i/oracle.gif

- For text, enter the full text string. For example:

Sample Application

3. In Logo Attributes, enter the appropriate attributes for the logo.
Image example:

width="100" height="20" alt="Company Logo"

Text example:

style="font-family:Arial; color:#000000; font-size:18; white-space:nowrap; font-weight:bold;"

See Also:
"Managing Images", "Verifying the Prefix for the Virtual Image Directory", "Customizing Templates", and "Page Templates"

Build Options

Displays existing build options. Most applications have a build option attribute. Build Options have two possible values: INCLUDE and EXCLUDE. If you specify an attribute to be included, then the Application Express engine considers it at run time. However, if you specify an attribute to be excluded, then the Application Express engine treats it as if it did not exist.

Do not specify a build option unless you plan to exclude that object from specific installations.

See Also:
"Using Build Options to Control Configuration"

Theme

Displays the current theme applied to the application. Themes are collections of templates that can be used to define the layout and style of an entire application. Each theme provides a complete set of templates that accommodate every user interface pattern that may be needed in an application.

See Also:
"Managing Themes"

Template Defaults

Lists the default templates for this application. To specify a new default template at the application level, you can either:

- Select a new theme. See "Switching the Active Theme".

- Select a new default page template on the Create/Edit Theme page. See "Changing the Default Templates in a Theme".

You can also override this default by making a selection from the Page Template list on the Page Attributes page.

Table 4-3 describes template defaults for the current application.

Table 4-3 Application Template Defaults Attributes

Attribute

Description

Default Page Template

Indicates the default page template to display pages. You can override this selection by making a selection from the Page Template list on the Page Attributes page.

See Also: "Editing Page Attributes"

Print Mode Page Template

Identifies the template to be used when the Application Express engine is in printer friendly mode.

When calling the Application Express engine to render a page, you have the option to specify whether or not the page should be displayed using the Print Mode Page Template specified.

If you specify Yes, then the page displays using a printer friendly template. The Application Express engine displays all text within HTML Form Fields as text. The printer friendly template does not need to have the #FORM_OPEN# or #FORM_CLOSE# substitution string.

See Also: "Optimizing a Page for Printing"

Error Page Template

Optional. Specifies a page template to use for errors that display on a separate page, as opposed to those that display inline.

See Also:
"Changing the Default Templates in a Theme" and "Customizing Templates"

Component Defaults

Displays the default templates used when running wizards. You can override these settings on the attributes page for each control or component. Table 4-4 describes component defaults for the current application.

Table 4-4 Component Defaults

Attribute

Description

Calendar

Default calendar template used when you create a new calendar.

Label

Default label template used when you create new page items.

Report

Default report template used when you create new report.

List

Default template used when you create a list.

Breadcrumb

Default template used when you create a breadcrumb.

Button

Default template used when you create new buttons that are template controlled.

Region

Default template used when you create a new region.

Chart Region

Default region template used when you create a chart.

Form Region

Default region template used when you create a form.

Report Region

Default region template used when you create a report.

Tabular Form Region

Default region template used when you create a tabular form.

Wizard Region

Default region template used when you create a new wizard component.

Breadcrumb Region

Default region template used when you create a new breadcrumb.

List Region

Default region template template used when you create a new list.

See Also:
"Changing the Default Templates in a Theme" and "Customizing Templates"

Configuring Security Attributes

You can provide security for your application by configuring attributes on the Edit Security Attributes page. The Security Attributes you choose apply to all pages within an application.

Topics in this section include:

- Accessing the Edit Security Attributes Page

- About the Security Attributes Page

See Also:
"Managing Application Security"

Accessing the Edit Security Attributes Page

To access the Edit Security Attributes page:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Security, click Edit Security Attributes.

The Edit Security Attributes page appears.

About Navigation Alternatives

The Edit Security Attributes page is divided into the following sections: Authentication, Authorization, Database Schema, Session State Protection, and Virtual Private Database. You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page.

When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

About the Security Attributes Page

The following sections describe the attributes available on the Edit Security Attributes page.

Topics in this section include:

- Authentication

- Authorization

- Database Schema

- Session State Protection

- Virtual Private Database (VPD)

Authentication

Authentication is the process of establishing users' identities before they can access an application. Although you define multiple authentication schemes for your application, only one scheme can be current at a time. Table 4-5 describes the attributes available under Authentication.

Table 4-5 Authentication Attributes

Attribute

Descriptions

Home Link

Specifies a URL or procedure that should be run when you run the application.

For example, Home Link could contain the relative URL used to locate the application home page. For example, f?p=6000:600 would specify application 6000 with a home page number of 600. In this example, the value you enter in Home Link replaces the #HOME_LINK# substitution string in application templates.

You can also use this attribute to name a procedure. For example, you could create a procedure such as personal_calendar which renders an HTML page to serve as the application home.

Note: Do not use the Home Link attribute to determine the page that displays after authentication. The page that displays after authentication is determined by other components within the application's authentication scheme.

See Also: "HOME_LINK"

Login URL

Replaces the substitution strings &LOGIN_URL. in HTML or #LOGIN_URL# in templates.

See Also: "LOGIN_URL" and "Creating an Authentication Scheme"

Public User

Identifies the Oracle schema used to connect to the database through the database access descriptor (DAD). The default value is ANONYMOUS in environments where the database server version is Oracle Database Express Edition and it is APEX_PUBLIC_USER for all other versions of the database server.

Once a user has been identified, the Application Express engine keeps track of each user by setting the value of the built-in substitution string APP_USER.

Note: Previous versions of Oracle Application Express used the built-in substitution string HTMLDB_PUBLIC_USER.

When APP_USER equals this value, the Application Express engine considers the current session to be a public user session. The Application Express engine supports the following built-in display conditions:

- USER_IS_PUBLIC_USER

- USER_IS_NOT_PUBLIC_USER

If the current application user (APP_USER) equals the value of this attribute, then the user is logged on as a public user. Some applications have public (not logged in) and a private (logged in) modes. By determining if the user is the public user, you can conditionally display or hide information.

For example, you can show a login button if the user is the public user and a logout link if the user is not a public user. Reference this value using APEX_APPLICATION.G_PUBLIC_USER. The Application Express engine also has built in condition types USER_IS_PUBLIC_USER and USER_IS_NOT_PUBLIC.

See Also: "HOME_LINK" and "Understanding Conditional Rendering and Processing"

Define Authentication Scheme

Click this button to define a new authentication scheme.

See Also: "Understanding How Authentication Works" and "Creating an Authentication Scheme"

Authorization

Authorization controls user access to specific controls or components based on user privileges. You can specify an authorization scheme for your application, by making a selection from the Authorization Scheme list. You can assign only one authorization to an entire application. However, you can assign an authorization scheme to individual pages, page controls (such as a region, a button, or an item), or a shared component (such as a menu, a list, or a tab).

To create a new authorization scheme, click Define Authorization Schemes.

An authorization scheme is a binary operation that either succeeds (equals true) or fails (equals false). If it succeeds, then the component or control can be viewed. If it fails, then the component or control cannot be viewed or processed. When you attach an authorization scheme to a page and it fails, an error message displays instead of the page. However, when you attach an authorization scheme to a page control (for example, a region, a button, or an item) and it fails, no error page displays. Instead, the control either does not display or is not processed or executed.

See Also:
"Providing Security Through Authorization"

Database Schema

Use Parsing Schema to specify the database scheme for the current application. Once defined, all SQL and PL/SQL commands issued by the application will be performed with the rights and privileges of the defined database schema.

Session State Protection

Enabling Session State Protection can prevent hackers from tampering with URLs within your application. URL tampering can adversely affect program logic, session state contents, and information privacy.

To enable or disable Session State Protection for your application, make a selection from the Session State Protection list. Setting Session State Protection to Enabled turns on session state protection controls defined at the page and item level.

To configure Session State Protection, click Manage Session State Protection.

See Also:
"Understanding Session State Protection"

Virtual Private Database (VPD)

A Virtual Private Database (VPD) provides an application programming interface (API) that enables developers to assign security policies to database tables and views. Using PL/SQL, developers can create security policies with stored procedures, and bind the procedures to a table or view by means of a call to an RDBMS package. Such policies are based on the content of application data stored within the database, or are based on context variables provided by the Oracle database. In this way, VPD permits access security mechanisms to be removed from applications and centralized.

The PL/SQL you enter in this field is executed immediately after the user is authenticated. V('USER') is accessible from this function. Session state for the current call is not yet initialized when this call is made. If your application does not need to employ VPD to support multiple customers in the same database, leave this attribute null.

See Also:
"Providing Security Through Authorization" and Oracle Label Security Administrator's Guide

Configuring Globalization Attributes

In Application Builder you can develop applications that can run concurrently in different languages. A single application can be translated to support different languages. Use the attributes on the Edit Globalization Attributes page to specify globalization options such as the primary application language.

Topics in this section include:

- Accessing the Globalization Attributes Page

- About the Edit Globalization Attributes Page

See Also:
"Managing Application Globalization"

Accessing the Globalization Attributes Page

To access the Edit Globalization Attributes page:

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

2. Select an application.
The Application Builder home page appears.

3. Click Shared Components.
The Shared Components page appears.

4. Under Globalization, click Edit Attributes.
The Edit Globalization Attributes page appears.

About the Edit Globalization Attributes Page

The following sections describe the attributes available on the Edit Globalization Attributes page.

See Also:
"Specifying the Primary Language for an Application"

Application Primary Language

Identifies the language in which an application is developed. This language is the base language from which all translations are made. For example, suppose application 100 was authored in English, translated into French, and published as application 101. English would be the Application Primary Language.

All modifications to the application should be made to the primary language specified here.

Application Language Derived From

Determines how Application Builder determines or derives the application language.

The application primary language can be static, derived from the Web browser language, or determined from a user preference or item. The database language setting also determines how the date is displayed and how certain information is sorted.

This option enables you to disable browser derived language support. You also have the option of having the application language derived from an application preference.

Automatic CSV Encoding

Automatic CSV Encoding controls the encoding of all comma-delimited (CSV) report output in an application. The default value for Automatic CSV Encoding is No. If Automatic CSV Encoding is set to Yes, CSV report output will be properly converted to a character set compatible with localized desktop applications. The character set for the CSV encoding is determined by the Application Language Derived From setting.

The encoding of pages in Application Builder is determined by the character set of the database access descriptor (DAD) used to access Application Express. For example, if the character set of the database access descriptor is AL32UTF8, all pages in all applications in the Application Express user interface will be encoded in UTF-8.

By default, the CSV output from report regions is encoded in the same character set as the database access descriptor. However, some desktop spreadsheet applications require that the data is encoded in the client desktop operating system character set. In the case of multibyte data, the CSV output from report regions will often appear corrupted when opened by a desktop spreadsheet application. This is because the CSV output is encoded differently than what is required by the desktop application. Enabling Automatic CSV Encoding resolves this issue.

For example, if the user's language preference for an application is de, the CSV data will be encoded in Western European Windows 1252, regardless of the Database Access Descriptor character set setting. If the user's language preference is zh-cn, the CSV data will be encoded in Chinese GBK.

See Also:
"Adding a Download Link to a Report"

About the Page Definition

A Page Definition is the basic building block of a page. Each page can have buttons and fields (called items), which are grouped into containers called regions. Pages can also have application logic (or processes). You can branch from one page to the next using conditional navigation; perform calculations (called computations); perform validations (such as edit checks); and display reports, calendars, and charts. You view, create, and edit the controls that define a page by accessing the Page Definition.

Topics in this section include:

- Accessing a Page Definition

- Understanding the Page Definition

See Also:
"Using the View List on the Page Definition", "Editing a Page Definition", "Editing Page Attributes", and "Using the Page Finder"

Accessing a Page Definition

You can view, create, and edit the controls that define a page through the Page Definition.

To access the Page Definition for an existing page:

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

2. Select an application.
The Application home page appears.

3. Select a page.
The Page Definition appears.

See Also:
"Using the Page Finder"

Understanding the Page Definition

A Page Definition is the basic building block of a page. You use the Page Definition to view, create, and edit the controls and application logic that define a page. The sections that follow describe the different parts of the Page Definition.

Topics in this section include:

- Available Navigation Bar Controls and Buttons

- About the Action Bar

- About Page Rendering, Page Processing, and Shared Components

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 new page number and page name.

- Delete. Deletes the current page.

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

See Also:
"Managing Pages in an Application" and "Running a Page or Application"

About the Action Bar

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

Run Page Icon

The Run Page icon resembles a small, light green traffic light. Click this icon to render the current page into viewable HTML. When you run a page, the Application Express engine dynamically renders the page based on data stored in the database. See "Running a Page or Application".

Shared Components Icon

The Shared Components icon resembles a small mechanical gear. Click this icon to view a list of shared components and user interface controls that can display or be applied on every page within an application. See "Working with Shared Components".

Developer Comment Icon

The Developer Comment icon resembles a green balloon. Use this icon to add comments to an application, a page, or a group of pages. See "Adding Developer Comments".

Lock Icon

The Lock icon indicates whether a page is available for editing. If a page is unlocked, the icon appears as an open padlock. If the page is locked, the icon appears as a locked padlock. Click this icon to change the lock status. See "Locking and Unlocking a Page".

Export Page Icon

The Export Page icon resembles a downward arrow. Click this icon to export the current page. See "Exporting a Page in an Application".

Find Icon

The Find icon resembles a flashlight. Click this icon to search for items, pages, queries, tables, PL/SQL, images, and cascading style sheets (CSS) within the current application or the schemas associated with the workspace. See "Using the Find Icon".

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

See Also:
"Using the Page Finder" and "Editing a Page Definition"

Using the View List on the Page Definition

You can use the View list to quickly switch from a Page Definition to the Page Events, Database Object Dependencies, History, Export, Groups, and Referenced Components pages.

Topics in this section include:

- Accessing the View List on the Page Definition

- About Page Events

- About Database Object Dependencies

- About History

- About Export

- About Groups

- About Referenced

See Also:
"Understanding the Page Definition"

Accessing the View List on the Page Definition

To access other pages using the View list:

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.

5. From the View list, select one of the following:

- Definition. See "Editing a Page Definition".

- Events. See "About Page Events".

- History. See "About History".

- Export. See "About Export".

- Groups. See "About Groups".

- Referenced. See "About Referenced".

About Page Events

Page Events details all currently defined page controls and processes. This page provides a chronological view of how and in what order the Application Express engine renders the page, invokes logic, and runs processes.

A navigation bar appears directly beneath the breadcrumb trail. Available controls include:

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

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

- Show All displays all possible page controls and processes, including those not currently defined.

- Show Used displays currently used page controls and processes (Default).

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

To view details about a specific page control or process, click the appropriate hypertext link. Alternately, you can create new page controls and processes by clicking the small icons to the left of each entry.

About Database Object Dependencies

The Database Object Dependencies page displays a list of database objects referenced by the current page.

A navigation bar appears directly beneath the breadcrumb trail. Available controls include:

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

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

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

About History

The History page displays a history of recent changes to the currently selected page by developer (or user), application, page number, modification date, component, and action.

A navigation bar appears directly beneath the breadcrumb trail. Available controls include:

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

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

- Display. Determines how many pages display. To change the number of pages that appear, make a selection from the Display list 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.

About Export

Use the Export page to export the current page and its referenced components. A navigation bar appears directly beneath the breadcrumb trail. Available controls include:

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

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

See Also:
"About the Action Bar", "How to Move an Application to Another Development Instance" and "Exporting a Page in an Application"

About Groups

The Groups page displays all pages that are part of the same page group as the current page. Click a page number to edit the page group. Click a page name to view the page definition.

A navigation bar appears directly beneath the breadcrumb trail. Available controls include:

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

- Display. Determines how many pages display. To change the number of pages that appear, make a selection from the Display list and click Go.

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

See Also:
"About the Action Bar" and "Grouping Pages"

About Referenced

The Referenced Components page lists page components and shared components associated with the current page.

A navigation bar appears directly beneath the breadcrumb trail. Available controls include:

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

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

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

Editing a Page Definition

A page is the basic building block of an application. Each page has a page number, a name, and typically some text attributes such as a header, title, and footer. You add content to your page by creating page controls (regions, items, and buttons). Page templates and page region templates control the exact look and feel of each page.

Topics in this section include:

- About the Edit All Icon

- About the Copy or Create Icons

- Reordering Page Components

- About Page Rendering

- About Page Processing

- About Shared Components

- Understanding Page Computations

- Understanding Validations

- Understanding Page Processes

- Understanding Branches

See Also:
"About the Page Definition", "Editing Page Attributes", "Using the Page Finder"

About the Edit All Icon

Each Page Definition is divided into three sections: Page Rendering, Page Processing, and Shared Components. Each of these sections is broken into subsections with headings that identify the type of control, component, or application logic.

You can edit all controls, components, or logic within a given subsection by clicking the Edit All icon that displays to the right of the subsection title. The Edit All icon resembles a small grid with a pencil on top of it.

Clicking the Edit All icon displays pages that enable you to edit or delete multiple controls, components, or application logic simultaneously or view a history of recent changes.

For example, selecting the Edit All icon under Regions displays a summary report of all currently defined regions on the current page. You can use this summary view to:

- Edit the multiple attributes at once by making new selections from the available fields and select lists.

- Link to a definition page by clicking the Edit icon.

You can access similar summary views on the next or previous page by clicking the Next and Previous buttons at top of each page. To save your edits to any summary view, click Apply Changes.

You can also view the attributes of a specific control or component by selecting its name on the Page Definition. For example, suppose your Page Definition contains a region named Customers. Clicking the region name Customers would display an attributes page for that region.

See Also:
"About Page Rendering", "About Page Processing", and "About Shared Components"

About the Copy or Create Icons

You can copy or create new controls or components by clicking the Copy and Create icons. The Copy icon resembles two small overlapping pages. Click the Copy icon to make a copy of an existing control or component.

The Create icon resembles a plus (+) sign overlapping a small page. Click the Create icon to create a new control or component.

Reordering Page Components

You can quickly change the order in which regions, button, and items display using the Reorder icon on the Page Definition. The Reorder icon displays as a light green downward arrow and upward arrow.

To reorder page components, click the Reorder icon. When the Reorder page appears click the up and down arrows and then click Apply Changes.

See Also:
"Using the Reorder Regions Icon", "Using the Reorder Buttons Icon", "Using the Edit All Icon to Edit Multiple Items", and "Using the Drag and Drop Layout Page"

About Page Rendering

Page rendering is the process of generating a page from the database. Use the Page Rendering section to modify controls that impact the rendering of a page, including page attributes, regions, buttons, items, page rendering computations, and page processes.

You can quickly navigate to a specific subsection by clicking the icons beneath the heading. When you select one of these icons, the subsection appears and all other subsections are temporarily hidden. To restore the view, click Show All. The Show All icon resembles an inverted triangle.

Topics in this section include:

- Page

- Regions

- Buttons

- Items

- Computations

- Processes

See Also:
"About the Page Definition", "About the Edit All Icon" and "About the Copy or Create Icons"

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.

See Also:
"Editing Page Attributes"

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.

See Also:

- "Understanding Regions" for information about creating and editing regions

- 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

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.

See Also:
"Creating Buttons"

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 or not 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.

See Also:
"Understanding Page-Level Items" and "Understanding Application-Level Items"

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.

See Also:
"Creating a Page Computation" and "Understanding Application Computations"

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.

See Also:
"Understanding Page Processes" and "Understanding Application Processes"

About Page Processing

Page processing is the process of submitting a page. A page is typically submitted when a user clicks a button. Use the Page Processing section of the Page Definition to specify application logic such as computations, validations, processes, and branches. In general, the Application Express engine runs this logic in the order it appears on the Page Definition.

You can quickly navigate to a specific subsection by clicking the icons beneath the heading. When you select one of these icons, the subsection appears and all other subsections are temporarily hidden. To restore the view, click Show All. The Show All icon resembles an inverted triangle.

Topics in this section include:

- Computations

- Validations

- Processes

- Branches

See Also:
"About the Page Definition", "About the Edit All Icon", and "About the Copy or Create Icons"

Computations

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

See Also:
"Understanding Page Computations"

Validations

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

See Also:
"Understanding Validations" and "About the When Button Pressed Attribute"

Processes

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

See Also:
"Understanding Page Processes"

Branches

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

See Also:
"Understanding Branches" and "About the When Button Pressed Attribute"

About Shared Components

The Shared Components section of the Page Definition contains common elements that can display or be applied on any page within an application.

You can quickly navigate to a specific subsection by clicking the icons beneath the heading. When you select one of these icons, the subsection appears and all other subsections are temporarily hidden. To restore the view, click Show All. The Show All icon resembles an inverted triangle.

See Also:
"Working with Shared Components"

Topics in this section include:

- Tabs

- Lists of Values

- Breadcrumbs

- Lists

- Theme

- Templates

- Security

- Navigation Bar

See Also:
"About the Page Definition", "About the Edit All Icon", and "About the Copy or Create Icons"

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 as well as context (or sense of place) within the application.

See Also:
"Creating Tabs"

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.

See Also:
"Creating Lists of Values"

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.

See Also:
"Creating Breadcrumbs"

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.

See Also:
"Creating Lists"

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.

See Also:
"Managing Themes"

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.

See Also:
"Customizing Templates"

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.

See Also:
"Providing Security Through Authorization"

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

See Also:
"Creating a Navigation Bar Entry"

Understanding Page Computations

Use page computations to assign a value to an identified item when a page is submitted or displayed. You can also use application-level computations to assign values to items. Most application-level computations are performed for every page in an application. In contrast, computations created at the page-level only execute when that page is rendered or processed.

See Also:
"Understanding Application Computations"

Topics in this section include:

- Creating a Page Computation

- Understanding Computation Points and Computation Syntax

- Editing Page Computation Attributes

Creating a Page Computation

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 as well as a computation type.

See Also:
"Computations"

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:

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

b. Sequence - Select the order of evaluation.

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

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

e. 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 new 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:

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

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

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

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

Editing the Computation Point and Source

You control when a computation executes under the Computation Point attributes by specifying a sequence and a computation point. The computation point On New Instance executes the computation when a new session (or instance) is generated.

Under Source, enter an expression or query to compute an item's value. In the event a computation fails, you can optionally define an error message in the Computation Error Message field.

Creating Conditional Computations

You can make a computation conditional by making a selection from the Condition Type list and entering text in the expression fields.

Understanding Validations

You can define a validation declaratively by selecting a validation method. You enter the actual validation edit check in the Validation Messages field. Be aware that if a validation fails, subsequent page processes or computations will not occur. Also remember that the validation you enter must be consistent with the validation type you selected. For more information about validation types, see online Help.

Topics in this section include:

- Creating a Validation

- Defining How Validation Error Messages Display

- Processing Validations Conditionally

See Also:
"About the When Button Pressed Attribute"

Creating a Validation

To create a new validation:

Note:
Text entered for validations may not exceed 3,950 characters.

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 4-6.

Table 4-6 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.

See Also:
"Validating User Input in Forms"

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 need to 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.

Tip:
If you select Inline with Field or Inline with Field and in Notification, be aware that the Application Express engine does not execute computations or processes during the re-rendering of the page when the validation error messages appear.

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.

Understanding Page Processes

A page process performs an action at a specified point during the rendering or submission of the page. For example, you can create a page process to execute logic or to make a call to the Application Express engine. A page process is a unit of logic that runs when a specific event occurs, such as loading or submitting a page.

From a functional perspective, there is no difference between page-level and application-level processes. The difference between these two process types is where the process is defined, that is at the page level or at the application level.

See Also:
"Understanding Application Processes"

Topics in this section include:

- Creating a Page Process

- Editing Process Attributes

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 new 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 4-7 describes available page process categories.

Table 4-7 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 in conjunction with tabular forms.

- Use Add Rows to Tabular Form in conjunction 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 as well as to clear existing user preferences.

See Also: "Managing Session State Values" and "Managing User Preferences"

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.

See Also:
"About the When Button Pressed Attribute"

Changing Processing Points and Source

You control when a process executes by specifying a sequence number and a process point under Process Point. You can prevent a process from running during subsequent visits to a page by selecting one of the following options under Run Process:

- Once for each page visit

- Once for each session or when reset

Enter the appropriate code for PL/SQL process types. For PL/SQL anonymous block processes, enter the appropriate code under Process. For Clear Cache processes, enter the appropriate code under Source. In the event a process fails, you can optionally define an error message in the Process Error Message field.

Creating Conditional Processes

You can make a process conditional by selecting a condition type and entering an expression under Conditional Processing.

Additionally, you can also make a selection from the When Button Pressed attribute. When you select a button from this list, the process only executes if a user clicks the selected button.

Understanding Branches

A branch is an instruction to go to a specific page, procedure, or URL. For example, you can branch from page 1 to page 2 after page 1 is submitted.

You create a new branch by running the Create Page Branch Wizard and specifying Branch Point and Branch Type. The Branch Type defines the type of branch you are creating. For more information about Branch Types, see online Help.

Topics in this section include:

- Defining a Branch Point and Action

- Branching Conditionally

See Also:
"About the When Button Pressed Attribute"

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.

See Also:
"Controlling Navigation Using Branches"

Editing Page Attributes

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. You access page attributes from the Page Definition.

Topics in this section include:

- Accessing Page Attributes

- About the Page Attributes Page

Accessing Page Attributes

To edit page attributes:

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

2. Under Page Rendering, locate the Page section.

The Page Attributes page is divided into categories that control specific page attributes such as the Page Name, Title, HTML Header, HTML Body, Help Text, Templates, and so on.

3. To edit page attributes you can either:

- Click the Edit page attributes icon to access the entire Page Attributes page. This icon resembles a small page with a pencil on top of it.

- Click a specific link. The specific information appears.

Tip:
Clicking the Edit page attributes icon is the only way to view all page attributes at once.

The Page Attributes page appears. Required values are marked with a red asterisk (*).

About the Page Attributes Page

The Page Attribute page is divided into the following sections: Name, Display Attributes, Header and Footer, HTML Header, HTML Body Attributes, Security, Duplicate, Cache, Configuration, Error, Help, and Comments.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

The topics that follow describe the specific sections of the Page Attributes page.

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 4-8 describes these attributes.

Table 4-8 Page Attributes: Name

Attributes

Descriptions

Name

Identifies the name of the current page for application developers. This name is used in numerous pages and reports, along with the page number and page title.

Page Alias

Enter an alphanumeric alias for this page. This alias must be unique within the current application.

For example, if you were working on page 1 of application 100, you could create an alias called home. You could then access this page from other pages using the following f?p syntax:

f?p=100:home

Group

Identify the page group you would like to associate with this page. Page groups do not affect functionality, but help developers manage the pages within an application.

To remove a page from a group, select No Group Assigned and click Apply Changes.

See Also: "Grouping Pages"

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 4-9 describes these attributes.

Table 4-9 Page Attributes: Display Attributes

Attributes

Descriptions

Page Template

Select a page template to control the appearance of this page. Making a selection here overrides the default page template defined within the current theme.

See Also: "Changing the Default Templates in a Theme"

Standard Tab Set

Select a standard tab set to be used for this page. A standard tab set is associated with a specific page and page number. You can use standard tabs to link users to a specific page.

See Also: "Creating Tabs"

Title

Enter a title to display in the title bar of the browser window. The Application Express engine uses the title you specify here in place of the #TITLE# substitution string used in the page template. This title is inserted between the HTML tag <TITLE></TITLE>.

Cursor Focus

Specify the cursor focus. Available options include:

- Select First item on page to have the cursor focus placed in the first field on the page.

- Select Do not focus cursor if you do not want to include JavaScript. Select this option to prevent conflicts between generated JavaScript and custom JavaScript.

Header and Footer

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

Table 4-10 Page Header, Footer and Text Attributes

Attribute

Description

Header Text

Enter text or HTML you want to appear immediately following the page header.

Footer Text

Enter text or HTML you want to appear before page template footer.

HTML Header

Use this attribute 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

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

See Also:
"Incorporating JavaScript into an Application"

Security

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

Table 4-11 Page Attributes: Security

Attribute

Description

Authorization Scheme

Select an authorization scheme to be applied to the page. Authorization schemes are defined at the application level and can be applied to many elements within the application.

An authorization scheme is evaluated either once for each application session (at session creation), or once for each page view. If the selected authorization scheme evaluates to true, then the page displays and is subject to other defined conditions. If it evaluates to false, then the page will not display and an error message displays.

See Also: "Providing Security Through Authorization"

Authentication

Specifies whether this page has been defined as public or requires authentication. If a page is identified as public, the page can be viewed before authentication. This attribute only applies to applications requiring authentication. The application's page sentry function can access this page attribute to identify pages that do not require prior authentication to view. The implementation of the authentication scheme's page sentry function determines if this attribute has any effect.

See Also: "Establishing User Identity Through Authentication"

Duplicate Submission

Use the Allow duplicate page submissions list to specify whether or not 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, 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 4-12 describes these attributes.

Table 4-12 Cache Attributes

Attribute

Description

Cache Page

Specify whether or not to enable page caching by selecting Yes or No. Page caching can improve performance because the page displays from cache instead of displaying dynamically.

Cache Timeout

Specify the amount of time for which a cached page remains valid.

Cache by User

Specify if the page should be cached by user. If Yes, the page is cached specifically for each user. If No, the same cached page is used for all users.

Cache Page Condition

Specify a condition. If the condition returns false, the page is rendered dynamically and is not be cached. If the condition returns true, the page is displayed from cache.

Expression 1

Enter values in this attribute based on the specific condition type selected.

Expression 2

Enter values in this attribute based on the specific condition type selected.

See Also:
"Managing Cached Regions and Pages" and "Utilizing Region Caching"

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.

See Also:
"Using Build Options to Control Configuration"

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.

See Also:
"Page Templates"

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"

See Also:
"Creating a Help Page" and "Using Shortcuts"

Comments

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

About the Developer Toolbar

The Application Express engine dynamically renders and processes pages based on data stored in database tables. To view a rendered version of your application, you run or submit it to the Application Express engine by clicking the Run icon.

See Also:
"Running a Page or Application"

When you run an application from within the development environment, the Developer toolbar appears at the bottom of the page. The Developer toolbar offers a quick way to edit the current page, create a new page, region, or page control, view session state, or toggle in and out of Debug mode. You can control whether the Developer toolbar displays by changing the Status attribute on the Edit Definition page.

See Also:
"About the Edit Definition Page" for information on the Status list

The Developer toolbar consists of the following links:

- Home links you the Workspace home page. See "About the Workspace Home Page".

- Application links you to the Application home page. See "About the Application Builder Home Page".

- Edit Page accesses the Page Definition for the current running page. See "Editing a Page Definition".

- Create links to a wizard for creating a new page, region, page control (item, button, branch, computation, process, or validation), or a shared control (navigation bar icon, tab, list of values, list, or breadcrumb). See "Creating a Page from the Developer Toolbar".

- Session displays a new window containing session state information for the current page. See "Viewing Session State".

- Activity links you the Activity reports for your application. See "Activity Reports".

- Debug toggles the page between Debug and No Debug mode. See "Accessing Debug Mode".

- Show Edit Links toggles between Show Edit Links and Hide Edit Links. Clicking Show Edit Links displays edit links next to each object on the page that can be edited.

Clicking Show Edit Links displays a small orange icon next to each editable object on the page. Each icon is orange and contains a triangle with two rules beneath it. Clicking the link displays another window in which to edit the object.

Working with Shared Components

Shared components are common elements that can display or be applied on any page within an application. You can use the tools and wizards on the Shared Components page either at the application-level or on specific pages.

Topics in this section include:

- Accessing the Shared Components Page

- About the Shared Components Page

- About Exporting Shared Components

- Accessing Reports on Shared Components

Accessing the Shared Components Page

To access 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. To create a shared component, select the appropriate link.

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.

See Also:
"About the Action Bar"

About the Shared Components Page

The following sections describe each link on the Shared Components page.

Application

The following section describes the links under Application.

Definition

Links to the Edit Application Definition page. Use this page to edit attributes that determine the application name, application availability, and static substitution strings. You can also use this page to define other attributes such as build options or an application logo as well as view associated templates and component defaults. See "Configuring the Application Definition".

Comments

Use Application Comments to enter comments specific to the currently selected application. See "Adding Application Comments"

Logic

The following section describes the links under Logic.

Application Items

Application-level items do not display, but are used as global variables to the application. Commonly, you set the value of a page-level item using an application or page computations. See "Understanding Application-Level Items".

Application Processes

Use application processes to run PL/SQL logic:

- At specific points for each page in an application

- As defined by the conditions under which the process is set to execute

- Upon the creation of a new session

Note that On Demand processes execute only when called from a page-level On Demand process. See "Understanding Application Processes".

Application Computations

Use application-level computations to assign values to application and page-level items for each page displayed or upon the creation of a new application session. You can also create an application-level computation and execute it conditionally on multiple pages. See "Understanding Application Computations".

Web Service References

Web service references in Application Builder are based on the Simple Object Access Protocol (SOAP). You can create a reference to a Web service and then incorporate it into an application to process data submitted by a form, or to render output in the form or report. See "Implementing Web Services".

Build Options

Use build options to conditionally display or process specific functionality within an application. You can use build options to control which features of an application are turned on for each application deployment. See "Using Build Options to Control Configuration".

Security

The following section describes the links under Security.

Authentication Schemes

Authentication is the process of establishing each user's identity before they can access your application. Authentication may require a user to enter a user name and password or may involve verification of a user's identity or use of a secure key. See "Establishing User Identity Through Authentication".

Authorization Schemes

Authorization restricts user access to specific controls or components based on predefined user privileges. See "Providing Security Through Authorization".

Session State Protection

Session State Protection is a built-in functionality that prevents hackers from tampering with the URLs within your application. URL tampering can adversely affect program logic, session state contents, and information privacy. See "Understanding Session State Protection".

Edit Security Attributes

Use the Edit Security Attributes page to configure general security attributes for all pages within an application. See "Configuring Security Attributes".

Globalization

The following section describes the links under Globalization.

Translate Application

You can develop applications in Oracle Application Express that can run concurrently in different languages. A single Oracle database and Oracle Application Express instance can support an application in multiple languages. Translating an application involves multiple steps. See "About Translating an Application and Globalization Support" and "Understanding the Translation Process".

Text Messages

Text messages are named text strings that can be called from the PL/SQL code you write. This PL/SQL can be anonymous blocks within page processes and page regions, or in packages and procedures. See "Translating Messages".

Edit Attributes

You can develop applications that can run concurrently in different languages. Click this link to specify globalization options such as the Application Primary Language and Application Language Derived From attributes. See "Configuring Globalization Attributes" and "About Translating an Application and Globalization Support".

Navigation

The following section describes the links under Navigation.

Tabs

Tabs are an effective way to navigate users between pages in an application. You can create two types of tabs: standard tabs or parent tabs. A standard tab set is associated with a specific page and page number. A parent tab set functions as a container to hold a group of standard tabs. See "Creating Tabs".

Lists

A list is a shared collection of links. You control the appearance of a list through list templates. Each list element has a display condition that enables you to control when it displays. See "Creating Lists".

Breadcrumbs

Breadcrumbs provide users with hierarchical navigation. A breadcrumb is a hierarchical list of links that display using templates. You can display a breadcrumb as a list of links or as a breadcrumb path. See "Creating Breadcrumbs".

Trees

A tree is an effective way to communicate hierarchical or multiple level data. See "Creating Trees".

Navigation Bar Entries

Navigation bar entries offer users a simple navigation path for moving between pages in an application. The location of a navigation bar depends upon the associated page template. Navigation bar entries can display as a link from an image or text. A navigation bar entry can be an image, an image with text beneath it, or text. See "Creating a Navigation Bar Entry".

User Interface

The following section describes the links under User Interface.

Themes

A theme is a named collection of templates that defines the application user interface. See "Managing Themes".

Templates

Templates control the look and feel of specific constructs within your application, such as pages, regions, items, and menus. See "Customizing Templates".

User Interface Defaults

User interface defaults enable you to assign default user interface properties to a table, column, or view within a specified schema. When you create a form or report using a wizard, the wizard uses this information to create default values for region and item properties.

Because user interface defaults are associated with a table, you can use them with applications created using the form and report wizards. See "Managing User Interface Defaults".

Lists of Values

A list of values (LOV) is a static or dynamic set of values used to display a popup list of values, select list, check box, or radio group. See "Creating Lists of Values".

Shortcuts

Use shortcuts to avoid repetitive coding of HTML or PL/SQL functions. You can create a shortcut to define a page control such as a button, HTML text, a PL/SQL procedure, or HTML. Once you define a shortcut, it is stored in a central repository so you can reference it from various locations within your application. See "Using Shortcuts".

Reports

The following section describes the links under Reports.

Report Queries

Use the Report Queries link to view a report of stored queries within the current application. See "About Report Queries".

Report Layouts

Use Report Layouts in conjunction with a report or shared query to render data in a printer-friendly format, such as PDF, Word or Excel. See "About Report Layouts".

Files

The following section describes the links under Files.

Cascading Style Sheets

Application Builder includes themes that contain templates that reference their own cascading style sheets (CSS). Use the Cascading Style Sheets link to upload cascading style sheets to your workspace. See "Using Custom Cascading Style Sheets".

Images

Use the Images link to upload images to your workspace. See "Managing Images".

Static Files

Use the Static Files link to upload static files to your workspace. See "Managing Static Files".

About Exporting Shared Components

You can export shared components and page components on the Component Export page. You can also use this wizard to back up a component before editing it or to create an export that functions as a patch to another Oracle Application Express instance.

Topics in this section include:

- Exporting Shared Components from the Export Page

- Exporting Shared Components from the Shared Components Page

Exporting Shared Components from the Export Page

To export shared components from the Shared Components page:

1. Navigate to the Export page:

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

b. Select an application.

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

d. 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".

Accessing Reports on Shared Components

You can access reports on shared components within your application by clicking Report on Shared Components on the Tasks list on the Shared Components page.

To access the Shared Components reports:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Tasks list, click Application Reports.
The Application Reports page appears.

5. Click Shared Components.
A variety of application reports appear and are divided into the same categories that appear on the Shared Components page, including:

- Application

- Logic

- Security

- Globalization

- Navigation

- User Interface

- Reports

- Files

Note that you can also navigate to these reports by clicking View Application Reports on the Tasks list on the Application home page.

See Also:
"Viewing Application Reports", and "About the Database Object Dependencies Report"

Understanding Application Processes

Application processes are blocks of PL/SQL logic that are set to run at specific points using processes from multiple pages of an application. By default, application processes execute at the same point for every page in the application. However, you can apply conditions for specific pages to control when the process executes.

Topics in this section include:

- About On Demand Application Processes

- Application Process Example

- Creating an Application Process

- Accessing Application Processes Reports

About On Demand Application Processes

A special type of application process is the On Demand process. An On Demand application process has a Process Point of On Demand and executes when called from a page-level On Demand process. On Demand processes are useful when you have PL/SQL logic that you would like to run from different execution points across multiple pages.

See Also:
"Creating a Page Process"

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.

See Also:
"Clearing Session State"

Application Process Example

A shopping cart application is a good example of when you might use an application process. For example, suppose you need to display the contents of a user's shopping cart with each page view. To accomplish this, you create a region on page zero of your application that displays the values of the application-level items TOTAL_CART_ITEMS and TOTAL_PURCHASE_PRICE.

See Also:
"Displaying Components on Every Page of an Application"

Instead of writing a process for each page to set the values of TOTAL_CART_ITEMS and TOTAL_PURCHASE_PRICE, you could write an application process of type On Load: Before Header to compute these values. Then, the Application Express engine would execute the process on each page as it renders the application. As a result, each page, would display the most current values for TOTAL_CART_ITEMS and TOTAL_PURCHASE_PRICE.

Creating an Application Process

To create an application process:

1. Navigate to the Shared Components page:

a. On the Workspace home page, click Application Builder.

b. Select an application.

c. On the Application home page, click Shared Components.
The Shared Components page appears.

2. Under Logic, select Application Processes.

3. Click Create.

4. For Identification:

a. Name - Enter a name for the application process.

b. Sequence - Specify the sequence number for this process. The sequence number determines the order in which the process will be evaluated relative to other processes.

c. Point - Identify the point at which this process executes.

d. Click Next.

5. For Source:

a. Process Text - Enter the text that is to be the source of your process.

b. Error Message - Enter the error message that displays if the process raises an error.

c. Click Next.

6. For Conditionality:

a. Condition Type - Select a condition type that must be met in order for this process to execute.

b. Expression 1 and Expression 2 - Use these attributes to conditionally control whether or not the process executes. Enter values in this attribute based on the specific condition type you select. The process will execute if the specified condition is met.

c. Click Create Process.

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.

Accessing Application Processes Reports

After you create an application process, you can access the Utilization and History reports.

To access application processes reports:

1. Navigate to the Workspace home page.

2. Click Application Builder.

3. Select an application.

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

5. Under Logic, select Application Processes.

6. Select one of the following tabs at the top of the page:

- Utilization

- History

7. Follow the on-screen instructions.

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.

Understanding Application Computations

Application Computations are units of logic that set the value of a single page or application-level item and are run at the same point across multiple pages in an application. Like page level computation, application computations can be based on static values, item values, PL/SQL, or SQL.

Topics in this section include:

- About Application Computations

- Creating an Application Computation

- Accessing the Application Computation History Report

About Application Computations

A common use of an application item is to store the value of the last page viewed in the application. By storing the value in an item, you can add a back button and then redirect the user to the page number captured by the computation. This type of computation works well, for example, when you need to enable users to back out of an error page.

The following is an example of a computation that stores the last page visited. In this example, the computation:

- Stores the last application page visited to an item named LAST_PAGE

- Checks that the value of a CURRENT_PAGE_ITEM is of type PL/SQL Function Body with a Computation body of:

BEGIN
:LAST_PAGE := nvl(:CURRENT_PAGE,:APP_PAGE_ID);
:CURRENT_PAGE := :APP_PAGE_ID;
RETURN :LAST_PAGE;
END;

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

Creating an Application Computation

To create an application computation:

1. Navigate to the Shared Components page:

a. On the Workspace home page, click Application Builder.

b. Select an application.

c. On the Application home page, click Shared Components.
The Shared Components page appears.

2. Under Logic, select Application Computations.

3. Click Create.

4. Under Item:

a. Sequence - Specify the sequence for this component. The sequence determines the order of evaluation.

b. Computation Item - Select the item this computation affects.

5. For Computation Point, select a process point at which this computation should be performed. Selecting After Submit causes the computation to be performed only after the page is displayed and then submitted.

6. Under Computation:

a. Computation Type - Select the manner in which this computation will be performed.

b. Computation - Enter the computation logic that corresponds to the computation type.

c. Computation Error Message - Enter the error message that displays if the computation fails.

7. For Authorization Scheme (optional), select an authorization scheme which must evaluate to True in order for this computation to execute.

8. Under Conditions:

a. Condition Type - Select a condition type that must be met in order for this computation to execute.

b. Expression 1 and Expression 2 - Use these attributes to conditionally control whether or not the computation executes. Enter values in this attribute based on the specific condition type you select. The computation will execute if the specified condition is met.

9. For Build Option (optional), select a build option for this component. See "Using Build Options to Control Configuration".

10. Click Create.

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.

Accessing the Application Computation History Report

Once you create an application computation, you can view the Application Computation History report.

To access the Application Computation History report:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. When Application Builder appears, click Shared Components.

5. Under Logic, select Application Computations.

6. Select the History tab at the top of the page.
This Application Computation History report displays a history of recently changed application computations by date.

Viewing Application Reports

Application Builder includes over 100 reports that provide a comprehensive view of your application from various perspectives. You can use application reports to achieve consistency among shared components and page components within your application. For example, you can view details about buttons used on all pages within your application. Additionally, many reports are updatable so you can standardize components, such as item and region labels, without navigating to a specific page.

Topics in this section include:

- Accessing Application Reports

- Shared Components Reports

- Page Components Reports

- Activity Reports

- Cross Application Reports

See Also:
"Creating Custom Activity Reports Using APEX_ACTIVITY_LOG"

Accessing Application Reports

To view reports specific to an application:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.
The Application home page appears.

4. On the Tasks list, click Application Reports.

5. Select a type of report to view:

- Shared Components. See "Shared Components Reports".

- Page Components. See "Page Components Reports".

- Activity. "Activity Reports".

- Cross Application. "Cross Application Reports".

Shared Components Reports

Shared Components reports offer information on common elements that can display on every page within an application. Reports are grouped by the following categories: including Application, Logic, Security, Globalization, Conditional Components, Navigation, User Interface, and Files. Report examples include Developer Comments, Database Object Dependencies, Application Items, Application Computations, Authentication Schemes, Breadcrumb Entries, and Shortcuts.

About the Database Object Dependencies Report

The Database Object Dependencies report identifies database objects referenced by the current application. Review this report to determine what objects to move when deploying an application.

See Also:
"How to Move an Application to Another Development Instance" and "Viewing Application Reports"

To view the Database Object Dependencies report:

1. Navigate to the appropriate application.

a. From the Workspace home page, click the Application Builder icon.

b. Select an application.

2. On the Tasks list, click Application Reports.

3. Click Shared Components.

4. Click Database Object Dependencies.

5. Click Compute Dependencies.

6. To view the components that reference a specific database object, select the Reference Count number.

Page Components Reports

Page Components reports offer detailed information on controls and logic that execute when a page is rendered (for example, branches, buttons, computations, items, and regions).

See Also:
"Editing Multiple Item Help Topics Simultaneously"

About the Search Region Source Report

Use the Search Region Source report to search through all region source in your application.

To view the Search Region Source report:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Tasks list, click Application Reports.

5. Click Page Components.

6. Under Regions, click Search Source.

7. To view the Page Definition for a region, select the page number.

8. To view region attributes for a region, select the region name.

Activity Reports

Activity reports offer details about developer activity within the current application. Available reports are grouped into the following categories: Page Views, Caching, Developer Activity, and Sessions.

Tip:
You can also access the Activity page by clicking the Activity link on the Developer toolbar. See "About the Developer Toolbar".

About the Page Views by Hour Report

To view the Page Views by Hour report:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Tasks list, click Application Reports.

5. Click Activity.

6. Under Page Views, click By Hour.

Cross Application Reports

Cross Application reports offer information that apply to multiple applications. Available reports include Application Attributes, Application Comments, Build Options, Build Status and Application Status, Page Component Counts, Security Profiles, Authentication Schemes, and Template Defaults by Application.

About the Application Comparison Report

Use the Application Comparison report to compare two applications.

To view the Application Comparison report:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. On the Tasks list, click Application Reports.

5. Click Cross Application.
The Application Comparison page appears.

6. In the navigation bar, specify the following:

a. Application 1 - Select the first application to compare.

b. Application 2 - Select the second application to compare.

c. Component - Select the components to include in the report.

d. Page - Identify a specific page number to compare.

e. Show - Select the number of differences to display on each page.

f. Click Go.

7. To view only differences, select Show Differences Only and click Go.

8. To view details, select Show Details and click Go.

5 Building an Application

This section describes how to use Application Builder to build an application and application components. It includes instructions for creating an application and adding pages as well as adding components (reports, charts, or forms), page controls (buttons, items, list of values), and shared components (breadcrumbs, lists, or tabs).

This section contains the following topics:

- Creating an Application

- Managing Pages in an Application

- Adding Application Comments

- Adding Developer Comments

- Creating Reports

- Creating Forms

- Creating Calendars

- Creating Charts

- Creating Buttons

- Understanding Page-Level Items

- Understanding Application-Level Items

- Creating Lists of Values

- Creating Dependent Select Lists

- Using Shortcuts

- Using the Find Icon

- Controlling Access to Applications, Pages, and Page Components

- Incorporating JavaScript into an Application

- Creating a Help Page

See Also:
"Using Application Builder", "Controlling Page Layout and User Interface", and "Adding Navigation"

Creating an Application

An application is a collection of pages that share a common session state and authentication. You create a new application in Application Builder using a wizard. You delete an application from the Application home page.

Topics in this section include:

- About Creating an Application Using a Wizard

- About the Create Application Wizard

- About the Create Application from Spreadsheet Wizard

- About Demonstration Applications

- Copying an Application

- Deleting an Application

Tip:
You can reduce the number of steps needed to create a new application by configuring Application Builder Defaults. See "Leveraging Application Builder Defaults".

About Creating an Application Using a Wizard

When you click Create on the Application Builder home page, you must choose one of the following options:

- Create Application. Creates an application. The application can be based on SQL queries or database tables. You can define blank pages or pages that contain reports, forms, tabular forms, or a report with a linked form. See "About the Create Application Wizard".

- Create Application from Spreadsheet. Creates an application based on spreadsheet data. You can upload or paste spreadsheet data to create a table and then add a user interface. In the resulting application, users can create queries, add, insert, or update records, or analyze the data. See "About the Create Application from Spreadsheet Wizard".

- Demonstration Application. Installs or uninstalls demonstration applications. Use demonstration applications to learn how to build applications. See "About Demonstration Applications".

See Also:
"Managing Pages in an Application"

About the Create Application Wizard

The Create Application wizard enables you to create a fully functional application based on any number of tables. You can use the Create Application Wizard to create blank pages, or pages based on SQL queries or database tables. You can create SQL queries by manually typing SQL, or by using the graphical user interface of Query Builder.

Applications based on tables can consist of a simple report, a form and report, or a tabular form. When creating pages on tables, you have the option to generate analysis pages. Analysis pages extend a simple report or a report on a form to include multiple drill-down reports and charts.

At the workspace level, you have the option of setting defaults that are used for applications built in that workspace. Setting these defaults enables you to exit the wizard without paging through each step. When you exit the wizard, the application you create uses the values you specified as defaults.

See Also:
"Building Queries with Query Builder" and "Leveraging Application Builder Defaults"

See Tutorials:
"Building Your Application" in Oracle Database 2 Day + Application Express Developer's Guide and Oracle Database Application Express Advanced Tutorials

Topics in this section include:

- Creating an Application Based on Tables or Queries

- About Application Models and User Interface Defaults

- Leveraging Application Models and User Interface Defaults

Creating an Application Based on Tables or Queries

You can create an application based on a table, query, or drill-down query by selecting Create Application in the Create Application Wizard.

To create an application based on a table, query, or drill-down query:

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

2. Click the Create button.

3. For Method, select Create Application and click Next.

4. For Name, enter the following and click Next:

a. Name - Enter a name to identify the application.

b. Application - Enter a unique integer value to identify the application.

c. Create Application - Select a creation method:

- Select From scratch to manually add all pages

- Select Based on existing application design model to copy page definitions from a previous application model.

Note that you will still have to define all other application attributes, or you can choose to copy some attributes by choosing to copy shared components from another application (See step 7 and "About Application Models and User Interface Defaults").

d. Schema - Your application will obtain its privileges by parsing all SQL as a specific database schema. Identify the database schema owner.

Next, add pages to your application.

5. For Pages:

a. Select the type of page you want to add. Options include:

- Blank creates a page with no built-in functionality.

- Report creates a page that contains the formatted result of a SQL query. You can choose to build a report based on a table you select, or based on a custom SQL SELECT statement or a PL/SQL function returning a SQL SELECT statement that you provide.

- Form creates a form to update a single row in a database table.

- Tabular Form creates a form to perform update, insert, and delete operations on multiple rows in a database table.

- Report and Form builds a two page report and form combination. On the first page, users select a row to update. On the second page, users can add a new record or update or delete an existing record.

Action displays the currently selected page type. For each selection, the wizard prompts you for a different types of information, such as selecting a table name.

Report pages include the Include Analysis Pages check box. Select this option and follow the wizard prompts to extend a simple report or a report on a form to include multiple drill-down reports and charts.

b. Click Add Page.
The page (or pages) appear at the top of the page. To delete a page, click Delete icon.

c. Repeat the previous steps until all pages have been added.

d. Click Next.

Tip:
To exit this wizard early and utilize Application Builder Defaults, click the Create button. To configure Application Builder Defaults, see "Leveraging Application Builder Defaults".

6. For Tabs, determine whether to include tabs in your application and click Next.

7. For Shared Components, determine whether to import shared components from another application. Shared components are common elements that can display or be applied on any page within an application.
To include shared components, select the following:

a. Copy Shared Components from Another Application - Select Yes.

b. Copy from Application - Select the application from which you want to import shared components.

c. Select Components to Import - Select the components to import.

d. Click Next.

Next, select a default authentication scheme. Authentication is the process of establishing users' identities before they can access an application. See "Establishing User Identity Through Authentication".

8. For Authentication Scheme, select one of the following:

- Application Express - Uses the user account credentials created and maintained with the Application Express Service Administration application. These are the accounts you use to log in to the Application Express development environment. You can also create accounts in this user account repository for end users of your applications.

- No Authentication - Also known as database authentication, this option enables users to access your application using the account credentials stored in the modplsql DAD definition. In most cases this results in users not having to login when accessing your application. This is the quickest way to create a "public" application.

- Database Account - Requires users logging into your application to enter a database schema name (or user name) and a password in order to authenticate. This account information is managed entirely within the Oracle database.

9. Next, select the following globalization preferences:

a. Language - Select the primary language for this application.
This attribute identifies the language in which an application is developed. This language is the base language from which all translations are made.

b. User Language Preference Derived From - Specifies how the engine determines the application language. The application primary language can be static (that is, derived from the Web browser language) or determined from a user preference or item. The database language setting determines date display and sorting characteristics.
You can alter the Language and User Language Preference Derived From attributes later on the Edit Globalization attributes page. See "Configuring Globalization Attributes".

c. Click Next.

10. For User Interface, select a theme and click Next.
Themes are collections of templates that can be used to define the layout and style of an entire application. See "Managing Themes".

11. Confirm your selections and click Create.

About Application Models and User Interface Defaults

The Create Application Wizard is designed with the assumption that the developer may run it multiple times. To facilitate this iterative approach to application development, every time you run the wizard it saves the page definitions to an application model.

Consider the following example. You create a new application by running the Create Application Wizard. After viewing the application, you realize it is not quite what you wanted. Instead of altering it, you can run the wizard again and select an application model. By selecting an existing application model when you rerun the wizard, you can quickly improve your application with minimal time and effort.

See Also:
"Managing Application Models"

Another way to increase your productivity when creating an application is to specify user interface defaults. User interface defaults are metadata that enable you to assign default user interface properties to a table, column, or view within a specified schema.

See Also:
"Managing User Interface Defaults"

Leveraging Application Models and User Interface Defaults

You can increase your productivity when creating applications by leveraging application models and user interface defaults. Consider the following scenario:

1. Create an application based on tables or views by running the Create Application Wizard.

2. Run the generated application. Note any functional deficiencies.

3. Evaluate whether to create or edit user interface defaults.
For example, you can use user interface defaults to control how form field or report labels display. You can also utilize user interface defaults to display specific columns or have columns display in an alternate order.

4. Navigate to the Application home page and create a new application by clicking Create.

5. Select Create Application.

6. When prompted to enter application details, specify the following:

a. Name - Enter a name to identify the application.

b. Application - Enter a unique integer value to identify the application, or accept the default.

c. Create Application - Select Based on existing application design model.

7. Select an application model.
Note the pages you previously created already appear.

8. Add pages, edit pages, or remove pages.

9. Complete the wizard.

10. Repeat steps 2 through 9 until the application meets your functional requirements.

About the Create Application from Spreadsheet Wizard

You can create an application based on spreadsheet data by selecting Create from Spreadsheet in the Create Application Wizard.

To create an application from spreadsheet data:

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

2. Click the Create button.

3. Select Create from Spreadsheet.

4. For Load Method, specify how spreadsheet data will be uploaded. Select one of the following and click Next:

a. Upload file, comma separated (*.csv) or tab delimited. Specify the following and click Next:

- Text File - Click Browse to locate the file to be uploaded.

- Separator - Specify the column separator character. Use \t for tab separators.

- Optionally Enclosed By - Enter a delimiter character. You can use this character to deliminate the starting and ending boundary of a data value. If you specify a delimiter character, the wizard ignores white space occurring before the starting and ending boundary of a data value. You can also use this option to enclose a data value with the specified delimiter character.

- File Character Set - Choose the character set in which the text file is encoded.

b. Copy and paste (up to 30KB). Copy and paste the spreadsheet data you wish to import and click Next.

5. For Table Properties, review how your table will display and click Next. Specify the table name and column names, or modify the data types. To specify whether or not to include a column, make a selection from the Upload list.

6. For User Interface Defaults:

a. Review the displayed Singular Name and enter a Plural Name.

b. (Optional) Under Column User Interface Defaults, review the displayed column labels.

c. Click Next.

7. For Summary By Column, select the columns for which data will be summarized in reports and charts and click Next.

8. For Application Options, specify the following:

a. Application Name - Enter an alphanumeric name for this application.

b. Create Mode:

- Read and Write includes insert and update pages.

- Read Only does not include insert and update pages.

c. Select a chart type.

d. Click Next.

9. For User Interface Theme, select a theme and click Next.
Themes are collections of templates that can be used to define the layout and style of an entire application. See "Managing Themes".

10. Confirm your selections and click Create.

See Also:
"Building Queries with Query Builder"

See Tutorial:
"How to Build an Access Control Page" in Oracle Database Application Express Advanced Tutorials

About Demonstration Applications

Oracle Application Express installs with a number of demonstration applications. Use these applications to learn more about the different types of functionality you can include in your applications.

See Also:
"Running a Demonstration Application", "Disabling the Creation of Demonstration Applications in a New Workspace", and "Downloading Public Packaged Applications and Sample Code in Oracle Database 2 Day + Application Express Developer's Guide

Accessing Demonstration Applications

To access demonstration applications:

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

2. Click the Create button.

3. Select Demonstration Application.
The Demonstration Applications page appears, displaying links to the following applications:

- Sample Application offers a working demonstration that highlights basic design concepts

- Collection Showcase demonstrates shopping cart concepts

4. To install a demonstration application, locate the application you want to install and click Install.

5. Follow the on-screen instructions.
The Application home page appears.

6. To run an installed demonstration application, click the Run Application icon.

7. Enter the appropriate login credentials and click Login.

- For Sample Application:

- For User Name, enter either demo or admin

- For Password, enter current workspace name in lowercase letters

- For other demonstration applications, enter your workspace user name and password.

Copying an Application

To copy an application:

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

2. Select an application.
The Application home page appears.

3. Click Copy this Application on the Tasks list. See "About the Tasks List".

4. On Copy Application:

a. Enter a new application ID.

b. Enter a new application name.

c. Specify whether or not to copy deployment attributes.

d. Click Next.

5. Click Copy Application.

Deleting an Application

You can delete an application from within Application Builder, or while editing application attributes. If you delete an application you also delete all defined components (reports, charts, or forms), page controls (buttons, items, list of values), and shared components (breadcrumbs, lists, and tabs, but not user interface defaults).

Topics in this section include:

- Deleting an Application from Application Builder

- Deleting an Application from the Edit Definition Page

See Also:
"Deinstalling Supporting Objects"

Deleting an Application from Application Builder

To delete an application from Application Builder:

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

2. Select an application.

3. When Application Builder appears, verify the application ID and name at the top of the page.

4. On the Tasks list, click Delete this Application.

5. When prompted, click Permanently Delete Now.

Deleting an Application from the Edit Definition Page

To delete an application from the Edit Definition page:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Application, click Definition.
The Edit Definition page appears.

5. Verify the application ID and name.

6. Click Delete at the top of the page.

7. When prompted, click Permanently Delete Now.

See Also:
"Configuring the Application Definition"

Managing Pages in an Application

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.

Topics in this section include:

- About Creating Pages

- Creating a Page from the Application Home Page

- Creating a Page from the Page Definition

- Creating a Page from the Developer Toolbar

- Running a Page or Application

- Grouping Pages

- Locking and Unlocking a Page

- Deleting a Page

See Also:
"Creating Reports", "Creating Charts", "Creating Forms", "Creating Calendars", "Creating Trees", and "Controlling Access to Applications, Pages, and Page Components"

About Creating Pages

You add a new page or add a component to an existing page by running the Create Page Wizard. You can access this wizard by:

- Clicking Create Page on the Application home page. See "Creating a Page from the Application Home Page".

- Clicking Create on the Page Definition. See "Creating a Page from the Page Definition".

- Click the Create link on the Developer toolbar and then select New Page. "Creating a Page from the Developer Toolbar".

Note:
You can also use the Create Page Wizard to add a component (that is, a report, chart, form, wizard, a calendar, or tree) to an existing page. When prompted, specify an existing page number.

Creating a Page from the Application Home Page

To create a new page from the Application home page:

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

2. Select an application.
The Application home page appears.

3. Click the Create Page button.

4. Select the type of page you want to create as described in the following table.

Page Type

Description

Blank Page

Creates a blank page.

Multiple Blank Pages

Creates multiple blank pages.

Report

Formatted result of a SQL query. Available options:

- Wizard Report - Creates a report without requiring any SQL knowledge. Select the appropriate schema, table, columns, and result set display.

- SQL Report - Creates a report based on a custom SQL SELECT statement or a PL/SQL function returning a SQL SELECT statement that you provide.

See Also: "Creating Reports"

Chart

Enables you to create three types of graphical charts: HTML, Scalable Vector Graphics (SVG), and Flash.
See Also: "Creating Charts"

Form

Creates a form interface with which users can update a single row or multiple rows within a table.
See Also: "Creating Forms"

Wizard

Create a wizard.

Calendar

Generates a calendar with monthly, weekly, and daily views.
See Also: "Creating Calendars"

Tree

Creates a a tree to graphically communicate hierarchical or multiple level data.
See Also: "Creating Trees"

Login Page

Creates a login page.
See Also: "Building a Login Page"

Access Control

Creates a page containing a access control list, enabling developers to control access to an application, individual pages, or page components.
See Also: "Controlling Access to Applications, Pages, and Page Components"

5. Follow the on-screen instructions.

Creating a Page from the Page Definition

To create a new page while viewing a Page Definition:

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

2. Click the Create button at the top of the page.

3. Select the type of page you want to create:

- New Page

- Region on this page

- Page control on this page

- Shared Control

See "About Create Page Types".

4. Follow the on-screen instructions.

See Also:
Editing a Page Definition

About Create Page Types

When you run the Create Page Wizard, you select a page type. Table 5-1 describes available create page options based on the type of page you select.

Table 5-1 Create Page Options

Create Page Options

Available Selections

New Page

Available page types:

- Blank page

- Multiple blank pages

- Report. See "Creating Reports".

- Chart. See "Creating Charts".

- Form. See "Creating Forms".

- Wizard

- Calendar. See "Creating Calendars".

- Tree. See "Creating Trees".

- Login Page. See "Building a Login Page".

- Access control. See "Controlling Access to Applications, Pages, and Page Components".

- Page Zero. See "Displaying Components on Every Page of an Application".

Region on this page

Regions function as containers for content. Available region types:

- HTML

- Report

- Form

- Chart

- List

- Breadcrumb

- PL/SQL Dynamic Content

- Tree

- URL

- Calendar

- Multiple HTML

- Help Text

See Also: "Understanding Regions" and "About Region Types"

Page control on this page

Page controls:

- Item. See "Understanding Page-Level Items"

- Button. See "Creating Buttons".

- Branch. See "Understanding Branches"

- Computation. See "Understanding Page Computations".

- Process. See "Understanding Page Processes".

- Validation. See "Understanding Validations".

Shared control

Shared component options:

- Navigation Bar icon. See "Creating a Navigation Bar Entry".

- Parent tab. See "Creating Tabs".

- Standard tab. See "Creating Tabs".

- List of values. See "Creating Lists of Values".

- List. See "Creating Lists".

- Breadcrumb. See "Creating Breadcrumbs".

Creating a Page from the Developer Toolbar

To view a rendered version of your application, you run or submit it to the Application Express engine by clicking the Run or Run Application icon.

See Also:
"Running a Page or Application"

When you run an application, the Developer toolbar appears at the bottom of the page. The Developer toolbar offers a quick way to edit the current page, create a new page, region, or page control, view session state, or turn edit links on and off. You can control whether the Developer toolbar displays by changing the Status attribute on the Edit Definition page.

See Also:
"Configuring the Application Definition" for information on the Status list

To create a new page from the Developer toolbar:

1. Run the application. See "Running a Page or Application".

2. On the Developer toolbar, click Create.
The New Component Wizard appears.

3. Select the type of component you want to create and click Next. Available options include:

- New Page

- Region on this page

- Page control on this page

- Shared control

See "About Create Page Types".

4. Follow the on-screen instructions.

See Also:
"About the Developer Toolbar"

Copying a Page

You can copy a page from the current application or from another application. During the copy process, you can also copy shared components or change mappings to shared components in the target application.

To copy a page:

1. Navigate to the application you want to copy to:

a. Navigate to the Workspace home page.

b. Click the Application Builder icon.

c. Select an application.

d. Select a page.
The Page Definition appears.

2. Click the Copy button.

3. For Copy Page Option, select one of the following:

- Page in this application

- Page in another application

4. Follow the on-screen instructions.

Running a Page or Application

The Application Express engine dynamically renders and processes pages based on data stored in database tables. To view a rendered version of your application, you run or submit it to the Application Express engine. As you create new pages, you can run them individually, or run an entire application. You can run an application by clicking the Run Application icon.

Topics in this section include:

- About the Run Application and Run Page Icons

- Running an Application from the Application Builder Home Page

- Running an Application from the Application Home Page

- Running a Page from the Page Definition

About the Run Application and Run Page Icons

The Run Application icon resembles a large traffic light and displays on the Application home page. Clicking the Run Application icon runs an entire application.

The Run Page icon resembles a small, light green traffic light and displays in the upper right corner of many pages within Application Builder. Clicking the Run Page icon runs the current page.

Running an Application from the Application Builder Home Page

To run an entire application from the Application Builder home page:

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

2. From the View list, select Details and click Go.

3. Locate the application in the Applications list.

4. Click the Run icon in the far right column.

Running an Application from the Application Home Page

To run an entire application from the Application home page:

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

2. Select on application.

3. Click the Run Application icon at the top of the page.

Running a Page on the Application Home Page

You can control how the Application home page displays by making a selection from the View list on the navigation bar at the top of the page. Selecting Details displays each page as a line in a report. Each line includes the page number, the page name, when the page was last updated, who last updated the page, a lock icon, and a Run icon.

To run a page from the Pages list:

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

2. Select an application.

3. From the View list, select Details and click Go.

4. From the Pages list, locate the page you want to run and click the Run icon in the far right column.

See Also:
"Locking and Unlocking a Page"

Running a Page from the Page Definition

To run a specific page from the Page Definition:

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

2. Select an application.

3. Select a page.
The Page Definition appears.

4. Click the Run Page icon in the upper right corner of the page.

Grouping Pages

You can make the pages within your application easier to access by organizing them into page groups. To use page groups, you create a group and then assign pages to the group.

Page groups do not have any function other than to help developers organize their application pages.

Topics in this section include:

- Viewing the Page Groups

- Creating a Page Group

- Assigning a Page to a Page Group

- Removing a Page from a Page Group

- Removing a Page Group

- Viewing the Pages by Page Group Report

Viewing the Page Groups

The section describes different ways to view page groups.

Accessing the Page Groups Page

To access the Page Groups page:

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

2. Select the application.

3. On the Tasks List on the right side of the page, click Page Groups.
The Page Groups page appears.

Use the Navigation bar at the top of the page to search for a page group by name or change the page display. You can change the default display by making a selection from View list. Available options include:

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

- Details displays each LOV as a line in a report. To edit an LOV, click the name.

4. To view the pages associated with a group, you can either:

- Click the group name.

- On the Tasks list, click Report Page Groups.

The Pages by Page Group report appears.

Note:
The Tasks list only appears if groups currently exist.

Viewing Page Groups from the Application Home Page

To view page groups from the Application home page:

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

2. On the Application Builder home page, select an application.

3. From the View list, select Page Groups and click Go.
Any defined groups appear. Pages not associated with a group are filed in the Unassigned folder.

4. To view or edit a page group, click the group name.
The following links display to the right of the page group name:

- View All Page Groups returns you to the previous view.

- Edit Page Group links you to the Page Groups page.

- Reassign Pages links to the Reassign Page Group page.

Viewing Page Groups from the Page Definition

To view page groups from the Page Definition:

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

2. From the View list, select Groups and click Go.

3. Take a selection from the Tasks list on the right side of the page.

Creating a Page Group

To create a page group:

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

2. Select an application.

3. On the Tasks List on the right side of the page, click Page Groups.

4. On the Page Groups page, click Create.

5. Enter a name, a description (optional), and click Create.

Editing a Page Group Definition

When you create page group you specify a name and description.

To edit the Page Group definition:

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

2. Select an application.

3. On the Tasks List on the right side of the page, click Page Groups.
Page Groups page appears.

4. On the Tasks List, click Edit Group Definition.

5. On the Page Groups page, edit the a name or a description and click Apply Changes.

6. To move to the next Page Group definition, click the Previous (<) and Next (>) buttons and repeat the previous step.

Assigning a Page to a Page Group

To assign pages to a group:

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

2. Select an application.

3. On the Tasks List on the right side of the page, click Page Groups.

4. On the Tasks list, click Report Unassigned Pages.
The Unassigned Pages report appears. Clicking a page number takes you to the Page Attributes page. Clicking the page Name links to the Page Definition.

5. From the Page Group list, select a group to which you want to assign pages and click Go.

6. Select the pages to be assigned and click Assigned Checked.

Reassigning a Page to a Another Page Group

To reassign a page to a page group:

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

2. Select an application.

3. On the Tasks List on the right side of the page, click Page Groups.

4. On the Tasks list, click Reassign Page Group.
The Reassign Pages page appears. Clicking the page number takes you to the Page Attributes page. Clicking the page Name links to the Page Definition.

5. From the Group list, select a group and click Go.

6. From Reassign Group, select a group to which you want to assign pages.

7. Select the pages to be reassigned and click Reassign Group.

Removing a Page from a Page Group

You remove a page from a page group on the Page Definition.

To remove a page to a page group:

1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition" or "Viewing the Pages by Page Group Report". In both page group reports, you can link to the Page Definition by clicking the page Name.
The Page Definition appears.

2. Under Name, locate the Group list and select - No Group Assigned -.

3. Click Apply Changes.

Removing a Page Group

To remove a page group:

1. Reassign all pages to another page group. See "Reassigning a Page to a Another Page Group".

2. On the Tasks List on the right side of the page, click Edit Group Definition.

3. Click Delete.
A confirmation page appears.

4. Confirm your request.

Viewing the Pages by Page Group Report

To view pages by page group:

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

2. Select an application.

3. On the Tasks List on the right side of the page, click Page Groups.

4. On the Tasks list, click Report Page Groups.
The Pages by Page Group report appears. Clicking the page number takes you to the Page Attributes page. Clicking the page Name links to the Page Definition.

5. To view a page group, make a selection from the Group list and click Go.

Locking and Unlocking a Page

You can prevent conflicts during application development by locking pages in your application. By locking a page, you prevent other developers from editing it.

Topics in this section include:

- Determining If a Page Is Locked

- Locking a Page

- Unlocking Pages

- Accessing Alternative Locked Pages Views

Determining If a Page Is Locked

A lock icon indicates whether a page is currently locked. If a page is unlocked, the icon appears as an open padlock. If the page is locked, the icon appears as a locked padlock. A lock icon appears on the Application home page and on the Page Definition.

To view the lock icon on the Application home page, select Details from the View list. A list of pages appears. The lock icon appears under the Lock column.

The lock icon also appears on the Action Bar on the Page Definition. See "About the Action Bar".

Locking a Page

You can lock pages from the Page Locks page, the Pages list, and from a Page Definition.

Locking a Page from the Page Locks Page

To lock a page from the Page Locks Page:

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

2. Select an application.

3. On the Tasks List on the right side of the page, click Page Locks.
The Page Locks page appears.

4. Select the appropriate pages and click Lock Checked.

5. Enter a comment in the Comment field.

6. Click Lock Page(s).

Locking a Page from the Details View

To lock a page from the Details view:

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

2. Select an application.

3. From the View list, select Details and click Go.

4. In the Pages list, locate the page you want to lock and click the Lock icon.

5. Enter a comment in the Comment field.

6. Click Lock Page(s).

Locking a Page from the Page Definition

To lock a page from the Page Definition:

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

2. Click the Lock icon in the Action bar. See "About the Action Bar".

3. Select the selected page and click Lock Checked.

4. Enter a comment in the Comment field.

5. Click Lock Page(s).

Unlocking Pages

Only the developer who locked a page can unlock it. However, a developer with administrative privileges can unlock pages locked by other developers.

Unlocking Pages from the Page Locks Page

To unlock a page from the Page Locks page:

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

2. Select the application.

3. On the Tasks List on the right side of the page, click Page Locks.
The Page Locks page appears.

4. Select the appropriate pages.

5. Click UnLock Checked.

Unlocking Pages from the from the Details View

To unlock a page from the Details view:

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

2. Select an application.

3. From the View list, select Details and click Go.

4. In the Pages list, locate the page you want to unlock and click the Lock icon.
The Edit Lock Comment page appears.

5. Click UnLock.

Unlocking Pages from the Page Definition

To unlock pages from the Page Definition:

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

2. Click the Lock icon in the upper right corner above Shared Components.
The Page Locks page appears.

3. Select the page you want to unlock and click Unlock Checked.

Accessing Alternative Locked Pages Views

You can access a number of different views of Locked Pages on the Locked Pages page.

To access different views of locked pages:

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

2. Select the application.

3. On the Tasks List on the right side of the page, click Page Locks.

4. On the Tasks list, click one of the following:

- Show Locked Pages displays only locked pages within the current application.

- Show All Pages displays all pages within the current application.

- Show Unlocked Pages displays only unlocked pages within the current application.

- Administer Locks enables an administrator to unlock any pages locked by a developer.

Deleting a Page

You can delete a page from the Page Definition or while editing page attributes.

Topics in this section include:

- Deleting a Page from the Page Definition

- Deleting a Page While Editing Page Attributes

Deleting a Page from the Page Definition

To delete a page from the Page Definition:

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

2. Verify the page name.

3. Click the Delete button at the top of the page.

4. Follow the on-screen instructions.

See Also:
"Editing a Page Definition" for information about editing page attributes

Deleting a Page While Editing Page Attributes

To delete a page while editing page attributes:

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

2. Under Page Rendering, locate the Page section.

3. Click the Edit page attributes icon to link to Page Attributes page. This icon resembles a small page with a pencil on top of it.

The Edit Page appears.

4. Verify the page number and page name.

5. Click Delete.

6. Follow the on-screen instructions.

Adding Application Comments

You can add comments concerning an entire application on the Application Comments page. You could add a description of the application or track the developers involved in working on the application.

Topics in this section include:

- Creating an Application Comment

- Viewing the Application Comments Report

See Also:
"Adding Developer Comments"

Creating an Application Comment

To create an application comment:

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. Under Application, click Application Comments.
The Application Comments page appears.

6. Enter comments in the Comments field and click Apply Changes.

Viewing the Application Comments Report

To view reports specific to an application:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.
The Application home page appears.

4. On the Tasks list, click Application Reports.

5. Click Application and then Application Comments.

Adding Developer Comments

You can add developer comments to an application, a page, or a group of pages using the Developer Comment icon. The Developer Comment icon resembles a green balloon. This icon displays on the Action bar.

You can use developer comments to communicate application changes, report issues, or record developer suggestions.

This section contains the following topics:

- Adding Developer Comments to an Application or Page

- Viewing and Editing Developer Comments

- Deleting Developer Comments

- About the Developer Comments Report

See Also:
"Adding Application Comments"

Adding Developer Comments to an Application or Page

The Developer Comment icon displays on any page in Application Builder that is related to a specific application or application page. You can add developer comments to an application, a page, or a group of pages.

To add a developer comment:

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

2. Select an application.

3. Click the Developer Comment icon.
The Create Comment page displays in a separate window.

4. In Relevant Page(s), specify the pages to which the comment applies. To enter a comment that:

- Applies to a specific page, enter the page number.

- Applies to multiple pages, enter a comma-delimited list of pages. For example:

1, 2, 3

- Does not apply to a page or group of pages, leave this field blank.

5. In Comment, enter up to 4000 characters of text.

6. Click Create or Create Another.

Viewing and Editing Developer Comments

To edit a developer comment:

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

2. Select an application.

3. Click the Developer Comment icon.
The Create Comment page displays in a separate window.

4. Click View Comments.
The View Comments page appears. See "About the Navigation Bar on the View Comments Page".

5. To edit a comment, click the Edit icon.
The Edit Comment page appears.

a. In Relevant Page(s), specify the pages to which the comment applies. To enter a comment that:

- Applies to a specific page, enter the page number.

- Applies to multiple pages, enter a comma-delimited list of pages. For example:

1, 2, 3

- Does not apply to a page or group of pages, leave this field blank.

b. In Comment, enter up to 4000 characters of text.

6. Click Apply Changes.

About the Navigation Bar on the View Comments Page

A navigation bar appears at the top of the View Comments page and contains the following controls:

- Page. Search for a page number. Enter a page number and click Go. To view all pages, leave the field blank and click Go.

- Comment. Search for comments. Enter a case insensitive query for comment text and click Go. To view all comments, leave the field blank and click Go.

- Developer. Limit the display to a specific developer. Select a developer to display and click Go.

- Display. Determines how comments display. To increase or decrease the number of comments that appear, make a selection from the Display list and click Go.

Deleting Developer Comments

You can delete developer comments on the Edit Comment page or on the Manage Comments page.

Topics in this section include:

- Deleting a Specific Developer Comment

- Deleting Multiple Developer Comments

Deleting a Specific Developer Comment

To delete a developer comment:

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

2. Select an application.

3. Click the Developer Comment icon.
The Create Comment page displays in a separate window.

4. Click View Comments.

5. Locate the comment to be deleted. See "About the Navigation Bar on the View Comments Page".

6. Click the Edit icon.
The Edit Comment page appears.

7. Click Delete.

Deleting Multiple Developer Comments

To delete multiple developer comments:

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

2. Select an application.

3. Click the Developer Comment icon.
The Create Comment page displays in a separate window.

4. Click Manage Comments.

5. Select one of the following actions:

- Delete all comments

- Delete comments created by a developer

- Delete comments by date

6. Follow the on-screen instructions.

About the Developer Comments Report

You can also view, edit, and manage developer comments from the Developer Comments report.

Topics in this section include:

- Accessing the Developer Comments Report

- Editing Comments from the Developer Comments Report

- Deleting a Comment from the Developer Comments Report

- Deleting Multiple Comments from the Developer Comments Report

- Downloading the Developer Comments Report

Accessing the Developer Comments Report

To access the Developer Comments report:

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

2. Select an application.

3. On the Application home page, click Application Reports on the Tasks list.

4. Click Shared Components

5. Under Application Reports, click Developer Comments.
The Developer Comments report appears.

About the Navigation Bar on the Developer Comments Report

A navigation bar appears at the top of the page and contains the following controls:

- Page. Search for a page number. Enter a page number and click Go. To view all pages, leave the field blank and click Go.

- Comment. Search for comments. Enter a case insensitive query of comment text and click Go. To view all, leave the field blank and click Go.

- Developer. Limit the display to a specific developer. Select a developer to display and click Go.

- Date. Limit the display to a specific date. Select a date and click Go.

- Display. Determine how comments display. To increase or decrease the number of comments that appear, make a selection from the Display list and click Go.

Editing Comments from the Developer Comments Report

To edit a comment from the Developer Comments report:

1. Navigate to the Developer Comments report. See "Accessing the Developer Comments Report".
The Developer Comments report appears.

2. Locate the comment to be edited. See "About the Navigation Bar on the Developer Comments Report".

3. Click the Edit icon.
The Edit Comment page displays in a separate window.

a. In Relevant Page(s), specify the pages to which the comment applies. To enter a comment that:

- Applies to a specific page, enter the page number.

- Applies to multiple pages, enter a comma-delimited list of pages, for example:

1, 2, 3

- Does not apply to a page or group of pages, leave this field blank.

b. In Comment, enter up to 4000 characters of text.

4. Click Apply Changes.

Deleting a Comment from the Developer Comments Report

To delete a comment from the Developer Comments report:

1. Navigate to the Developer Comments report. See "Accessing the Developer Comments Report".
The Developer Comments report appears.

2. Locate the comment to be deleted. See "About the Navigation Bar on the Developer Comments Report".

3. Click the Edit icon.
The Edit Comment page displays in a separate window.

4. Click Delete.

Deleting Multiple Comments from the Developer Comments Report

To delete multiple comments from the Developer Comments report:

1. Navigate to the Developer Comments report. See "Accessing the Developer Comments Report".
The Developer Comments report appears.

2. Locate the comment to be deleted. See "About the Navigation Bar on the Developer Comments Report".

3. Click the Edit icon.
The Edit Comment page displays in a separate window.

4. Click Manage Comments.

5. Select one of the following actions:

- Delete all comments

- Delete comments created by a developer

- Delete comments by date

6. Follow the on-screen instructions.

7. Click Apply Changes.

Downloading the Developer Comments Report

You can download the Developer Comments report as a comma-delimited file (.csv) file by clicking the Export link.

To download the Developer Comments report:

1. Navigate to the Developer Comments report. See "Accessing the Developer Comments Report".
The Developer Comments report appears.

2. Click the Export link at the bottom of the page.

3. Follow the on-screen instructions.

Creating Reports

In Oracle Application Express, a report is the formatted result of a SQL query. You can generate reports by selecting and running a built-in query, or by defining a report region based on a SQL query.

Topics in this section include:

- Creating a Report Using a Wizard

- Editing Report Attributes

- Altering Report Layout Using Column Attributes

- Controlling Report Pagination

- Enabling Column Sorting

- Adding a Download Link to a Report

- Exporting a Report as an XML Fileor a CSV File

- Creating a Column Link

- Defining an Updatable Column

- Defining a Column as a List of Values

- Controlling When Columns Display

- Controlling Column Breaks

- Printing Report Regions

Creating a Report Using a Wizard

Application Builder includes a number of built-in wizards for generating reports.

To create a report using a wizard:

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

2. Select the application.

3. Click Create Page.

4. Select Report.

5. Select a report type:

- Wizard Report - Creates a report without requiring any SQL knowledge. Select the appropriate schema, table, columns, and result set display.

- SQL Report - Creates a report based on a custom SQL SELECT statement or a PL/SQL function returning a SQL SELECT statement that you provide.

- Report on collection containing Web service result - Creates a report based on a Web service result.

6. Follow the on-screen instructions. To learn more about a specific field, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

See Tutorials:
"How to Create a Drill Down Report" and "How to Create a Parameterized Report" in Oracle Database Application Express Advanced Tutorials

Editing Report Attributes

You can use the Report Attributes page to precisely control report layout, pagination, column sorting, error messages, export links, and column breaks.

Topics in this section include:

- Accessing the Report Attributes Page

- About Navigation Alternatives

See Tutorials:
Oracle Database Application Express Advanced Tutorials

Accessing the Report Attributes Page

You can access the Report Attributes page by clicking the Report link next to the report region you want to edit on the Page Definition. You can also navigate to the Report Attributes page by clicking the region name and then selecting the Report Attributes tab.

To access the Report Attributes page:

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

2. Select the application.

3. Select a page.
The Page Definition appears.

4. Under Regions, click Report next to the name of the report region you want to edit.
The Report Attributes page appears and is divided into the following sections:

- Column Attributes control the report layout. See "Altering Report Layout Using Column Attributes".

- Layout and Pagination attributes control report pagination. See "Controlling Report Pagination".

- Sorting attributes enable you to define images and image attributes for images that display in report headings to sort values. See "Enabling Column Sorting".

- Messages contain attributes that enable you to define messages that display if no data is found or more data is found than can be displayed.

- Report Export attributes enable you to add download link to a report or export a report as either an XML file or CSV file. See "Adding a Download Link to a Report" and "Exporting a Report as an XML Fileor a CSV File".

- Break Formatting attributes enable you to control if a specific column repeats and how column breaks appear when printed. See "Controlling Column Breaks".

5. To learn more about a specific attribute, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

6. Click Apply Changes.

See Also:
"Creating a Column Link" and "Defining an Updatable Column", and "Defining a Column as a List of Values", and "Controlling When Columns Display"

About Navigation Alternatives

The Report Attribute page is divided into these sections: Column Attributes, Layout and Pagination, Sorting, Messages, Report Export, Break Formatting, and External Processing.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page.

When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Altering Report Layout Using Column Attributes

You can use the Column Attributes section of the Report Attributes page to precisely control the report layout. For example, you can use these attributes to alter column heading text, change column positioning, hide a column, create a sum of a column, or select a sort sequence.

To access the Column Attributes:

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

2. Select the application.

3. Select a page.
The Page Definition appears.

4. Under Regions, click Report next to the name of the report region you want to edit.
The Report Attributes page appears with the Column Attributes section at the top of the page.

Use the Column Attributes section to control report column appearance and functionality.

Heading Type identifies how the heading is generated for the report. The Link column indicates if a column link is currently defined. The Edit column indicates whether or not a column is currently updatable.

Table 5-2 describes common report column edits.

Table 5-2 Common Report Column Edits

Description

Developer Action

Alter column display sequence.

Click the up and down arrows to change the column display sequence.

Alter heading alignment.

Under Column Alignment, select a new column alignment.

Change column heading text.

Under Heading, enter different heading text.

Control which columns display.

Click Show to indicate a column should display.

Enable a unique sort sequence.

Click Sort and select a sequence number from Sort Sequence.

Any number of columns can be sort enabled. However, at least one column must have a Sort Sequence defined.

Enable the sum of a column.

Click Sum to enable the sum of a column.

You can further refine the attributes of a specific column on the Column Attributes page.

5. To access the Column Attributes page, click the Edit icon next to the appropriate column Alias.
To learn more about a specific attribute, click the item label.

When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

See Also:
"Creating a Column Link" and "Defining an Updatable Column", and "Defining a Column as a List of Values", and "Controlling When Columns Display"

Controlling Report Pagination

You control report pagination by:

- Including a pagination substitution string in the report template

- Making selections from the Layout and Pagination section on the Report Attributes page

You control how pagination displays by making selections from the Layout and Pagination attributes on the Report Attributes page.

Topics in this section include:

- Accessing and Understanding Layout and Pagination Attributes

- Including Pagination After the Rows in a Report

- Including Pagination Before the Rows in a Report

Accessing and Understanding Layout and Pagination Attributes

To access the Layout and Pagination section of the Report Attributes page:

1. Create a report. See "Creating a Report Using a Wizard".

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

3. Under Regions, click the appropriate Report attributes link.
The Report Attributes page appears.

4. Scroll down to Layout and Pagination.
You use the Layout and Pagination attributes to select a pagination style, determine where pagination occurs, and specify the number of rows that display on each page. Table 5-3 describes the most commonly used Layout and Pagination attributes.

To learn more about a specific attribute, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

Table 5-3 Layout and Pagination Attributes

Attribute

Description

Report Template

Specifies a template to be applied to this report. Report templates provide control over the results of a row from your SQL query. You can choose from a number of default templates, or pick a custom build template.

Show Null Values as

Enter the text you want to display for null columns. The default value is (null).

Pagination Scheme

Specifies a pagination scheme for this report.

Pagination provides the user with information about the number of rows and the current position within the result set. Pagination also defines the style of links or buttons used to navigate to the next or previous page.

For more information, see the Help information for this attribute.

Display Position

Defines where pagination occurs.

If you choose to display pagination above a report, the selected report template needs to support that type of display.

Number of Rows

Defines the maximum number of rows to display on each page.

Number of Rows (Item)

Defines the number of rows displayed by default per page for SQL queries (obtained dynamically from an item). Identify the item in this attribute.

Maximum Row Count

Defines the maximum number of rows to query, for example, rows 1 - 10 or 456.

If you set this attribute to 200, the result would appear as follows:

rows 1 - 10 of more than 200 rows

Note that this attribute impacts performance. Counting fewer rows can improve performance and counting thousands of rows can degrade performance.

Strip HTML

Specify whether or not to remove HTML tags from the original column values for HTML expressions, column links and report data exported as CSV files.

If you select values from the database that already contain HTML tags, then those tags can cause conflicts with the HTML generated for your columns links or HTML expressions. When this option is enabled, only the actual data portion of your column value is used.

Sort Nulls

For reports with column heading sorting, specify if you want null valued columns to sort first or last.

See Also: "Enabling Column Sorting"

Including Pagination After the Rows in a Report

To include pagination after the rows in a report:

1. Create a report. See "Creating a Report Using a Wizard".
Next, select the appropriate Layout and Pagination attributes.

2. Navigate to the Report Attributes page:

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

b. Under Regions, click the appropriate Report attributes link.
The Report Attributes page appears.

3. Under Layout and Pagination, select the following:

a. Report Template - Select a report template (optional).

b. Pagination Scheme - Select a pagination scheme.

c. Display Position - Select a display position.

d. Number of Rows - Specify how many rows display on each page.

e. Click Apply Changes.

4. Edit the report template:

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

b. Under Templates, select the report template name.

c. Include the #PAGINATION# substitution string in the After Rows attribute.

d. Click Apply Changes.

5. Run the page.

Including Pagination Before the Rows in a Report

To include pagination before the rows in a report:

1. Create a report. See "Creating a Report Using a Wizard".
Next, select the appropriate Layout and Pagination attributes.

2. Navigate to the Report Attributes page:

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

b. Under Regions, click the appropriate Report attributes link.
The Report Attributes page appears.

3. Under Layout and Pagination:

a. Report Template - Select a report template (optional).

b. Pagination Scheme - Select a pagination scheme.

c. Display Position - Select a position that contains the word top.

d. Number of Rows - Specify how many rows display on each page.

e. Click Apply Changes.

4. Edit the report template.

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

b. Under Templates, select the report template name.

c. Include the #TOP_PAGINATION# substitution string in the Before Rows attribute.

d. Click Apply Changes.

5. Run the page.

Enabling Column Sorting

You enable column sorting on the Report Attributes page.

To enable column sorting:

1. Navigate to the Report Attributes page. See "Editing Report Attributes".

2. Under Column Attributes, select the Sort check box next to the columns to be sorted.

3. From Sort Sequence, select a sequence number.
Sort Sequence is optional. However, if there are one or more sort enabled columns, then at least one column needs a defined Sort Sequence.

4. Scroll down to Sorting.

5. Specify ascending and descending image attributes or click set defaults.

Tip:
Note that column sorting must be enabled if you want columns with null values to display at the top or end of the report. To learn more about the Sort Nulls attribute, see "Accessing and Understanding Layout and Pagination Attributes".

Adding a Download Link to a Report

You can create a link within a report that enables users to export the report as a comma-delimited file (.csv) file. To add a CSV link to a report you need to enable the CSV output option. When using the CSV output option, the report template is not important. You can include a CSV link with any report template that has the CSV export substitution string defined.

See Also:
"Automatic CSV Encoding"

Enabling the CSV Output Option

To enable the Enable CSV output option:

1. Navigate to the appropriate Report Attributes page. See "Editing Report Attributes".

2. Scroll down to Report Export.

3. From Enable CSV output, select Yes.

4. (Optional) In the Separator and Enclosed By fields, define the separator and delimiter.
The default Enclosed By by characters are a double quotation marks (" "). The default delimiter is either a comma or a semicolon depending upon your current NLS settings.

5. In the Link Label field, enter link text. This text will display in your report and enable users to invoke a download.

6. (Optional) To specify a default export file name, enter a name in the Filename field.
By default, the Application Express engine creates an export file name by taking the region name and adding the appropriate file name extension (.csv or .xml).

7. Click Apply Changes.

Exporting a Report as an XML File or a CSV File

You can export a report as an XML file by selecting a report template.

To export a report as a file:

1. Navigate to the appropriate Report Attributes page. See "Editing Report Attributes".

2. Scroll down to Layout and Pagination.

3. From the Report Template list, select export: XML or export: CSV.
Selecting export: XML prevents the Application Express engine from rendering the page and dumps the content to an XML file.

4. Click Apply Changes.

Creating a Column Link

Use the Column Link attributes to create a link from a report to another page in your application or to a URL.

To create a column link to another page:

1. Navigate to the appropriate Report Attributes page. See "Editing Report Attributes".

2. Under Column Attributes, locate the column to contain the link.

3. Click the Edit icon next to the column name.
The Column Attributes page appears.

4. Scroll down to Column Link.

5. To create a column link to another page:

a. From Target, select Page in this Application.

b. (Optional) In Link Attributes, specify additional column link attributes that will be included in the <a href= > tag (for example, a link target, classes, or styles).

c. In Link Text, enter the text to be displayed as a link, specify an image tag, or pick from the list of default images.

d. In Page, specify the target page number. To reset the pagination for this page, select Reset Pagination.

e. In Request, specify the request to be used.

f. In Clear Cache, specify the pages (that is, the page numbers) on which to clear cache. You can specify multiple pages by listing the page numbers in a comma-delimited list.

g. Use the Name and Value fields to specify session state for a specific item.

6. Click Apply Changes.

To create a column link to a URL:

1. Navigate to the appropriate Report Attributes page. See "Editing Report Attributes".

2. Access the Column Attributes page by clicking the Edit icon next to the appropriate column.
The Column Attributes page appears.

3. Scroll down to Column Link.

4. Under Column Link, specify the following:

a. From Target Type, select URL.

b. In Link Text, enter the text to be displayed as a link and select a substitution string.

c. (Optional) In Link Attributes, specify additional column link attributes that will be included in the <a href= > tag (for example, a link target, classes, or styles).

d. In URL, enter the appropriate address.

5. Click Apply Changes.

Defining an Updatable Column

You can make a column updatable by editing Tabular Form Element attributes on the Column Attributes page. Note that the Application Express engine can only perform updates if:

- A multirow update is defined

- A PL/SQL process is implemented to process updated data

- When using the built-in tabular form elements and display types, then the report has to be defined using the type SQL Query (updatable report)

To define updatable column attributes:

1. Navigate to the appropriate Report Attributes page. See "Editing Report Attributes".

2. Access the Column Attributes page by clicking the Edit icon next to the appropriate column.
The Column Attributes page appears.

3. Scroll down to Tabular Form Element.

4. Under Tabular Form Element, specify the following:

a. Display As - Select a type of updatable column.
Use this option to make a column updatable. Updates can only be performed if a multirow update is defined, or a PL/SQL process is implemented to process updated data.

b. Date Picker Format Mask - Make a selection if you selected the Display As type of Date Picker.

c. Element Width - Specify the width of the form item.

d. Number of Rows - Specify the height of a form item (applicable to text areas).

e. Element Attributes - Define a style or standard form element attribute.

f. Element Option Attributes - Specify form element attributes for items in a radio group or check box.

g. Primary Key Source Type - Identify the default type.

h. Primary Key Source - Identify the default source.
If the current column is part of the primary key defined in an MRU process, only the primary key source type and source appear.

Otherwise, Default and Default Type appear. Use Default and Default Type to establish a relationship between two master records in a master detail form, or to set the default values for new rows.

i. Reference Table Owner - Identify the owner of the referenced table. Use this attribute to build User Interface Defaults for reports.

j. Reference Table Name - Identify the table or view that contains the current report column.

k. Reference Column Name - Identify the column name that this report column references.

5. Click Apply Changes.

Defining a Column as a List of Values

Report columns can be rendered as lists of values. For example, a column can be rendered using a select list or a popup list of values. Or, a column can be rendered as read-only text based on a list of values.

This last approach is an effective strategy when creating display lookup values and is particularly useful in regular, nonupdatable reports. This approach enables you to display the value of a column without having to write a SQL JOIN statement.

To render a report column as a list of values:

1. Navigate to the appropriate Report Attributes page. See "Editing Report Attributes".

2. Access the Column Attributes page by clicking the Edit icon next to the appropriate column.
The Column Attributes page appears.

3. Scroll down to List of Values.

4. From Named LOV, make a selection from the List of Values repository. See "Creating Lists of Values".

5. To include a null value in a list of values:

a. In Display Null, select Yes.

b. In Null Text, specify the value that displays.

A column can also have a value that does not display in its list of values.

6. To define a value that does not display in the list of values:

a. From Display Extra Value, select Yes.
The extra value is used if the actual column value is not part of the LOV. In that situation, the actual value is shown. If you do not display extra values, you may end up with the wrong value and unintentionally update your data incorrectly.

b. In Null Value, specify the value that displays.

c. If you have not selected a Named LOV, enter the query used to display a select list in the LOV Query field.

7. If you have not selected a Named LOV, enter the query used to display a select list in LOV Query.

8. Click Apply Changes.

See Tutorials:
"How to Create a Tabular Form" in Oracle Database Application Express Advanced Tutorials

Controlling When Columns Display

You can use the Authorization and Condition attributes to control when a column displays.

Authorization enables you to control access to resources (such as a report column) based on predefined user privileges. For example, you could create an authorization scheme in which only managers can view a specific report column. Before you can select an authorization scheme, you must first create it.

A condition is a small unit of logic that enables you to control the display of a column based on a predefined condition type. The condition evaluates to true or false based on the values you enter in the Expressions fields.

To specify Authorization and Condition attributes:

1. Navigate to the appropriate Report Attributes page. See "Editing Report Attributes".

2. Access the Column Attributes page by clicking the Edit icon next to the appropriate column.
The Column Attributes page appears.

3. Under Authorization, make a selection from the Authorization Scheme list.

4. Under Conditions, make a selection from the Condition Type list, and depending upon your selection, enter an expression or value in the appropriate Expression fields.
If the authorization is successful and the condition type display evaluates to true, the column displays.

See Also:
"Providing Security Through Authorization", "Understanding Conditional Rendering and Processing", and Appendix A, "Available Conditions"

Controlling Column Breaks

You can control if a specific column repeats and how column breaks appear when printed using Break Formatting attributes. For example, suppose your report displays employee information by department number. If multiple employees are members of the same department, you can increase the readability by specifying the department number only appears once.

To create this type of column break:

1. Navigate to the appropriate Report Attributes page. See "Editing Report Attributes".

2. Scroll down to Break Formatting.

3. Make a selection from the Breaks list.

Printing Report Regions

You can configure a report region to print by exporting it to a PDF, RTF (rich text format), or XLS format. By taking advantage of region report printing, your application users can view and print reports that have a predefined orientation, page size, column headings, and page header and footer.

Topics in this section include:

- About Printing Reports to PDF

- About Report Printing Configuration Options

- About Report Printing Methods

- About Report Queries

- About Report Layouts

- Overview of Printing Report Regions

- Configuring Report Region Print Attributes

Tip:
If you are running Oracle Application Express with Oracle Database 11g Release 1 (11.1), you must enable network services in order to use report printing. See "Enabling Network Services in Oracle Database 11g"

See Also:
"How to Create a Master Detail PDF Report" in Oracle Database Application Express Advanced Tutorials

About Printing Reports to PDF

When printing to a PDF, the report data is transformed using an externally defined report server. When the application end user clicks a print link, a request is sent to the Application Express engine. The Application Express engine then generates the report data in XML format and report template in XSL-FO or RTF format. The external reporting engine then transforms the data and the template into a PDF which displays to the end user using the convert servlet that ships with BI Publisher 10.1.3.2 (formerly known as Oracle XML Publisher). Fortunately, this architectural complexity is transparent to both end users and developers. End users just click a print link, and developers just declaratively set regions to support PDF printing.

About Report Printing Configuration Options

Your report server can be Oracle BI Publisher or another standard XSL-FO processing engine. Oracle BI Publisher provides a higher level of functionality. To accommodate the difference in functionality, Oracle Application Express provides two report printing configuration options:

- Standard Support. Enables you to print report regions and report queries using either the built-in templates (provided with a standard XSL-FO processing engine), or other XSL-FO compatible formats you provide. This setting does not support RTF.

Standard Support provides declarative formatting of report regions and report queries with basic control over page attributes, including page orientation, page size, column heading formats, page header, and page footer.

- Advanced Support. Requires a valid license of Oracle BI Publisher (also known as Oracle XML Publisher). This setting, provides you with all the capabilities of the Standard configuration plus the ability to define RTF-based report layouts developed using the BI Publisher Word Template Builder.

To learn more about installing and configuring Oracle BI Publisher, see PDF Printing in Application Express 3.0.

Note:
To use the full functionality of report printing, your Oracle Application Express service administrator must enable it for your site. See "Configuring Report Printing".

About Report Printing Methods

There are two ways to print report regions:

- Configure Printing Attributes for a Report Region. You can print a report region by configuring the Printing Attributes for the region. See "Configuring Report Region Print Attributes".

- Create a Report Query. You can print a report by defining a report query as a Shared Component. See "About Report Queries".

Both report regions and report queries can be downloaded in the following formats:

- PDF

- RTF - Compatible with Microsoft Word.

- XLS - Compatible with Microsoft Excel. Note that this is not a true .xls file because the content is HTML-based.

- HTML

To format either a report region or report query, you associate it with a report layout. To learn more, see "About Report Layouts".

About Report Queries

You can print a report region by defining a report query as a Shared Component. Unlike SQL statements contained in regions, report queries are standalone SQL statements that are validated when you save the query. Note that report queries must be SQL statements, not functions returning SQL statements.

You can associate a report query with a report layout and download it as a formatted document. The reports can include session state of the current application.

To make these reports available to end users, you then integrate them with an application. For example, you can associate a report query with a button, list item, branch, or other navigational component that allows you to use URLs as targets. Selecting that item then initiates the printing process.

Creating a Report Query

Note that the availability of the report query options depends on how your service administrator configures report printing for your instance. All options described in these steps may not be available to you.

See Also:
"About Report Printing Configuration Options"

To create a report query:

1. Navigate to the Shared Components page. See "Accessing the Shared Components Page".

2. Under Reports, click Report Queries.

3. Click Create.

4. For Query, specify the following information:

a. Name - Enter a name for your report query.
This name will be part of the request string in the URL used to download the report query.

b. SQL Query - Enter a SQL statement directly or click Query Builder to build a SQL statement by clicking and pointing.
To reference applications and page items in the SQL statement, reference them as bind variables.

c. Click Next.

5. To test the query, click Test Query. Testing the report query ensures that the desired result set is returned.
If you include bind variables, you are able to set test values before running the query. The test values are then used in subsequent steps in this wizard, when exporting the XML structure of your report query and to download a formatted test version of your report query.

6. After you test the query, click Next.

7. (Optional) For Include Session State, specify the following:

a. To include a session state, click the up arrow and select an item from the list.
Use a session state item to show additional data along with your report. For example, select an item to display a customer address to display that information on an order form. The order header information is shown along with order details.

b. Click Add to move the item to the box.

c. Click Next.

8. For Download XML, follow the on-screen instructions.

9. For Confirm:

a. Query Name - Identifies the query.

b. Report Layout - Identifies the report layout you selected.

c. Output Format - Select the format for this report query.

d. (Optional) Item - Select the item to hold the format information.

e. URL - To integrate this report with your application, use the displayed URL as the target for a button, list item, link, or other navigational component. This enables end users to click a button, for example, to start the printing process.

f. Test Report - Click this to preview your report.

g. Click Finish.
The Report Query is created and saved to Shared Components.

Editing Report Queries

To edit a report query:

1. Navigate to the Shared Components page. See "Accessing the Shared Components Page".

2. Under Reports, click Report Queries.

3. On the Report Queries page, you can use the Navigation bar at the top of the page to search for a query by name or change the page display. For example, you can change the default display by making a selection from View list. Available options include:

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

- Details displays each query as a line in a report. To edit a query, click the name.

4. Edit the information.

5. To export the report as XML, click the link in the Tasks list.

6. Click Apply Changes.

Copying a Report Queries

To copy a report query:

1. Navigate to the Shared Components page. See "Accessing the Shared Components Page".

2. Under Reports, click Report Queries.

3. On the Report Queries page, click Copy.

4. On the Copy Report Query, select the query you want to copy, enter a new name for the copy, and click Copy.
The new copy appears in the query list.

About Report Layouts

To format either a report region or report query, you associate it with a report layout. Using report layouts renders the data in a printer-friendly format. If you do not select a report layout, a default XSL-FO layout is used.

When creating and using report layouts, you can:

- Take advantage of the default layouts for report regions and generic layouts for report queries provided with Application Express.

- Utilize the built-in XSL-FO-based layouts for report regions by copying and customizing the code. You can edit a number of attributes for report regions that control page size, fonts, colors, and so on.

- Create RTF or XSL-FO report layouts to customize the report look and feel. To use RTF report layouts, your Oracle Application Express service administrator must select the Advanced setting for your site. ee "Configuring Report Printing".

About Report Layout Options

You can create a new report layout based on one of these options:

- Generic Columns - A generic report layout works with most query result sets. With this layout, the number of columns is automatically adjusted when generating the printable document.

A number of report layout attributes can be defined declaratively for report regions using the built-in XSL-FO default layout. This step allows for creating customizable copies of the built-in default XSL-FO layout, if additional control over the report layout is needed.

- Named Columns - A named column report layout is a query-specific report layout designed to work with a defined list of columns in the query result set. This type of layout is used for custom-designed layouts when precise control of the positioning of page items and query columns is required.

Note that the availability of the Report Layout options depends on how your service administrator configured the report printing settings at your site. All options described in these steps may not be available to you.

Creating a Report Layout

To create a report layout:

1. Navigate to the Shared Components page. See "Accessing the Shared Components Page".

2. Under Reports, click Report Layouts.

3. Click Create.
The Create Report Layout wizard appears.

4. For Layout Type, select an option and click Next:

- Generic Columns (XSL-FO) - This layout is pre-populated with a default template, which you can edit to fit your needs.

- Named Columns (RTF) - This layout is uploaded as an RTF file.

- Named Columns (XSL-FO) - This layout is uploaded as an XSL-FO file.

5. For Layout Source, review and edit the appropriate information. The options that appear on this page depend on the layout type you select:

- If you selected Generic Columns:

a. Report Layout Name - Enter a name to identify the report layout when associating it with a report query or report region.

b. Report Layout - The report layout is the XSL-FO based definition of the page formatting. All attributes defining page size, orientation, fonts, styles, and so on, are defined in this section.
To see a list of valid substitution strings and other information, click the item label, Report Layout. This opens a separate Help window.

c. Report Column Heading - Defines the look of each cell in the report heading row.

d. Report Column - Defines the look of each cell for all report rows.

e. Report Column Width - This width is computed at runtime time or can be derived from the report column definition of a report region.

- If you selected Named Columns:

a. Report Layout Name - Enter a name to identify the report layout when associating it with a report query or report region.

b. Upload the file containing the report layout.

Editing Report Layouts

You can edit a generic column report layout directly in Application Express. However, to edit a named column report layout, you need to download the current file, edit it, and then upload it again.

To edit a report layout:

1. Navigate to the Shared Components page. See "Accessing the Shared Components Page".

2. Under Reports, click Report Layouts.

3. On the Report Layouts page, select the layout you want to edit.

4. For generic column layouts, edit the layout directly on the Edit Report Layout. Then click Apply Changes.

5. For named column layouts, click Download and save the file to your computer.
Edit the file and then upload the updated version as a new report layout.

Copying Report Layouts

You can copy a report layout to edit and save.

To copy a report layout:

1. Navigate to the Shared Components page. See "Accessing the Shared Components Page".

2. Under Reports, click Report Layouts.

3. On the Report Layouts page, click Copy.

4. On the Copy Report Layout page, select the layout you want to copy, enter a new name for the copy, and click Copy.
The new copy appears in the layout list.

Overview of Printing Report Regions

To download or print report regions in the supported formats, you need to:

1. Select the page containing the report region you want to set up.

2. Create or select a region of type Report.
A report query, based on a standard SQL query whose results appear in your report, must be associated with this region.

3. Enable report printing for that region.
You must select this option. For the remaining steps in this task, you can accept the defaults or select different options.

4. Select an output format.

5. Associate a report layout with the report region.
The default report layout includes a Print link that appears under the report. You can replace that with your own custom button.

6. Set up other printing attributes, such as the paper size, orientation, header and footer.
If you use the default report layout, the end users click the Print link to initiate the print process.

Configuring Report Region Print Attributes

One approach to printing a report region is to configure Print Attributes. Once configured, these attributes only apply only to current region and cannot be used outside the context of the region.

If the printing feature is set up for your instance, you can configure a report region to print in various formats.

See Also:
T "About Report Printing Methods" and "Configuring Report Printing"

To configure a report region for printing:

1. In your application, select the page containing the report region you want to print.
The Page Definition appears.

2. Under Regions, click Report next to the region you want to print.

3. Click the Print Attributes tab.

4. Under Printing, specify the appropriate information:

- Enable Report Printing - Select Yes.

- Link Label - Enter the text for the link that starts the printing process.

- (Optional) File Name - Enter a name for the downloaded file. If you leave this blank, the region name is used as the file name.

- Output Format - Select an output option.

- Item - If you select Derive from Page Item, select the item.

- Report Layout - Select Default Report Layout or an available report layout you or your administrator created.

5. In the remaining sections, define page size, paper orientation, page headers and footers, fonts, text color, and background color.

6. Click Apply Changes.

If you used the default template, end users can click a Print link to print the report in the format you specified for this region.

Creating Forms

You can include a variety of different types of forms in your applications. You can include forms that enable users to update just a single row in a table or multiple rows at once. Application Builder includes a number of wizards you can use to create forms automatically, or you can create forms manually.

Topics in this section include:

- Creating a Form Using a Wizard

- Creating a Tabular Form

- Creating a Master Detail Form

- Creating a Form Manually

- Validating User Input in Forms

Creating a Form Using a Wizard

The easiest way to create a form is to use a wizard. For example, the Form on Table or View Wizard creates one item for each column in a table. It also includes the necessary buttons and processes required to insert, update, and delete rows from the table using a primary key. Each region has a defined name and display position; all other attributes are items, buttons, processes, and branches.

To create a form using a wizard:

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

2. Select an application.

3. Click Create Page.

4. Select Form and click Next.

5. Under Forms, select a type of form page as described in Table 5-4.

Table 5-4 Forms Page Types

Form Page Type

Description

Form on a Procedure

Builds a form based on stored procedure arguments. Use this approach when you have implemented logic or data manipulation language (DML) in a stored procedure or package.

Form on a Table or View

Creates a form that enables users to update a single row in a database table.

Form on a Table with Report

Creates two pages. One page displays a report. Each row provides a link to the second page to enable users to update each record.

Note: This wizard does not support tables having more than 127 columns. Selecting more than 127 columns generates an error.

Master Detail Form

Creates a form that displays a master row and multiple detail rows within a single HTML form. With this form, users can query, insert, update, and delete values from two tables or views.

See Also: "Creating a Master Detail Form"

Tabular Form

Creates a form in which users can update multiple rows in a database.

See Also: "Creating a Tabular Form"

Form on Web Service

Creates a page with items based on a Web service definition. This wizard creates a user input form, a process to call the Web service, and a submit button.

See Also: "Creating a Form on a Web Service"

Form and Report on Web Service

Creates a page with items based on a Web service definition. This wizard creates a user input form, a process to call the Web service, a submit button, and displays the results returned in a report.

See Also: "Creating an Input Form and Report on a Web Service"

Summary Page

Creates a read-only version of a form. Typically used to provide a confirmation page at the end of a wizard.

Form on a SQL Query

Creates a form based on the columns returned by a SQL query such as an EQUIJOIN.

6. Follow the on-screen instructions. To learn more about a specific field, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

Creating a Tabular Form

A tabular form enables users to update multiple rows in a table. The Tabular Form Wizard creates a form to perform update, insert, and delete operations on multiple rows in a database table.

To create a tabular form:

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

2. Select an application.

3. Click Create Page.

4. Select Form and click Next.

5. Select Tabular Form and click Next.
The Tabular Form Wizard appears.

6. For Table/View Owner:

a. Specify the table or view owner on which you want to base your tabular form.

b. Select the operations to be performed on the table (for example, Update, Insert and Delete).

c. Click Next.

7. For Table/View Name, select a table and click Next.

8. For Displayed Columns:

a. Select the columns (updatable and nonupdatable) to include in the form.
Note that you can modify the column order or your SQL query after you create the page.

b. Click Next.

9. For Primary Key, select the Primary Key column and a secondary Primary Key column (if applicable) and click Next.

10. For Primary Key Source, select a source type for the primary key column and click Next. Valid options include:

- Existing trigger - Select this option if a trigger is already defined for the table. You can also select this option if you plan on specifying the primary key column source later after completing the form.

- Custom PL/SQL function - Select this option if you wish to provide a PL/SQL function to generate returning key value.

- Existing sequence - Select this option if you wish to pick the sequence from a list of sequences available in the selected schema.

11. On Updatable Columns, select which columns should be updatable and click Next.

12. On Page and Region Attributes:

a. Specify page and region information.

b. Select a region template.

c. Select a report template.

d. Click Next.

13. On Tab, specify a tab implementation for this page and click Next.

14. On Button Labels, enter the display text to appear for each button and click Next.

15. On Branching, specify the pages to branch to after the user clicks the Submit and Cancel buttons and click Next.

16. Click Finish.

Note:
Any modification of the select list of a SQL statement of a tabular form after it has been generated is not recommended. If you do modify the query, make sure the values of the updateable columns are not altered after being queried from the database by the Application Express engine.

See Also:
"Managing User Interface Defaults"

See Tutorial:
""How to Create a Tabular Form" in Oracle Database Application Express Advanced Tutorials

Creating a Master Detail Form

A master detail form reflects a one-to-many relationship between two tables in a database. Typically, a master detail form displays a master row and multiple detail rows within a single HTML form. With this form, users can insert, update, and delete values from two tables or views.

To create a master detail form:

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

2. Select an application.

3. Click Create Page.

4. Select Form and click Next.

5. Select Master Detail Form and click Next.
The Master Detail Wizard appears.

6. On Master Table:

a. Select a table or view owner.

b. Select a table or view name.
The columns in that object appear under Available Columns.

c. Select the columns to display in the form and then click the arrow keys to move them to Displayed Columns.

d. Click Next.

7. On Detail Table:

a. Specify whether to show only related tables by selecting Yes or No.

b. Select the table or view owner.

c. Select a table or view name.
The columns in that object appear under Available Columns.

d. Select the columns to display in the form and then click the arrow keys to move them to Displayed Columns.

e. Click Next.

8. On Primary Key Source, select the primary key column for the master table, and then select the primary key column for the detail table. Options include:

- Existing trigger - Select this option if a trigger is already defined to populate the primary key.

- Custom PL/SQL function - Select this option if you wish to provide a PL/SQL function to populate the primary key.

- Existing sequence - Select this option if there is already an existing sequence you want the wizard to create the necessary trigger.

9. On Master Options, specify whether or not to include master row navigation and click Next.
If you include master row navigation, define navigation order columns. If a navigation order column is not defined, the master update form navigates by the primary key column.

10. On Choose Layout, specify the layout of the master detail pages and click Next.
You can include the master detail as a tabular form on the same page, or add the master detail on a separate page.

11. On Page Attributes, review and edit the master page and detail page information and then click Next.

12. On Tab, specify whether or not to include a tab set and click Next.

13. Click Create.

Creating a Form Manually

You can also create a form manually by performing the following steps:

- Create an HTML region (to serve as a container for your page items)

- Create items to display in the region

- Create processes and branches

To create a form manually by creating and HTML region:

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

2. Create an HTML region:

a. Under Regions, click the Create icon.

b. Select the region type HTML.

c. Follow the on-screen instructions.

3. Start adding items to the page:

- Under Items, click the Create icon.

- Follow the on-screen instructions.

Processing a Form

Once you create a form, the next step is to process the data a user types by inserting into or updating the underlying database tables or views. There are three ways to process a form:

- Creating an Automatic Row (DML) Processing Process

- Creating a Process that Contains One or More Insert Statements

- Using a PL/SQL API to Process Form Values

Creating an Automatic Row (DML) Processing Process

One common way to implement a form is to manually create an Automatic Row Processing (DML) process. This approach offers three advantages. First, you are not required to provide any SQL coding. Second, Oracle Application Express performs DML processing for you. Third, this process automatically performs lost update detection. Lost update detection ensures data integrity in applications where data can be accessed concurrently.

To implement this approach you need to:

- Add items, define the Item Source Type as Database Column, and specify a case-sensitive column name.

- Select the option Always overrides the cache value.

To create an Automatic Row Processing (DML) process:

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

2. Under Processes, click the Create icon.

3. Select the process Data Manipulation.

4. Select the process category Automatic Row Processing (DML).

5. Specify the following process attributes:

a. In the Name field, enter a name to identify the process.

b. In the Sequence field, specify a sequence number.

c. From the Point list, select the appropriate processing point. In most instances, select Onload - After Header.

d. From the Type list, select Automated Row Processing (DML).

6. Follow the on-screen instructions.

Creating a Process that Contains One or More Insert Statements

In this approach to form handling, you create one or more processes to handle insert, update, and delete actions. Instead of having the Application Express engine handling everything transparently, you are in complete control.

For example, suppose you have a form with three items:

- P1_ID - A hidden item to store the primary key of the currently displayed row in a table.

- P1_FIRST_NAME - A text field for user input.

- P1_LAST_NAME - A text field for user input.

Assume also there are three buttons labeled Insert, Update, and Delete. Also assume you have a table T that contains the columns id, first_name, and last_name. The table has a trigger that automatically populates the ID column when there is no value supplied.

To process the insertion of a new row, you create a conditional process of type PL/SQL that executes when the user clicks the Insert button. For example:

BEGIN
INSERT INTO T ( first_name, last_name )
VALUES  (:P1_FIRST_NAME, :P1_LAST_NAME);
END;

To process the updating of a row, you create another conditional process of type PL/SQL. For example:

BEGIN
UPDATE T
SET first_name = :P1_FIRST_NAME,
last_name = :P1_LAST_NAME
WHERE ID = :P1_ID;
END;

To process the deletion of a row, you create a conditional process that executes when the user clicks the Delete button. For example:

BEGIN
DELETE FROM T
WHERE ID = :P1_ID;
END;

Using a PL/SQL API to Process Form Values

For certain types of applications, it is appropriate to centralize all access to tables in a single or a few PL/SQL packages. If you created a package to handle DML operations, you can call procedures and functions within this package from an After Submit PL/SQL process to process insert, updates, and delete requests.

Populating Forms

Oracle Application Express populates a form either on load or when the Application Express engine renders the page. You can populate a form in the following ways:

- Create a process and define the type as Automated Row Fetch.

- Populate the form manually by referencing a hidden session state item.

To create an Automated Row Fetch process:

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

2. Under Processes, click Create.

3. Select the process type Data Manipulation.

4. Select the process category Automatic Row Fetch.

5. Specify the following process attributes:

a. In the Name field, enter a name to identify the process.

b. In the Sequence field, specify a sequence number.

c. From the Point list, select the appropriate processing point.

d. From the Type list, select Automated Row Fetch.

6. Follow the on-screen instructions.

You can also populate a form manually by referencing a hidden session state item. For example, the following code in an Oracle Application Express process of type PL/SQL would set the values of ename and sal. The example also demonstrates how to manually populate a form by referencing a hidden session state item named P2_ID.

FOR C1 in (SELECT ename, sal
FROM emp WHERE ID=:P2_ID)
LOOP
:P2_ENAME := C1.ename;
:P2_SAL := C1.sal;
END LOOP;

In this example:

- C1 is an implicit cursor.

- The value of P2_ID has already been set.

- The process point for this process would be set to execute (or fire) on or before Onload - Before Regions.

Validating User Input in Forms

You can use validations to check data a user enters before processing. Once you create a validation and the associated error message, you can associate it with a specific item. 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.

Creating an inline error message involves these steps:

- Create a new validation and specify error message text.

- Associate the validation with a specific item.

Creating a Validation

To create a new validation:

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

2. Under Validations, click the Create icon.

3. When the Create Validations Wizard appears, follow the on-screen instructions.
Validation Types are divided into two categories:

- Item. These validations start with the term Item and provide common checks you may want to perform on the item with which the validation is associated.

- Code. These validations require that you provide either a piece of PL/SQL code or SQL query that defines the validation logic. Use this type of validation to perform custom validations that require verifying values of more than one item or accessing additional database tables.

4. Follow the on-screen instructions.

Note:
Validations cannot contain more than 3,950 characters.

Associating a Validation with a Specific Item

To associate an item with a validation and specify error message text:

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

2. Under Validations, select the validation item you want to associate.
The attributes page for the validation appears.

3. Scroll down to Error Message:

- In Error message display location, verify the display location.

- In Associated Item, select the item you want to associate with this validation.

4. Click Apply Changes.

About Error Message

Error message display location 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 processes, including any remaining validations, you must display the error on an error page.

Creating Calendars

Application Builder includes a built-in wizard for generating a calendar with monthly, weekly, and daily views. Once you specify the table on which the calendar is based, you can create drill-down links to information stored in specific columns. Note that Oracle Application Express supports the creation of only one calendar per page.

Topics in this section include:

- About Creating Calendars

- Creating a New Calendar

- Editing a Calendar Title

- Editing Calendar Attributes

- Converting an Easy Calendar to a SQL Calendar

- Upgrading a Calendar Created in a Previous Releases

About Creating Calendars

Application Builder supports two calendar types:

- Easy Calendar creates a calendar based on schema, table, and columns you specify. The wizard prompts you to select a date column and display column.

- SQL Calendar creates a calendar based on a SQL query you provide. The SQL SELECT statement you provide must include at least two columns: a date column and display column.

See Also:
"Calendar Display"

Supported Calendar Substitution Strings

Application Builder supports a number of date format substitution strings. You can view a complete list of supported substitution strings on the Calendar Templates page.

To view a list of supported substitution strings for calendars:

1. Navigate to the appropriate calendar template.

2. View the Substitution Stings list on the right side of the page.

See Also:
"Editing Templates"

Creating a New Calendar

How you create a calendar depends on if you are adding a calendar to an existing page or adding a calendar on a new page. When creating calendars remember:

- You can only create one calendar for each page. The calendar includes daily, weekly, and monthly views.

- The date column determines which days on the calendar will contain entries.

- The display column defines a specific row that will display a calendar date.

Topics in this section include:

- Adding a Calendar to an Existing Page

- Adding a Calendar to a New Page

Adding a Calendar to an Existing Page

Oracle Application Express supports the creation of one calendar per page.

To add a calendar to an existing page:

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

2. Under Regions, click the Create icon.
The Create Region Wizard appears.

3. Select Calendar and click Next.

4. Select the type of calendar you want to create and click Next:

- Easy Calendar creates a calendar based on the date column and display column you specify.

- SQL Calendar creates a calendar based on a SQL query you provide.

5. Follow the on-screen instructions.

Adding a Calendar to a New Page

To create a calendar on a new page:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. Click Create Page.

5. Select Calendar and click Next.

6. Select the type of calendar you want to create and click Next:

- Easy Calendar creates a calendar based on the date column and display column you specify.

- SQL Calendar creates a calendar based on a SQL query you provide.

7. Follow the on-screen instructions.

See Also:
"Editing Calendar Attributes"

Editing a Calendar Title

The title that appears at the top of calendar corresponds to the region title.

To alter the region title:

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

2. Under Regions, select the region name.
The Region Definition appears.

3. Under Identification, enter a new title.

4. Click Apply Changes.

Editing Calendar Attributes

Once you create a calendar, you can alter the display by editing attributes on the Calendar Attributes page.

Note that if you want to disable a view of a calendar, you need to delete the Monthly, Weekly, or Daily buttons on the calendar page.

Topics in this section include:

- Accessing the Calendar Attributes Page

- About the Calendar Attributes Page

Accessing the Calendar Attributes Page

To access the Calendar Attributes page:

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

2. Under Regions, click Calendar next to the region name.
The Calendar Attributes page appears.

3. Edit the appropriate attributes. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark.

4. Click Apply Changes.

See Also:
"About the Calendar Attributes Page" and "About Field-Level Help"

About Navigation Alternatives

The Calendar Attribute page is divided into sections.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

About the Calendar Attributes Page

The topics that follow describe specific sections of the Calendar Attributes page. You can use these attribute to specify general calendar formatting, define the dates included in the calendar, or create a link on the column or a day in the calendar.

Calendar Display

Use Calendar Display to specify a calendar template, date columns, and general calendar formatting.

Calendar Template determines what template is used when the Application Express engine renders a calendar. Date Column defines the column from the table or query containing the dates to be placed on the calendar. Display Column defines a specific row that displays on a calendar date.

To select another Display Column:

1. Navigate to the appropriate Calendar Attributes page.

2. Locate the Calendar Display section.

3. To specify another display column, make a selection from the Display Column list.

4. Click Apply Changes.

To specify a custom Display Column:

1. Navigate to the appropriate Calendar Attributes page.

2. Locate the Calendar Display section.

3. From Display Type, select Custom.

4. In Column Format, enter a custom column format. You can use an HTML expression and supported substitution strings.

5. Click Apply Changes.

See Also:
"Supported Calendar Substitution Strings"

Display Attributes

Use Display Attributes to define the dates that are included in the calendar.

Begin at Start of Interval determines when the calendar should start. Selecting this option creates a calendar that spans an entire interval (such as a month). For example:

- If Begin at Start of Interval is selected, the date is June 15th, and the display is monthly, the resulting calendar spans from June 1st to June 30th.

- If Begin at Start of Interval is not selected, the date is June 15th, and the display is monthly, the resulting calendar spans from June 15th to June 30th.

The next two attributes define which items hold the calendar start date and end date. You can use these attributes to create calendars that span multiple months at a time. Note that the format of the date of either item must be YYYYMMDD:

- Item Containing Start Date points to an item that holds the start date of the calendar.

- Item Containing End Date points to an item that holds the end date of the calendar.

Start of Week for Monthly determines the day on which the calendar starts for the monthly view.

Start Day for Weekly determines the day on which the calendar starts for the weekly view.

End Day for Weekly determines the day on which the calendar ends for the weekly view.

Target Format determines if you want to display the time in 12-hour or 24-hour format.

Start Time and End Time determine the start and end times to display in the weekly and daily calendar views.

Column Link

Use Column link to create a link on the column in the calendar.

To create a column link to another page:

1. Navigate to the appropriate Calendar Attributes page.

2. Scroll down to Column Link.

3. From Target is a, select Page in this Application.

4. In Page, specify the target page number. To reset the pagination for this page, select reset pagination for this page.

5. In Request, specify the request to be used.

6. In Clear Cache, specify the pages (that is, the page numbers) on which to clear cache. Specify multiple pages by listing the page numbers in a comma-delimited list.
You can set session state (that is, give a listed item a value) using the next two attributes: the Set these items attribute and the With these values attribute.

7. To set session state:

a. Set these items - Enter a comma-delimited list of item names for which you would like to set session state.

b. With these values - Enter a comma-delimited list of values for the items specified in the previous step.
You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL cannot contain a colon (:). Additionally, item values cannot contain commas unless you enclose the entire value in backslashes (for example, \1234,56\).

8. Click Apply Changes.

See Also:
"Supported Calendar Substitution Strings"

To create a column link to a URL:

1. Navigate to the appropriate Calendar Attributes page.

2. Scroll down to Column Link.

3. From Target is a, select URL.

4. In URL, enter the appropriate address.

5. Click Apply Changes.

Day Link

Use Day link to create a link on a day in the calendar. This attribute creates a link on an actual number (or day) on the calendar.

To create a day link to another page:

1. Navigate to the appropriate Calendar Attributes page.

2. Scroll down to Day Link.

3. From Target is a, select Page in this Application.

4. In Page, specify the target page number.
To reset the pagination for this page, select reset pagination for this page.

5. In Request, specify the request to be used.

6. In Clear Cache, specify the pages (that is, the page numbers) on which to clear cache. Specify multiple pages by listing the page numbers in a comma-delimited list.
You can set session state (that is, give a listed item a value) using the next two attributes: Set these items and With these values.

7. To set session state:

a. Set these items - Enter a comma-delimited list of item names for which you would like to set session state.

b. With these values - Enter a comma-delimited list of values for the items specified in the previous step.
You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL cannot contain a colon (:). Additionally, item values cannot contain commas unless you enclose the entire value in backslashes (for example, \1234,56\).

8. Click Apply Changes.

To create a day link to a URL:

1. Navigate to the appropriate Calendar Attributes page.

2. Scroll down to Day Link.

3. From Target is a, select URL.

4. In URL, enter the appropriate address.

5. Click Apply Changes.

Upgrading a Calendar Created in a Previous Releases

By default, calendars you create in Oracle Application Express 3.0 include daily, weekly, and monthly views. If you want to update calendars created in a previous release to include these views, you can either:

- Create a new calendar:

a. Create a new calendar page and integrate the SQL query from your previous calendar.

b. Replace the previous calendar page with the new one in your application.

- Upgrade the theme:

a. Change the identification number of the existing theme. See "Changing a Theme Identification Number".

b. Recreate the theme. See "Creating a New Theme".

c. Apply the new theme to your application. See "Switching the Active Theme".

Converting an Easy Calendar to a SQL Calendar

Creating an Easy Calendar is the simplest way to create a calendar. However, if you find the resulting calendar does not meet your needs, you can quickly convert it to a SQL Calendar.

To convert an Easy Calendar to a SQL Calendar:

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

2. Under Regions, click Calendar next to the region name.
The Calendar Attributes page appears.

3. On the Tasks list, click Convert to SQL Based calendar.
Converting an Easy Calendar to a SQL Calendar adds a Region Source section to the Region Definition. The Region Source contains the original SQL query that creates the calendar. By accessing the Region Source, you can edit the query to meet your needs.

Creating Charts

Application Builder includes built-in wizards for generating HTML, Scalable Vector Graphics (SVG), and Flash charts. Oracle Application Express supports only those three types of graphical charts.

Topics in this section include:

- About Supported Chart Types

- About Creating SQL Queries for Charts

- Creating an HTML Chart

- Creating a SVG Chart

- Creating a Flash Chart

- Editing Chart Attributes

- Enabling Asynchronous Updates

- Displaying SVG Charts in Other Languages

See Tutorial:
"How to Create a Stacked Bar Chart" in Oracle Database Application Express Advanced Tutorials

About Supported Chart Types

Oracle Application Express supports three types of graphical charts: HTML, Scalable Vector Graphics (SVG), and Flash.

About Flash Charts

Flash chart support in Oracle Application Express is based on the Anychart Flash Chart Component. Anychart is a flexible Macromedia Flash-based solution that enables developers to create animated, compact, interactive flash charts. Flash charts are rendered by a browser and require Flash player 8 or higher. For more information about Anychart, go to

http://www.anychart.com

About SVG Plug-in Support

SVG is an XML-based language for Web graphics from the World Wide Web Consortium (W3C). SVG charts are defined using an embed tag. When evaluating whether or not an SVG chart is the appropriate chart type for your application, remember that:

- Some Web browsers do not support SVG charts.

- Most Web browsers that support SVG charts require that users download an SVG plug-in.

The Adobe SVG plug-in can handle data encoded in UTF-8, UTF-16, ISO-8859-1, and US-ASCII. Encoding of an SVG chart is determined by the database access descriptor (DAD) database character set. If the DAD character set is not UTF8, AL32UTF8, AL16UTF16, WE8ISO8859P1, or US7ASCII, SVG charts may not render properly in the Adobe SVG plug-in.

See Also:
"Creating a SVG Chart" and "About Migrating SVG Charts to Flash"

About Creating SQL Queries for Charts

You define a chart in Application Builder using a wizard. For most chart wizards, you select a chart type and provide a SQL query using the following syntax:

SELECT link, label, value
FROM   ...

Where:

- link is a URL.

- label is the text that displays in the bar.

- value is the numeric column that defines the bar size.

For example:

SELECT null, last_name, salary
FROM   employees
WHERE  DEPARTMENT_ID = :P101_DEPARTMENT_ID

Note:
Do not change the type of an existing chart. Instead, delete the existing chart and then re-create it.

Dial Chart Syntax

To create a dial chart, select a dial chart type and provide a SQL query using the following syntax:

SELECT value , maximum_value [ ,low_value [ ,high_value] ]
FROM   ...

Where:

- value is the starting point on the dial.

- maximum_value is the possible highest point on the dial.

- low_value and high_value are the historical low and high values.

For example:

SELECT dbms_random.value(500, 1200), 1300, dbms_random.value(100, 200)
FROM DUAL

Multiple Series Syntax (Flash only)

For column charts and line Flash charts, you can define multiple series in one SQL query. The series names for these chart types are derived from the corresponding column aliases in the query. To define a multiple series Flash chart, use the following syntax:

SELECT link, label, series_1_value [, series_2_value [, ...]]
FROM   ...

Range Chart Syntax (Flash only)

Range charts require two values for each bar. To create a range chart, create a Flash chart and provide a SQL query using the following syntax:

SELECT link, label, low_value, high_value
FROM   ...

Scatter Chart Syntax (Flash only)

Scatter charts require an x value and y value for each point. To create a range chart, create a Flash chart and provide a SQL query using the following syntax:

SELECT link, label, x_value, y_value
FROM   ...

Candlestick Chart Syntax (Flash only)

Candlestick charts require open, low, high, and close values for each candlestick. To create a candlestick chart, create a Flash chart and provide a SQL query using the following syntax:

SELECT link, label, open, low, high, close
FROM   ...

Creating an HTML Chart

How you create a chart depends upon whether you are adding the chart to an existing page, or adding a chart on a new page. This chart type creates a bar chart showing one data series with each data point represented by a bar.

Topics in this section include:

- Adding an HTML Chart to an Existing Page

- Adding an HTML Chart to a New Page

Adding an HTML Chart to an Existing Page

To add an HTML chart to an existing page:

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

2. Under Regions, click the Create icon.
The Create Region Wizard appears.

3. Select Chart and click Next.

4. For Region, select HTML Chart and click Next.

5. For Display Attributes

a. Specify the following:

- Title

- Region Template

- Display Point

- Sequence

- Column

To learn more, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

b. Click Next.

6. For Source:

a. Specify a query by either:

- Entering a SQL query in the field provided. See "About Creating SQL Queries for Charts".

- Clicking the Build Query button. When the Build Chart Query Wizard appears, follow the on-screen instructions.

b. Specify relevant chart attributes. To learn more, click the item label.

7. Click Create Region.

Adding an HTML Chart to a New Page

To create an HTML chart on a new page:

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

2. Select an application.

3. Click Create Page.

4. Select Chart and click Next.

5. For Region, select HTML Chart and click Next.

6. For Page Attributes:

a. Specify the following:

- Page Number

- Page Name

- Region Template

- Region Column

- Breadcrumb

To learn more, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

b. Click Next.

7. Specify whether or not to include tabs and click Next.

8. For Chart Definition:

a. Specify a query by either:

- Entering a SQL query in the field provided. See "About Creating SQL Queries for Charts".

- Clicking the Build Query button. When the Build Chart Query Wizard appears, follow the on-screen instructions.

b. Specify relevant chart attributes. To learn more, click the item label.

c. Click Next.

9. Click Finish.

Creating a SVG Chart

Oracle Application Express supports a number of different SVG charts. To see a complete listing, see "About SVG Chart Types".

How you create a chart depends upon whether you are adding the chart to an existing page, or adding a chart on a new page. This chart type creates a bar chart showing one data series with each data point represented by a bar.

Topics in this section include:

- Adding a SVG Chart to an Existing Page

- Adding a SVG Chart to a New Page

- About SVG Chart Types

- Understanding SVG Chart Cascading Style Sheet Classes

- Referencing a Custom SVG Chart Cascading Style Sheet

- Specifying Custom CSS Styles Inline for SVG Charts

See Also:
"About SVG Plug-in Support" and "About Migrating SVG Charts to Flash"

Adding a SVG Chart to an Existing Page

To add a SVG chart to an existing page:

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

2. Under Regions, click the Create icon.
The Create Region Wizard appears.

3. Select Chart and click Next.

4. For Region, select SVG Chart.

5. For Region, select a chart type and click Next. See "About SVG Chart Types".

6. For Display Attributes

a. Specify the following:

- Title

- Region Template

- Display Point

- Sequence

- Column

To learn more, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

b. Click Next.

7. For Source:

a. Specify a query by either:

- Entering a SQL query in the field provided. See "About Creating SQL Queries for Charts".

- Clicking the Build Query button. When the Build Chart Query Wizard appears, follow the on-screen instructions.

b. Specify relevant chart attributes. To learn more, click the item label.

8. Click Create Region.

Adding a SVG Chart to a New Page

To create a SVG chart on a new page:

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

2. Select an application.

3. Click Create Page.

4. Select Chart and click Next.

5. Select SVG Chart.

6. Select a chart type and click Next. See "About SVG Chart Types".

7. For Page Attributes:

a. Specify the following:

- Page Number

- Page Name

- Region Template

- Region Name

- Chart Color Theme

- Breadcrumb

To learn more, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

b. Click Next.

8. Specify whether or not to include tabs and click Next.

9. For Query:

a. Specify a query by either:

- Entering a SQL query in the field provided. See "About Creating SQL Queries for Charts".

- Clicking the Build Query button. When the Build Chart Query Wizard appears, follow the on-screen instructions.

b. Specify the remaining attributes. To learn more, click the item label.

c. Click Next.

10. Click Finish.

About SVG Chart Types

Table 5-5 describes the SVG chart types available in Application Builder.

Table 5-5 Available SVG Chart Types

Chart Type

Description

Bar, Horizontal

Single series-based bar chart oriented horizontally with each data point in the series represented by a bar.

SVG-based. Requires an SVG plug-in.

Bar, Vertical

Single series-based bar chart oriented vertically with each data point in series represented by a bar.

SVG-based. Requires an SVG plug-in.

Cluster Bar, Horizontal

Multiple series-based bar chart oriented horizontally and clustered by a common variable with each data point in the series represented by a bar (for example, Department sales total clustered by month of year).

SVG-based. Requires an SVG plug-in.

Cluster Bar, Vertical

Multiple series-based bar chart oriented vertically clustered by a common variable with each data point in series represented by a bar (for example, Department sales total clustered by month of year).

SVG-based. Requires an SVG plug-in.

Dial - Sweep

Also known as an angular gauge; this chart shows either percentage of maximum value or absolute value compared to a maximum value represented as a solid area.

SVG-based. Requires an SVG plug-in.

Dial

Also known as angular gauge; this chart shows either percentage of maximum value or absolute value compared to maximum value represented as a line.

SVG-based. Requires an SVG plug-in.

Line

Multiple series-based line chart oriented with each line representing all data points in the series.

SVG-based. Requires an SVG plug-in.

Pie

Single series-based pie chart with each slice representing a data point in the series.

SVG-based. Requires an SVG plug-in.

Stacked Bar, Horizontal

Multiple series-based bar chart oriented horizontally with each data point being an absolute value in the series representing a segment of a single bar.

SVG-based. Requires an SVG plug-in.

Stacked Bar, Vertical

Multiple series-based bar chart oriented vertically with each data point being an absolute value in the series representing a segment of a single bar.

SVG-based. Requires an SVG plug-in.

Stacked Percentage Bar, Horizontal

Multiple series-based bar chart oriented horizontally with each data point being a percentage of 100% of the series represented by a segment of a single bar.

SVG-based. Requires an SVG plug-in.

Stacked Percentage Bar, Vertical

Multiple series-based bar chart oriented vertically with each data point being a percentage of 100% of the series represented by a segment of a single bar

SVG-based. Requires an SVG plug-in.

Understanding SVG Chart Cascading Style Sheet Classes

When you create a new chart, Oracle Application Express renders it based on cascading style sheet (CSS) classes associated with the current theme. You can change the appearance of a chart by referencing another CSS or by overriding individual classes in the CSS section of the Edit Attributes page

The following sample contains the CSS classes for the dial chart in Sample Application. This example contains all the available CSS classes. Class names appear in boldface.

text{font-family:Verdana, Geneva, Arial, Helvetica, sans-serif;fill:#000000;}
tspan{font-family:Verdana, Geneva, Arial, Helvetica, sans-serif;fill:#000000;}
text.title{font-weight:bold;font-size:14;fill:#000000;}
text.moredatafound{font-size:12;}
rect.legend{fill:#EEEEEE;stroke:#000000;stroke-width:1;}
text.legend{font-size:10;}
#background{fill:#FFFFFF;stroke:none;}
rect.chartholderbackground{fill:#ffffff;stroke:#000000;stroke-width:1;}
#timestamp{text-anchor:start;font-size:9;}
text.tic{stroke:none;fill:#000000;font-size:12}
line.tic{stroke:#000000;stroke-width:1px;fill:none;}
#dial{stroke:#336699;stroke-width:2px;fill:#336699;fill-opacity:.5;}
#dial.alert{fill:#FF0000;fill-opacity:.5;}
#dialbackground{stroke:#000000;stroke-width:none;fill:none;filter:url(#MyFilter);}
#dialcenter{stroke:none;fill:#111111;filter:url(#MyFilter);}
#dialbackground-border{stroke:#DDDDDD;stroke-width:2px;fill:none;filter:url
(#MyFilter);}#low{stroke-width:3;stroke:#336699;}
#high{stroke-width:3;stroke:#FF0000;}
#XAxisTitle{letter-spacing:2;kerning:auto;font-size:14;fill:#000000;text-anchor:middle;}
#YAxisTitle{letter-spacing:2;kerning:auto;font-size:14;fill:#000000;text-anchor:middle;writing-mode:tb;}
.XAxisValue{font-size:8;fill:#000000;}
.YAxisValue{font-size:8;fill:#000000;text-anchor:end;}
.nodatafound{stroke:#000000;stroke-width:1;font-size:12;}
.AxisLine{stroke:#000000;stroke-width:2;fill:#FFFFFF;}
.GridLine{stroke:#000000;stroke-width:0.3;stroke-dasharray:2,4;fill:none;}
g.dataholder rect{stroke:#000000;stroke-width:0.5;}
.legenditem rect{stroke:#000000;stroke-width:0.5;}

Table 5-6 describes all supported CSS classes. Note that certain classes only apply to specific chart types.

Table 5-6 Available SVG Chart CSS Classes

Class

Description

text

Defines the appearance of text that displays in a chart.

tspan

Defines the appearance of text that displays in a chart. tspan should match the definition of text.

text.title

Overrides the default chart text. Use this class for title text.

text.moredatafound

Defines the appearance of more datafound text.

rect.legend

Creates the rectangular box that holds the chart legend.

To remove the legend border, change rect.legend to the following:

rect.legend{fill:#CCCC99;stroke:none;}

text.legend

Defines the text that appears in the chart legend.

#background

Creates the entire background for the SVG plug-in.

For a solid white background with no border, change #background to the following:

#background{fill:#FFFFFF;stroke:#FFFFFF;stroke-width:2;}

rect.chartholderbackground

Not applicable to pie and dial charts. Creates the background of the rectangle that holds the chart data.

For a clear background, change rect.chartholderbackground to the following:

rect.chartholderbackground(display:none;)

#timestamp

Only applicable if the Asynchronous Update chart attribute is set to Yes. Controls the appearance of the update timestamp test.

To disable the display of the timestamp, use defines #timestamp as follows in the Custom CSS, Inline attribute.

"#timestamp{display:none;}"

See Also: "Enabling Asynchronous Updates"

text.tic

Dial charts only. Defines the numbers on a dial chart.

line.tic

Dial charts only. Defines the graduation mark that displays directly beneath the number on a dial chart.

#dial

Dial charts only. Defines the value that displays on the dial chart.

#dial.alert

Dial charts only. Defines a value (called an alert value) that renders in a dial chart using a different display.

#dialbackground

Dial charts only. Creates the background of a dial chart.

#dialcenter

Dial charts only. Creates the center of the dial on a dial chart.

#dialbackground-border

Dial charts only. Works in conjunction with #dialbackground to create specific graphic effect.

#low

Dial charts only. Defines the historical low watermark of the data being displayed on a chart.

#high

Dial charts only. Defines the historical high watermark of the data being displayed on a chart.

#XAxisTitle

Defines the title that appears on the x-axis

#YAxisTitle

Defines the title that appears on the y-axis.

.XAxisValue

Defines the value that appears on the x-axis.

.YAxisValue

Defines the value that appears on the y-axis.

.AxisLabel

Similar to the axis value.

.nodatafound

Defines the text element that displays if no information is available.

.AxisLine

Indicates zero on charts that have negative values.

.GridLine

Creates the horizontal and vertical lines on the chart.

g.dataholder rect

Applies a blanket style to all data that displays in the chart.

.legenditem rect

Applies a blanket style to all rectangular items in the legend.

Referencing a Custom SVG Chart Cascading Style Sheet

You can reference a custom cascading style sheet for a chart using the CSS section of the Chart Attributes page. When you reference an external CSS, you can reference it entirely or simply override specific styles.

To reference a custom chart CSS:

1. Upload the CSS to Application Builder. See "Uploading Cascading Style Sheets".

2. Create a chart. See "Creating a SVG Chart".

3. Navigate to the Page Definition. See "Accessing a Page Definition".

4. Under Regions, click Chart next to the region name.
The Chart Attributes page appears.

5. Scroll down to the CSS section.

6. From Use Custom CSS, select Yes.

7. To reference an external CSS exclusively:

a. In Custom CSS, Link, enter a link to a custom CSS. For example:

#IMAGE_PREFIX#themes/theme_4/svg.css

b. Specify that the CSS should be used exclusively. In Custom CSS, Inline enter the following:

/**/

8. To reference a custom CSS and override specific styles:

a. In Custom CSS, Link, enter a link to a custom style sheet. For example:

#IMAGE_PREFIX#themes/theme_4/svg.css

b. In Custom CSS, Inline, enter the custom CSS styles you want to override.

Specifying Custom CSS Styles Inline for SVG Charts

You can override specific styles within the default CSS, using the Custom CSS, Inline attribute on the Chart Attributes page.

To override specific styles within the default CSS:

1. Create a chart. See "Creating a SVG Chart".

2. Navigate to the Page Definition. See "Accessing a Page Definition".

3. Under Regions, click Chart next to the region name.
The Chart Attributes page appears.

4. Scroll down to CSS.

5. From Use Custom CSS, select Yes.

6. In Custom CSS, Inline, enter the custom CSS styles you want to override.

Creating a Flash Chart

How you create a flash chart depends upon whether you are adding the chart to an existing page, or adding a chart on a new page.

Tip:
Note that in order to view Flash charts, you must install Flash Player 8 or higher.

Topics in this section include:

- Adding a Flash Chart to an Existing Page

- Adding a Flash Chart to a New Page

- Migrating a SVG Chart to Flash

- Migrating all SVG Charts in a Application to Flash

See Also:
"About Flash Charts" and "About Migrating SVG Charts to Flash"

Adding a Flash Chart to an Existing Page

To add a flash chart to an existing page:

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

2. Under Regions, click the Create icon.
The Create Region Wizard appears.

3. Select Chart and click Next.

4. For Region, select Flash Chart.

5. For Display Attributes

a. Specify the following:

- Title

- Region Template

- Display Point

- Sequence

- Column

To learn more, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

b. Click Next.

6. On Chart Preview, configure the chart attributes. Click Update to refresh the preview image.

7. Click Next.

8. For Source:

a. Specify a query by either:

- Entering a SQL query in the field provided. See "About Creating SQL Queries for Charts".

- Clicking the Build Query button. When the Build Chart Query Wizard appears, follow the on-screen instructions.

b. Specify relevant chart attributes. To learn more, click the item label.

9. Click Create Region.

Adding a Flash Chart to a New Page

To create a flash chart on a new page:

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

2. Select an application.

3. Click Create Page.

4. Select Chart and click Next.

5. Select Flash Chart.

6. For Page Attributes:

a. Specify the following:

- Page Number

- Page Name

- Region Template

- Region Name

- Breadcrumb

To learn more, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

b. Click Next.

7. Specify whether or not to include tabs and click Next.

8. For Chart Preview, configure the chart attributes. Click Update to refresh the preview image.

9. Click Next.

10. For Query:

a. Specify a query by either:

- Entering a SQL query in the field provided. See "About Creating SQL Queries for Charts".

- Clicking the Build Query button. When the Build Chart Query Wizard appears, follow the on-screen instructions.

b. Specify the remaining attributes. To learn more, click the item label.

c. Click Next.

11. Click Finish.

About Migrating SVG Charts to Flash

You can automatically migrate single or multiple SVG charts to Flash.

About SVG Chart Migration Restrictions

Note that SVG charts are migrated with the following restrictions:

- Only number formats defined in axis format strings will be migrated. Date and time formats will be ignored.

- Number format elements containing the following will be migrated:

0,9,D,G,, (comma),. (period),$,C,L,FM

- The label for each series in the Flash chart will be derived from each series' column alias. This differs from SVG charts, where the label for each series was derived from the Series Name attribute.

- Flash Dial charts display actual values instead of percentages.

- In SVG charts, only the labels for the first series are used for the x-axis. In Flash charts, this has been enhanced so that all data appears, even if the data's label does not occur in the first series.

Migrating a SVG Chart to Flash

To migrate a SVG chart to Flash:

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

2. Under Regions, click region name. The region name displays to the left of SVG Chart.
The Region Definition appears.

3. From the Tasks list, click Migrate SVG Chart to Flash Chart.

4. Click Migrate.

Migrating all SVG Charts in a Application to Flash

To migrate all SVG Charts to Flash charts:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.
The Application home page appears.

4. On the Tasks list, click Application Reports.

5. Click Page Components.

6. Under Regions, click Migrate SVG to Flash Charts.
The Migrate SVG to Flash Charts page appears.

7. To migrate specific charts, select the charts to be migrated and click Migrate Checked.

8. To migrate all charts, click Migrate All.

Editing Chart Attributes

Once you have created a chart, you can alter its display by editing chart attributes on the Chart Attributes page.

To access the Chart Attributes page:

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

2. Under Regions, click the chart type (Chart, SVG Chart, or Flash Chart).
The Chart Attributes page appears.

3. Edit the appropriate attributes.

4. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

5. Click Apply Changes.

Tip:
Removing the chart title of an SVG chart (that is, the Chart Title attribute) may negatively impact the location and display of the chart legend.

About Navigation Alternatives

The Chart Attributes page is divided into sections. You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Using Custom XML with Flash Charts

There are additional chart settings that cannot be controlled using the standard attributes on the Chart attributes page. To further control the look and feel of a chart, you can use custom XML.

To use custom XML:

1. Navigate to the Chart Attributes page:

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

b. Under Regions, click the chart type, Flash Chart.
The Chart Attributes page appears.

2. Scroll down to Chart XML.

3. From Use Custom XML, select Yes.
Note that when you select to use custom XML, regions with attributes that no longer apply are hidden. To display these regions again, select No for Use Custom XML.

4. Edit the XML.

5. Click Apply Changes.

Tip:
For more information on supported XML format for charts, see the Online XML Reference at:

http://www.anychart.com

Enabling Asynchronous Updates

You can create SVG and Flash charts that monitor information by enabling the Asynchronous Update attribute on the Chart attributes page. Enabling this attribute updates the chart to reflect changes in the underlying data within a specified time interval.

To enable asynchronous updates:

1. Create an SVG or Flash chart. See "Creating a SVG Chart" or "Creating a Flash Chart".

2. Navigate to the Page Definition. See "Accessing a Page Definition".

3. Under Regions, click Chart next to the region name.
The Chart Attributes page appears.

4. Scroll down to Refresh.

5. From Asynchronous Update, select Yes.

6. In Update Interval (Seconds), enter the interval in seconds between chart updates. For optimal performance, select an interval that is greater than 2 seconds.

When Asynchronous Update is enabled for an SVG chart, a timestamp displays on the chart indicating the last update.

To disable the Asynchronous Update timestamp:

1. Navigate to the Chart Attributes page.

2. Locate the CSS section.

3. From Use Custom CSS, select Yes.

4. In Custom CSS, Inline edit #timestamp as follows:

#timestamp{display:none;}

Displaying SVG Charts in Other Languages

To display an SVG chart in another language, you edit the text and tspan classes to reflect the correct language.

To display an SVG chart in another language:

1. Navigate to the Chart Attributes page. See "Editing Chart Attributes".

2. Scroll down to CSS.

3. From Use Custom CSS, select Yes.

4. In Custom CSS, Inline, edit the text and tspan classes to reflect the correct language. The following example demonstrates how to change a chart to Korean:

text{font-family:Batang;fill:#000000;}
tspan{font-family:Batang;fill:#000000;}

Creating Buttons

As you design your application, you can use buttons to direct users to a specific page or URL, or to post or process information (for example, by creating Create, Cancel, Next, Previous, or Delete buttons).

Buttons can perform two different types of actions. A button can submit a page and then redirect to a URL. Alternately, a button can branch to a URL without submitting the page, such as for a Cancel button.

Topics in this section include:

- About the Buttons Section of the Page Definition

- Creating a Button Using a Wizard

- Creating Multiple Buttons

- Editing Buttons

- Understanding the Relationship Between Button Names and REQUEST

- About Branching with Buttons

- Displaying Buttons Conditionally

See Also:
"Calling a Page from a Button URL"

About the Buttons Section of the Page Definition

You create and edit buttons on the Page Definition. The Buttons section appears in the Page Rendering area. See "Accessing a Page Definition".

You can temporarily hide all other subsections by clicking the Buttons icon. To restore the view, click Show All. The Show All icon resembles an inverted triangle.

The following icons display next to the section title:

- Edit All. The Edit All icon resembles a small grid with a pencil on top of it. Use this icon to edit all buttons at once.

- Copy. The Copy icon resembles two small overlapping pages. Use this icon to make a copy of an existing button.

- Create. The Create icon resembles a plus (+) sign overlapping a small page. Click this icon to create a new button.

Buttons are organized by region. To edit a button, click the button name.

See Also:
"Editing Buttons"

Creating a Button Using a Wizard

You create a button by running the Create Button Wizard from the Page Definition. Each button resides in a region. A region is an area on a page that serves as a container for content.

To create a new button:

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

2. If necessary, create an HTML region. See "Understanding Regions".

3. Under Buttons, click the Create icon.
The Create Button Wizard appears.

4. Select a region to contain the button and click Next.

5. Select a position for the button and click Next:

- Create a button displayed among this region's items - Select this option to display the button within or between page items (for example, to add a button directly to the right of a form field).

- Create a button in a region position - Select this option to place the button in a region position. A region position is a position defined by a region template.

6. If you select Create a button in a region position:

a. Specify the Button Name and Label.

b. Select a Button Type: HTML Button (Default), Image, or Template Driven
Select Button is Reset to create an Undo button. When enabled, this type of button resets the page values to the state they were in when the page was initially rendered.

c. Select an Action:

- Submit page and redirect to URL submits the current page to the Application Express engine whenever a user clicks the button.

- Redirect to URL without submitting page avoids submitting the page. Choose this action when submitting the page for processing is not necessary (for example, a Cancel button). This action avoids processing in the database and therefore reduces the load.

d. Click Next.

7. If you select Create a button displayed among this region's items:

a. Specify the Button Name and Sequence.

b. Specify if the button displays at the beginning of a new line or new field.

c. Specify a Label.

d. Enter the value of Request.

e. Select the Button Style.

f. Click Next.

8. Follow the on-screen instructions. To learn more about a specific field, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

See Also:
"Understanding the Relationship Between Button Names and REQUEST"

Creating an HTML Button

Buttons can be placed in a predefined region template position or among items in a form. To create an HTML button, select one of the following while running the Create Button Wizard:

- Under Task, select Create a button in a region position.

- Under Button Type, select a button type and then HTML Button (default).

Creating Multiple Buttons

You can create multiple buttons within the same region at once using the Create Multiple Buttons Wizard.

To create multiple buttons at once:

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

2. If necessary, create an HTML region. See "Understanding Regions".

3. Under Buttons, click the Create icon.
The Create Button Wizard appears.

4. Select Create Multiple Buttons at the bottom of the page.
The Create Multiple Button Wizard appears.

5. From Place Buttons in Region, select the region to contain the buttons.

6. From Template, select a template.

7. In HTML Attributes, specify HTML attributes for these buttons. This text will be added to the HTML element definition. For example, you could set the class of a text button as follows:

class="myclass"

8. To quickly populate the remaining fields, make a selection from the Quick Button list on the right side of the page.

9. Click Create Buttons.

Editing Buttons

When you want to edit a button, you start from the Buttons section on the Page Definition. You can edit the attributes of a button, edit multiple buttons at once, or change a button position within a region.

Topics in this section include:

- Editing Button Attributes

- Using the Edit All Icon to Edit Multiple Buttons

- Using the Reorder Buttons Icon

See Also:
"About the Edit All Icon"

Editing Button Attributes

You can edit button attributes on the Edit Pages Buttons page.

To edit attributes for an existing button:

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

2. Under Buttons, select the button name.
The attributes page for the button appears.

3. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

4. Click Apply Changes.

Using the Edit All Icon to Edit Multiple Buttons

You can edit multiple buttons at once by clicking the Edit All icon on the Page Definition. The Edit All icon resembles a small grid with a pencil on top of it.

Clicking the Edit all icon displays the Buttons page, which contains a table listing the buttons in the region. This enables you to edit multiple buttons at once.

From the Buttons page, you can delete multiple buttons or view a history of recent changes.

To edit multiple buttons:

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

2. Under Buttons, click the Edit All icon.
The Buttons page appears.

3. Edit the attributes on the Buttons page, or click the Edit icon to edit the attributes for a single button.

4. Click Apply Changes.

Delete Multiple Buttons

To delete multiple buttons at once:

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

2. Under Buttons, click the Edit All icon.

3. Click Delete Multiple Buttons.
The Delete Multiple Buttons page appears.

4. Select the buttons to delete and click Remove Buttons.

History

Use the History page to view a summary of recent edits to buttons.

Using the Reorder Buttons Icon

You can quickly edit a button label or change a button position within a region by clicking the Reorder Region Buttons icon on the Page Definition. The Reorder Region Buttons icon resembles a light green downward arrow and upward arrow and displays next to the region name.

To edit buttons using the Reorder Region Buttons icon:

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

2. Under Buttons, click the Reorder Region Buttons icon.
The Reorder Buttons page appears. Use this page to edit the button label, select a new region position, or change the button order.

3. To edit the button label, enter a new name in the Label field.

4. To change the region position, make a selection from the Position list.

5. To change the order in which buttons display, click the up and down arrows in the far right column.
Note that you can also control the order in which buttons display by editing the Sequence attribute. See "Editing Button Attributes".

6. Click Apply Changes.

Note:
To change the region where a button resides, you must edit the button attributes. See "Editing Button Attributes".

Understanding the Relationship Between Button Names and REQUEST

The name you give a button determines the value of the built-in attribute REQUEST. You can reference the value of REQUEST from within PL/SQL using the bind variable :REQUEST. By using this bind variable, you can conditionally process, validate, or branch based on which button the user clicks. You can also create processes that execute when the user clicks a button. And you can use a more complex condition as demonstrated in the following examples:

If :REQUEST in ('EDIT','DELETE') then ...
If :REQUEST != 'DELETE' then ...

These examples assume the existence of buttons named EDIT and DELETE. You can also use this syntax in PL/SQL Expression conditions. Be aware, however, that the button name capitalization (case) is preserved. In other words, if you name a button LOGIN, then a request looking for the name Login will fail. For example:

<input type="BUTTON" value="Finish" onClick="javascript:doSubmit('Finish');">

Note that in this example Finish is the name of the REQUEST and this example is case-sensitive.

About Branching with Buttons

Each page can include any number of branches. A branch links to another page in your application or to a URL. The Application Express engine considers branching at different times during page processing. You can choose to branch before processing, before computation, before validation, and after processing. Like any other control in Application Builder, branching can be conditional. For example, you can branch when a user clicks a button. When you create a branch, you associate it with a specific button. The branch will only be considered if a user clicks the button.

See Also:
"Controlling Navigation Using Branches"

Displaying Buttons Conditionally

You can choose to have a button display conditionally by editing attributes on the Edit Pages Button page.

To have a button display conditionally:

1. Create the button. See "Creating a Button Using a Wizard".

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

3. Under Buttons, select the button name.
The attributes page for the button appears.

4. Scroll down to Conditional Button Display.

5. Make a selection from the Condition Type list.

6. Enter an expression in the fields provided.

7. Click Apply Changes.

See Also:
"About Bind Variable Syntax"

Understanding Page-Level Items

An item is part of an HTML form. An item can be a text field, text area, password, select list, check box, and so on. Item attributes affect the display of items on a page. For example, these attributes can impact where a label displays, how large an item will be, and if the item will display next to or below the previous item.

Topics in this section include:

- Differences Between Page Items and Application Items

- About the Items Section of the Page Definition

- Creating Page-Level Items

- Editing Page-Level Items

- Using the Drag and Drop Layout Page

- Referencing Item Values

- Displaying Conditional or Read-Only Page Items

- Working with a Multiple Select List Item

- Populating an Alternative Date Picker Format for an Application

- Populating an Alternative Date Picker Format for a Specific Item

See Also:
"Understanding Application-Level Items", "How Item Attributes Affect Page Layout", "Understanding Substitution Strings", and "About the Item Finder"

Differences Between Page Items and Application Items

There are two types of items: page items and application items. Page items are placed on a page and have associated user interface properties, such as Display As, Label and Label Template. Examples of page-level items include a check box, date picker, display as text, file browse field, popup list of values, select list, or a text area. Application items are not associated with a page and therefore have no user interface properties. You can use an application item as a global variable.

See Also:
"Understanding Application-Level Items"

About the Items Section of the Page Definition

You create and edit page-level items on the Page Definition. The Items section appears in the Page Rendering area.

You can temporarily hide all other subsections by clicking the Items icon. To restore the view, click Show All. The Show All icon resembles an inverted triangle.

The following icons display next to the section title:

- Edit All. The Edit All icon resembles a small grid with a pencil on top of it. Use this icon to edit all items at once. See "Using the Edit All Icon to Edit Multiple Items".

- Copy. The Copy icon resembles two small overlapping pages. Use this icon to make a copy of an existing item.

- Create. The Create icon resembles a plus (+) sign overlapping a small page. Click this icon to create a new item.

Items are organized by region. To edit an item, click the item name.

See Also:
"Editing Page Item Attributes" and "Using the Reorder Buttons Icon"

About the Drag and Drop Icon

You can quickly change the appearance of a page by clicking the Drag and drop icon to access the Drag and Drop Layout page. The Drag and drop icon resembles a green rectangle and displays to the right of the Reorder Region Items icon.

You can use the Drag and Drop Layout page to interactively reorder items within a given region, change select item attributes, create new items, or delete existing items. See "Using the Drag and Drop Layout Page".

About the Reorder Items Icon

You can quickly edit the label and position of items in a region by clicking the Reorder Region Items icon on the Page Definition. This icon resembles a light green down or up arrow.

See Also:
"Using the Reorder Region Items Icon"

Creating Page-Level Items

Topics in this section include:

- Creating a Page-Level Item on the Page Definition

- About Item Naming Conventions

- About Item Types

- Creating Multiple Items Using Tabular Form

- Creating Multiple Items Using Drag and Drop

- Creating a Static List of Values

See Also:
"Differences Between Page Items and Application Items"

Creating a Page-Level Item on the Page Definition

You create a page-level item by running the Create Item Wizard from the Page Definition.

To create a new page-level item:

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

2. If necessary, create an HTML region. See "Understanding Regions".

3. Under Items, click the Create icon.

4. Select an item type. See "About Item Types".

5. Follow the on-screen instructions.

6. To learn more about a specific field, click the field label.
When help is available, the item label changes to red when you pass your cursor over it, and the cursor changes to an arrow and question mark. See "About Field-Level Help".

About Item Naming Conventions

When specifying an item name, remember the following rules. Item names must:

- Be unique within an application

- Not have quotation marks

- Begin with a letter or a number, and subsequent characters can be letters, numbers, or underscore characters

- Be case-insensitive

- Should not exceed 30 characters

- Cannot contain letters outside the base ASCII character set

About Item Types

When you create an item, you specify an item type. Once you create an item, these types appear on the Display As list on the Edit Page Item page. Table 5-7 describes available item types.

Table 5-7 Available Item Types

Item Type

Description

Check Box

Displayed using a list of values. A list of values is required for items displayed as check boxes. The value corresponding to a checked box is returned in a single colon-delimited string.

The following example demonstrates how to create a single check box that returns YES. This example would display both a check box and a field label.

SELECT NULL display_text, 'YES' return_value FROM DUAL;

This example includes the additional text Click to select.

SELECT 'Click to select' display_text, 'YES' return_value FROM DUAL;

See Also: "APEX_UTIL" for information about breaking up returned values

Date Picker

Displays a text field with a Calendar icon next to it. When clicked, this icon displays a small calendar where the user can select a date and a time (optional).

If the format you need is not included in the Display As list, select Date Picker (use application format mask) or Date Picker (use item format mask). The latter uses the value from the Format Mask field in the Source section of the Edit Page Item page.

See Also: "Populating an Alternative Date Picker Format for an Application" and "Populating an Alternative Date Picker Format for a Specific Item"

Display Only

Available Display As Text subtypes include:

- Display as Text (does not save state) - Displays the item's source value on the page without creating a form item.

- Display as Text (escape special characters, does not save state) - Displays the item's source value with special characters ('<','>','&') escaped.

- Display as Text (saves state) - Displays the item's source value and creates a form item that gets submitted with the page to pass the value into session state.

- Display as Text (based on LOV, does not save state) - Displays the display value from an LOV by matching the item's source value with the LOV's return value.

- Display as Text (based on LOV, saves state) - Same as the previous option, but also generates a form item that gets submitted with the page to pass the return value into session state.

File Browse

Displays a text field with a Browse... button. This enables the user to locate a file on a local file system and upload it. Oracle Application Express provides a table for these files to be uploaded to as well as an API to retrieve the files.

See Also: "Understanding the Security Risks of File Upload Tables"

Hidden

Renders an HTML hidden form element. Session state can be assigned and referenced just like a text field.

List Manager

Based on a list of values. This item enables you to manage a list of items by selecting and adding to a list. The list of values display as a popup.

Multiple Select

Renders as a multiselect HTML form element. When submitted, selected values are returned in a single colon-delimited string. You can break up the values using the APEX_UTIL API.

See Also: "Working with a Multiple Select List Item" and "APEX_UTIL"

Password

Renders as an HTML password form element.

Popup List of Values

Renders as a text field with an icon. When the user clicks the icon, a popup window appears with one of these, depending on the popup selection you make:

- List of values represented as a series of links - When the user makes a selection from the list, the selected value is placed in the text field.

- Color picker - When the user makes a selection from the palette, the HTML value for the color selected (for example, #000000 for black) is returned.

With the exception of the color picker, you control popup lists of values through templates. You can only specify one popup list of values (LOV) template for each application. A popup LOV is a good choice for lists of values that are too large to return on a single page.

There are two types of Popup LOVs: one that fetches a set of rows when the window pops up and one that does not. Available popup LOVs include:

- Popup Key LOV (Displays description, returns key value)

- Popup Key LOV No Fetch (Displays description, returns key value without pre-fetch)

- Popup LOV (fetches first rowset and filters

- Popup LOV (fetches first rowset)

- Popup LOV (no fetch)

- Popup Color Picker

Popup LOVs must be based on a query that selects two columns with different column aliases. For example:

SELECT ename name, empno id
FROM emp

If one of the columns is an expression, remember to use an alias. For example:

SELECT ename||' '||job display_value, empno FROM emp

Radio

Renders as an HTML radio group form element, based on a list of values. Choose Radiogroup with Submit to have the page submitted when the radio button is selected.

The following example displays employee names (ename), but returns employee numbers (empno):

SELECT ename, empno FROM emp

Select List

Displays using a list of values. A list of values is required for items displayed as a select list. Select lists are rendered using the HTML form element <select>. The values in a select list are determined using a named list of values or a list of values defined at the item level. You can specify the NULL display value and NULL return value.

The following example would return employee names (ename) and employee numbers (empno) from the emp table. Note that column aliases are not required and are included in this example for clarity.

SELECT ename display_text, empno return_value FROM emp

Oracle Application Express provides additional enhancements to a standard HTML select list:

- Select List with Submit - Submits the page when the user changes its selected value. Upon submit, the REQUEST will be set to the name of the item that represents the select list, allowing you to execute conditional computations, validations, processes, and branches.

- Select List with Redirect - Redirects the user back to the same page, setting ONLY the newly selected value of the select list in session state.

- Select List Returning URL Redirect - Based on a list of values with URLs as the return values. Changing the value of the select list causes the browser to redirect to the corresponding URL.

- Select List with Branch to Page - Based on a list of values with page numbers as return values. Changing the selected value in the select list causes the Application Express engine to branch to the corresponding page.

Note: Long select lists can cause errors. If you have a long select list that generates an error, try using a Popup List of Values instead.

Shuttle

Renders as a multiple select list that includes two boxes containing lists. The left list displays a source list of values. Users use the shuttle control icons and buttons to select list items and move them from the left (source) list to the right (destination) list. Each shuttle has five controls:

- Move all - Moves all items in the source list to the destination list.

- Move selected - Moves only selected items (Ctrl + Shift items) to destination list.

- Remove selected - Moves only selected items (Ctrl + Shift items) to the source list.

- Remove all - Moves all items on destination list back to the source list.

- Refresh - Resets the source and destination lists.

The right destination list includes the sort controls Move to top, Move up, Move down, and Move to bottom.

Note: In order to create this item type, you must define a list of values. See "Creating a Static List of Values", "Creating Lists of Values", and "Working with a Multiple Select List Item".

Text

Displays as an HTML text field containing a maximum of 30,000 bytes of text. You control the maximum length and display width by editing the Height and Width item attribute.

Available Text display options include:

- Text Field - Renders as a text field.

- Text Field (Disabled, does not save state) - Displays a read-only version of a display value from a list of values by using the item's value in session state to look up the corresponding display value in the associated list of values. The value displayed on the screen is not saved in session state upon submit.

- Text Field (Disabled, saves state) - Displays a read-only version of a display value from a list of values by using the item's value in session state to look up the corresponding display value in the associated list of values.

- Text Field (always submits page when Enter pressed) - Displays a read-only version of the value in session state. Upon submit, the value displayed is saved in session state.

- Text Field with Calculator Popup - Renders as a text field with an icon next to it. When clicked, the icon displays a small window containing a calculator. Calculations are placed back in the text field.

Text Area

Renders as an HTML text area. There is no maximum length for an item displayed as a text area. You control the height and width by editing the Height and Width item attribute. Additional available Text Area Display As options include:

- Text Area

- Text Area (auto height) - Varies the height based on the amount of text. Use this option to scale the text area to the amount of data.

- Text Area with Counter - Includes a counter that displays the number of bytes entered in the field.

- Text Area with Spell Checker - Provides a popup English language spell checker.

- HTML Editor Minimal - Provides basic text editing features, including the application of bold, italics, and underline styles, the ability to create numbered and bulleted lists, and indentation.

- HTML Editor Standard - Provides more editing functionality, such as font, format and color, than HTML Editor Minimal.

- Text Area with HTML Editor - Provides basic text formatting controls. Note that these controls may not work in all Web browsers.

Stop and Start Table

Forces the close of an HTML table using the </table> tag and starts a new HTML table. You can use this item type to reset the column width in the middle of the region.

Note that a Stop and Start Table item only displays its label. You can prevent the label from displaying at all by setting it to null. To do this, you simply remove the default label.

Creating Multiple Items Using Tabular Form

To create multiple items simultaneously:

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

2. If necessary, create an HTML region. See "Understanding Regions".

3. Under Items, click the Create icon.
The Create Item wizard appears.

4. At the bottom of the page, click the Create multiple Items Using Tabular Form link.

5. On the Create Multiple Items page, specify the following:

a. Create Item(s) in Region - Select the region to contain the items.

b. Item Template - Select an item template.

c. For each item, enter the Sequence, Name, Label, Type and specify whether the item should be cached.

6. Click Create Multiple Items.

See Also:
"About the Drag and Drop Icon"

Creating Multiple Items Using Drag and Drop

To create multiple items using the Drag and Drop Layout page:

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

2. If necessary, create an HTML region. See "Understanding Regions".

3. Under Items, click the Create icon.
The Create Item wizard appears.

4. At the bottom of the page, click the Create multiple Items Using Drag and Drop Layout link.
The Drag and Drop Layout page appears.

5. Select an item from the palette on the left side of the page and drag it to the appropriate position on the page.

6. Edit the item attributes at the of the page.

a. Display Name - Enter an item name. Use this name retrieve the value of the item. Item names longer than 30 characters cannot be referenced using bind variable syntax.

b. Label - Enter the label for this item. You may include HTML, JavaScript, and shortcuts. You can also use the substitution string #CURRENT_ITEM_NAME# to obtain the name of the item associated with this label.

c. Display Type - Select a display type (if applicable). See "About Item Types".

7. To edit an existing item, edit the Item Name and Label fields, or select a new Display Type at the top of the page.

8. Click Next.

9. Optionally, edit the each item's Name and Label.

10. Click Apply Changes.

See Also:
"Using the Drag and Drop Layout Page"

Creating a Static List of Values

One way to create a static list of values is to edit an item's List of Values definition. Note that this type of list of values is not reusable. As a best practice, create a list of values as a shared component whenever possible.

See Also:
"Creating Lists of Values"

To create a static list of values:

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

2. Under Items, select the item name.
The Edit Page Item page appears.

3. Under Name, specify how the item will be rendered. Make a selection from the Display As list.

4. Under List of Values, create a static list of values:

a. From Named LOV, select Select Named LOV.

b. In List of values definition, enter a definition using the following syntax:

STATIC[2]:Display Value[;Return Value],Display Value[;Return Value]

Where:

- The first keyword may be STATIC or STATIC2.

STATIC results in the values being sorted alphabetically by display value. STATIC2 results in the values being displayed in the order they are entered in the list.

- A semicolon separates the display value from the return value in each entry.

- Return Value is optional. If a Return Value is not included, the return value is the same as the display value.

5. To learn more, see item Help. To view help for a specific item on a page, click the item label.
When help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

6. Click Apply Changes.
The examples that follow demonstrate syntax for three different static LOVs.

Example 1: Four Values Displayed in Alphabetical Order

In this example, the list of values has four values (Cow, Dog, Cat, and Lion) that display in alphabetical order. The return value of each entry equals the display value.

STATIC:Cow,Dog,Cat,Lion

Example 2: Ten Values Displayed in the Order Listed

In this example, the list of values has ten values that display in the order listed in the definition. The return value of each entry equals the display value.

STATIC2:10,15,20,25,50,100,200,500,1000,10000

Example 3: A List of Values with Having Both a Return and Display Value

In this example, the list of values has two values: Yes and No (the display value Yes and its return value Y, and the display value No and its return value N).

STATIC:Yes;Y,No;N

See Tutorial:
"How to Control Form Layout" in Oracle Database Application Express Advanced Tutorials

Editing Page-Level Items

You can edit page-level items by editing page item attributes or using the Edit All or Reorder Items icons.

Topics in this section include:

- Editing Page Item Attributes

- Using the Edit All Icon to Edit Multiple Items

- Using the Reorder Region Items Icon

See Also:
"Using the Drag and Drop Layout Page"

Editing Page Item Attributes

Once you create a page item, you can edit it on the Edit Page Item page.

To edit page item attributes:

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

2. Under Items, select the item name.
The Edit Page Item page appears.

3. To learn more about a specific attribute on a page, click the attribute label.
When help is available, the item label changes to red when you pass your cursor over it, and the cursor changes to an arrow and question mark. See "About Field-Level Help".

4. Click Apply Changes.

See Also:
"How Item Attributes Affect Page Layout" and "About Cross-Site Scripting Protection"

About Navigation Alternatives

The Edit Page Item page is divided into the following sections: Name, Displayed, Label, Element, Source, Default, List of Values, Security, Conditions, Read Only, Help Text, Configuration, and Comments.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Using the Edit All Icon to Edit Multiple Items

You can edit multiple items at once by clicking the Edit All icon on the Page Definition. The Edit All icon resembles a small grid with a pencil on top of it.

Clicking the Edit All icon displays a series of pages that enable you to edit multiple items simultaneously or view a history of recent changes.

Topics in this section include:

- Page Items

- Item Help

- Reassign Region Items

- Delete Multiple Items

- History

See Also:
"How Item Attributes Affect Page Layout"

Page Items

Item attributes control how items display on a page. You can use the Page Items page to edit the sequence, field label, template, region, and overall position for all items on a page.

A Navigation bar displays at the top of the page. Use the Page field to navigate to another page. To limit the display to just items in a specific region, make a selection from Show Regions list.

See Also:
"Editing Page Item Attributes"

The Page Items page displays items in an editable report. Table 5-8 describes each editable attribute.

Table 5-8 Editable Attributes on Page Items

Attribute

Description

Sequence

Specify the display sequence for this component. The sequence determines the order of evaluation.

Prompt

Enter the label for this HTML form element. You may include HTML, JavaScript, and shortcuts. You can also use the substitution string #CURRENT_ITEM_NAME# to obtain the name of the item associated with this label.

Field Template

Determines the a label template. Label templates enable you to define the user interface attributes in a central place and share that definition among many labels.

Region

Defines the region in which the item displays. All items must be in a region.

New Line

Determines whether this item displays on the same line as the previous item or whether it displays on the next line. Items are laid out in an HTML table. Select Yes to have an item display as the first field in a new row in the table.

Width

Specifies the length (in characters) of the form element that displays for this item.

Height

Specifies the height (in lines) for text areas and multi select lists.

Column Span

Items are laid out in HTML tables. This property defines the value to be used for the COLSPAN attribute in the table cell.

Row Span

Items are laid out in HTML tables. The attribute determines the value to be used for the ROWSPAN attribute in the table cell that the item displays in.

Edit the appropriate attributes and click Apply Changes.

Item Help

Use the Item Help page to edit item help for all items on a page. You can avoid repeating the same Help text in multiple locations by subscribing to another item.

See Also:
"Creating a Help Page"

To edit item Help:

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

2. Under Items, click the Edit All icon.

3. Click Item Help.
The Item Help page appears.

Use the Navigation bar at the top of the page to narrow or broaden the display. Available options include:

- Page - Select or enter a new number and click Go.

- Search - Enter a case insensitive query and click Go.

- Show - Select whether to display All, Subscribed, or Unsubscribed Help text.

- All Pages - Select to run the search query on all pages in the application.

- Current Page - Select to restrict the search query to the current page.

You can also use the arrows in the Navigation bar to scroll through the application pages.

4. To subscribe to an existing Help item, make a selection from Subscribed To.

5. To edit help for a specific item, click the item name.
On the Edit Help page:

a. Reference Master Item Help From - (Optional) Select a existing item Help topic to subscribe to.

b. Help Text - Enter or edit the Help text for this item.

c. Click Apply Changes.

6. Click Apply Changes.

Reassign Region Items

Use the Reassign Region Items page to assign items to a new region.

To Reassign Region Items page:

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

2. Under Items, click the Edit All icon.

3. Click Reassign Region Items.
The Reassign Region Items page appears.

Use the Navigation bar at the top of the page to narrow or broaden the display. Available options include:

- Page - Select or enter a new number and click Go.

- Show Regions - Select a region to display and click Go.

4. To reassign an item to another region:

a. Select the items to reassign.

b. From Assign to Region, select a new region.

c. Click Reassign Region Items.

Delete Multiple Items

Use the Delete Multiple Items page to delete multiple items at once.

To delete multiple items:

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

2. Under Items, click the Edit All icon.

3. Click Delete Multiple Items.
The Delete Multiple Items page appears.

Use the Navigation bar at the top of the page to narrow or broaden the display. Available options include:

- Page - Select or enter a new number and click Go.

- Show Regions - Select a region to display and click Go.

- Forward (>) and Next (<) buttons - Display the previous and next page.

4. To reassign an item to another region:

a. Select the items to reassign.

b. From Assign to Region, select a new region.

c. Click Reassign Region Items.

History

Use the History page to view a summary of recent edits to page-level items.

Using the Reorder Region Items Icon

You can quickly edit the label and position of items in a region by clicking the Reorder Region Items icon on the Page Definition. This icon resembles a light green down or up arrow.

To use the Reorder Region Items icon:

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

2. Under Items, click the Reorder Region Items icon.
The Reorder Region Items page appears with items laid out in tables. You can edit the position of an item by selecting values for New Line, New Field, Column Span, and Label Alignment attributes. Note that a graphical representation of how the items display appears at the bottom of the page.

3. To edit an item label, enter a new title in the Label field.

4. To change the position of an item, edit the following attributes:

- New Line. Determines if the item displays on the same line as the previous item, or displays on the next line. Select Yes to have an item display as the first field in a new row in the table.

- New Field. Determines if the item displays in the next column or in the same column as the previous item. Select Yes to have the label and value for the item display in a new HTML table cell. Use this attribute in combination with the New Line and Span attributes to control layout.

- Column Span. Defines the value to be used for the COLSPAN attribute in the table cell. The COLSPAN attribute defines the number of columns that it spans across the table.

5. To change label alignment, make a new selection from the Label Alignment list.

6. To change the order in which items display, click the up and down arrows in the far right column. Clicking the arrow moves the item one row up or down.
Note that the order you specify here translates to sequence number in the Sequence attribute on the Edit Page Item page. See "Editing Page Item Attributes".

7. Click Apply Changes.

Tip:
You can also use the Drag and Drop Layout feature to reorder items. See "Using the Drag and Drop Layout Page".

Note:
To change the region in which an item resides, you must edit the item attributes. See "Editing Page Item Attributes".

Using the Drag and Drop Layout Page

You can use the Drag and Drop Layout page to interactively reorder items within a given region, change select item attributes, create new items, or delete existing items.

Topics in this section include:

- Accessing the Drag and Drop Layout Page

- About the Drag and Drop Layout Page

- Creating a New Item

- Editing Existing Items

- Deleting Items

See Also:
"Creating Multiple Items Using Drag and Drop"

Accessing the Drag and Drop Layout Page

You access the Drag and Drop Layout page by either:

- Clicking the Drag and drop icon on the Page Definition. See "About the Drag and Drop Icon".

- Clicking the Reorder Regions Items icon and selecting the Drag and Drop Layout tab. See "Using the Reorder Buttons Icon".

See Also:
"Differences Between Page Items and Application Items"

About the Drag and Drop Layout Page

The Drag and Drop Layout page is divided into two sections: Item palette and Layout region.

The Item palette displays on the left side of the page. You add new items by clicking an item type on the palette and dragging it to the correct position in the Layout region. Note that when you position the cursor over an item type, a tooltip appears.

Use the right side of the page (or Layout region) to position items. To move an item vertically, click the Add Row button to insert an empty row. Then drag and drop the item into the empty row.

See Also:
"Deleting Items"

Creating a New Item

To create a new item on the Drag and Drop Layout page:

1. Navigate to the Drag and Drop Layout page. See "Accessing the Drag and Drop Layout Page".

2. Click an item type in the Item palette on the left side of the page and drag it to the appropriate location in the Layout region.
Note that when you position the cursor over an item type, a tooltip appears.

3. You can reposition the item:

- To move an item horizontally, select the item and drag it to the appropriate position on the page.

- To insert an existing or new item between two existing rows, click the Add Row button and drag it between the existing rows. This creates an empty row where you can then move the item.

4. Edit the item attributes at the of the page.

a. Display Name - Enter an item name. Use this name to retrieve the value of the item. Item names longer than 30 characters cannot be referenced using bind variable syntax.

b. Label - Enter the label for this item. You may include HTML, JavaScript, and shortcuts. You can also use the substitution string #CURRENT_ITEM_NAME# to obtain the name of the item associated with this label.

c. Display Type - Select a display type (if applicable). Note that the select list is restricted to options corresponding to the type of item you are creating. See "About Item Types".

5. Click Next.

6. Optionally, edit the each item's Name and Label.

7. Click Apply Changes.

See Also:
"Creating Multiple Items Using Drag and Drop" and "Editing Page Item Attributes"

About List of Values

If you create an item that requires a list of values (LOV), the Drag and Drop Layout Wizard creates a static inline LOV for you. Note you must edit and fix this LOV once you complete the layout process.

See Also:
"Creating a Static List of Values"

Editing Existing Items

To edit an existing item on the Drag and Drop Layout page:

1. Navigate to the Drag and Drop Layout page. See "Accessing the Drag and Drop Layout Page".

2. To reposition the item:

- To move an item horizontally, select the item and drag it to the appropriate position on the page.

- To insert an existing or new item between two existing rows, click the Add Row button and drag it between the existing rows. This creates an empty row where you can then move the item.

3. If required, select an item and edit its attributes at the of the page.

a. Display Name - Enter an item name. Use this name retrieve the value of the item. Item names longer than 30 characters cannot be referenced using bind variable syntax.

b. Label - Enter the label for this item. You may include HTML, JavaScript, and shortcuts. You can also use the substitution string #CURRENT_ITEM_NAME# to obtain the name of the item associated with this label.

c. Display Type - Select a display type (if applicable). Note that the select list is restricted to options corresponding to the type of item you are creating. See "About Item Types". See "About Item Types".

4. Click Next.

5. Optionally, edit the each item's Name and Label.

6. Click Apply Changes.

Note:
To change the region in which an item resides, you must edit the item attributes. See "Editing Page Item Attributes".

Deleting Items

To delete an item, click it and drag it to the Recycle box at the bottom of the page. If you delete an existing item, it appears in the Recycle box and can be retrieved until you click Apply Changes on the next page. Note that if you drop a new item you have just created in the Recycle box, it instantly disappears and cannot be retrieved.

Referencing Item Values

You can reference item values stored in session state in regions, computations, processes, validation, and branches. Table 5-9 describes the supported syntax for referencing item values.

See Also:
"Managing Session State Values"

Table 5-9 Syntax for Referencing Item Values

Type

Syntax

Description

SQL

:MY_ITEM

Standard bind variable syntax for items whose names are 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 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

&MY_ITEM

Static text.

Static Text (exact)

&MY_ITEM.

Static text. Exact Substitution.

You can set the value of an item in your application using any of the following methods:

- For page-level items, use the Source Attribute to set the item value.

From the Page Definition, select the item name to view the Edit Page Item page. Scroll down to Source and edit the appropriate fields.

You can also set the value of an item in any region based on PL/SQL or a process using the following syntax:

BEGIN
:MY_ITEM :=  'new value';
END;

- Pass the value on a URL reference using f?p syntax. For example:

f?p=100:101:10636547268728380919::NO::MY_ITEM:ABC

- Set the value using a computation. Computations are designed to set item values. For example:

TO_CHAR(SYSDATE,'Day DD Month, YYYY');

- Use the PL/SQL API to set an item value within a PL/SQL context. For example:

APEX_UTIL.SET_SESSION_STATE('MY_ITEM',SYSDATE);

See Also:
"Clearing Session State", "Oracle Application Express APIs", and "About Cross-Site Scripting Protection"

Displaying Conditional or Read-Only Page Items

You can choose to have an item display conditionally or as read-only by editing attributes on the Edit Pages Item page.

To display a conditional or read-only item:

1. Create the item. See "Creating Page-Level Items".

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

3. Under Items, select the item name.
The Edit Page Item page appears.

4. To display an item conditionally:

a. Scroll down to Conditions.

b. Make a selection from the Condition Type list.

c. Enter an expression in the fields provided.

5. To make an item read-only:

a. Scroll down to Read Only Display Settings.

b. Make a selection from the Read Only Condition Type list.

c. Enter an expression in the fields provided.

6. Click Apply Changes.

Working with a Multiple Select List Item

A multiple select item renders as a multiple select list form element which can be either a Multiselect List or Shuttle item type. When submitted, selected values are returned in a single colon-delimited string. You can handle values in this format in two ways:

- Using the INSTR function

- Using the APEX_UTIL.STRING_TO_TABLE function

Using APEX_UTIL.STRING_TO_TABLE to Convert Selected Values

Suppose you had a report on the EMP and DEPT tables that is limited by the departments selected from a Department multiple select list. First, you create the multiple select item, P1_DEPTNO, using the following query:

SELECT dname, deptno
FROM dept

Second, you return only those employees within the selected departments as follows:

SELECT ename, job, sal, comm, dname
FROM emp e, dept d
WHERE d.deptno = e.deptno
AND instr(':'||:P1_DEPTNO||':',':'||e.deptno||':') > 0

Next, assume you want to programmatically step through the values selected in the multiple select item, P1_DEPTNO. To accomplish this, you would convert the colon-delimited string into a PL/SQL array using the APEX_UTIL.STRING_TO_TABLE function. The following example demonstrates how to insert the selected departments into an audit table containing the date of the query.

DECLARE
l_selected APEX_APPLICATION_GLOBAL.VC_ARR2;
BEGIN
--
-- Convert the colon separated string of values into
-- a PL/SQL array

l_selected := APEX_UTIL.STRING_TO_TABLE(:P1_DEPTNO);

--
-- Loop over array to insert department numbers and sysdate
--

FOR i IN 1..l_selected.count
LOOP
INSERT INTO report_audit_table (report_date, selected_department)
VALUES (sysdate, l_selected(i));
END LOOP;
END;

See Also:
"STRING_TO_TABLE Function"

Populating an Alternative Date Picker Format for an Application

If you need to create a Date Picker item, but the format you need does not appear in the Display As list, select Date Picker (use application format mask). When an application uses this type of date picker, the Application Express engine derives the date format from an item named PICK_DATE_FORMAT_MASK. You can populate this item in two ways:

- By defining an application substitution string named PICK_DATE_FORMAT_MASK

- By creating an application-level item named PICK_DATE_FORMAT_MASK

Defining PICK_DATE_FORMAT_MASK as an Application Substitution String

One approach to populating PICK_DATE_FORMAT_MASK is to create an application substitution string. You define application-level substitution strings on the Edit Definition page. Remember that an application-level substitution string is a static value and cannot be altered at run time.

To define a new application substitution string named PICK_DATE_FORMAT_MASK:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Application, click Application Definition.

5. Scroll down to Substitutions.

6. Create a new static substitution string named PICK_DATE_FORMAT_MASK:

a. In Substitution String, enter the name PICK_DATE_FORMAT_MASK.

b. In Substitution Value, enter a value for your date format (for example, Month DD, YYYY).

Defining an Application-Level Item Named PICK_DATE_FORMAT_MASK

Another approach to populating PICK_DATE_FORMAT_MASK is to create an application-level item named PICK_DATE_FORMAT_MASK. This approach enables you to control any items rendered as Date Picker (use application format mask) by simply setting the value of this item. Plus, you can set the value of PICK_DATE_FORMAT_MASK using a computation from anywhere within your application.

If you want to provide the user with a list of date formats as preferences, you will need to create an application-level item named PICK_DATE_FORMAT_MASK and then use a computation to set the value of this item based upon the user's selection.

See Also:
"Understanding Application-Level Items"

Populating an Alternative Date Picker Format for a Specific Item

If you need to create a Date Picker item, but the format you need does not appear in the Display As list, select Date Picker (use item format mask). This item type enables you to control the Date Picker format mask using the item-level format mask. When an application uses this type of date picker, the Application Express engine derives the date format from the Format Mask attribute on the Edit Page Item page.

See Also:
"Editing Page Item Attributes"

Understanding Application-Level Items

Application-level items do not display, but are used as global variables to the application. You can use an application item as a global variable.

Topics in this section include:

- Creating an Application-level Item

- Accessing Application Item History

- Editing Application-level Item Attributes

See Also:
"Differences Between Page Items and Application Items" and "Referencing Item Values"

Creating an Application-level Item

To create a new application-level item:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. When Application Builder appears, click Shared Components.

5. Under Logic, select Application Items.
The Application Items page appears.

6. To create a new application item, click Create.

7. Follow the on-screen instructions.

About the Application Items Page

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

- Icons (the default) displays each application item as a large icon. To edit an application item, click the appropriate icon.

- Details displays each application item as a line in a report. To edit an application item, click the name.

Accessing Application Item History

You can view a history of changes to application items by clicking History at the top of the Application Items page.

Editing Application-level Item Attributes

Once you create an application-level item, you can edit it on the Create/Edit Application Item page.

To edit application-level item attributes:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

4. When Application Builder appears, click Shared Components.

5. Under Logic, select Application Items.
The Application Items page appears.

6. Select an application item.
The Create/Edit Application Item page appears.

7. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

8. Click Apply Changes.

See Also:
"About Cross-Site Scripting Protection"

About Navigation Alternatives

The Create/Edit Application Item page is divided into the following sections: Name, Security, Configuration, and Comments.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Creating Lists of Values

A list of values (LOV) is a static or dynamic set of values used to display a specific type of page item, such as popup lists of values, a select list, a check box, a radio group, or multiple select lists.

Creating a LOV as a shared component has a number of advantages:

- It can be added to any page within an application.

- All LOV definitions are stored in one location, making them easy to locate and update.

Topics in this section include:

- Creating a Named LOV at the Application Level

- About Static LOVs

- Editing an Existing LOV

- Referencing Session State Within an LOV

- Referencing a Null Value in an Item Based on an LOV

- Accessing LOV Reports

See Also:
"Creating a Static List of Values" and "Working with Shared Components"

Creating a Named LOV at the Application Level

You define named (or shared) LOVs at the application level by running the Create LOV Wizard and adding them to the List of Values repository. All LOVs can be defined as static or dynamic. Static lists are based on predefined pairs of display values and return values. Dynamic lists are based on a SQL query you write that selects values from a table.

To create a named LOV:

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

2. Select an application.
The Application home page appears.

3. Click the Shared Components icon.

4. Under User Interface, select Lists of Values.
The Lists of Values page appears.

5. To create a new LOV, click Create.

6. Follow the on-screen instructions.
New named LOVs are added to the List of Values repository. Note to add the LOV to a page you must edit the appropriate item or column and select the named LOV.

See Also:
"Defining a Column as a List of Values"

About the List of Values Page

Once you create an LOV, it appears on the List of Values page.

Use the Navigation bar at the top of the page to search for a LOV by name or change the page display. For example, you can change the default display by making a selection from View list. Available options include:

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

- Details displays each LOV as a line in a report. To edit an LOV, click the name.

About Static LOVs

Static LOVs are based on a static list of display values and return values you specify when you run the Create LOV Wizard. To create a static LOV, run the Create LOV Wizard and select the LOV type Static. Oracle Application Express stores the display values, return values, and sort sequence you specify in the List of Values repository. Once you add a static LOV to the repository, you can create an item and display it as a check box, radio group, select list, or popup list based on this definition.

Editing an Existing LOV

To edit an existing LOV, select the LOV on the Lists of Values page.

To edit an LOV:

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

2. Select an application.

3. Click Shared Components.

4. Under User Interface, select Lists of Values.

5. Select an LOV.
The Edit List of Values page appears.

6. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

7. Click Apply Changes.

About Navigation Alternatives

The Edit List of Values page is divided into the following sections: Name, Subscription, Source, and Comments.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

See Also:
"About the Edit All Icon"

Bulk Edit of Static LOVs

You can edit the display values of all static LOVs by clicking the Grid Edit button on the Edit List of Values page.

To perform a bulk edit of static LOVs:

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

2. Select an application.

3. Click Shared Components.

4. Under User Interface, select Lists of Values.
By default, LOVs display as icons.

5. Change the default display. Select Details from the View list and click Go.

6. Locate the Static LOV and select the LOV name.

7. Click the Grid Edit button located under Subscription.

8. Edit the appropriate display values and click Apply Changes.

Referencing Session State Within an LOV

You can reference session state by using bind variables. Keep in mind that referencing session state makes an LOV a bit less reusable, but is still a recommended development practice. In the following example, this LOV only works if the item called my_deptno contains a valid department number.

SELECT ename, empno FROM emp WHERE deptno = :P1_DEPTNO

Referencing a Null Value in an Item Based on an LOV

LOVs have a null display value option and a null return value option. The null display value is the value the end user sees in the list indicating the no selection from the proper (non-null) values of the list will be made. When a user selects a null display value, the LOV's null return value is sent to the application when the page is submitted. If the developer has left the null return value unspecified (or empty), the actual value transmitted is not an empty string or an Oracle null, but the literal %null%. The application must be prepared to deal with this literal and treat is as the null selection.

Be aware of this behavior when writing code to evaluate submitted values. For example, suppose a page evaluates the submitted item P1_X and you need to use the PL/SQL expression replace(:P1_X,'%'||'null%',null) to prepare the item for permanent storage in session state or for passing to DML or other APIs.

To avoid problems, be aware of the appropriate way to code %null% in expressions that occur in page computations, processes, and validations. You must break up the string so that the application does not replace %null% with a null value in the page metadata when it is saved. Consider the following example:

'%'||'null%'

Accessing LOV Reports

Application Builder includes a number of reports designed to help you better manage LOVs.

To access LOV reports:

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

2. Select an application.

3. When Application Builder appears, click Shared Components.

4. Under User Interface, select Lists of Values.

5. Select one of the following tabs at the top of the page:

- Search

- Subscription

- Utilization

- History

6. Follow the on-screen instructions.

Search

Click Search to display the Search Dynamic Lists of Values page. Use this page to search the queries that make up dynamic LOVs. Enter a query in the Query Contains field and click Go.

Subscription

Click Subscription to display the List of Values Subscription page. This page displays all subscribed LOVs in your application.

Utilization

Click Utilization to display the List of Values Utilization page. This page displays LOVs used in the current application. To edit an LOV, click the LOV name.

History

Click History to display the List of Values History page. This page displays a history of recently changed LOVs by date.

Creating Dependent Select Lists

You can use a select list to determine the range of values of another select list on the same page. You can achieve this functionality by having a driving select list submit values to a subsequent select list. You incorporate these values in the subsequent select list as a bind variable in the WHERE clause of its query.

To have one LOV drive another LOV:

- Create a basic form.

- Define two lists of values. Note that the driving LOV must submit the page after a value is chosen.

- Define a branch that branches back to the current page.

Consider the following example. The first LOV enables the user to pick a state:

SELECT state_name d, state_id v
FROM states

The second LOV selects the county name and county ID based on the state selected in the first LOV:

SELECT county_name d, county_id v
FROM counties
WHERE state_id = :P1_STATE_ID

See Also:
"Creating Forms", "Creating Lists of Values", and "Controlling Navigation Using Branches"

Using Shortcuts

By using shortcuts you can avoid repetitive coding of HTML or PL/SQL functions. You can use a shortcut to define a page control such as a button, HTML text, a PL/SQL procedure, or HTML. Once defined, you can invoke a shortcut using specific syntax unique to the location in which the shortcut is used. Shortcuts can be referenced many times, thus reducing code redundancy.

This section contains the following topics:

- About Shortcut Types

- Defining Shortcuts

- Editing Existing Shortcuts

- Accessing Shortcut Reports

About Shortcut Types

When you create a new shortcut, you must specify the type of shortcut you want to create. Oracle Application Express supports the following shortcut types:

- PL/SQL Function Body

- HTML Text

- HTML Text with Escaped Special Characters

- Image

- Text with JavaScript Escaped Single Quotes

- Message

- Message with JavaScript Escaped Special Quotes

Text with JavaScript Escaped Single Quotes

Use this type of shortcut to reference a shortcut inside of a JavaScript literal string. This shortcut defines a text string. When the shortcut is referenced, it escapes the single quotation marks required for JavaScript.

Message

Use this type of shortcut to reference a translatable message at run time. Note that since this shortcut does not have a shortcut body, the name of the shortcut must match the corresponding message name. At run time, the name of the shortcut expands to the text of the translatable message for the current language.

Message with JavaScript Escaped Single Quotes

Use this type of shortcut to reference a shortcut inside of JavaScript literal string and reference a translatable message at run time.

See Also:
"About Translating an Application and Globalization Support"

Defining Shortcuts

Before you can incorporate a shortcut in your application, you must define it and add it to the Shortcuts repository. You reference new shortcuts using the following syntax:

"MY_SHORTCUT"

Note that the shortcut name must be capitalized and enclosed in quotation marks.

To define a new shortcut:

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

2. Select an application.

3. When Application Builder appears, click Shared Components.

4. Under User Interface, select Shortcuts.

5. Click Create.

6. Select one of the following creation methods:

- From Scratch

- As a Copy of an Existing Shortcut

7. Follow the on-screen instructions.

New shortcuts are added to the Shortcut repository and are available for use within the following locations:

- The Region Source attribute of regions defined as HTML Text (with shortcuts). See "Understanding Regions".

- Region Header and Footer Text attribute. See "Specifying a Region Header and Footer".

- Item Label attributes and Default Value attribute. See "Items".

- Region Templates attributes. See "Editing Templates".

About the Shortcuts Page

Once you create a shortcut, it appears on the Shortcuts page. You control how the page displays by making a selection from the View list. Available options include:

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

- Details displays each shortcut as a line in a report. To edit a shortcut, click the name.

Editing Existing Shortcuts

Once you create a shortcut, you can alter it by editing attributes on the Edit Shortcut page.

To edit an existing shortcut:

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

2. Select an application.

3. Click Shared Components.

4. Under User Interface, select Shortcuts.

5. Select a shortcut.
The Edit Shortcut page appears.

6. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

7. Click Apply Changes.

About Navigation Alternatives

The Edit Shortcut page is divided into the following sections: Name, Subscription, Source, Configuration, and Comments.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Accessing Shortcut Reports

Application Builder includes a number of reports designed to help you better manage shortcuts.

To access shortcut reports:

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

2. Select an application.

3. When Application Builder appears, click Shared Components.

4. Under User Interface, select Shortcuts.

5. Click one of the following tabs:

- Subscription

- History

Note:
The Subscription and History tabs only appear after you create a shortcut.

Subscribed Shortcuts

Click Subscription to display the Subscribed Shortcuts page. This page displays all subscribed shortcuts in your application.

Shortcut History

Click History to display the Shortcut History page. This page displays a history of recently changed shortcuts by date.

Using the Find Icon

You can search for items, pages, queries, tables, PL/SQL code, images, or cascading style sheets by clicking the Find icon on numerous pages within Application Builder.

This section contains the following topics:

- About the Find Icon

- About the Item Finder

- Using the Page Finder

- Using the Query Finder

- Using the Table Finder

- Using the PL/SQL Finder

- Using the Images Finder

- Using the CSS Finder

About the Find Icon

The Find icon resembles a flashlight and often displays to the right of the Run Page and Edit Page icons as shown in the following illustration. The Find icon displays on many pages in Application Builder, including the Application Home page, the Page Definition, application attribute pages, and numerous pages for creating and managing shared components.

See Also:
"About the Application Home Page"

About the Item Finder

In Application Builder, an item can be a text field, text area, password, select list, check box, and so on. You can use the Item Finder to search for items within the current application or within the schema associated with the workspace.

See Also:
"Understanding Page-Level Items"

To search for an item using the Item Finder:

1. Click the Find icon.
The Item Finder appears.

A search bar displays at the top of the page and contains the following controls:

- Search. Search for an item name. Enter case insensitive keywords in the Search field and click Go. To view all items, leave the Search field blank and click Go.

- Page. Search for pages that contain items. Enter a page number in the Page field or select a page number from the list and click Go. To view all pages containing items, leave the Page field blank and click Go.

- Display. Determine how many rows display in the resulting report. To change the number of rows that display, make a selection from the Display list and click Go.

A Item Finder report appears, displaying the item name, label, item type, and associated page number.

2. To restrict the report to display just items on a specific page, click the appropriate page number in the far right column.
Note the page number you select appears in the Page field at the top of the page. To expand the view to all pages, delete the page number in the Page field and click Go.

3. To edit a specific item, navigate to the appropriate item. See "Editing Page Item Attributes" and "Using the Edit All Icon to Edit Multiple Items".

Using the Page Finder

A page (or Page Definition) is the basic building block of an application. You can use the Page Finder to search for pages within the current application or within the schema associated with the workspace.

To search for a page:

1. Click the Find icon.

2. Select the Pages tab.
The Page Finder appears.

A search bar displays at the top of the page and contains the following controls:

- Search. Search for a page name. Enter case insensitive keywords in the Search field and click Go. To view all pages, leave the Search field blank and click Go.

- Display. Determine how many rows display in the resulting report. To change the number of rows that display, make a selection from the Display list and click Go.

The Page Finder report appears, displaying the page number, page name, page alias, title, tab set, and counts of the number of items and regions on the page.

3. To link to the Items page, click the page number.

See Also:
"About the Page Definition" and "Editing a Page Definition"

Using the Query Finder

You can use the Query Finder to locate a query within your application or within the schema associated with the workspace.

To search for a query using the Query Finder:

1. Click the Find icon.

2. Select the Queries tab.
The Query Finder appears.

A search bar displays at the top of the page and contains the following controls:

- Search. Search for query statements. Enter case insensitive keywords in the Search field and click Go. To view all queries, leave the Search field blank and click Go.

- Display. Determine how many rows display in the resulting report. To change the number of rows that display, make a selection from the Display list and click Go.

The Query Finder report appears, displaying the page number, page name, the region containing the query, and the query source.

3. To link to the Items page, click the page number.

See Also:
"About the Page Definition" and "Editing a Page Definition"

Using the Table Finder

You can use the Table Finder to view tables within the schema associated with the workspace.

To view tables associated within the current schema:

1. Click the Find icon.

2. Select the Tables tab.
The Table Finder appears.

A search bar displaying the selected schema displays at the top of the page and contains the following controls:

- Search. Search for a table name. Enter case insensitive keywords in the Search field and click Go. To view all tables, leave the Search field blank and click Go.

- Display. Determine how many rows display in the resulting report. To change the number of rows that display, make a selection from the Display list and click Go.

- Views. Select the Views checkbox and click Go to include views in the resulting report.

The Table Finder report appears displaying the table name, the number of rows, and the object type.

3. Select a table name.
A table definition appears on the right side of the page.

This report displays the column names, data type, length, precision, and scale as well as the SQL necessary to re-create the table appears at the bottom of the page.

See Also:
"Managing Tables"

Using the PL/SQL Finder

You can use the PL/SQL Finder to locate and view details about stored procedures, functions, and packages associated with each object within the schema associated with the workspace.

To search for PL/SQL code in the current schema:

1. Click the Find icon.

2. Select the PL/SQL tab.
The PL/SQL Finder appears.

A search bar displays at the top of the page contains the following controls:

- Search. Search for procedure, function, or package names. Enter case insensitive keywords in the Search field and click Go. To view all, leave the Search field blank and click Go.

- Display. Determine how many rows display in the resulting report. To change the number of rows that display, make a selection from the Display list and click Go.

- Procedures, Functions, or Packages. Select at least one check box and click Go to include procedures, functions, and packages in the report. You must select at least one check box to return results.

The PL/SQL Finder report appears.

3. To view additional details, select the procedure, function, or package name.

The procedure, package, or function name appears as well as additional information including the owner, source name, source type, return type, argument names, data types, and IN/OUT parameters.

See Also:
"Managing Database Objects with Object Browser", specifically "Managing Packages", "Managing Procedures", and "Managing Functions"

Using the Images Finder

You can use the Images Finder to identify images available to the current application.

To view available images:

1. Click the Find icon.

2. Select the Images tab.
The Images Finder appears.

A search bar displays at the top of the page and contains the following controls:

- Search. Search for image names. Enter case insensitive keywords in the Search field and click Go. To view all, leave the Search field blank and click Go.

- Icon Size. Select the size of icon you wish to search for and click Go.

- Display. Determine how many rows display in the resulting report. To change the number of rows that display, make a selection from the Display list and click Go.

- Columns. Select the number of columns to view per row and click Go.

3. From Show, select the type of images to view. Options include:

- Standard Images

- Workspace Images

- Application Images

See Also:
"Managing Database Objects with Object Browser", specifically "Managing Packages", "Managing Procedures", and "Managing Functions"

Using the CSS Finder

You can use the CSS Finder to view cascading style sheets that are available to any application regardless of theme.

To view available cascading style sheets:

1. Click the Find icon.

2. Select the CSS tab.
The CSS Finder appears.

A search bar displays at the top of the page and contains the following controls:

- Search. Enter case insensitive keywords in the Search field and click Go. To view all, leave the Search field blank and click Go.

- Category. Select a CSS category and click Go. Available options include:

- Absolute Sizes

- Anchor Tags

- Relative Sizes

- Display. Determine how many rows display in the resulting report. To change the number of rows that display, make a selection from the Display list and click Go.

See Also:
"About Cascading Style Sheets" and "Using Custom Cascading Style Sheets"

Controlling Access to Applications, Pages, and Page Components

You can control access to an application, individual pages, or page components by creating an access control list.

This section contains the following topics:

- How the Access Control List Works

- Creating an Access Control List

- Selecting an Application Mode and Adding Users

- Controlling Access for Pages and Page Components

See Also:
"Building Queries with Query Builder"

See Tutorial:
"How to Build an Access Control Page" in Oracle Database Application Express Advanced Tutorials

How the Access Control List Works

You create an access control list by running the Access Control Wizard. The Access Control Wizard creates a new page named Access Control Administration. This page contains a list of application modes and an Access Control List. Once you create the Access Control Administration page, you:

1. Run the Access Control Administration page.

2. Select one of the following application modes:

- Full access to all, access control list not used.

- Restricted access. Only users defined in the access control list are allowed.

- Public read only. Edit and administrative privileges controlled by access control list.

- Administrative access only.

3. Add users to the Access Control List.

In addition to creating the Access Control Administration page, the Access Control Wizard also creates:

- two tables within the application's default schema to manage the access control

- the authorization schemes that correspond to the application mode list options

- the privileges available in the Access Control List

You can control access to a specific page or page component by selecting one of these authorization schemes on the page or component attributes pages. Once you create an Access Control, you can customize the page, tables and values to suit the specific needs of your application.

See Also:
"Attaching an Authorization Scheme to an Application"

Creating an Access Control List

You create an access control list by creating a new page. You can create a new page on the Application home page, while viewing a Page Definition, or by clicking Create on the Developer toolbar.

Topics in this section include:

- Creating an Access Control from the Application Home Page

- Creating an Access Control from the Page Definition

- Creating an Access Control from the Page Definition

Creating an Access Control from the Application Home Page

To create an access control list from the Application home page:

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

2. Select an application.
The Application home page appears.

3. Click Create Page.

4. For page type, select Access Control and click Next.
The Access Control Wizard appears.

5. Specify a page number and click Next.

6. Select a tab option and click Next.

7. Review the confirmation page and click Finish.

Creating an Access Control from the Page Definition

To create an access control list from the Page Definition:

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

2. Click the Create button next to the navigation bar at the top of the page.

3. Select New page and click Next.

4. For page type, select Access Control and click Next.
The Access Control Wizard appears.

5. Specify a page number and click Next.

6. Select a tab option and click Next.

7. Review the confirmation page and click Finish.

Creating an Access Control List from the Developer Toolbar

To create an access control list from the Developer toolbar:

1. Run the application. See "Running a Page or Application".

2. On the Developer toolbar, click Create.
The New Component Wizard appears.

3. Select New page and click Next.

4. For page type, select Access Control and click Next.
The Access Control Wizard appears.

5. Specify a page number and click Next.

6. Select a tab option and click Next.

7. Review the confirmation page and click Finish.

Selecting an Application Mode and Adding Users

You can control access to an application by running the Access Control Administration page, selecting an application mode, and then adding users to the Access Control list.

This section contains the following topics:

- Selecting an Application Mode

- Adding Users to the Access Control List and Selecting Privileges

- Removing Users from the Access Control List

Selecting an Application Mode

To select an application mode:

1. Create an access control list. See "Creating an Access Control List".
The wizard creates a new page named Access Control Administration.

2. Run the Access Control Administration page. See "Running a Page or Application".

3. Select an Application Mode. Options include:

- Full access to all, access control list not used.

Select this option to enable all users access to an application.

- Restricted access. Only users defined in the access control list are allowed.

Select this option to restrict access to users on the Access Control List. Only users on the Access Control List can view pages and components associated with an authorization scheme.

- Public read only. Edit and administrative privileges controlled by access control list.

Provides public access to pages and components associated with the access control - view authorization scheme.

- Administrative access only.

Only users with Administrator privileges can access pages or components associated with an authorization scheme.

4. Click Set Application Mode.

Note that the user interface of your page is dependent upon the theme you selected for your application. See "Managing Themes".

Next, add users to the Access Control List.

Adding Users to the Access Control List and Selecting Privileges

To add users to the Access Control List:

1. Under Access Control List, click Add User.
A new row appears.

2. Enter a user in the Username field.

3. Associate a privilege with the user. Available options include:

- Administrator

- Edit

- View

4. Click Apply Changes.

5. Repeat steps 1 to 5 for all users.

Removing Users from the Access Control List

To remove users from the Access Control List:

1. Select the user to be removed by selecting the check box to the left of the user name.

2. Click Delete.

Controlling Access for Pages and Page Components

The Access Control Wizard creates authorization schemes that correspond to the application mode list options and the privileges available in the Access Control List.

You can control access to a specific page or page component by selecting one of the following authorization schemes on the page or component attributes pages:

- access control administrator. Only users with Administrator privileges can view the page or component.

- access control - edit. Users with both Edit and Administrator privileges can view the page or component. Users with View privileges cannot view the page or component.

- access control - view. Users with Administrator, Edit, or View privileges can view the page or component.

- Not access control administrator. Users with Administrator privileges cannot view the page or component.

- Not access control - edit. Users with both Edit and Administrator privileges cannot view the page or component. Users with View privileges can view the page or component.

- Not access control - view. Users with Administrator, Edit, or View privileges cannot view the page or component.

See Also:
"Attaching an Authorization Scheme to an Application, Page, or Components"

Incorporating JavaScript into an Application

Adding JavaScript to a Web application is a great way to add features that mimic those found in client/server applications without sacrificing all the benefits of Web deployment. Oracle Application Express includes multiple built-in interfaces especially designed for adding JavaScript.

Remember that JavaScript is not appropriate for data intensive validations. For example, to verify that a name is contained within a large database table, you would need to pull down every record to the client, creating a huge HTML document. In general, complex operations are much better suited for server-side Application Express validations instead of JavaScript.

This section contains the following topics:

- Referencing Items Using JavaScript

- Incorporating JavaScript Functions

- Calling JavaScript from a Button

See Also:
"Understanding Validations"

Referencing Items Using JavaScript

When you reference an item, the best approach is to reference by ID. If you view the HTML source of an Oracle Application Express page in a Web browser, you would notice that all items have an id attribute. This id corresponds to the name of the item, not the item label. For example, if you create an item with the name P1_FIRST_NAME and a label of First Name, the ID will be P1_FIRST_NAME.

Knowing the item ID enables you to use the JavaScript method getElementById() to get and set item attributes and values. The following example demonstrates how to reference an item by ID and display its value in an alert box.

<script language="JavaScript1.1" type="text/javascript">
function firstName(){
alert('First Name is ' + document.getElementById('P1_FIRST_NAME').value );
}
// or a more generic version would be
function displayValue(id){
alert('The Value is ' + document.getElementById(id).value );
}
</script>

// Then add the following to the "Form Element Attributes" Attribute of the item:
onchange="displayValue('P1_FIRST_NAME');"

Incorporating JavaScript Functions

There are two primary places to include JavaScript functions:

- In the HTML Header attribute of the page

- In a .js file in the page template

See Also:
"Text with JavaScript Escaped Single Quotes" for information about referencing a shortcut inside of a JavaScript literal string

Incorporating JavaScript into the HTML Header Attribute

One way to include JavaScript into your application is to add it to the HTML Header attribute of the page. This is a good approach for functions that are very specific to a page as well as a convenient way to test a function before you include it in the .js file.

You can add JavaScript functions to a page by simply entering the code into the HTML Header attribute of the Page Attributes page. In the following example, adding the code would make the test function accessible from anywhere on the current page.

To add JavaScript code in the HTML Header attribute:

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

2. Select an application.

3. Select a page.

4. Under Page, click the Edit page attributes icon.

5. Scroll down to HTML Header.

6. Enter code into HTML Header and click Apply Changes.

For example, adding the following would test a function accessible from anywhere on the current page.

<script type="text/javascript">
function test(){
window.alert('This is a test.');
}
</script>

See Also:
"HTML Header"

Including JavaScript in a .js File Referenced by the Page Template

In Oracle Application Express, you can reference a .js file in the page template. This approach makes all the JavaScript in that file accessible to the application. This is the most efficient approach since a .js file loads on the first page view of your application and is then cached by the browser.

The following demonstrates how to include a .js file in the header section of a page template. Note the line script src= that appears in bold.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>#TITLE#</title>
#HEAD#
<script src="http://myserver.myport/my_images/custom.js" type="text/javascript"></script>
</head>
<body #ONLOAD#>#FORM_OPEN#

See Also:
"Page Templates"

Calling JavaScript from a Button

Calling JavaScript from a button is a great way to confirm a request. Oracle Application Express uses this technique for the delete operation of most objects. For example, when you delete a button, a JavaScript message appears asking you to confirm your request. Consider the following example:

<script type="text/javascript">
function deleteConfirm(msg)
{
var confDel = msg;
if(confDel ==null)
confDel= confirm("Would you like to perform this delete action?");
else
confDel= confirm(msg);

if (confDel== true)
doSubmit('Delete');
}
</script>

This example creates a function to confirm a delete action and then calls that function from a button. Note that the function optionally submits the page and sets the value of the internal variable :REQUEST to Delete, thus performing the deletion using a process that conditionally executes based on the value of the request.

Note that when you create the button, you would need to select Action Redirect to URL without submitting page. Then, you would specify a URL target such as the following:

confirmDelete('Would you like to perform this delete action?');

See Also:
"Creating a Button Using a Wizard"

Creating a Help Page

Application Builder includes built-in attributes to create Help for your application. Creating Help for your application involves the following steps:

1. Create a dedicated Help page and Help region.

2. Define page Help text.

3. Define item Help text.

4. Create a navigation bar icon to link to your Help page.

Help created in Application Builder displays on a dedicated Help page. To access Help, users click a link that takes them to a dedicated Help page. This Help page displays page and item Help topics specific to the page they are viewing.

Topics in this section include:

- Creating a Help Page and Region

- Defining Help Text

- Creating a Help Navigation Bar Entry

Creating a Help Page and Region

The first step in creating Help for your application is to create a dedicated page and Help Text region.

To create a new Help Text region:

1. Create a new page for your Help. See "Managing Pages in an Application".

2. Navigate to the Page Definition of your Help page. See "Accessing a Page Definition".

3. Under Regions, the Create icon.

4. When prompted to select a region type, select Help Text.

5. Follow the on-screen instructions.

Defining Help Text

You define Help text for a page or single item by editing attributes. Ideally, you would define these attributes as you create your application. For simplicity, however, the following procedures describe how to define this text after the fact.

See Also:
"Item Help"

Topics in this section include:

- Defining Help for a Page

- Defining Help Text for an Item

- Editing Multiple Item Help Topics Simultaneously

Defining Help for a Page

To define page Help text:

1. Navigate to the Page Definition for the page for which you want to add page Help. See "Accessing a Page Definition".

2. Under Page, click the Edit page attributes icon to view the existing page attributes.

3. Scroll down to Help.

4. Enter your Help text in the field provided.

5. Click Apply Changes.

Repeat the previous procedure for each page requiring page Help text.

Defining Help Text for an Item

To define item Help text for an item:

1. Navigate to the Page Definition for the page for which you want to add item Help. See "Accessing a Page Definition".

2. Under Items, click the name of the item you want to edit.

3. Scroll down to Help Text.

4. Enter your Help text in the field provided.

5. Click Apply Change.

Repeat the previous procedure for each item requiring Help text.

Editing Multiple Item Help Topics Simultaneously

If you are including item Help in your application, you can edit multiple item Help topics at once using the Bulk Edit Item Help report.

Accessing the Bulk Edit Item Help Report

To view the Bulk Edit Item Help report:

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

2. Select an application.

3. On the Tasks list, click Application Reports.

4. Click Page Components.

5. Under Items, click Item Help Text.
A report displays at the bottom of the page.

6. In Bulk Item Help Report, you can:

- Update existing Help topics. Edit the Help text that appears and click Apply Changes.

- Link to the Page Definition containing the item by clicking the page number.

- Link to the Page Item by clicking the item name.

Seeding Item Help Topics

If your application does not yet contain item Help, you can perform a mass update of default Help text.

To seed item Help topics:

1. Access the Bulk Edit Item Help report as described in the previous topic.

2. Click Seed Item Help Text.

3. In Default Help Text, enter the default text to appear in all Help topics.

4. Click Apply Changes.

Searching for Existing Item Help Topics

You can search for existing Help text, or for an item label.

To search for existing item Help topic:

1. In Help Contains, enter keywords.

2. Click Go.

Searching for an Item Label

To search for an item label:

1. In Help Contains, enter keywords.

2. Click Go.

See Also:
"Viewing Application Reports"

Creating a Help Navigation Bar Entry

Once you have created your Help, the next step is to create a navigation bar entry so users can link to it.

To create a navigation bar entry:

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

2. Under Navigation Bar, click the Create icon.

3. For Attributes:

a. Sequence - Specify the sequence for this component. The sequence determines the order of evaluation.

b. Alt Tag Text - Enter ALT text for navigation icons that are images. If you do not specify an image name, then this text displays.

c. Icon Image Name - Enter the name of the image that displays.

d. Image Height - Enter the height of the image.

e. Image Width - Enter the width of the image.

f. Text - Enter additional text to display with the image. You can include text or use icons with no text. This attribute is optional and can be translated.

g. Click Next.

Next, specify the target location.

4. For Target:

a. Target is a - Select Page in this application.

b. Page - Specify the page number of the help page you created in "Creating a Help Page and Region".

c. Request - Enter the following:

&APP_PAGE_ID.

By specifying substitution string &APP_PAGE_ID as the Request, you are instructing the Application Express engine to display Help text for the current page when the user clicks this icon.

d. Click Next.

5. Click Create.

6 Adding Navigation

When you build an application, you can include different types of navigation controls, such as navigation bar entries, tabs, breadcrumbs, lists, and trees. This section describes how to implement navigation in your application.

Navigation controls are shared components, so you create the specific type of navigation control at the application level on the Shared Components page. After that, you can add them to any page within your application.

This section contains the following topics:

- Creating Tabs

- Creating Lists

- Creating Breadcrumbs

- Creating Trees

- Creating a Navigation Bar Entry

- Controlling Navigation Using Branches

See Also:

- "Working with Shared Components"

- "About the Page Definition"

- "Controlling Page Layout and User Interface"

Creating Tabs

Tabs are an effective way to navigate users between pages of an application. You can create a tabbed application look by using parent tabs, standard tabs, and lists.

Application Builder includes two different types of tabs:

- Standard tabs

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

- Parent tabs

A parent tab set functions as a container to hold a group of standard tabs. Parent tabs give users another level of navigation as well as a context (or sense of place) within the application. You can use parent tabs to link users to a specific URL associated with a specific page.

Topics in this section include:

- About Template Support

- About the Tabs Section of the Page Definition

- Using the Reorder Tabs Icon

- About the Tabs Page

- How to Create a Tab

- Editing Tabs

- Accessing Tab Reports

Note:
When running the Create Application Wizard, you have the option of creating an application with tabs. The following procedures assume you have already created an application that does not have any tabs.

See Also:
"Creating an Application"

About Template Support

Before you can create parent and standard tabs, you need to check that your default template has positions defined for both standard and parent tabs using the appropriate substitution strings. You also need to make sure you do not override this template at the page level.

See Also:

- "Template Defaults" for information about setting a default page template at the application level

- "Display Attributes" for information about setting a template at the page-level

About the Tabs Section of the Page Definition

You can create and edit tabs on the Page Definition. Tabs display under the Shared Components section.

You can temporarily hide all other Shared Components subsections by clicking the Tabs icon under the Shared Components title. To restore the view, click Show All. The Show All icon resembles an inverted triangle.

The following icons appear in the Tabs section:

- Edit All. The Edit All icon resembles a small grid with a pencil on top of it. Use this icon to edit all tabs at once.

- Create. The Create icon resembles a plus (+) sign overlapping a small page. Click this icon to create a new tab.

- Reorder. The Reorder icon resembles light green down and up arrows. Click this icon to edit the label and location of tabs.

To edit a tab, click the tab name.

See Also:
"About the Tabs Page" and "Using the Reorder Tabs Icon"

Using the Reorder Tabs Icon

You can quickly edit the label and location of tabs by clicking the Reorder Tabs icon. It appears in the Tabs section of the Page Definition. This icon resembles light green down and up arrows.

To edit tabs using the Reorder Tabs icon:

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

2. Under Tabs, click the Reorder Tabs icon.
The Reorder Tabs page appears.

3. Edit the appropriate information:

a. Label - Enter a label for the tab.

b. Page - Enter the page number that corresponds to the tab.

c. Tab Also Current For - List other pages that also correspond to this tab. To enter multiple pages, enter a list of pages delimited by a comma. For example:

11,12,13,14,29,14

4. To change the order in which tabs display, click the up and down arrows in the far right column.

5. Click Apply Changes.

About the Tabs Page

The Tabs page displays a graphical representation of the tabs defined in your application. You access the Tabs page from the Shared Components page, or by clicking the heading Tabs on the Page Definition.

How to Create a Tab

You create a parent tab or standard tab from the Tabs page.

To create a tab:

1. Access the Tabs page:
To access the Tabs page from the Shared Components page:

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

b. Select an application.

c. On the Application Builder home page, click Shared Components.

d. Under Navigation, click Tabs.

To access the Tabs page from a Page Definition:

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

b. Under Shared Components, click the Create icon in the Tabs section.

2. To create a tab:

a. Click Add in the appropriate row:

- Use the Add button in the upper row to add Parent tabs.

Think of parent tabs as a container to hold standard tabs. For example, to add two levels of tabs, you first create a parent tab and then add standard tabs to it.

- Use the Add button in the lower row to add Standard tabs.

The Create Parent Tab or Create Standard Tab Wizard appears.

b. Follow the on-screen instructions.

Editing Tabs

You can edit multiple tabs simultaneously. Also, for standard tabs, you can update tab properties, such as their labels and order sequence, by using the Standard Tab Tasks list.

Editing Multiple Tabs Simultaneously

You can edit multiple tabs simultaneously.

To edit multiple tabs simultaneously:

1. Navigate to the Tabs page:

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

b. Select an application.

c. Click Shared Components.

d. Under Navigation, click Tabs.

2. Click one of the following buttons:

- Edit Standard Tabs

- Edit Parent Tabs

Using the Standard Tab Task List

The Standard Tab Task list displays on the right side of the Tabs page. You can access the links on this list to rename a standard tab set, resequence the display order, associate pages with a tab set, create a new standard tab, or create a new standard tab set.

To access the Standard Tab Task list:

1. Navigate to the Tabs page:

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

b. Select an application.

c. Click Shared Components.

d. Under Navigation, click Tabs.

2. Make a selection from the Standard Tab Task list:

- Rename Standard Tab Set

- Resequence Display Order

- Associate Page(s) with Selected Standard Tab

- Create New Standard Tab

- Create New Standard Tab Set

Accessing Tab Reports

You can view the Tab Utilization and Tab History reports by clicking the appropriate tab at the top of the Tab Manager page.

Standard Tab Utilization

Click Utilization to access the Standard Tab Utilization report. This report lists the standard tabs used in the current application.

Standard and Parent Tab History

Click History to view the Standard Tab History and Parent Tab History reports. These reports display a history of changes to tab attributes for the current application.

Creating Lists

A list is a shared collection of links. You add a list to a page by creating a region and specifying the region type as List. You control the appearance of a list through list templates.

Each list element has a display condition, which enables you to control when it displays. You can define a list element to be either current or non-current for a specific page. You further specify what current looks like using template attributes.

Topics in this section include:

- How To Create a List

- Adding a List to a Page

- Editing a List

- Editing Multiple List Entries Simultaneously

- Accessing List Reports

See Also:
"Creating a New Template" and "List Templates" for information about altering list display

How To Create a List

To add a list to a page in your application, you must:

1. Create the list using one of these methods:

- Create a list from scratch by running the Create/Edit Lists Wizard from either the Shared Components page or Page Definition.

- Copy an existing list. If the list contains list items or entries, the items are also copied.

2. Add entries to the list:

- Create list entries from scratch.

- Copy a single list entry from the current list. This copies the list entry attributes.

- Copy list entries from another list into the current one. This merges the two sets of list entries without changing the list whose entries are copied into the current one.

3. Add the list to a page by creating a List region.

Topics in this section include:

- Creating a List from Scratch

- Copying Lists

- Adding List Entries and Sublists

- Changing Parents of List Entries

- Removing Parent of Orphaned List Entries

Creating a List from Scratch

To create a list:

1. Access the Create/Edit Lists Wizard:
To access the wizard from the Shared Components page:

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

b. Select an application.

c. On the Application Builder home page, click Shared Components.

d. Under Navigation, click Lists.

e. Click Create.

To access the wizard from a Page Definition:

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

b. Under Shared Components, click the Create icon in the Lists section.

2. In the Create/Edit Wizard:

a. Name - Enter a name for the list.

b. List Template - Select a list template.

c. Build Option - If applicable, select a build option for this component. Build options are predefined settings that determine whether or not components within an application are enabled.

3. Click Create.

Copying Lists

To copy a list:

1. Access the Copy List Wizard:
To access the wizard from the Shared Components page:

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

b. Select an application.

c. On the Application Builder home page, click Shared Components.

d. Under Navigation, click Lists.

e. Click Copy.

To access the wizard from a Page Definition:

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

b. Under Shared Components, click the Copy icon in the Lists section.
The Copy icon appears only if a list already exists for this page.

2. In the Copy Wizard, select the location of the list to copy and click Next.

3. If you selected List in another application, select the application and click Next.

4. For Identify List, enter a name for the new list and click Copy.

For the list to appear on a page, you need to add it to the page.

Adding List Entries and Sublists

Once your list is created, you need to add entries to it. You can add list entries from scratch, copy one list entry within a list, or copy existing entries from one list to another.

You can also create hierarchical lists that contain sublists. To create a hierarchical list, you must:

- Select a list template that supports hierarchical lists. To determine which list templates support hierarchical lists, look for templates having the naming convention "with Sublist."

- Select a Parent List Item when you create each list entry.

See Also:
"Editing Templates" and "List Templates"

Adding Entries or Sublists from Scratch

To add an entry or sublist from scratch:

1. Navigate to the Lists page:

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

b. Select an application.

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

d. Under Navigation, select Lists.
The Lists page appears.

2. Select a list.

3. Click Create List Entry.
The Create/Edit List Entry page appears.

4. Under Entry:

a. Parent List Item - Identify the parent for this list entry. Use this attribute if you are creating a hierarchical list that will contain a sublist.

b. Sequence - Indicate the order in which list entries appear.

c. Image - Identify the file name for the image used to display this list entry. List templates control this attribute.

d. Attributes - Identify the image attributes (such as width="12" height="12") for the list element image.
Use the #LIST_LABEL# substitution string to reference the list label text. This substitution string allows for the title image attribute to be automatically set based on the value of the list label text. For example:

title="#LIST_LABEL#"

e. List Entry Label - Enter the label text for this link.

5. Specify a target location.
If the target location is a URL, specify the following:

- Target is a - Select URL.

- URL Target - Enter a URL. For example:

http://www.yahoo.com

If the target location is a page:

a. Target Type - Select Page in this Application.

b. Page - Specify the target page number.
You can also select reset pagination for this page. Selecting this option causes the page to return to the first set of data meeting a user's new query.

You can also select Printer Friendly. Selecting this option displays the target page using the application's Printer Friendly template. Printer friendly templates optimize a page for printing. "Changing the Default Templates in a Theme" and "Optimizing a Page for Printing".

c. Request - Specify the request to be used.

d. Clear Cache - Specify the page numbers on which to clear cache.

e. To set session state (that is, give a listed item a value):

- Set these items - Enter a comma-delimited list of item names for which you would like to set session state.

- With these values - Enter a comma-delimited list of values for the items specified in the previous step.

You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL cannot contain a colon. Additionally, item values cannot contain commas unless you enclose the entire value in backslashes (for example, \1234,56\).

6. Under Current List Entry:

a. List Entry Current for Pages Type - Specify when this list entry should be current based on the page type.
List items can be current or non-current. Current list items use the current template; non-current list items use the non-current list item template. The actual condition and templates are defined in subsequent attributes.

b. List Entry Current for Condition - Based on the selection above, define a condition to evaluate. When this condition is true, then the list item becomes current.

7. To make the list entry conditional, specify the appropriate information under Conditions.

8. Under Authorization, you can specify an authorization scheme.
This authorization scheme must evaluate to TRUE in order for this component to be rendered or otherwise processed.

9. Under Configuration, you can select a build option for this component.
Build options are predefined settings that determine whether or not components within an application are enabled.

10. Under Click Counting, you can specify if you want the list entries to be included in the click count.
If this is a link to an external page, such as www.google.com, you can count clicks. For more information, see "COUNT_CLICK Procedure".

11. To specify additional attributes, use the User Defined Attributes section. For example, the following adds a tabindex and accesskey.

tabindex="15" accesskey="D"

12. When you are finished defining list attributes, click Create or Create and Create Another.

Copying List Entries

To copy list entries:

1. Navigate to the List Entries page:

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

b. Select an application.

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

d. Under Navigation, select Lists.
The Lists page appears.

e. On the Lists page, click the name of the list whose entries you want to copy.
The List Entries page appears.

2. To copy a single list entry that appears in the current list:

a. Click the Copy icon in the in the row you want to copy. The Copy icon appears under the Copy column in the list.
All the attributes of the selected list entry, such as image and parent, will be copied to the new entry.

b. For Copy List Entry, enter the appropriate information and click Copy List Entry.

3. To copy list entries from one list to another:

a. Click Copy List Entries from one List to Another under the Tasks list on the right side of the page.

b. For Identify Copy Target, select the target list where you want to add the entries and click Next.

c. For Confirm List Entry Copy, click the Report of New Combined List to review the composite list.

d. Click Copy List Entries.

Changing Parents of List Entries

To change the parent of list entries:

1. Navigate to the List Entries page:

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

b. Select an application.

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

d. Under Navigation, select Lists.
The Lists page appears.

e. On the Lists page, click the name of the list whose entries you want to update.
The List Entries page appears.

2. From the Tasks list on the right, click Reparent List Entries within this List.

3. On the Reparent List Entries page:

a. Enter the appropriate information for List and Start With and click Go.
You can use the Start With field to filter down a large, hierarchical list to pinpoint the entries you need to reparent. You can also use these fields to focus on a subset of a list you want to edit.

b. For Reparent To, select the new parent for the list entries.

c. Select the check boxes for the list entries you want to include.

d. Click Reparent Checked Entries.

Removing Parent of Orphaned List Entries

An orphaned list entry is a list entry whose parent is no longer a member of the current list. When a list entry becomes orphaned, remove the parent entry.

To remove the parent of an orphaned list entry:

1. Navigate to the List Entries page:

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

b. Select an application.

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

d. Under Navigation, select Lists.
The Lists page appears.

e. On the Lists page, click the name of the list whose entries you want to update.
The List Entries page appears.

2. From the Tasks list on the right, click Manage Oprhaned List Entries.

3. On the Manage Orphaned List Entries page:

a. From the Show list, select Orphaned and click Go.

b. Select the check boxes for the orphaned list entries.

c. Click Remove Parent Entry.

Adding a List to a Page

Once you create a list and list entries, the next step is to add it to a page by creating a region and specifying the region type as List.

See Also:
"Creating a New Template" and "List Templates" for information about altering list display

To add a list to a page:

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

2. Under Regions, click the Create icon.

3. For Region, select List as the region type and click Next.

4. For Display Attributes, specify the appropriate information and click Next:

- Title - Enter a title for the region. This title will display if the region template you choose displays the region title.

- Region Template - Choose a template to control the look of the region.

- Display Point - Identify a display point for this region.

- Page Template Body - These positions are displayed where indicated by the #BODY# substitution string in the page template.

- Page Template Region - These positions are controlled by page template substitution strings (#REGION_POSITION_01#..#REGION_POSITION_08#). Page template region positions enable exact placement of a region within a template.

- Sequence - Specify the sequence for this component. The sequence determines the order of evaluation.

- Column - Indicate the column where this region is to be displayed. A page can have multiple regions, which can be displayed in different columns. Note that this attribute only applies to regions that are displayed in a Page Template Body position.

5. For Source, select the list you want to add.

6. Click Create List Region.

Repeat these procedures for each page where you would like to add a list.

Editing a List

Once you create a list, you can edit it on the Lists page.

To edit a list:

1. Navigate to the Lists page.
From the Page Definition:

a. Navigate to the Workspace home page.

b. Click the Application Builder icon.

c. Select an application.

d. Select a page.

e. Under Shared Components, click Edit All.

From the Shared Components page:

a. Navigate to the Workspace home page.

b. Click the Application Builder icon.

c. Select an application.

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

e. Under Navigation, click Lists.

2. On the Lists page, you can change the appearance of the page by making a selection from the View list:

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

- Details displays each list as a line in a report. To edit a list, click the list name.

3. Select a list.
The List Entries page appears.

4. Select the appropriate list name.
The Create/Edit List Entry page that appears is divided into sections. You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

5. Edit the appropriate attributes.

6. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

7. Click Apply Changes.

Editing Multiple List Entries Simultaneously

You can edit multiple list entries simultaneously by clicking Grid Edit on the List Entries page.

To edit multiple list entries at once:

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

2. Select an application.

3. On the Application Builder home page, click Shared Components.

4. Under Navigation, click Lists.
The Lists page appears.

5. Select a list name.
The List Entries page appears.

6. Click Grid Edit.

7. Edit the appropriate items and click Apply Changes.

Accessing List Reports

You can view the List Utilization by Page, Unused Lists, and List History reports by clicking the appropriate tab at the top of the Lists page.

Note:
The List Utilization, Unused Lists, and History buttons only appear after you create a list.

Utilization

Click List Utilization on the Lists page to access the Lists Utilization report. This report displays all lists included in the current application. From the report:

- To edit list entries, select the list name.

- To view the pages on which the list appears, click the number in the Pages column.

- To view the template used with the list, click List Template Utilization. Then click the name to view or edit the list template.

Unused

Click Unused on the Lists page to identify lists that are not used in the current application.

History

Click History on the Lists page to view changes to list definitions and list entries by developer and date.

Creating Breadcrumbs

Breadcrumbs provide users with hierarchical navigation. A breadcrumb is a hierarchical list of links that display using templates. You can display a breadcrumb as a list of links or as a breadcrumb path.

Topics in this section include:

- About Breadcrumbs

- How to Create Breadcrumbs

- Editing Breadcrumbs

- Reparenting Breadcrumb Entries

- Accessing Breadcrumb Reports

See Also:
"Creating a New Template" and "Breadcrumb Templates"

About Breadcrumbs

A breadcrumb trail indicates where the user is within the application from a hierarchical perspective. In addition, users can click a specific breadcrumb link to instantly view the page. You use breadcrumbs as a second level of navigation at the top of each page, complementing other user interface elements such as tabs and lists.

How to Create Breadcrumbs

You can create breadcrumbs while creating a page, or manually by running the Create Breadcrumb Wizard.

Topics in this section include:

- Creating a Breadcrumb While Creating a Page

- Creating a Breadcrumb Manually

Creating a Breadcrumb While Creating a Page

To create a breadcrumb while creating a page:

1. Run the Create Page Wizard to add a new page. See "Managing Pages in an Application". You can access this wizard by:

- Clicking Create Page on the Application home page

- Clicking Create on the Page Definition

- Clicking the Create link on the Developer toolbar

During the wizard, a Breadcrumb list appears. The actual page on which this list displays depends upon the type of page you are creating.

2. From the Breadcrumb list, select any option other than the following:

- do not use breadcrumbs on page -

The Create Breadcrumb Entry form appears.

3. In Entry Name, enter a name for the breadcrumb.

4. For Parent Entry:

- To specify a parent, select a parent page from the Select Parent Entry list.

- If this breadcrumb does not have a parent, select No parent breadcrumb entry.

5. Follow the on-screen instructions.

Creating a Breadcrumb Manually

To create breadcrumbs manually, you need to add a breadcrumb to each page in your application as follows:

1. Create the breadcrumb by running the Create/Edit Breadcrumb Wizard from either the Shared Components page or the Page Definition.

2. Add entries to it.

3. Add the breadcrumb to a page by creating a region.

Creating Breadcrumbs from the Shared Components Page

To create breadcrumbs from the Shared Components page:

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

2. Select an application.

3. On the Application Builder home page, click Shared Components.

4. Under Navigation, click Breadcrumbs.
The Breadcrumbs page appears.

5. Click Create.

6. Enter a name and click Create.

Creating Breadcrumbs from a Page Definition

To create breadcrumbs from a Page Definition:

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

2. Under Shared Components, scroll down to Breadcrumbs and click the Create icon.

3. For Create, select Breadcrumb and click Next.

4. Enter a name and click Create.

After you create a breadcrumb, you add entries to it.

Adding Breadcrumb Entries

To add a breadcrumb entry:

1. Navigate to the Breadcrumbs page:

a. Navigate to the Workspace home page.

b. Click the Application Builder icon.

c. Select an application.

d. On the Application Builder home page, click Shared Components.

e. Under Navigation, click Breadcrumbs.
The Breadcrumbs page appears.

2. Select a breadcrumb to add entries to.

3. Click Create Breadcrumb Entry.

4. Under Breadcrumb, specify the page where this breadcrumb entry will display.

5. Under Entry:

a. Sequence - Indicate the order in which breadcrumb entries appear.

b. Parent Bread Entry - Identify the parent of this entry.

c. Short Name - Specify the short name of this entry (referenced in the breadcrumb template).

d. Long Name - Specify the long name of this entry (referenced in the breadcrumb template).

6. Under Target, specify the target location. The information that appears on the page depends on the branch type you selected:

a. If the target location is a URL, specify the following:

- Target is a - Select URL.

- URL Target - Enter a URL. For example:

http://www.yahoo.com

b. If the target location is a page, specify the following:

- Target is a - Select Page in this Application.

- Page - Specify the target page number.

You can also select reset pagination for this page. Selecting this option causes the page to return to the first set of data meeting a user's new query.

- Request - Specify the request to be used.

- Clear Cache - Specify the page numbers on which to clear cache.

c. To set session state (that is, give a listed item a value):

- Set these items - Enter a comma-delimited list of item names for which you would like to set session state.

- With these values - Enter a comma-delimited list of values for the items your specified.

You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL cannot contain a colon. Additionally, item values cannot contain commas unless you enclose the entire value in backslashes (for example, \1234,56\).

d. Click Next.

7. To make the breadcrumb conditional:

a. Make a selection from the Condition Type list.

b. Enter an expression in the fields provided.

8. Under Authorization, you can specify an authorization scheme.
This authorization scheme must evaluate to TRUE in order for this component to be rendered or otherwise processed.

9. Under Configuration, you can select a build option for this component.
Build options are predefined settings that determine whether or not components within an application are enabled.

10. When you are finished defining menu attributes, click Create at the top of the page.

Repeat these procedures for each breadcrumb entry you need to create.

Adding a Breadcrumb Region

A region is an area on a page that serves as a container for content. Once you create a breadcrumb and a breadcrumb template, the next step is to create a region. Once you create a region, you can add a breadcrumb to a page.

See Also:
"Creating a New Template" and "Breadcrumb Templates" for information about changing menu display

To create a breadcrumb region:

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

2. Under Regions, click the Create icon.
The Create Region Wizard appears. Note that each wizard page displays a series of blocks on the left, representing the sequence of steps. The highlighted block indicates the step you are performing.

3. For the region type, select Breadcrumb and click Next.

4. For Breadcrumb Container Region:

a. Region Title - Enter a title for this region.

b. Region Template - Select a region template.

c. Display Point - Select a Display Point.
Regions are organized by position (or Display Point). To determine the appropriate region position, click the flashlight icon. A graphical representation appears.

d. Sequence - Enter a number for the sequence.

e. Click Next.

5. For Breadcrumb:

a. Breadcrumb - Select the breadcrumb to be associated with this region.

b. Breadcrumb Template - Select a template.

c. Click Next.

6. For Breadcrumb Entry, identify the breadcrumb entry used to identify this page:

a. Breadcrumb Entry Label - Enter a label for the breadcrumb entry.

b. Parent Breadcrumb Entry - Select the appropriate hierarchical parent.

c. Click Next.

7. Click Finish.

Repeat these procedures for each page where you would like to add breadcrumb navigation.

About Creating Dynamic Breadcrumbs

To give users more exact context, you can include session state in breadcrumbs, making your breadcrumbs dynamic. For example, suppose a page in your application displays a list of orders for a particular company and you want to include the following breadcrumb:

Home > Orders > Orders for ACME Inc

In this example, ACME Inc not only indicates the page a user is on but also the navigation path. The Application Express engine stores the value of ACME Inc. in session state.

To create this type of dynamic menu, you must include a reference to a session state item in the breadcrumb's short name or long name. For example:

&COMPANY_NAME.

Editing Breadcrumbs

Once you create a breadcrumb, you can edit it on the Breadcrumbs page.

To edit a breadcrumb:

1. Navigate to the Workspace home page.

2. Click the Application Builder icon.

3. Select an application.

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

5. Under Navigation, select Breadcrumbs.
The Breadcrumbs page appears.

You can change the appearance of the page by making a selection from the View list and clicking Go:

- Icons (the default) displays each breadcrumb as a large icon. To edit a breadcrumb, click the icon.

- Details displays each breadcrumb as a line in a report. To edit a breadcrumb, click the appropriate name.

6. Select a breadcrumb.
The Breadcrumb Entries page appears and features two views: Hierarchical View and Tabular View.

7. Select the appropriate breadcrumb entry name.
The Create/Edit Breadcrumb Entry page appears.

8. Edit the appropriate attributes.

Tip:
To learn more about a specific item on a page, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

9. (Optional) In the Breadcrumb Entry list on the right side of the page, you can select the Synchronize Breadcrumb With Page Name and Title option.
Selecting this option makes changing the name of a page and breadcrumb a one-step process. The information you provide for breadcrumb names is used to update the referenced page name and title.

10. Click Apply Changes.

About Navigation Alternatives

The Create/Edit Breadcrumb Entry page is divided into the following sections: Breadcrumb, Entry, Target, Conditions, Authorization and Configuration.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Reparenting Breadcrumb Entries

You can select a new parent for selected breadcrumb entries on the Reparent Entries page.

To reparent breadcrumb entries:

1. Navigate to the Breadcrumbs page:

a. Navigate to the Workspace home page.

b. Click the Application Builder icon.

c. Select an application.

d. On the Application Builder home page, click Shared Components.

e. Under Navigation, select Breadcrumbs.
The Breadcrumbs page appears.

2. Select a breadcrumb.
The Breadcrumb Entries page appears.

3. From the Tasks list, click Reparent Entries within this Breadcrumb.
The Reparent Entries page appears.

4. Use the navigation bar to edit or filter the view:

- Breadcrumb - Identify the breadcrumb you wish to edit and click Go.

- Start With - Make a selection to restrict your view to a subset of the breadcrumb hierarchy and click Go.

5. From Reparent to, select the new parent.

6. Select the breadcrumbs entries you wish to move and click Reparent Checked Entries.

Accessing Breadcrumb Reports

You can view the Breadcrumb Utilization and Breadcrumb History reports by clicking the appropriate tab at the top of the Breadcrumbs page.

Note:
The Utilization and History buttons only appear after you create a breadcrumb.

Breadcrumb Utilization Report

Click Utilization to access the Breadcrumb Utilization report. This report lists breadcrumbs by page. Click the page number to go to a specific page.

Breadcrumb History Report

Click History to view the Breadcrumb History report. This report lists recent changes to breadcrumbs.

Creating Trees

You can use a tree in your application to effectively communicate hierarchical or multiple level data.

Topics in this section include:

- How To Create a Tree

- Editing a Tree

- Accessing Tree Reports

How To Create a Tree

To create a tree:

1. Navigate to the Shared Components page:

a. Navigate to the Workspace home page.

b. Click the Application Builder icon.

c. Select an application.

d. On the Application Builder home page, click Shared Components.

2. Under Navigation, click Trees.
The Trees page appears.

3. Click Create.
The Create Tree Wizard appears. Note that each wizard page displays a series of blocks on the left, representing the sequence of steps. The highlighted block indicates the step you are performing.

4. For Page Attributes, enter basic page information and click Next.
To learn more about a specific item on a page, click the item label. A Help window appears with a description of the item or field.

5. For Tab, specify how tabs should be implemented and click Next.

6. For Tree Attributes:

a. Tree Name - Enter a name.

b. Default Expanded Levels - Specify the number of default expanded levels.

c. Start Tree - Specify how you want to determine the starting point. This determines what point in the hierarchy you want to display.
- Based on New Item with Popup List of Values - Select this option if you want to set up an item containing a list of values. This option enables the user to determine the starting point to display by selecting an option for the list of values.

- Based on a SQL Query - Select this option if you want to write a query that dynamically finds the starting point of a hierarchy (the entry with no parent).

- Static Value - Select this option to hard code the starting point.

d. Click Next.

7. For Tree Template, select a template and click Next.

8. For Tree Start, specify a starting point and click Next. Depending on your Start Tree selection, enter either a query or a single value.

9. For Expand/Collapse, select the buttons to include and click Next.

10. For Table/View Owner, specify the owner of the table on which the tree will be based and click Next.

11. For Table/View Name, specify the name of the table on which the tree will be based and click Next.

12. A tree is based on a query and returns data that can be represented in a hierarchy. This hierarchy is determined by the relationship between ID and Parent ID values. Identify the column you want to use as the ID, the Parent ID, and specify the text that should appear on the leaf nodes.

a. ID - Enter the column you want to use as the ID.

b. Parent ID - Enter the Parent ID.

c. Leaf Node Text - Specify the text that should appear on the leaf nodes.

d. Link Option - Select Existing Application Item to make the leaf node text a link. If you select this option, specify a page to link to.

13. Identify an optional where and order by clause to add to your query.

14. Specify the display text for the Go button.

15. Identify the page you want to branch to when the user clicks a button.

16. Click Finish.

Editing a Tree

Once you create a tree, you can edit it on the Trees page.

To edit a tree:

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

2. Select an application.

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

4. Under Navigation, select Trees.
The Trees page appears.

5. You can change the appearance of the page by making a selection from the View list:

- Icons (the default) displays each tree as a large icon.

- Details displays each tree as a line in a report.

6. Select a tree.
The Edit Tree page appears.

7. Edit the appropriate attributes.

8. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

9. Click Apply Changes.

About Navigation Alternatives

The Edit Tree page is divided into the following sections: Name, Query, Before and After, Static Node Templates, Dynamic Templates, Node Text Templates, and Link Templates.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Accessing Tree Reports

You can view the Trees Utilization and Tree History reports by clicking the appropriate tab at the top of the Trees page.

Note:
The Utilization and History buttons only appear after you have created a tree.

Tree Utilization

Click Utilization on the Trees page to access the Tree Utilization report. This report displays all trees included in the current application. To edit a tree, select the tree name.

Tree History

Click History on the Trees page to view changes to trees by developer and date.

Creating a Navigation Bar Entry

Navigation bar entries offer an easy way to move users between pages in an application. For example, a navigation entry enables you to display a link from an image or text. The associated page template determines the location of a navigation bar.

Topics in this section include:

- About Navigation Bars

- How to Create a Navigation Bar Entry

- Editing a Navigation Bar Entry

- Editing Multiple Navigation Bar Entries Simultaneously

- Using the Reorder Navigation Bar Entries Icon

- Accessing Navigation Bar Entry Reports

See Also:
Customizing Templates

About Navigation Bars

A navigation bar entry can be an image, text, or an image with text beneath it. You must supply the images and text to use in the navigation bar entries.

Navigation bars are different from other shared components in that you do not need to reference them on a page-by-page basis. If your page template includes the #NAVIGATION_BAR# substitution string, the Application Express engine automatically includes any defined navigation bars when it renders the page.

See Also:
"Supported Page Template Substitution Strings" on using the #NAVIGATION_BAR# substitution string

How to Create a Navigation Bar Entry

Before adding a navigation bar, you must create entries for the navigation bar. To do so, access the Navigation Bar page from either the Page Definition or from the Shared Components page.

See Also:
"Working with Shared Components",

To create a navigation bar entry:

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

2. Under Shared Components, scroll down to Navigation Bar.

3. Under Navigation Bar, click the Create icon.
The Create Navigation Bar Entry Wizard appears. Note that each wizard page displays a series of blocks on the left, representing the sequence of steps. The highlighted block indicates the step you are performing.

4. For Attributes, specify the appropriate information:

a. Sequence - Specify the order of evaluation for this component.

Tip:
To review the existing entries, click the Existing Navigation Bar Entries link at the bottom of the page.

b. Alt Tag Text - Enter ALT text for navigation icons that are images. If you do not specify an image name, then this text displays.

c. Icon Image Name - Enter an image name. For naming conventions, click the item label (Icon Image Name). This opens item-level help with a list of supported prefixes and examples of image names.

d. Image Height - Define the height of the image in pixels.

e. Width - Define the width of the image in pixels.

f. Text - For text-only entries, enter the entry text. For images, you can also enter additional text to display with the image. This attribute can be translated.

g. Click Next.

5. For Target, specify the target location.

a. If the target location is a URL, specify the following:

- Target is a - Select URL.

- URL Target - Enter a URL. For example:

http://www.yahoo.com

b. If the target location is a page, specify the following:

- Target is a - Select Page in this Application.

- Page - Specify the target page number.

You can also select reset pagination for this page. Selecting this option causes the page to return to the first set of data meeting a user's new query.

You can also select Printer Friendly. Selecting this option displays the target page using the application's Printer Friendly template. Printer friendly templates optimize a page for printing. "Changing the Default Templates in a Theme" and "Optimizing a Page for Printing".

- Request - Specify the request to be used.

- Clear Cache - Specify the page numbers on which to clear cache.

c. To set session state (that is, give a listed item a value):

- Set these items - Enter a comma-delimited list of item names for which you would like to set session state.

- With these values - Enter a comma-delimited list of values for the items your specified.

You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL cannot contain a colon. Additionally, item values cannot contain commas unless you enclose the entire value in backslashes (for example, \1234,56\).

d. Click Next.

6. To set a condition for displaying the navigation bar entry, specify the appropriate conditional information and click Create.

Editing a Navigation Bar Entry

Once you create a navigation bar entry, you can edit it on the Navigation Bar Entries page.

To edit a navigation bar entry:

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

2. Select an application.

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

4. Under Navigation, click Navigation Bar Entries.
The Navigation Bar Entries page appears. You can change the appearance of the page by making a selection from the View list and clicking Go. Available options include:

- Icons (the default) displays each navigation bar entry as a large icon. To edit a navigation bar entry, click the icon.

- Details displays each navigation bar as a line in a report. To edit a navigation bar, click the appropriate sequence number.

5. Select a navigation bar entry.
The Edit Navigation Bar Entry page appears.

The Edit Navigation Bar Entry is divided into the following sections: Sequence, Subscription, Image Attributes, Target, Conditions, Authorization, Configuration, and Comments.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

6. Edit the appropriate attributes.

7. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

8. Click Apply Changes.

Editing Multiple Navigation Bar Entries Simultaneously

To edit multiple navigation bar entries simultaneously:

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

2. Select an application.

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

4. Under Navigation, click Navigation Bar Entries.
The Navigation Bar Entries page appears.

5. Click Grid Edit at the top of the page.

6. Edit the appropriate attributes and click Apply Changes.

Using the Reorder Navigation Bar Entries Icon

You can quickly change the order of navigation bar entries by clicking the Reorder Navigation Bar Entries icon on the Page Definition. This icon resembles light green down and up arrows.

To change the order of the navigation bar entries using the Reorder Tabs icon:

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

2. Under Navigation Bar, click the Reorder Navigation Bar Entries icon.
The Reorder Navigation Bar Entries page appears.

3. To change the order in which the entries display on this page, click the up and down arrows in the far right column or edit the numbers.

4. Click Apply Changes.

Accessing Navigation Bar Entry Reports

You can view the Navigation Bar Entry Subscription and Navigation Bar Entry History reports by clicking the appropriate tab at the top of the Navigation Bar Entries page.

Note:
The Subscription and History buttons only appear after you create a navigation bar.

Navigation Bar Entry Subscription Report

Click Subscription to access the Subscribed NavBars report. This report displays subscribed navigation bar entries in your application.

Navigation Bar Entry History

Click History to view the Navigation Bar History report. This report lists recent changes to navigation bars.

Controlling Navigation Using Branches

A branch is an instruction to link to a specific page, procedure, or URL after a given page is submitted. For example, you can branch from page 1 to page 2 after page 1 is submitted.

You create a new branch by running the Create Branch Wizard and specifying the branch point and branch type.

To create a branch:

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

2. Under Branches in the Page Processing column, click the Create icon.

3. For Point and Type, select a branch point:

- On Submit: Before Computation - Occurs before computations, validations, or processing. Use this option for a Cancel button.

- On Submit: Before Validation - Occurs after computations, but before validations or processing. Typically not used. 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 might want to branch based on the result of a computation (for example, to the previous branch point).

- On Submit: Before Processing - 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 - 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 - 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.

4. Select a branch type and click Next.

5. For Target, specify the target location. The information that appears on the page depends on the branch type you selected:

a. If the target location is a URL, specify the following:

- Target is a - Select URL.

- URL Target - Enter a URL. For example:

http://www.yahoo.com

b. If the target location is a page, specify the following:

- Target is a - Select Page in this Application.

- Page - Specify the target page number.

You can also select reset pagination for this page. Selecting this option causes the page to return to the first set of data meeting a user's new query.

You can also select include process success message. Selecting this option displays a message when a user submits a page and a branch is taken to another page. If you do not select this option, the message does not display because it is part of submitting the page, not displaying the next one.

- Request - Specify the request to be used.

- Clear Cache - Specify the page numbers on which to clear cache. Separate multiple entries with a comma.

c. To set session state (that is, give a listed item a value):

- Set these items - Enter a comma-delimited list of item names for which you would like to set session state.

- With these values - Enter a comma-delimited list of values for the items your specified.

You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL cannot contain a colon. Additionally, item values cannot contain commas unless you enclose the entire value in backslashes (for example, \1234,56\).

d. Click Next.

6. Follow the on-screen instructions.

See Also:
"About the When Button Pressed Attribute"

Creating a Branch on a Page with a Component that Submits

If you have a page with a component that submits, such as a Go button or select list with submit, note that you need to create a branch that links back to that page. For example, suppose you have a page with a select list and a submit button. For processing to occur properly, you need to create a branch on the page that links back to the page.

7 Controlling Page Layout and User Interface

This section describes different ways you can customize your application's user interface and page layout including customizing regions, editing item attributes, customizing templates, and incorporating cascading style sheets and images.

This section contains the following topics:

- Understanding Page Layout in Oracle Application Express

- Displaying Components on Every Page of an Application

- Understanding Regions

- Creating a Multiple Column Layout

- How Item Attributes Affect Page Layout

- Incorporating Content from Other WebSites

- Managing Themes

- Customizing Templates

- Optimizing a Page for Printing

- Using Custom Cascading Style Sheets

- Managing Images

- Managing Static Files

- Rendering HTML Using Custom PL/SQL

See Also:
"Adding Navigation" and "Using the Drag and Drop Layout Page"

Understanding Page Layout in Oracle Application Express

The Application Express engine renders pages by combining templates with application components defined by the developer and data in the database.

The overall framework (or structure of a page) is determined by the page template. For example, the page template controls if a page uses tabs and a navigation bar. It can also define if a page includes a bar on the left side that serves as a placeholder for navigation or secondary content. Finally, a page template can include definitions of region positions, which enable precise control over placement of regions using HTML tables or style sheet definitions. The page template itself is composed of HTML combined with substitution strings, which are substituted with the appropriate components at run time.

As a developer, you add content to a page by creating a region. A region is an area of a page that serves as a container for content. Each region contains a different type of content such as HTML, a report, a form, a chart, a list, a breadcumb, PL/SQL, a tree, a URL, or a calendar. You position a region either relative to other regions (that is, based on its sequence number and column), or by using a region position defined in the page template. The style of the region is also controlled by the region template. Like the page template, the region template defines the structure of the area that the region takes up on a page. It defines if the region title is displayed and where it is displayed relative to the main content or the body. A region can also define absolute positions for buttons.

See Also:
"Creating a Region"

Displaying Components on Every Page of an Application

Page zero of your application functions as a master page. The Application Express engine renders all components you add to page zero on every page within your application. You can further control whether or not the Application Express engine renders a component or runs a computation, validation, or process by defining conditions.

To create a page zero:

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

2. Select an application.
The Application home page appears.

3. Click the Create Page button.

4. For Select a page type, select Page Zero.
Note that the Page Zero option only appears if the application does not have a page zero.

5. Click Finish.

See Also:
"Managing Pages in an Application", "Understanding Conditional Rendering and Processing" and "Available Conditions"

Understanding Regions

A region is a area on a page that serves as a container for content. Each page can have any number of regions. You control the appearance of a region through a specific region template. The region template controls the look of the region, the size, determines whether or not there will be a border or a background color, and what type of fonts display. A region template also determines the standard placement for any buttons placed in region positions.

You can use regions to group page controls (such as items or buttons). You can create simple regions that do not generate additional HTML, or create elaborate regions that frame content within HTML tables or images.

Regions display in sequence within HTML table columns. You can also explicitly place regions in positions defined in the page template. You can also choose to display regions conditionally.

Topics in this section include:

- About the Regions Section of the Page Definition

- Using the Reorder Regions Icon

- Creating a Region

- About Region Types

- Editing Region Attributes

- Copying a Region

About the Regions Section of the Page Definition

You create and edit regions on the Page Definition. Regions display under the Page Rendering section. See "Accessing a Page Definition".

You can temporarily hide other subsections by clicking the Regions icon. To restore the view, click Show All. The Show All icon resembles an inverted triangle.

The following icons display adjacent to the section title:

- Edit All. The Edit All icon resembles a small grid with a pencil on top of it. Use this icon to edit all regions at once.

- Copy. The Copy icon resembles two small overlapping pages. Use this icon to make a copy of an existing region.

- Create. The Create icon resembles a plus (+) sign overlapping a small page. Click this icon to create a new region.

Regions are organized by position (or Display Point). The links available for a given region depend upon the type of region.

See Also:
"Editing Region Attributes" and "Using the Reorder Regions Icon"

Using the Reorder Regions Icon

You can quickly change the order that regions display, edit a region title, or change a region template by clicking the Reorder Regions icon on the Page Definition. The Reorder Regions icon displays as light green down and up arrows and displays to the right of Display Point.

To edit regions using the Reorder Regions icon:

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

2. Under Regions, click the Reorder Regions icon.
The Reorder Regions page appears. Use this page to edit the region title or select a new template.

3. In Region, enter a new title.

4. From Template, select a new template.

5. To change the order in which regions display, click the up and down arrows in the far right column.

6. Click Apply Changes.

Editing Region Attributes

You can alter the appearance of a page by editing attributes on the Region Definition.

Topics in this section include:

- Editing a Region Definition

- How Region Attributes Affect Page Layout

- Using the Reorder Regions Icon

- Controlling Region Positioning

- Specifying a Region Header and Footer

- Enabling Users to Customize a Page

- Utilizing Region Caching

- Specifying a Static Region ID

Editing a Region Definition

To edit region attributes:

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

2. Under Regions, select the region name.
The Region Definition appears.

3. Edit the appropriate attributes.

4. To learn more about a specific item on a page, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

5. Click Apply Changes.

See Also:
"How Region Attributes Affect Page Layout", "Controlling Region Positioning", "Using the Reorder Regions Icon", and "Specifying a Region Header and Footer"

About Navigation Alternatives

The Region Definition page is divided into the following sections: Identification, User Interface, Source, Conditions, Cache, Header and Footer, Authorization, Customization, Configuration, and Comments.

You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

How Region Attributes Affect Page Layout

Table 7-1 describes region attributes that affect the layout of a page.

Table 7-1 Region Attributes Affecting Page Layout

Attribute

Description

User Interface, Template

Determines the look of the region. Select from the region templates defined in the application. To view template attributes, click the template name on the Page Definition.

See Also: "Customizing Templates" and "Region Templates"

User Interface, Sequence

Specifies the display order of the regions within the page.

User Interface, Display Point

Identifies where the region displays within the page. Regions are rendered in order of sequence number within a Display Point. Click the View icon to see the page layout and select a position.

The possible display points for a region are determined by the page-level template (which is a page attribute). If no page-level template is selected, the default page-level template, defined in the Application Definition, is used.

User Interface, Region HTML table cell attributes

Defines additional attributes to be used in the HTML table cells when regions display in multiple columns. The attributes control the cells in the table used to lay out a region in multiple columns.

User Interface, Column

Determines the column where the region displays. If two regions are in the same display point, you can place them next to one another by setting the second region to display in column 2. Many regions can display in each column and the display order of the regions within the region display point and column is controlled by the region display sequence number.

Header and Footer

Specifies HTML text to be displayed at the top of the region (just before the #BODY# content).

Conditional Display

Defines conditions and appropriate expressions that determine if the region displays. Conditions can reference session state, the currently logged in user, or environment preferences (such as whether or not a page is in Print View mode).

See Also: "Understanding Conditional Rendering and Processing" and "Optimizing a Page for Printing"

Customization

Enables end-user customization. To utilize this feature, you must include the #CUSTOMIZE# substitution string in the Header, Body, or Footer section of the page template.

See Also: "Enabling Users to Customize a Page"

Controlling Region Positioning

When you create a region, you must specify its position (or Display Point) on the page. You can choose either a default position (such as Page Template Body) or a user-defined position in the template (such as Page Template Region Position 1.)

In addition to Display Point, you can specify the column in which the region will be placed. When you place regions in multiple columns, Oracle Application Express automatically renders the necessary HTML to produce a multiple column layout.

Specifying a Region Header and Footer

In addition to the body content of a region (which can be a report, a chart, or HTML with form elements), you can specify additional HTML to be placed above and below a region or in its header and footer.

The region footer supports the following substitution strings:

- #TIMING# shows the elapsed time in seconds used when rendering a region. You can use this substitution string for debugging purposes.

- #ROWS_FETCHED# shows the number of rows fetched by the Oracle Application Express reporting engine (the page size). You can use these substitution strings to display customized messages to the user. For example:

Fetched #ROWS_FETCHED# rows in #TIMING# seconds.

- #TOTAL_ROWS# displays the total number of rows that satisfy a SQL query used for a report.

- #FIRST_ROW_FETCHED# and #LAST_ROW_FETCHED# display the range of rows displayed. For example:

Row(s) #FIRST_ROW_FETCHED# through #LAST_ROW_FETCHED# of #ROWS_FETCHED# displayed

Enabling Users to Customize a Page

You can use the Customization attribute to enable users to turn regions on and off in a running application.

To enable end-user customization:

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

2. Under Regions, click the region name.
The Region Definition appears.

3. Scroll down to Customization and select one of the following:

- Customizable and Not Shown By Default

- Customizable and Shown By Default

4. In Customized Option Name, enter the label that represents this region on the page to the user.

5. Include the #CUSTOMIZE# substitution string in the Header, Body, or Footer section of the page template.

To use this feature, you must include the #CUSTOMIZE# substitution string in the Header, Body, or Footer section of the page template.

If at least one region supports end-user customization, a link called Customize appears wherever you include the #CUSTOMIZE# substitution string in the page template. When users click this link, a window appears, enabling them to turn on and off regions on the page.

See Also:
"Customizing Templates"

Utilizing Region Caching

Enabling region caching is an effective way improve the performance of static regions such as regions containing lists that do not use conditions or regions containing static HTML.

When you enable region caching, the Application Express engine renders a region from a cached (or stored) respository instead of rendering it dynamically. Keep in mind that the actual session identifiers are not cached. Instead, the Application Express engine caches a &SESSION. substitution string and the current session rendering the cached region is substituted on display. For example, if a region contains a link and the link includes a session, the exact session is not cached to ensure that the links works for all sessions.

The Application Express engine only renders a region from cache if it meets the defined condition. Additionally, regions can be cached specific to a user or cached independent of a user.

See Also:
"Cache"

Enabling Region Caching

To enable region caching:

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

2. Under Regions, click the region name.
The Region Definition appears.

3. Scroll down to Cache and specify the following:

a. Caching - Select Cached to cache the region independent of the user. Select Cached by User to cache the region specific to a given user.

b. Timeout Cache After - Identify how long the cached region remains valid.

c. Cache Condition Type - Select a condition type from the list. If the condition returns false, the region is rendered dynamically and is not be cached. If the condition returns true, the region is cached.

d. Expression 1 and Expression 2 - Enter values based on the specific condition type selected.

4. Click Apply Changes.

Specifying a Static Region ID

Specifying a static region ID is useful when creating custom JavaScript or cascading stylesheets. You can use the Static ID attribute on the Edit Region page to uniquely identify a region. You can then reference the region using the #REGION_STATIC_ID# substitution string in a region templates, the header, the footer, or the body.

To specify a static region ID:

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

2. Under Identification, enter a value in Static ID.

3. Click Apply Changes.

Creating a Region

You create new regions by running the Create Region Wizard.

To create a new region:

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

2. Under Regions, click the Create icon.
The Create Region Wizard appears.

3. Select a region type. See "About Region Types".

4. Follow the on-screen instructions.

About Region Types

When you create a region, you select a region type. The Application Express engine interprets a region differently based on the type you select. Table 7-2 describes the available region types.

Table 7-2 Region Types

Region Type

Description

HTML

When you select HTML, the wizard prompts you to select one of the following:

- HTML - Functions as containers for items and contains the HTML you provide. Any HTML you type may contain substitution strings.

- HTML Text (escape special characters) - Same as HTML region, but the Application Express engine escapes special characters before they are rendered.

- HTML Text (with shortcuts) - Same as HTML region, but with support for shortcuts.

See Also: "Using Shortcuts"

Report

Report regions can be defined by a SQL query you write, or by using a wizard to guide you through the steps needed to write a query.

See Also: "Creating Reports"

Form

Form regions are used to contain a form.

See Also: "Creating Forms"

Chart

Chart regions contain line, bar, or pie charts based on SQL queries.

See Also: "Creating Charts"

List

List regions contain a shared collection of links called list.

See Also: "Creating Lists"

Breadcrumb

Breadcrumb regions contain a hierarchical list of links called a breadcrumb.

See Also: "Creating Breadcrumbs"

PL/SQL Dynamic Content

Regions based on PL/SQL enable you to render any HTML or text using the PL/SQL Web Toolkit.

Tree

Trees are a hierarchical navigational control based on a SQL query executed at run time. It enables the user to expand and collapse nodes.

See Also: "Creating Trees"

URL

URL based regions obtain their content by calling a Web server using a predefined URL.

See Also: "Incorporating Content from Other WebSites"

Calendar

Calendar regions are used to contain a calendar.

See Also: "Creating Calendars"

Multiple HTML

Use this option to create multiple HTML regions at once. In the fields provided, specify the Sequence, Title, Display Point, Report Template, and Column for each region.

Help Text

Help Text regions enable you to provide page-level help.

See Also: "Creating a Help Page"

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

Copying a Region

You can quickly copy a region by clicking the Copy icon on the Page Definition. The Copy icon resembles two small overlapping pages.

When you copy a region, you also have the option to copy the button and items within the region.

Note:
You cannot copy a Tree region since this type of region encompasses more than one region.

To copy a region:

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

2. Under Regions, click the Copy icon.
The Copy Region Wizard appears.

3. For Region to Copy, select the region you want to copy.

4. For To Page:

a. To Page - Select the page to which you want to copy the region.

b. Copy Region Items - Select Yes or No to determine whether to copy items within this region.

c. Copy Buttons - Select Yes or No to determine whether to copy buttons within this region.

d. Click Next.

5. Click Copy Region.

Creating a Multiple Column Layout

A region is an area on a page that uses a specific template to format HTML content. You use regions to group page controls. To create a multiple column layout, you create two regions that display in adjacent cells of the same table.

You can create a multiple column layout by either:

- Manually creating the two adjacent regions

- Defining a page template that contains a multiple column table

Topics in this section include:

- Creating Regions in Multiple Columns

- Creating a Multiple Column Page Template

Creating Regions in Multiple Columns

You create new regions using the Create Region Wizard. To create a two-column page, you create two regions. Oracle Application Express replaces the #BOX_BODY# substitution string within a two-column table and displays the regions in two separate cells.

To create a two-column page by creating regions:

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

2. Create the first region:

a. Under Regions, click Create.
The Create Region Wizard appears.

b. Select a region type.

c. From the Column field, select 1.

d. Follow the on-screen instructions.

3. Create the second region:

a. Under Regions, click Create.
The Create Region Wizard appears.

b. Select a region type.

c. From the Column field, select 2.

d. Follow the on-screen instructions.

Creating a Multiple Column Page Template

Page templates define the appearance of individual pages, including the placement of page controls and components. Each page template is divided into three sections: Header, Body, and Footer. The most basic template must include the substitution string #BOX_BODY# in the Body attribute. When the page is rendered, the Application Express engine replaces #BOX_BODY# with HTML to display the regions on that page.

You can create a multiple column page by defining a page template that contains a multiple column table. You then explicitly place regions within specific table cells.

The following example demonstrates how to create a two-column page and specify a region position using the #REGION_POSITION_XX# substitution string in each column. You would enter the code in the Body section of the page-level template.

<body #ONLOAD#>
#FORM_OPEN#
<table style="width:100%">
<tr>
<td style="width:50%;padding:5px;">#REGION_POSITION_01#</td>
<td style="width:50%; border-left:2px #bbbbbb dashed; padding:5px;">#REGION_POSITION_02#</td>
</tr>
<br />
#BOX_BODY#
#FORM_CLOSE#
</body>

Once you create this page-level template, the newly defined positions would be available as Display Point options when you run the Create Region Wizard.

How Item Attributes Affect Page Layout

An item is part of an HTML form and can be a text field, text area, password, select list, check box, and so on. You can alter the appearance of a page by changing the item attributes. For example, these attributes can effect where a label displays, how large an item will be, if the item will display next to or below the previous item.

See Also:
"Understanding Page-Level Items" and "Using the Drag and Drop Layout Page"

To edit item attributes:

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

2. Under Items, click the item name.
The Edit Page Item page appears.

Table 7-3 describes how item attributes affect the layout of a page.

Table 7-3 Item Attributes Effecting Page Layout

Heading

Attribute

Description

Displayed

Sequence

Determines the order that items are rendered within a region.

Displayed

Region

Defines the region where the item displays. All items must be in a region.

Displayed

Begin On New Line

Determines if this item displays on the same line or on the next line as the previous item.

Displayed

...Field

Determines if this item displays in the next column or in the same column as the previous item.

Displayed

ColSpan

Items are laid out in HTML tables. Defines the value to be used for the COLSPAN attribute of the table cell containing an item.

Displayed

RowSpan

Items are laid out in HTML tables. Defines the value to be used for the ROWSPAN attribute in the table cell where the item displays.

Label

Label

Defines the label for this item. You can include HTML, JavaScript, and shortcuts. You can also use the substitution string #CURRENT_ITEM_NAME# to obtain the name of the item associated with this label.

Label

Horizontal/Vertical Alignment

Controls the placement as well as the horizontal and vertical alignment of the label. Labels can be displayed above, below, or to the left of the item.

Label

Template

Specifies the label template. Use label templates to apply a consistent appearance to labels in your application.

Label

HTML Table Cell Attributes

Defines additional attributes for the cell containing this item's label (for example, nowrap="nowrap").

Element

Pre Element Texts

Specifies additional attributes for the HTML table cell used to display each individual option in a radio group or set of check boxes. Can include HTML, JavaScript, and shortcuts. You can reference the following substitution strings:

- #CURRENT_FORM_ELEMENT# obtains the name of the HTML form element with which this post element text is associated.

- #CURRENT_ITEM_NAME# obtains the name of the item with which this post element text is associated.

Element

Post Element Texts

Specifies additional attributes for the HTML table cell used to display each individual option in a radio group or set of check boxes. Can include HTML, JavaScript, and shortcuts. You can reference the following substitution strings:

- #CURRENT_FORM_ELEMENT# obtains the name of the HTML form element with which this post element text is associated.

- #CURRENT_ITEM_NAME# obtains the name of the item with which this post element text is associated.

List of Values

Columns

Applies to radio groups and check boxes. Defines the number of columns to use to display the values defined in the List of Values. By default, all values display in one column.

Conditions

Condition Type and Expressions

Defines conditions and appropriate expressions that determine if an item displays.

See Also: "Understanding Conditional Rendering and Processing"

Read Only Display Settings

Read Only Condition Type

Defines conditions and expressions that determine if the item displays as read-only. Use this attribute to display certain items to a set of users as updatable, while displaying that same set of items to others users as nonupdatable. Reduces the need to code duplicate interfaces for different users.

Incorporating Content from Other Web Sites

Typically, pages in an application are based on data stored in an Oracle database. To incorporate content from other servers, you can create a region based on a URL to display content. For example, suppose you wanted to reference the current Oracle stock price. You could create a region of type URL based on a URL such as the following:

http://quote.yahoo.com/q?d=b&s=ORCL

You could then create an item called STOCK_SYMBOL and base your region on a stock price entered by the user. For example:

http://quote.yahoo.com/q?d=b&s=&STOCK_SYMBOL.

Sometimes (as is the case with the previous example) the HTML returned to the region is more than is needed. To restrict the HTML displayed, you can use the following region attributes:

- URL (discard until but not including this text)

- URL (discard after and including this text)

Note that the previous example may require that you set the Proxy Server application attribute. If you do not set the Proxy Server application attribute, you get an error message. Oracle Application Express uses the Oracle utl_http.request_pieces function to obtain the HTML generated from the given URL. See "Configuring the Application Definition".

Working with SSL-Enabled URLs

If you call a SSL-enabled URL (for example, by invoking a Web service), or create a region of type URL that is SSL-enabled, you must create a wallet. A wallet is a password-protected container that stores authentication and signing credentials (including private keys, certificates, and trusted certificates) needed by SSL.

Tip:
See "Configuring Wallet Information".

Managing Themes

Themes are collections of templates that can be used to define the layout and style of an entire application. The idea behind a theme is to provide a complete set of templates that accommodate every UI pattern that may be needed in an application. Templates are organized first by type (breadcrumb, button, calendar, label, list, page, popup list of values, region, and report) and then by template classes, identifying the purpose of the each template within that type. Each template type provides a group of standard classes and eight custom classes. These classifications enable Oracle Application Express to map templates among themes, making it easy to quickly change the entire look and feel of an application.

Topics in this section include:

- Accessing the Themes Page

- Changing the Default Templates in a Theme

- Creating a New Theme

- Switching the Active Theme

- Copying a Theme

- Deleting a Theme

- About Exporting and Importing Themes

- Changing a Theme Identification Number

- Viewing Theme Reports

See Also:
"Customizing Templates"

Accessing the Themes Page

You manage themes on the Themes page. You can access the Themes page from the Shared Components page or from the Page Definition.

Topics in this section include:

- Accessing the Themes Page from Shared Components

- Accessing the Themes Page from a Page Definition

- About the Themes Page

Accessing the Themes Page from Shared Components

To access the Themes page from Shared Components:

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

2. Select an application.

3. Click Shared Components.

4. Under User Interface, select Themes.
The Themes page appears.

5. Select Details from the View list and click Go.
A check mark in the Current column indicates which theme is selected.

6. Click the theme name.
The Create/Edit Theme page appears.

Accessing the Themes Page from a Page Definition

To access the Themes page from the Page Definition:

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

2. Select an application.

3. Select a page.
The Page Definition appears.

4. Under Shared Components, locate the Theme section.

5. Click a theme name.
The Create/Edit Theme page appears.

Changing the Default Templates in a Theme

A standard theme contains templates for every type of application component and region type. You can change the selected default templates for a theme on the Create/Edit Theme page.

You can override the default templates in a theme by selecting another template when you create new components or regions, or by changing the template on the component or region attributes page.

To review or change the default templates in a theme:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.
The Themes page appears.

2. To edit a theme:

a. From the View list, select Details and click Go.

b. Click the theme name.

The Create/Edit Theme page appears.

The Create/Edit Theme page is divided into sections. You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Note the application ID and the Theme Identification Number display at the top of the page.

3. To change the theme name, enter a new name in the Name field.

4. To change a default template, make a new selection from the appropriate list.
Table 7-4 describes the default templates available under Component Defaults.

Table 7-4 Component Default Templates

Attribute

Description

Page

Identifies the default template for displaying pages. If a developer does not explicitly choose a template, then the Application Express engine uses the template specified here.

Once defined, this default template appears on the Edit Definition page under the heading Application Template Defaults.

See Also: "Display Attributes" for information about overriding the page template on the Page Attributes page

Error Page

Specifies a page template to use for errors that display on a separate page as opposed to those that display inline. Leave this attribute blank if you do not want to use a template designed to display errors.

Once defined, this default template appears on the Edit Definition page under the heading Application Template Defaults.

Printer Friendly Page

Identifies the template to be used when the Application Express engine is in printer friendly mode.

See Also: "Optimizing a Page for Printing"

Breadcrumb

Identifies the default breadcrumb template used when you create a breadcrumb.

Button

Identifies the default button template used when you create a button.

Calendar

Specifies the default calendar template used when you create a calendar.

Label

Identifies the default label template used when you create a label.

List

Specifies the default list template used when you create a list.

Region

Specifies the default region template used when you create a region.

Report

Identifies the default region template used when you create a report.

Table 7-5 describes the default templates available under the section Regions Defaults.

Table 7-5 Region Defaults

Attribute

Description

Breadcrumbs

Default region template used when you create a breadcrumb.

Charts

Default chart template used when you create a chart.

Forms

Default form template used when you create a form.

Lists

Default region template used when you create a list.

Reports

Default region template used when you create a report.

Tabular Forms

Default region template used when you create a tabular form.

Wizards

Default region template used when you create a wizard component.

Creating a New Theme

You can create a new theme from scratch or select an existing theme from the repository.

To create a new theme:

1. Navigate to the Themes page:

a. On the Workspace home page, click Application Builder.

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. Click Create.

3. Select a creation method:

- From the Repository

- From Scratch

- From Export

4. Follow the on-screen instructions.

5. To learn more about a specific field, click the field label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

About the Themes Page

Once you create a theme, it appears on the Themes page. A navigation bar appears at the top of the page and contains the following controls:

- Theme. Enter a case insensitive query for a theme name and click Go. To view all themes, leave the field blank and click Go.

- View. Controls how the page displays. Options include:

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

- Details displays each theme as a line in a report. To change the theme name or default templates, click the theme name. In Details view, you can select the following options from the Show list:

- Summary View displays the theme number, name, and current status.

- Detailed View displays the theme number, name, current status, and the number of templates in each template type.

- Display. Determines how themes display. To increase or decrease the number, make a selection from the Display list and click Go.

Switching the Active Theme

When you switch to a new theme, all components with assigned templates are assigned to a corresponding template in the new theme. Application Builder accomplishes template mapping through the assignment of template class identifiers.

Note:
You can only switch to a new theme if that theme already exists. For example, before you can switch to a theme available in the repository, you must first create it. See "Creating a New Theme".

To apply a theme to an application:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. Click Switch Theme.
The Switch Theme page appears.

3. From Switch to Theme, select a new theme and click Next.

4. Review the Status column to identify problematic mappings:

- Check indicates the mapping was successful.

- Warning indicates there are more than one template in the theme you are switching to with the identified class. The warning provides a select list from which to choose the appropriate template.

- Error indicates that Application Builder was unable to map the class among the themes. Ensure that a class is identified for the templates in both themes.

5. Click Next to continue.

6. Click Switch Theme.

See Also:
"Creating a New Theme"

Copying a Theme

Each theme is identified by a numeric identification number (ID). When you copy a theme, you specify a new theme ID. Copying a theme is useful if you want to experiment with editing a theme or to export a theme with a different ID.

To copy a theme:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. On the Tasks list, click Copy Theme.

3. On Copy Theme:

a. Copy From Theme - Select the theme you want to copy.

b. Copy to this Theme Identification Number - Enter a new ID for the theme.

c. Click Next.

4. Click Copy Theme ID.

Deleting a Theme

You can only delete inactive themes. When you delete a theme, Application Builder only removes inactive templates.

To delete a theme:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. On the Tasks list, click Delete Theme.

3. From Remove Theme, select the theme you want to delete and click Next.

4. Click Delete Theme.

About Exporting and Importing Themes

You export a theme in the same way you export any related application files. Exporting a theme from one development instance to another involves the following steps:

1. Export the theme using the Export Theme utility. See "Exporting Themes".

2. Import the exported file into the target Oracle Application Express instance. See "Importing Export Files".

3. Install the exported file from the Export Repository. See "Installing Export Files".

Changing a Theme Identification Number

Each theme has an identification number (ID). You can use the Change Theme ID utility to change a theme ID to another identification number. Changing a theme ID is useful when you want to export a theme with a different number and then import it into another application.

To change a theme identification number:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. On the Tasks list, click Change Identification Number.

3. For Theme Number:

a. Identify Theme - Select a theme.

b. Change to this Theme Identification Number - Specify a new identification number.

c. Click Next.

d. Confirm your changes and click Change Theme ID.

Viewing Theme Reports

Application Builder includes a number of reports designed to help you manage themes and templates.

Topics in this section include:

- Viewing All Templates in a Theme

- Viewing Theme Template Counts

- Viewing File References

- Viewing Class References

- Viewing Template Substitution Strings

Viewing All Templates in a Theme

To view all templates that comprise a theme:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. Click Reports.

3. On the Theme Reports page:

a. From Report, select Application Templates.

b. From Theme, select a theme.

c. Click Go.

A list of templates appears with the template type, template name, the associated theme, and template class.

4. To edit a template, select the template name.

Viewing Theme Template Counts

The Theme Template Count report lists which template classes currently have templates created for them.

To view the Theme Template Count report:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. Click Reports.

3. On the Theme Reports page:

a. From Report, select Theme Template Counts.

b. From Theme, select a theme.

c. Click Go.

4. If you are using custom classifications, select Show Custom and click Go.

Viewing File References

The File References report displays a list of all files associated with templates, shared components, or page components in the current application.

To view the File References report:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. On the Themes page, click Reports.

3. On the Theme Reports page:

a. From Report, select File References.

b. From Theme, select a theme.

c. Click Go.

4. On the File References page:

a. From Show, select the type of component to include in the report. If you do not make a selection, no results are returned.

b. From Show Files, select one of the following:

- With context displays the component, the theme identification number, the component name, the image (if applicable), and the page number. Select the page number to link to a Page Definition.

- Without context displays only the file name and the image (if applicable).

c. From File Extensions, select the type of extensions for which to search.

d. Click Go.

5. To download a comma-delimited file (.csv) version of this report, click Download at the bottom of the page.

Viewing Class References

Accessing the Class References report displays a list of classes associated with templates, shared components, or page components in the current application.

To view the Class References report:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. Click Reports.

3. On the Theme Reports page:

a. From Report, select Class References.

b. From Theme, select a theme.

c. Click Go.

4. On the Class References page:

a. From Show, select the components to check for a class reference. If you do not make a selection, no results are returned.

b. From Show Class Names, select one of the following:

- With context displays the component, the theme identification number, the component name, the image (if applicable), and the page number.

- Without context displays only the referenced class.

c. Click Go.

5. To download a comma-delimited file (.csv) version of this report, click Download at the bottom of the page.

Viewing Template Substitution Strings

Use the Template Substitution Strings report to view all supported substitution strings by component.

To view the Substitution String report:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. Click Reports.

3. On the Theme Reports page:

a. From the Report list, select Template Substitution Strings.

b. From the Theme list, select which themes to include in the report.

c. Click Go.

4. To link to a template definition, select the component name.

See Also:
"Understanding Substitution Strings"

Customizing Templates

The Application Express engine creates the user interface of an application based on a named collection of templates called a theme. Templates control the look and feel of the components in your application. If you need to create a custom template, it is generally easier to start with an existing template and then modify it. Once you have created one or more default templates, you can modify those templates to fit your specific needs.

Topics in this section include:

- About Cascading Style Sheets

- Selecting a Default Page Template

- Creating a New Template

- Viewing Template Reports

- Editing Templates

- Breadcrumb Templates

- Button Templates

- Calendar Templates

- Label Templates

- List Templates

- Page Templates

- Popup LOV Templates

- Region Templates

- Report Templates

See Also:
Managing Themes

About Cascading Style Sheets

A cascading style sheet (CSS) provides a way to control the style of a Web page without changing its structure. When used properly, a CSS separates visual attributes such as color, margins, and fonts from the structure of the HTML document. Oracle Application Express includes themes that contain templates that reference their own CSS. The style rules defined in each CSS for a particular theme also determine the way reports and regions display.

See Also:
"Using the CSS Finder" and "Using Custom Cascading Style Sheets"

Selecting a Default Page Template

You can specify a default page template in two ways:

- Select a default page template within a specific theme.

- Select a specific page template on a page-by-page basis.

By default, the Application Express engine uses the Page template specified on the Themes page.

Topics in this section include:

- Selecting a Page-level Template Within a Theme

- Selecting a Page-level Template for a Specific Page

Selecting a Page-level Template Within a Theme

To specify a default page template within a theme:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.
The Themes page appears.

2. From View, select Details and click Go.

3. In the Themes list, select the theme name.
The Create/Edit Theme page appears.

4. Under Component Defaults, make a selection from the Page list.

5. Click Apply Changes at the top of the page.

See Also:
"Changing the Default Templates in a Theme"

Selecting a Page-level Template for a Specific Page

To specify a page-level template for a specific page:

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

2. Select an application.

3. Select a page.

4. Under Page, click the Edit page attributes icon.

5. Locate the section Display Attributes.

6. Make a selection from the Page Template list.

7. Click Apply Changes at the top of the page.

Creating a New Template

If you need to create a custom template, it is generally easier to start with an existing template and then modify it. Once you have created one or more default templates, you can modify those templates to fit your specific needs.

To create a custom template:

1. Navigate to the Templates page.

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Templates.

2. Click Create.

3. Select the type of template you want to create.

4. Select a creation method:

- From Scratch

- As a Copy of an Existing Template

5. Follow the on-screen instructions.

Tip:
Make sure you associate your template with the correct theme.

Viewing Template Reports

Application Builder includes reports describing template utilization, subscription, and edit history.

To view template reports for the current application:

1. Navigate to the Themes page:

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

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Templates.

2. You can narrow the display by making a selections from the following lists and clicking Go.

- Theme - View only templates in a specific theme.

- Show - View a specific type of template.

- View - View all templates, those currently referenced, or those not referenced.

3. To view template reports, click the following buttons:

- Utilization displays template utilization in the current application for all template types (page, report, region, label and list).

- Subscription displays subscribed templates in your application.

- History details recent changes to templates by developers and the last update date.

Editing Templates

You can view all available templates on the Templates page. Alternatively, you can access a template associated with a specific page on the Page Definition.

Topics in this section include:

- Viewing Templates on the Templates Page

- Viewing Templates Associated with a Specific Page

See Also:
"Viewing All Templates in a Theme", "Breadcrumb Templates", "Button Templates", "Calendar Templates", "Label Templates", , "List Templates", "Page Templates", "Popup LOV Templates", "Region Templates", and "Report Templates"

Viewing Templates on the Templates Page

To view existing templates:

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

2. Select an application.

3. Click Shared Components.

4. Under User Interface, select Templates.
The Templates page appears.

5. You can narrow the display by making a selections from the following lists and clicking Go.

- Theme - View only templates in a specific theme.

- Show - View a specific type of template.

- View - View all templates, those currently referenced, or those not referenced.

6. To see a preview of a template, click the Run icon in the Preview column.
Note that not all template types have the preview capability.

7. To view or edit a template definition, click the template name.
The template definition appears.

Each template definition is divided into sections. You can access these sections by manually scrolling, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

8. Edit the appropriate attributes.
Note that if you edit a template, you can make changes in one window and run your application in another by selecting the Return to Page check box on the right side of the template definition page. Selecting this check box keeps the page you are editing current after you click Apply Changes.

9. Click Apply Changes.

Viewing Templates Associated with a Specific Page

To view templates associated with a specific page:

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

2. Select an application.

3. Select a page.
The Page Definition appears. Templates associated with the current page display under the Templates heading in the far right column.

4. To view or edit a template definition, click the template name.
The Template Definition appears.

Each template definition is divided into sections. You can access these sections by manually scrolling, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

5. Edit the appropriate attributes.
Note that if you edit a template, you can make changes in one window and run your application in another by selecting the Return to Page check box on the right side of the template definition page. Selecting this check box keeps the page you are editing current after you click Apply Changes.

6. Click Apply Changes.

Breadcrumb Templates

A breadcrumb template controls the display of breadcrumb entries. You select a breadcrumb template when you create a region.

See also:
"Customizing Templates" and "Managing Themes"

About Breadcrumb Style Navigation

Breadcrumbs usually indicate where the current page is relative to other pages in the application. In addition, users can click a specific page to instantly view it. For example, the Oracle Application Express user interface includes breadcrumb paths at the top of each page.

See Also:

- Online help for information about using specific sections of the Edit Breadcrumb Template page

- "Creating Breadcrumbs"

Breadcrumb Template Attributes

This section describes specific sections of the Edit Breadcrumb Template page. You can access the sections of the page by either scrolling down the page, or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Name

Name identifies the name of the template. Use the Translatable check box to indicate that the template contains text strings that require translation. Theme indicates the theme to which the template is a member.

Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class.

Subscription

Use Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, click Refresh.

Template Type

Select one of the following template styles:

- Child Breadcrumb Entries displays all breadcrumb entries that are children of the current page parent breadcrumb (that is, peers of the current breadcrumb).

- Current Breadcrumb displays all breadcrumb entries in sequence with a common parent.

- Parent Breadcrumb Entries displays all breadcrumb entries for the current pages parent breadcrumb (that is, one level up from the current breadcrumb entry).

- Parent to Leaf (breadcrumb style) displays the current page breadcrumb entry, its parent to the left, and so on, until the root node is reached.

Definition

Table 7-6 describes available breadcrumb Entry attributes.

Table 7-6 Breadcrumb Entry Control attributes

Attribute

Description

Before First

Defines text that displays before the first breadcrumb entry.

Current Page Breadcrumb Entry

Defines the look of a breadcrumb entry that corresponds to the current page. This attribute supports the following substitution strings:

- #NAME# specifies the short name of the breadcrumb entry.

- #LINK# specifies the anchor target of the breadcrumb entry.

- #LONG_NAME# specifies the long name of the breadcrumb entry.

Non Current Page Breadcrumb Entry

Defines the look of a breadcrumb entry that does not correspond to the current page. This attribute supports the following substitution strings:

- #NAME# specifies the short name of the breadcrumb entry

- #LINK# specifies the anchor target of the breadcrumb entry

- #LONG_NAME# specifies the long name of the breadcrumb entry

After Last

Defines text that displays after the last breadcrumb entry.

Between Level

Defines text that displays between levels of breadcrumb entries. For example, if a breadcrumb has three levels this text would display at the "X" in the example that follows:

main X cars X porsche X 911

Maximum Levels

Specifies the number of levels that appear when displaying breadcrumbs in a breadcrumb style.

Link Attributes

Use Breadcrumb Link Attributes to specify hypertext link attributes for a breadcrumb entry.

Comments

Use this attribute to record comments about this component.

Substitution Strings

Lists substitution string usage for this template. Substitution strings are used within subtemplates to reference component values.

Button Templates

Button templates enable application developers to customize the look and feel of a button. To build a button, you can use multiple images or HTML tags. Using button templates is optional.

See also:
"Customizing Templates" and "Managing Themes"

Button Template Attributes

This section describes specific sections of the Edit Button Template page. You can access the sections of the page by either scrolling down the page, or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Name

Template Name identifies the name of the template. Use the Translatable check box to indicate if the template contains text strings that require translation. Theme indicates the theme to which the template is a member.

Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class.

Subscription

Use Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, click Refresh Template.

Definition

Use Template to define the button template that displays. You have the option of including standard application substitutions. For example, &ITEM_NAME. values can be substituted at rendering time. Button templates support the following substitution strings:

- #LABEL# is replaced with a button label.

- #LINK# is replaced with a URL. The URL then calls a #doSubmit# or a redirect JavaScript that submits the page (that is, setting the request value), or simply redirects it to the supplied URL.

Comments

Use this attribute to record comments about this component.

Substitution Strings

Lists substitution string usage for this template. Substitution strings are used within subtemplates to reference component values.

Calendar Templates

Calendar templates control the appearance and placement of a calendar. Calendar templates frequently use HTML tables to arrange dates. You place calendar attributes using substitution strings such as #DD# and #MONTH#. A list of supported substitution strings appears on the right side of the Edit Calendar Template page. Note that template substitution strings must be in uppercase letters and begin and end with a number sign (#).

See Also:
"Creating Calendars", "Customizing Templates", and "Managing Themes"

Calendar Template Attributes

This section describes specific sections of the Edit Calendar Template page. You can access the sections of the page by either scrolling down the page, or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Calendar Definition

Name

Name identifies the name of the template. Theme indicates the theme to which the template is a member.

Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class.

Template Subscription

Use Template Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, click Refresh.

Comments

Use this attribute to record comments about this component.

Monthly Calendar, Weekly Calendar, and Daily Calendar

Use the Monthly Calendar, Weekly Calendar, and Daily Calendar attributes to control the appearance and placement of specific calendars.

To learn more about a specific attribute, click the attribute label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

Label Templates

Label templates are designed to centrally manage HTML markup of page item labels. Each item can have an optional label. You can control how these labels display using label templates. For example, you could create a label template called Required Field that references an image (such as an asterisk) to indicate to the user that the field is required.

Label templates enable you to define a before-and-after text string that gets prepended and appended to the item.

See Also:
"Customizing Templates" and "Managing Themes"

Label Template Attributes

This section describes specific sections of the Edit Label Template page. You can access the sections of the page by either scrolling down the page, or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Name

Template Name identifies the name of the template. Use the Translatable check box to indicate that the template contains text strings that require translation. Theme indicates the theme to which the template is a member.

Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class.

Subscription

Use Template Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, click Refresh Template.

Definition

In Before Label, enter HTML to display before the item label. Before Label supports the substitution strings #CURRENT_FORM_ELEMENT#; #CURRENT_FORM_ID#, and #CURRENT_ITEM_NAME#. For example:

<label for="#CURRENT_ITEM_NAME#">
<a href="javascript:popupFieldHelp('#CURRENT_ITEM_ID#',
'&APP_SESSION.','&CLOSE.')" >

In After Label, enter HTML to display after the item label. Since the label will automatically display before the HTML in this region, any open HTML tags in the Before Label region should be closed here. For example:

</a></label>

Error Display

In On Error Before Label, enter HTML to precede the item label when an application displays an inline validation error message for the item. For example:

<font class="fieldtitleleft">#ERROR_MESSAGE#

In On Error After Label, enter HTML to be appended to the item label when an application displays an inline validation error message for the item. This attribute supports the substitution strings #CURRENT_FORM_ELEMENT#, #CURRENT_FORM_ID#, and #CURRENT_ITEM_NAME#. The following example would append a space and a closing bracket to the displayed item label with the error.

&nbsp;]</font>

Comments

Use this attribute to record comments about this object.

Substitution Strings

Lists substitution string usage for this template. Substitution strings are used within subtemplates to reference component values.

List Templates

A list is a shared collection of links. You control the appearance of a list through list templates. Using template attributes, you can also define a list element to be either current or non current for a specific page.

See Also:
"Creating Lists", "Customizing Templates", and "Managing Themes"

About Hierarchical Lists

Oracle Application Express supports hierarchical lists. To create a hierarchical list, you must:

- Select a list template that supports hierarchical lists. To determine which list templates support hierarchical lists, look for templates having the naming convention "with Sublist."

- Select a Parent List Entry when you create each list entry.

See Also:

- Online Help for information about using specific sections of the Edit List Template page

- "Creating Lists"

List Template Attributes

This section describes specific sections of the Edit List Template page. You can access the sections of the page by either scrolling down the page, or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Name

Name identifies the name of the template. Use the Translatable check box to indicate that the template contains text strings that require translation. Theme indicates the theme to which the template is a member.

Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class.

Subscription

Use Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, click Refresh Template.

Before List Entry

Enter HTML that displays before any list elements. You can use this attribute to open an HTML table or HTML table row.

Template Definition

Defines current and noncurrent list templates. Supported substitution strings include #LINK#, #TEXT#, #IMAGE_PREFIX#, #IMAGE#, #IMAGE_ATTR#, and #A01# to #A10#.

- List Template Current. Enter HTML or text to be substituted for the selected (or current) list template.

- List Template Current with Sub List Items. Enter HTML or text to be substituted for the selected (or current) list template when an item has sublist items. If not specified, the current list item template will be used.

- List Template Noncurrent. Enter HTML or text to be substituted for the unselected (or noncurrent) list template.

- List Template Noncurrent with Sub List Items. Enter HTML or text to be substituted for the unselected (or noncurrent) list template used when an item has sublist items. If not specified, the current list item template will be used.

- Between List Elements. Enter HTML that displays between list elements. This attribute will be ignored if no HTML is specified.

Before Sub List Entry

Enter HTML that displays before any sublist elements.

Sub List Entry

Defines current and noncurrent list templates. Supported substitution strings include #LINK#, #TEXT#, #IMAGE_PREFIX#, #IMAGE#, #IMAGE_ATTR#, and #A01# to #A10#.

- Sub List Template Current. Enter HTML or text to be substituted for the selected (or current) list template.

- Sub List Template Current with Sub List Items. Enter HTML or text to be substituted for the selected (or current) list template when an item has sublist items. If not specified, the current list item template will be used.

- Sub List Template Noncurrent. Enter HTML or text to be substituted for the unselected (or noncurrent) list template.

- Sub List Template Noncurrent with Sub List Items. Enter HTML or text to be substituted for the unselected (or noncurrent) list template used when an item has sublist items. If not specified, the current list item template will be used.

- Between Sub List Items. Enter HTML that displays between list elements. This attribute will be ignored if no HTML is specified.

After Sub List Entry

Enter HTML that displays after displaying sublist elements.

After List Entry

Enter HTML that displays after displaying all list elements. You can use this attribute to close an HTML table opened in the Before List Elements attribute.

Comments

Use this attribute to record comments about this object.

Substitution Strings

Lists substitution string usage for this template. Substitution strings are used within subtemplates to reference component values.

Page Templates

Page templates define the appearance of a page. Each template consists of a header template, a body template, a footer template, and a number of subtemplates. If you do not specify a page template as a page-level attribute, then the Application Express engine uses the default page template defined on the Create/Edit Theme page.

Page templates combine static HTML with substitution strings that are replaced at run time. You use substitution strings to indicate the existence and placement of a component within a page template. You can further specify how a component should display using subtemplates.

See Also:
"Customizing Templates" and "Managing Themes"

Topics in this section include:

- Supported Page Template Substitution Strings

- Page Template Attributes

Supported Page Template Substitution Strings

Table 7-7 describes the available page template substitution strings. Note that all template substitution strings must be in uppercase letters and begin and end with a number sign (#).

To view a report of substitution strings supported by a given template, look at the Substitution Stings section of the Edit Page Template page. See "Page Template Attributes".

Table 7-7 Page Template Substitution Strings

Substitution String

Description

#APP_VERSION#

Can be used in the Header or Footer sections of the page template. You define the value of #APP_VERSION# in the Version attribute on the Edit Definition page

See Also: "Name"

#BOX_BODY#

Identifies where the Body displays. If the Body is null, then #BOX_BODY# will be used instead.

#CUSTOMIZE#

Can be used in the Header, Body, or Footer sections of the page template.

The Customization section of the Region Definition enables you to turn on end-user customization. To utilize this feature, you must also include the #CUSTOMIZE# substitution string in the page template.

If at least one region supports end-user customization, a link called Customize appears wherever the #CUSTOMIZE# substitution string appears in the page template. When users click this link, a window displays enabling them to turn on and off regions on the page.

See Also: "Editing Region Attributes"

#FORM_CLOSE#

If a #FORM_OPEN# is included, then you must include a #FORM_CLOSE# in the header, body, or footer template. #FORM_OPEN# must appear before the #BOX_BODY# and #FORM_CLOSE# must appear after the #BOX_BODY# substitution string.

#FORM_OPEN#

Specifies where the HTML open form tag <form> is placed. You must include this substitution string in order to submit a form.

You do not need to code your own form open; the Application Express engine does it for you.

#GLOBAL_NOTIFICATION#

Displays the Global Notification attribute. Global notifications are intended to communicate system status, such as pending system downtime. You can also use APEX_APPLICATION.G_GLOBAL_NOTIFICATION to set this value if you want to set it programmatically.

See Also: "Global Notifications" for information about the Global Notification attribute

#HEAD#

Used after the <head> open tag but before the </head> close tag. You can optionally define the contents of #HEAD# for each page (for example, to reference additional style sheets or JavaScript libraries).

#LOGO#

Identifies an application logo.

In the Logo section of the Edit Definition page, you can identify an image and image attributes for an application logo. To utilize this feature, you must also include the #LOGO# substitution string in the Header or Body page template.

See Also: "Logo"

#NAVIGATION_BAR#

Defines the existence of navigation bar entries. A navigation bar will appear on every page in your application that uses a template that includes this substitution string.You can expand this substitution string using the Navigation bar subtemplate.

See Also: "Subtemplate" for information about the Navigation Bar subtemplate

#NOTIFICATION_MESSAGE#

Enables developers to communicate messages to the user. Defines where a summary of inline error messages is displayed. Inline error messages can be displayed next to a field, inline in the notification area, or both.

#ONLOAD#

Can be used in the Header and Footer section of the page template and should be placed inside the <body> html tag. For example:

<body #ONLOAD#>

Use this string as a substitute in a JavaScript call to be executed when a page is loaded by the Web browser. The JavaScript to be called can vary for each page.

#PARENT_TAB_CELLS#

Identifies the display of parent tabs. Parent tabs require standard tabs. If your application only has one level of tabs, you do not need this substitution string.

See Also: "Standard Tab Attributes" for information about defining Parent Tab Attributes

#REGION_POSITION_NN#

Identifies the exact placement of regions within a page. If no region is specified (for example, #REGION_POSITION_01#), then #REGION_POSITION_01# will be replaced with nothing.

#SUCCESS_MESSAGE#

Defines where in the page success and error messages appear. If the page process runs without raising errors, then this text displays.

You can customize the display of the success message for each template by adding HTML to be displayed before and after the success message.

#TAB_CELLS#

Identifies the display of standard tabs.

See Also: "Standard Tab Attributes"

#TITLE#

Defines the page title. Typically included within HTML title tags.

See Also:
""Understanding Substitution Strings"and "Managing Pages in an Application"

Page Template Attributes

This section describes specific sections of the Edit Page Template page. You can access the sections of the page by either scrolling down the page, or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Name

Name identifies the name of the template. Theme indicates the theme to which the template is a member.

Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class. Use the Translatable check box to indicate that the template contains text strings that require translation.

Subscription

Use Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, select Refresh Template.

Definition

Each template consists of a header, a body, a footer, and subtemplates. Use substitution strings to include dynamic content. All template substitution strings must be in uppercase letters and begin and end with a number sign (#). See item Help for information about supported substitution strings.

Header is the first section of the page template. Enter HTML that defines the <Head> section of the HTML document. Regions that display or processes and computations that execute AFTER HEADER will display or execute immediately after this section in the template that is rendered. For example:

<html>
<head>
<title>#TITLE#</title>
#HEAD#
</head>

Body is the second section in the page template and is rendered after the header section but before the footer section. Enter HTML that defines the <Body> section of the HTML document. At a minimum, you must include the #BOX_BODY# substitution string. It is recommended that you also include the #FORM_OPEN# and #FORM_CLOSE# substitution strings. For example:

<body #ONLOAD#>
#FORM_OPEN#
#BOX_BODY#
#FORM_CLOSE#
</body>

Footer is the third section in the page template that displays after the body.

Display Points

Breadcrumb Display Point applies to generated components that use breadcrumbs. It defines where the breadcrumbs are placed on the page. Sidebar Display Point applies to generated components that use Sidebars. It defines where sidebars are placed on the page.

Subtemplate

Use Subtemplate to specify how a component should display. Available subtemplates include:

- Success Message. Expands the #SUCCESS_MESSAGE# substitution string. You can define a success message either programmatically or as an attribute of a process. If a success message exists and if the page template includes the #SUCCESS_MESSAGE# substitution string, then this subtemplate is used to render the message.

- Navigation Bar. Controls the display of navigation bar entries. Enter HTML or text to be substituted when the #NAVIGATION_BAR# substitution string is referenced in the template header, body, or footer. Use the #BAR_BODY# substitution string to identify where each navigation bar icon should display.

- Navigation Bar Entry. Enter HTML or text to be substituted into the navigation bar #BAR_BODY# substitution string for each navigation bar entry. Use the following substitution strings to create the navigation bar entry subtemplate.

- Notification. Enter HTML or text to be substituted when the #NOTIFICATION_MESSAGE# substitution string is referenced in the template header, body, or footer. Use the substitution string #MESSAGE# to indicate where the body of the message will appear in the Notification Message.

Standard Tab Attributes

You must populate this attribute if your application includes standard tabs. Standard tabs can be placed in the header, body, or footer sections of the page template using the #TAB_CELLS# substitution string. The page template Header/Body/Footer defines the HTML table and rows. This subtemplate defines how these tabs display by defining the specific cell. Available attributes include:

- Current Tab. Enter HTML or text to be substituted for the currently selected standard tab. Whether or not a tab is current is determined by standard tab attributes. For example:

<td>#TAB_LABEL#</td>

- Non Current Standard Tab. Enter HTML or text that will be substituted for the unselected standard tabs. Use the #TAB_TEXT# substitution string to position a tab's label and link within the template. For example:

<td><a href="#TAB_LINK#">#TAB_LABEL#</a></td>

See Also:
"Creating Tabs"

Parent Tab Attributes

You must populate this attribute if your application includes two levels of tabs. Enter HTML or text that will be substituted for the selected parent tabs. Parent tabs can be placed in the header, body, or footer section of the page template using the #PARENT_TAB_CELLS# substitution string. Parent tabs only display in conjunction with standard tabs. Available attributes include:

- Current Parent Tab. Enter HTML or text that will be substituted for the selected parent tabs. Whether or not a tab is current is determined by the page that displays and the standard tab set that the page uses. Use the #TAB_TEXT# substitution string to position a tab's label and link within the template. For example:

<td><a href="#TAB_LINK#">#TAB_LABEL#</a></td>

- Non Current Parent Tab. Enter HTML or text that will be substituted for the unselected parent tabs. Use the #TAB_TEXT# substitution string to position a tab's label and link within the template. For example:

<td><a href="#TAB_LINK#">#TAB_LABEL#</a></td>

See Also:
"Creating Tabs"

Image Based Tab Attributes

Use this subtemplate for tabs that are entirely based on images. Available attributes include:

- Current Image Tab. Enter HTML to be used to indicate that an image-based tab is currently selected. Include the #TAB_TEXT# substitution string to show the displayed name of the tab.

- Non Current Image Tab. Enter the HTML to be used to indicate that an image tab is not currently selected. Include the #TAB_TEXT# substitution string to show the displayed name of the tab.

Multi Column Region Table Attribute

If the Application Express engine displays regions in multiple columns in the same region position, then Oracle Application Express will render an HTML table. This attribute enables you to control the attributes of the <table> tag.

Error Page Template Control

Use this attribute only when a page template will be designated as an error template. Use the #MESSAGE# substitution string to place the error message and the #BACK_LINK# substitution string to display a link back to the previous page. A template can be designated as an error template by editing the application attributes. For example:

#MESSAGE#

<br>

<a href="#BACK_LINK#">back</a>

Comments

Use this attribute to record comments about this component.

Substitution Strings

Lists substitution string usage for this template. Substitution strings are used within subtemplates to reference component values.

Popup LOV Templates

Popup LOV templates control how popup lists display for all items defined as POPUP. You can only specify one popup LOV template for each theme.

See Also:
"Creating Lists of Values", "Customizing Templates", and "Managing Themes"

Popup List of Values Template Attributes

This section describes specific sections of the Edit Popup List of Values Template page. You can access the sections of the page either by scrolling down the page or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Application

Theme indicates the theme to which the template is a member. Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class. Use the Translatable check box to indicate that the template contains text strings that require translation.

Subscription

Use Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, click Refresh Template.

Icon

Use Popup Icon to specify an icon to display to the right of a form field for items of type POPUP. By default, the Application Express engine uses a list.gif image. Use Popup Icon Attr to define image attributes, such as height and width, for the Popup Icon.

Search Field

Use these attributes to specify how a Search field displays. Table 7-8 describes available Search Field attributes.

Table 7-8 Search Field Attributes

Attribute

Description

Before Field Text

Defines text to display before the popup list of values search field displays.

Filter Width

Displays the text field using this width.

Filter Max Width

Displays the text field widget using this maximum width.

Filter Text Attribute

Displays the text field using these attributes. This will be included within the HTML input tag.

After Field Text

Displays this text after displaying the search field, the search button, and the close button.

Buttons

Use these attributes to define the button name and attributes for the Find, Close, Next, and Previous buttons.

Window

Popup lists of values are executed using JavaScript. Use these attribute to control the values of scrollbars=, resizable=, width=, and height=. For information about default values, see item Help.

Pagination

Defines how row count results display.

Result Set

Use these attributes to define text or HTML to display before and after a result set.

Page Attributes

Use these attributes to define popup pages. For more information, see item Help.

Region Templates

Region templates control the appearance and placement of region attributes. Region templates frequently use HTML tables to arrange content.

Region templates apply style elements to regions. Region templates display substitution strings. The only required substitution string, #BODY#, identifies where the source of the region should be placed. All other substitution strings are optional. You can use these substitution strings to indicate the existence and placement of a page control, such as a button, within the region.

See Also:
"Understanding Regions", "Customizing Templates", and "Managing Themes"

Region Template Attributes

This section describes specific sections of the Edit Region Template page. You can access the sections of the page either by scrolling down the page or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Name

Name identifies the name of the template. Theme indicates the theme to which the template is a member.

Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class. Use the Translatable check box to indicate that the template contains text strings that require translation.

Subscription

Use Template Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, click Refresh Template.

Definition

Region templates provide the appearance for a portion of a page called a region. Use substitution strings to indicate the existence and placement of a component within the region. #BODY# is the only required substitution string. It identifies where the source of the region should be placed. All other substitution strings are optional. The following are valid substitution strings:

- #TITLE#

- #EXPAND#

- #CHANGE#

- #BODY#

- #FORM_OPEN#

- #FORM_CLOSE#

When you create a button in a region position, the positions you define will appear in a select list. Use the following substitution strings to define positions for the placement of buttons in a region:

- #EDIT#

- #CLOSE#

- #CREATE#

- #EXPAND#

- #HELP#

- #DELETE#

- #COPY#

- #NEXT#

- #PREVIOUS#

See Also:
"Understanding Substitution Strings"

Form Table Attributes

Page items display within regions. Items are rendered as HTML form elements in an HTML table. With this template property, you can define attributes that will be placed in the <table> tag. For example:

class="instructiontext"

Comments

Use this attribute to record comments about this component.

Substitution Strings

Lists substitution string usage for this template. Substitution strings are used within subtemplates to reference component values.

Report Templates

Report column templates provide you with control over the results of a row from a SQL query. This type of template defines a cell, not an entire row.

Each report template identifies column names using the syntax #1#, #2#, #3#, and so on. You can also name columns using column name substitution syntax such as #ENAME# or #EMPNO#. You can reference any item from your application within your template. For example, to reference an item called ABC. in your template, you could include the exact substitution string &ABC.. The actual value of ABC. would be provided by an end user editing an item in your application named ABC.

See Also:
"Creating Reports", "Customizing Templates", and "Managing Themes"

Topics in this section include:

- About Generic Column Templates and Named Column Templates

- Report Column Template Attributes for Generic Column Templates

- Report Column Template Attributes for Named Column Templates

- About Using JavaScript in Column Templates

About Generic Column Templates and Named Column Templates

Oracle Application Express includes two types of report templates:

- Generic column templates

- Named column templates

Generic Column Templates

A generic column template determines the appearance of a report by defining the look of the column once. This look is then repeated as many times as is necessary, based on the number of columns specified in the report's definition. This type of template is limited to reports that have a standard row and column structure. Additional style can be applied to a report using this type of template through the use of conditions.

The following example demonstrates how to have each column use a specific style:

<td class="tabledata" align="#ALIGN#">#COLUMN_VALUE#</td>

This example assumes your page template includes a CSS containing the class tabledata. This example also demonstrates the use the substitution strings #ALIGN# and #COLUMN_VALUE#. If you actually ran this report, these substitution strings would be replaced with values generated by the results of a SQL query.

If your query uses an expression in the select list, it is a good idea to create an alias for the columns to avoid run time errors. For example, suppose your query was as follows:

SELECT ename, (sal + comm) * 12 FROM emp

You could rewrite the query to alias the columns as follows:

SELECT ename, (sal + comm) * 12 yearly_comp FROM emp

Named Column Templates

Named column templates allow for more flexibility in report design. However, because they reference columns by name, they can only be used by reports that are based on those columns. For example:

<tr><td>#ENAME#</td><td>#SAL#</td></tr>

Although named column templates offer flexibility, you may need to create a new template for each query. You can also include a position notation. The following example demonstrates how to use following HTML and substitution strings:

<tr><td>#ENAME#</td><td>#SAL#</td></tr>

<tr><td>#1#</td><td>#2#</td></tr>

Report Column Template Attributes for Generic Column Templates

This section describes specific sections of the Edit Report Template page for Generic Column Templates. You can access the sections of the page by either scrolling down the page, or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Report Template

Template Name identifies the name of the template. Template Type indicates the type of template. Named Column templates reference column names in the template. Generic Column Templates reference the #COLUMN_VALUE# substitution string in the template.

Theme indicates the theme to which the template is a member. Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class. Use the Translatable check box to indicate the template contains text strings that require translation.

Template Subscription

Use Template Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, click Refresh Template.

Before Rows

In Before Rows, enter HTML that displays once at the beginning of a report template. Opening an HTML table is a common use of this attribute as shown in the following example:

<table>

You can identify column headers using the syntax #1#, #2#, #3#. For example:

<th>#1#</th><th>#2#</th><th>#3#</th>

You can include pagination above a report by including the substitution string #TOP_PAGINATION#. This substitution string generates HTML that starts with an opening <tr> tag and ends with a closing </tr> tag. For example, to include an open table tag and the #TOP_PAGINATION# substitution string, you would enter the following:

<table>#TOP_PAGINATION#

You can also include the substitution string #CSV_LINK# to include support for exporting your report to comma-separated value (CSV) format, a format compatible with most spreadsheet programs.

Column Headings

Use Column Heading Template to add color to each column header cell. Note that the text of this attribute must indicate where the cell heading text will be colorized. For example:

<th #ALIGNMENT#>#COLUMN_HEADER#</th>

If you do not want any column headings, enter the following:

OMIT

If you do use this attribute, Application Express engine applies the default column heading template.

Before Each Row

In Before Each Row, enter text to display before all columns in the report. Use this attribute to open a new HTML row. Before Each Row supports the following substitution strings:

- #ROWNUM#

Use this substitution string to specify the current row.

- #COLCOUNT#

Use this substitution string to specify the number of columns.

- #HIGHLIGHT_ROW#

Use this substitution string to specify the number of highlighted rows.

Column Templates

Column templates define the look of each column. You can define up to four column templates; each can be conditional. For example, you can have different background colors for even and odd rows, or highlight rows that meet a PL/SQL defined condition.

In each Column Template, you define the look of each column. Column Templates support the substitution strings described in Table 7-9.

Table 7-9 Column Template Substitution Strings

Substitution String

Description

#ALIGNMENT#

Determines the column alignment. Specified by the user.

#COLCOUNT#

Defines the count of the number of columns.

#COLNUM#

Defines the current column number.

#COLUMN_HEADER#

Defines the column header.

#COLUMN_VALUE#

Replaced with the value of the column.

#ROWNUM#

Specifies the current row number.

Consider the following example:

<td> #ALIGNMENT#>#COLUMN_VALUE#</td>

If you actually ran this report, these substitution strings would be replaced with values generated by the results of a SQL query.

By creating conditions, you can create a report that displays columns differently depending on whether or not the specified condition is met. To specify a column template be used conditionally, select a condition type from the Column Template Condition list. Valid values include:

- Use Based on PL/SQL Expression. Conditionally formats columns based on data in that row.

- Use for Even Numbered Rows. Conditionally formats even numbered rows.

- Use for Odd Numbered Rows. Conditionally formats odd numbered rows.

If you select Use Based on PL/SQL Expression, the next step is to enter a PL/SQL expression in the Column Template Expression field. For example, the following expression displays a value in bold if the value is greater than 2000:

#SAL# > 2000

Note that you could also use the substitution string #ROWNUM#. For example:

#ROWNUM# > 2000

After Each Row

In After Each Row, enter HTML that displays after all columns in the report display. This attribute is often used to close an HTML table row. For example:

</tr>

After Rows

Use After Rows to specify text that should display after the last row. A common use of this attribute is to close the HTML table tag. For example:

</table>

The After Rows attribute supports the following substitution strings:

- #PAGINATION#

Replaced with a pagination attribute.

- #COLCOUNT#

Substituted at run time with the number of columns defined in the report.

Row Highlighting

Use Background color for checked row to control the background color of a report row when the row selector is checked. Use Background color for current row to control the background color of a report row when the user moves the mouse over the row.

Pagination Subtemplate

The Pagination Subtemplate section contains attributes for editing the Pagination Template, Next Page Template, Previous Page Template, Next Set Template, and Previous Template. Pagination Subtemplates support the substitution strings #PAGINATION_NEXT#, #PAGINATION_NEXT_SET#, #PAGINATION_PREVIOUS# and #PAGINATION_PREVIOUS_SET#. Table 7-12 describes these templates.

Table 7-10 Pagination Subtemplate Attributes

Pagination Subtemplate Attribute

Description

Pagination Template

Applies to the entire pagination subtemplate. For example:

<span class="instructiontext">#TEXT#</span>

You can use the substitution string #TEXT# to specify where you want the pagination subtemplate to display.

Use the other Pagination Subtemplate attributes to modify individual items.

Next Page Template

Enter HTML to modify how the Next Page portion of the pagination subtemplate appears. For example:

<a href="#LINK#">next</a>

Previous Page Template

Enter HTML to modify how the Previous Page portion of the pagination subtemplate appears. For example:

<a href="#LINK#">previous</a>

Next Set Template

Enter HTML to modify how the Next Set portion of the pagination subtemplate appears. For example:

<a href="#LINK#">next set</a>

Previous Set Template

Enter HTML to modify how the Previous Set portion of the pagination subtemplate appears. For example:

<a href="#LINK#">previous set</a>

Comments

Use this attribute to record comments about this component.

Report Column Template Attributes for Named Column Templates

This section describes specific sections of the Edit Report Template page for Named Column Templates. You can access the sections of the page by either scrolling down the page, or by clicking a navigation button at the top of the page. Note that when you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

Name

Template Name identifies the name of the template. Template Type indicates the type of template. Named Column templates reference column names in the template. Generic Column Templates reference the #COLUMN_VALUE# substitution string in the template.

Theme indicates the theme to which the template is a member. Use the Translatable check box to indicate the template contains text strings that require translation. Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. Application Builder accomplishes this template mapping through the assignment of a template class.

Subscription

Use Subscription to apply an existing template to the current application. When you select an existing template, you become a subscriber to that template.

To load a new copy of a master template, click Refresh.

Row Templates

Row templates define the look of each column. You can define up to four row templates, each of which can be conditional.

In each Row Template, you define the look of each row. Row Templates support the substitution strings described in Table 7-11.

Table 7-11 Row Template Substitution Strings

Substitution String

Description

#ALIGNMENT#

Determines the row alignment. Specified by the user.

#COLCOUNT#

Defines the count of the number of columns.

#COLNUM#

Defines the current column number.

#COLUMN_HEADER#

Defines the column header.

#COLUMN_VALUE#

Replaced with the value of the column.

#ROWNUM#

Specifies the current row number.

By creating conditions, you can create a report that displays rows differently depending on whether or not the specified condition is met. To specify a row template be used conditionally, select a condition type from the Column Template Condition list. Valid values include:

- Use Based on PL/SQL Expression. Conditionally formats columns based on data in that row.

- Use for Even Numbered Rows. Conditionally formats even numbered rows.

- Use for Odd Numbered Rows. Conditionally formats odd numbered rows.

If you select Use Based on PL/SQL Expression, the next step is to enter a PL/SQL expression in the Column Template Expression field. For example, the following expression displays a value in bold if the value is greater than 2000:

#SAL# > 2000

Note that you could also use the substitution string #ROWNUM#. For example:

#ROWNUM# > 2000

Column Headings

Use this template to add color to each column header cell. The text of this attribute must include help to indicate where the cell heading text should be colorized. If you do not enter a Column Heading Template, then a default column header template is applied. If you do not want any column headings, then enter OMIT. For example:

<th #ALIGNMENT#>#COLUMN_HEADER#</th>

Before first and after last row text

In Before Rows, enter HTML that displays once at the beginning of a report template. Opening an HTML table is a common use of this attribute, as shown in the following example:

<table>

You can identify column headers using the syntax #1#, #2#, #3#. For example:

<th>#1#</th><th>#2#</th><th>#3#</th>

You can include pagination above a report by including the substitution string #TOP_PAGINATION#. This substitution string generates HTML that starts with an opening <tr> tag and ends with a closing </tr> tag. For example, to include an open table tag and #TOP_PAGINATION# substitution string, you would enter the following:

<table>#TOP_PAGINATION#

You can also include the substitution string #CSV_LINK# to include support for exporting your report to CSV format, a format compatible with most spreadsheet programs.

Use After Rows to specify text that should display after the last row. A common use of this attribute is to close the HTML table tag. For example:

</table>

The After Rows attribute supports the following substitution strings:

- #PAGINATION#

Replaced with a pagination attribute.

- #COLCOUNT#

Substituted at run time with the number of columns defined in the report.

Pagination

The Pagination section contains attributes for editing the Pagination Template, Next Page Template, Previous Page Template, Next Set Template, and Previous Template. Pagination Subtemplates support the substitution strings #PAGINATION_NEXT#, #PAGINATION_NEXT_SET#, #PAGINATION_PREVIOUS# and #PAGINATION_PREVIOUS_SET#. Table 7-12 describes these templates.

Table 7-12 Pagination Subtemplate Attributes

Pagination Subtemplate Attribute

Description

Pagination Template

Applies to the entire pagination subtemplate. For example:

<span class="instructiontext">#TEXT#</span>

You can use the substitution string #TEXT# to specify where you want the pagination subtemplate to display.

Use the other Pagination Subtemplate attributes to modify individual items.

Next Page Template

Enter HTML to modify how the Next Page portion of the pagination subtemplate appears. For example:

<a href="#LINK#">next</a>

Previous Page Template

Enter HTML to modify how the Previous Page portion of the pagination subtemplate appears. For example:

<a href="#LINK#">previous</a>

Next Set Template

Enter HTML to modify how the Next Set portion of the pagination subtemplate appears. For example:

<a href="#LINK#">next set</a>

Previous Set Template

Enter HTML to modify how the Previous Set portion of the pagination subtemplate appears. For example:

<a href="#LINK#">previous set</a>

Comments

Use this attribute to record comments about this component.

About Using JavaScript in Column Templates

You can conditionally display HTML depending upon values in the database using JavaScript. The following example displays an HTML row only if the GROUP_DESC query column is not null:

<script language="javascript">
IF ( "#GROUP_DESC#" != "" )
document.writeln( "<TR>;
<TD BGCOLOR=#336699>;</TD>
</TR>
</TR>
<TD>#GROUP_DESC#</TD>
</TR>" );
</TR>" );

See Also:

- Online Help for information about using specific sections of the Edit Report Template page

- "Understanding Regions"

Optimizing a Page for Printing

You can optimize a page for printing by creating a specific Printer Friendly template and selecting that template on the Create/Edit Theme page. See "Changing the Default Templates in a Theme".

Generally, a Printer Friendly template optimizes a page for printing. For example, a Printer Friendly template might:

- Not display tabs or navigation bars

- Display items as text instead of as form elements

If the theme you select does not include a printer friendly template, you can create a Printer Friendly template by creating a new page template.

See Also:
"Changing the Default Templates in a Theme", "Creating a New Template", and "Printing Report Regions"

Topics in this section include:

- Selecting a Printer Friendly Template for an Application

- Using f?p Syntax to Toggle to Printer Friendly Mode

Selecting a Printer Friendly Template for an Application

To select a Printer Friendly template:

1. Navigate to the Themes page:

a. On the Workspace home page, click Application Builder.

b. Select an application.

c. Click Shared Components.

d. Under User Interface, select Themes.

2. In the Themes list, click the theme name.
The Create/Edit Theme page appears.

3. Scroll down to Component Defaults and locate the Printer Friendly Page list.

4. Make a new selection from the Printer Friendly Page list.

5. Click Apply Changes.

See Also:
"Changing the Default Templates in a Theme"

Using f?p Syntax to Toggle to Printer Friendly Mode

Once you create a Printer Friendly template and select it, you can use f?p syntax to toggle to Printer Friendly mode. Including the ninth f?p syntax argument (PrinterFriendly) renders the page in printer friendly mode (optimizing printed output). For example, you could include this argument when coding a link or creating a navigation bar icon.

See Also:
"Using f?p Syntax to Link Pages"

Using Custom Cascading Style Sheets

A cascading style sheet (CSS) provides a way to control the style of a Web page without changing its structure. When used properly, a CSS separates visual attributes such as color, margins, and fonts from the structure of the HTML document. Oracle Application Express includes themes that contain templates that reference their own CSS. The style rules defined in each CSS for a particular theme also determine the way reports and regions display.

Topics in this section include:

- Uploading Cascading Style Sheets

- Referencing an Uploaded Cascading Style Sheet in the Page Template

See Also:
"Using the CSS Finder"

Uploading Cascading Style Sheets

You upload cascading style sheets to your workspace using the Cascading Style Sheet Repository. Uploaded cascading style sheets (CSS) are available to any application created in your workspace. The cascading style sheets are written to the file system, so you can reference them in your HTML source code.

To upload cascading style sheets:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Files, select Cascading Style Sheets.
The Cascading Style Sheet page appears.

5. From the View list, select Details. See "About the Cascading Style Sheets Page".

6. To upload a new CSS, click Create and follow the on-screen instructions.

7. To edit an existing CSS, select the CSS name.

8. To download an existing CSS, click the Download icon.

About the Cascading Style Sheets Page

Once you upload a CSS to the CSS Repository, you control how the page displays by making a selection from the View list. Available options include:

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

- Details displays each CSS as a line in a report. To edit a CSS, click the appropriate name.

Referencing an Uploaded Cascading Style Sheet in the Page Template

You can reference an uploaded cascading style sheet within the Header section of the page template. You use the Header section to enter the HTML that makes up the <HEAD> section of the HTML document.

To reference an uploaded cascading style sheet:

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

2. Select an application.

3. Click Shared Components.

4. Under User Interface, select Themes.
The Themes page appears.

5. On the Tasks list, click View Templates.

6. Select the name of the page template you want to edit.

7. Use a <link> tag within the head section to reference the appropriate style sheet.
To reference an uploaded file that is associated with a specific application, you would use the substitution string #APP_IMAGES#. For example:

<html>
<head>
<title>#TITLE#</title>
#HEAD#
<link rel="stylesheet" href="#APP_IMAGES#sample2.css" type="text/css">
</head>
...

To reference an uploaded file that is associated with a specific workspace, you would use the substitution string #WORKSPACE_IMAGES#. For example:

<html>
<head>
<title>#TITLE#</title>
#HEAD#
<link rel="stylesheet" href="#WORKSPACE_IMAGES#sample3.css" type="text/css">
</head>
...

See Also:
"Uploading Cascading Style Sheets", "Creating a New Template", "Editing Templates", "Page Templates", "APP_IMAGES", and "WORKSPACE_IMAGES"

Managing Images

You can reference images within your application by uploading them to the Images Repository. When you upload an image, you can specify whether it is available to all applications or a specific application.

Topics in this section include:

- Uploading Images

- Referencing Images

- Editing Image Attributes

- Deleting an Image

Tip:
You can use the Images Finder to identify images available to the current application. See "Using the Images Finder".

Uploading Images

You upload images to your workspace using the Image Repository.

To upload images to your workspace:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Files, select Images.
The Images page appears.

5. To upload a new image, click Create.

6. On the Create Image page, specify the following:

a. Application - Select No Application Associated to make the image available to all applications within the workspace, or select a specific application ID.

b. Upload New Image - Click Browse to identify a file to upload.

c. Note - Enter details that describe the image.

7. Click Upload.

Referencing Images

You can reference images in your application by referencing the substitution string #IMAGE_PREFIX# or including a fully qualified URL to the image.

Topics in this section include:

- Verifying the Prefix for the Virtual Image Directory

- Referencing an Image Using #IMAGE_PREFIX#

- Referencing Images Using a Fully Qualified URL

Verifying the Prefix for the Virtual Image Directory

When you install Application Builder, the installer creates a virtual directory for images. This virtual directory points to the actual path on the file system that contains uploaded images. By default, you reference this virtual directory using the prefix:

/i/

When you first create an application, you need to verify this prefix on the Edit Definition page.

To verify the Image Prefix for an application:

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

2. Select an application.

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

4. Under Application, select Definition.

5. When the Edit Application Definition page appears, locate the Image Prefix field.
By default, this attribute is defined as /i/. Contact your administrator for information about the name of this virtual directory for your installation.

Referencing an Image Using #IMAGE_PREFIX#

When you embed an image in static text (for example, in page headers, region headers, or footers), you can reference the image using the substitution string #IMAGE_PREFIX#. For example, to reference the image go.gif, you would use the following syntax:

<img src="#IMAGE_PREFIX#go.gif">

See Also:
"About Built-in Substitution Strings", "IMAGE_PREFIX", "APP_IMAGES", and "WORKSPACE_IMAGES"

Referencing Images Using a Fully Qualified URL

Alternatively, you can also reference an image using a fully qualified URL. For example:

<img src="http://g-images.amazon.com/images/G/01/associates/navbar2000/logo-no-border(1).gif">

Editing Image Attributes

When you edit image attributes, you can add notes that describe an image or change the associated application. However, you cannot change the actual image. To change an image, delete it and then upload it again.

See Also:
"Deleting an Image" and "Uploading Images"

To edit images attributes:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Files, select Images.
The Images page appears.

5. Use the following controls to filter the view:

a. Image - Enter text to search for an image name or notes describing the image. Select whether to search for All Images, Workspace Images, or Application Images.

b. View - Select one of the following:

- Icons (the default) displays each image as a large icon.

- Details displays each image as a line in a report.

c. Display - Determines the number of images that display.

d. Click Go.

6. Select an image.
The Edit Image Attributes page appears.

7. From Application, specify the image availability.
Select No Application Associated to make the image available to all applications within the workspace, or select a specific application ID.

8. In Notes, enter details that describe the image.

9. Click Apply Changes.

Deleting an Image

To delete an image:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Files, select Images.
The Images page appears.

5. Use the following to filter the view:

a. Image - Enter text to search for an image name or notes describing the image. Select whether to search for All Images, Workspace Images, or Application Images.

b. View - Select one of the following:

- Icons (the default) displays each image as a large icon.

- Details displays each image as a line in a report.

c. Click Go.

6. Select an image.

7. Click Delete.

Managing Static Files

You can upload static files to your workspace using the Static File Repository.

Topics in this section include:

- Uploading Static Files

- Editing an Uploaded File

- Downloading an Uploaded File

- Deleting an Uploaded File

Uploading Static Files

To upload static files:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Files, select Static Files.
The Static Files page appears.

5. To upload a file, click Create.

6. Follow the on-screen instructions.

Editing an Uploaded File

You can edit static files smaller than 30,000 bytes by selecting the file name. Otherwise, you must edit the file offline and upload it again.

To edit a static file smaller than 30,000 bytes:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Files, select Static Files.
The Static Files page appears.

5. Use the following controls to filter the view:

a. Static File - Enter text to search for a file name or notes describing the file.

b. Application - Narrow or broaden the view by selecting one of the following:

- All Static Files

- No Associated Application

- A specific application

c. View - Select one of the following:

- Icons (the default) displays each file as a large icon.

- Details displays each file as a line in a report.

d. Display - Determines the number of files to display.

e. Click Go.

6. Select a file.

7. If the file is smaller than 30,000 bytes, edit the file.

8. In Notes, edit or enter notes describing the file.

9. Click Apply Changes.

Downloading an Uploaded File

To download an uploaded file:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Files, select Static Files.
The Static Files Repository appears.

5. From View, select Details and click Go.
Details displays each file as a line in a report.

6. Select the Download icon next to the appropriate file.

Deleting an Uploaded File

To delete an uploaded static file:

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

2. Select an application.

3. Click Shared Components.
The Shared Components page appears.

4. Under Files, select Static Files.
The Static Files Repository appears.

5. Use the following controls to filter the view:

a. Static File - Enter text to search for a file name or notes describing the file.

b. Application - Narrow or broaden the view by selecting one of the following:

- All Static Files

- No Associated Application

- A specific application

c. View - Select one of the following:

- Icons (the default) displays each file as a large icon.

- Details displays each file as a line in a report.

d. Display - Determines the number of files to display.

e. Click Go.

6. Select a file.

7. Click Delete.

Rendering HTML Using Custom PL/SQL

If you need to generate specific HTML content not handled by Oracle Application Express forms, reports, and charts, you can use the PL/SQL region type. To generate HTML in this type of region, you need to use the PL/SQL Web Toolkit. You can reference session state using bind variable syntax. Keep in mind that when you generate HTML in this way, you do not get the same consistency and control provided with templates.

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

To give you more control over HTML dynamically generated within a region, you can use PL/SQL. For example, to print the current date, you could create a region with the following source:

htp.p(TO_CHAR(SYSDATE,'Day Month DD, YYYY'));

This next example accesses tables:

DECLARE
l_max_sal NUMBER;
BEGIN
SELECT max(sal) INTO l_max_sal FROM emp;
htp.p('The maximum salary is: '||TO_CHAR(l_max_sal,'999,999.00'));
END;

8 Understanding Application Administration

In the Oracle Application Express development environment, users log in to a shared work area called a workspace. These users are divided into two primary roles: developer and workspace administrator.

Developers can create and edit applications as well as view developer activity, session state, workspace activity, application, and schema reports. Workspace administrators additionally can create and edit user accounts, manage groups, and manage development services. This section describes how to perform Workspace administrator tasks and access many of these reports.

This section contains the following topics:

- Understanding Administrator Roles

- About the Application Administration Page

- About the Manage Services Page

- Managing Session State and User Preferences

- Managing Cached Regions and Pages

- Managing Workspace Preferences

- Managing Application Models

- Managing Demonstration Applications

- Leveraging Application Builder Defaults

- Viewing the Workspace Overview Report

- Terminating a Workspace Service

- Requesting a Database Schema

- Requesting Additional Storage

- Viewing Schema Reports

- Managing Log Files

- Managing Application Express Users

- Monitoring Activity within a Workspace

See Also:
"Monitoring the Database" and "Viewing Database Details"

Understanding Administrator Roles

In an Oracle Application Express development environment, there are two different administrator roles:

- Workspace administrator

- Oracle Application Express administrator

A Workspace administrator performs administrator tasks specific to a workspace such as managing user accounts, monitoring workspace activity, and viewing log files. In contrast, an Oracle Application Express administrator is a superuser who manages the entire hosted instance. To become a Workspace administrator, an existing administrator must give the developer administrator privileges on the Edit User Page.

See Also:
"Managing an Oracle Application Express Hosted Service" for more information on the responsibilities of an Oracle Application Express administrator

About the Application Administration Page

Use the Application Administration page to manage your application development environment. The Application Administration page contains the following icons:

- Manage Services links to the Manage Services page. Use this page to manage services, including session state, log files, service termination, schema requests, storage requests, schema reports, preferences, and application models. See "About the Manage Services Page".

- Manage Application Express Users links to the Manage Application Express Users page. Use this page to manage Application Express user accounts and user groups. See "Managing Application Express Users".

- Monitor Activity links to the Monitor Activity page. Use this page to monitor changes to page views and entire applications in your workspace. It also shows reports on such information as login attempts and external click counts. See "Monitoring Activity within a Workspace".

A Tasks list displays on the right side of the page and displays the following links:

- Change Password links to a form you can use to change your password. See Resetting Your Password from Application Administration.

- About Application Express links to an About page that lists basic product information. See "Viewing the Application Express Product Information Page".

Topics:

This section contains the following topics:

- Accessing the Application Administration Page

- Resetting Your Password from Application Administration

- Viewing the Application Express Product Information Page

Accessing the Application Administration Page

Use the Application Administration page to manage your application development environment.

To access the Application Administration page:

1. Navigate to the Workspace home page.

2. On the Administration list, click Administration.
The Application Administration page appears.

Resetting Your Password from Application Administration

To reset your password from the Application Administration page:

1. Log in to Oracle Application Express. See "Logging In to Oracle Application Express".

2. On the Tasks list, click Administration.
The Application Administration page appears.

3. On the Tasks list, click Change Password.

4. In Change Password, enter the following:

- Enter Current Password - Enter your current password.

- Enter New Password - Enter your new password.

- Confirm New Password - Enter your new password again.

5. Click Apply Changes.

See Also:
""Changing an End User Password"

Viewing the Application Express Product Information Page

The About Application Express page lists basic product information. You can access the About Application Express page from either the Workspace home page or the Application Administration page.

The About Application Express page displays the following product information:

- Product build

- Schema compatibility

- Last DDL time

- Host schema

- Application Owner

- Workspace ID

- Workspace Name

- Current user

- Language Preference

- Current Time (on server)

- NLS_CHARACTERSET

- DAD CHARACTERSET

- JOB_QUEUE_PROCESSES

- Database Version Information

To view the About Application Express page:

1. Navigate to the Workspace home page.

2. On the Administration list, click About Application Express.
The About Application Express page appears.

About the Manage Services Page

You can use the Manage Services page to manage session state, caching, preferences, application models, demonstration applications, log files, service termination, schema requests, storage requests, schema reports, and log files.

The Manage Services page contains the following sections:

- Session State. Use these links to purge session state and user preferences. See "Managing Session State and User Preferences".

- Caching. Use these links to view and purge cached regions and pages. See "Managing Cached Regions and Pages".

- Workspace Preferences. Use this link to disable and enable application preferences such as PL/SQL program unit editing in Object Browser. See "Managing Workspace Preferences".

- Applications. Use the Application Models link to search for and delete application models. Use the Demonstration Applications link to manage demonstration applications. See "Managing Application Models" and "Managing Demonstration Applications".

- Workspace:

- Request Database Schema. Use this link to request a new database schema. See "Requesting a Database Schema".

- Request Storage. Use this link to submit a request for additional storage space for your workspace. See "Requesting Additional Storage".

- Request Service Termination. Use this link to terminate the current workspace. See "Terminating a Workspace Service".

- Workspace Overview. Use this link to view a summary report about the current workspace. See "Viewing the Workspace Overview Report".

- Workspace Schema Reports. Use these links to view detailed reports about the schemas in the current workspace. See "Viewing Schema Reports".

- Logs. Use these links to purge the Developer Activity and External Count Clicks logs. See "Managing Log Files".

Accessing the Manage Services Page

To access the Manage Services Page:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

Managing Session State and User Preferences

A session is a logical construct that establishes persistence (or stateful behavior) across page views. Each session is assigned an unique ID, which the Application Express engine uses to store and retrieve an application's working set of data (or session state) before and after each page view. Sessions persist in the database until purged.

Topics in this section include:

- Managing Session State

- Managing User Preferences

See Also:
"Understanding Session State Management" and "Managing Session State"

Managing Session State

A session establishes persistence (or stateful behavior) across page views. You can review session details for the current session or for recent sessions. You can also purge the current session state or purge sessions based on their age.

Topics in this section include:

- Removing Session State After Reviewing Session Details

- Viewing Session State Details

- Purging Session State for the Current Session

- Purging Sessions by Age

Removing Session State After Reviewing Session Details

You can determine whether to remove existing sessions by first reviewing session details. From the Session Details page, you can then remove the session record or session state.

To view session details and remove session state:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Session State, click Manage Session State.

4. Click Recent Sessions with Drill-Down to Session Details.

5. To narrow the results, select a time frame, specify a user, and click Go.

6. To view session details, select the session ID.
The Session Details page appears.

7. Click one of the following buttons:

- Remove Session removes the record of the session from the SESSIONS table along with the session state (including collections data) associated with the session.

Any user using a session that is removed will no longer be able to use the session and will be prompted to re-authenticate upon their next page request (in most situations). This option could be used by administrators who might have a need to make sure a specific user could no longer access an Oracle Application Express application.

- Remove State clears the session data from the session state tables (including collections data) but does not remove the session record. Removing a session is a good approach for developers during debugging.

This is the equivalent of clearing session state for the current session using the Clear Cache argument value SESSION in the f?p URL. This option might also be used by developers during debugging.

See Also:
"Clearing Cache for the Current User Session" and "Debugging an Application"

Viewing Session State Details

To view session state for the current or recent sessions:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Session State, click Manage Session State.

4. On the Manage Session State page:

- To view information about the current session, click Report Session State for Current Session. To search for an item in the details, enter the item and click Go.

- To view a list of recent sessions, click Recent Sessions with Drill-Down to Session Details.

See Also:
"Removing Session State After Reviewing Session Details"

Purging Session State for the Current Session

To purge session state for the current session:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Session State, click Manage Session State.

4. On the Manage Session State page, click Purge Session State for Current Session.

5. From the Purge Session State page:

- To view information about the current session, click View Session State.

- To reset the session state for the current session, click Purge Session State.

Purging Sessions by Age

To purge existing sessions by age:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Session State, click Manage Session State.

4. Select Purge sessions by Age.

5. Make a selection from the Sessions older than list.

6. Click one of the following buttons:

- Report Sessions generates a report detailing the total number of sessions for the workspace, the number of users, and the number of old sessions.

- Purge Sessions purges existing sessions by the age you selected.

See Also:
"Viewing Session State"

Managing User Preferences

You can use preferences to store values for a specific Application Express user across distinct sessions. Once set, these preferences can be removed programmatically or manually. You can set user preferences by creating a page process, by the calculation of a preference Item Source Value, or programmatically by using a PL/SQL API.

Topics in this section include:

- Viewing and Resetting Preferences for the Current User

- Viewing Preferences for Users

- Setting User Preferences

- Removing User Preferences Programatically

- Resetting User Preferences Using a Page Process

- Purging Preferences for a Specific User

Viewing and Resetting Preferences for the Current User

To manage user preferences for the current user:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Session State, click Manage Preferences.

4. On the Manage Preferences page:

- To view preference information about the current user, click Report Current User Preferences.

- To view and reset preferences for the current user, click Purge Preferences by Current User. On the Purge Preferences page, click the appropriate button.

Viewing Preferences for Users

You view preferences for specific users on the Preferences by User report.

To view the Preferences by User report:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Session State, click Preferences by user.
The Preferences by Users page appears.

4. To narrow the results, specify a user, name, or preference type, and click Go.

Setting User Preferences

You can set user preferences within your application through the creation of a page process, by creating a preference item, or programmatically.

Topics in this section include:

- Setting User Preferences Using a Page Process

- Setting the Source of an Item Based on a User Preference

- Setting User Preferences Programatically

Setting User Preferences Using a Page Process

To set user preference values by creating a page process:

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

2. Under Processes, click the Create icon.
The Create Page Process Wizard appears.

3. For the process category, select Session State.

4. For the process type, select one of the following:

- Set Preference to value of item

- Set Preference to value of item if item is not null

5. Specify a process name, sequence, and processing point.

6. Specify the preference value in the field provided using the format:

PreferenceName:Item

7. Click Page Items to see a list of available items.

8. Click Create Process.

Setting the Source of an Item Based on a User Preference

You can set the source of an item based on a user preference by defining the item source type as Preference.

To define the source of item based on a user preference:

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

2. Under Items, click the Create icon.
The Create Item Wizard appears.

3. For the item type, select Hidden.

4. Specify the Item Name, sequence, and region.

5. From the Item Source list, select Preference.

6. In Item Source Value, enter the name of the preference.

7. Click Create Item.

Setting User Preferences Programatically

To set or reference user preferences programmatically, you must use a PL/SQL API. User-level caching is available programmatically. You can use the set_preference function to set a user level preference called NAMED_PREFERENCE. For example:

APEX_UTIL.SET_PREFERENCE(
p_preference=>'NAMED_PREFERENCE',
p_value =>:ITEM_NAME);

You can reference the value of a user preference using the function GET_PREFERENCES. For example:

NVL(APEX_UTIL.GET_PREFERENCE('NAMED_PREFERENCE'),15)

In the previous example, the preference would default to the value 15 if the preference contained no value.

See Also:
"GET_PREFERENCE Function" and "SET_PREFERENCE Procedure"

Removing User Preferences Programatically

To remove user preferences programmatically, you must use a PL/SQL API. You can use the REMOVE_PREFERENCE procedure to remove a user level preference called NAMED_PREFERENCE. For example:

APEX_UTIL.REMOVE_PREFERENCE(
p_preference=>'NAMED_PREFERENCE');

Resetting User Preferences Using a Page Process

You can reset user preferences by creating a page process and selecting the Reset Preferences process type.

To reset user preferences using a page process:

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

2. Under Processes, click the Create icon.
The Create Page Process Wizard appears.

3. For the process category, select Session State.

4. From Type, select Reset Preferences.

5. Specify a process name, sequence, and process point.

6. Follow the on-screen instructions.

Purging Preferences for a Specific User

You can purge preferences for a specific user on the Purge Preferences page.

To purge preferences for a specific user:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Session State, click Purge preferences by User.
The Purge Preferences page appears.

4. Select a specific user and click Report.
A report appears at the bottom of the page.

5. To purge the displayed user preferences, click Purge User Preferences.

Managing Cached Regions and Pages

One way to improve an application's performance it to take advantage of page and region caching. Developers can configure page and region caching by setting the Cache attribute on Edit Page or Edit Region pages. This section describes how Workspace administrators can view and purge cached regions and pages.

Topics:

Topics in this section include:

- Purging Cached Regions

- Purging Cached Pages

See Also:
"Accessing Page Attributes" and "Editing Region Attributes"

Purging Cached Regions

To view and purge cached regions:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Caching, click Manage Cached Regions.

4. To locate an application, page, or region, enter a case-insensitive query in the appropriate field at the top of the page and click Go.

5. To purge cached regions, you can:

a. Select the regions you want to purge and click Purge Checked.

b. Click the Purge by Application tab, select the application, and click Purge Cached Regions.

c. Click the Purge All tab and then click Purge All Cached Regions.

Purging Cached Pages

To view and purge cached pages:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Caching, click Manage Cached Pages.
The Manage Cached Pages page appears.

4. To locate an application, page, or region, enter a case-insensitive query in the appropriate field at the top of the page and click Go.

5. To purge cached pages, you can:

a. Select the pages you want to cache and click Purge Checked.

b. Click the Purge by Application tab, select the application, and click Purge Cached Pages.

c. Click the Purge Expired tab, select the application, and then click Purge Expired.

Managing Workspace Preferences

Workspace administrators can set up the following preferences and apply the settings for the current workspace:

- PL/SQL Editing

- Account Login Control

Topics:

Topics in this section include:

- Disabling PL/SQL Program Unit Editing for a Workspace

- Enabling Login Controls for a Workspace

Disabling PL/SQL Program Unit Editing for a Workspace

By default, developers can change and compile PL/SQL source code when browsing database procedures, packages, and functions in SQL Workshop Object Browser. Workspace administrators can disable PL/SQL program unit editing by selecting Do not allow PL/SQL program unit editing on the Preferences page.

To disable PL/SQL program unit editing:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Click Preferences.
The Preferences page appears.

4. Under PL/SQL Editing, select one of the following:

- Allow PL/SQL program unit editing

- Do not allow PL/SQL program unit editing

If you select Do not allow PL/SQL program unit editing, developers can still create and replace PL/SQL program units using scripts or SQL Commands.

See Also:
"Disabling PL/SQL Program Unit Editing for an Instance" and "Using SQL Commands"

Enabling Login Controls for a Workspace

There are two different ways to configure login controls:

- An Oracle Application Express administrator enables account login controls for all Application Express accounts in all workspaces across a development instance.

If your Oracle Application Express administrator configures these preferences for an instance, those settings display as the defaults for all workspaces. See "Enabling Login Controls for All Workspaces".

- If the Oracle Application Express administrator does not enable login controls across an entire instance, then each Workspace administrator can enable the following controls on a workspace-by-workspace basis:

- Require end-user account expiration and locking

- Set up a maximum number of failed login attempts for end-user accounts

- Set the password lifetime for end-user accounts, that is, the number of days an end-user account password can be used before it expires

Tip:
This feature applies only to accounts created using the Application Express user creation and management facilities. It provides additional authentication security for applications. See "Managing Application Express Users".

To enable login controls for a workspace:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Workspace Preferences, click Set Workspace Preferences.

4. Under Account Login Control:

a. Account Expiration and Locking - Click Enable.
If you select Enable, end-user account passwords will expire after a configurable time period, accounts will be locked after a configurable number of authentication failures, and account passwords can be set to expire after the first use.

If your Oracle Application Express administrator set the Require User Account Expiration and Locking preference to Yes, this preference defaults to Enable and you cannot update it.

b. Maximum Login Failures Allowed - Enter a number for the maximum number of consecutive unsuccessful authentication attempts allowed before an end-user account is locked. If you do not specify a value in this field, the instance-level setting for Maximum Login Failures Allowed is used.

c. User Account Lifetime (days) - Enter a number for the maximum number of days an end-user account password may be used before the account expires. If you do not specify a value in this field, the instance-level setting for Account Password Lifetime is used.

5. Click Apply Changes.

Managing Application Models

Running the Create Application Wizard creates an application model. This model contains basic application property values, such as the application pages and page definitions, DML processes, and multi-row operation processes. When you create a new application, you can base it on an existing application model, making the creation process more productive.

See Also:
"About the Create Application Wizard"

This section contains the following topics:

- Deleting an Application Model

Deleting an Application Model

You can remove unwanted application models on the Application Models page.

To delete an application model:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Applications, click Application Models.

4. On the Application Models page:

- To narrow the results, select the owner and click Go.

- To search for a model, enter a case insensitive query in the Model field and click Go.

5. Select the models you want to delete and click Delete Checked.

See Also:
"Creating an Application"

Managing Demonstration Applications

Workspace administrators can review a list of available demonstration applications as well as install, re-install, edit, or remove them from your workspace.

To manage your demonstration applications:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Applications, click Demonstration Applications.
The Demonstration Applications wizard appears.

4. Click the appropriate link.

See Also:
"Running a Demonstration Application" and "Disabling the Creation of Demonstration Applications in a New Workspace"

Leveraging Application Builder Defaults

Application Builder Defaults enable developers to reduce the number of steps needed to create a new application. By configuring these attributes, developers can exit the Create Application Wizard early and can create a new application in two simple steps.

Topics in this section include:

- About Application Builder Defaults

- Configuring Application Builder Defaults

About Application Builder Defaults

Application Builder Defaults are specific to each workspace. These attributes define preferences for tabs, authentication schemes, themes, and globalization when running the Create Application Wizard. When a Workspace administrator configures these attributes, developers within that workspace can utilize these defaults and exit the Create Application Wizard after two easy steps

See Also:
"Creating Tabs", "Establishing User Identity Through Authentication", "Managing Themes", and "Managing Application Globalization"

Configuring Application Builder Defaults

To configure Application Builder Defaults:

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

2. From the Tasks list, select Application Builder Defaults.
The Manage Application Builder Defaults page appears.

3. For each section of the page, select the appropriate default.

4. To learn more about a specific attribute, click the item label.
When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

5. Click Apply Changes.

See Also:
"About Creating an Application Using a Wizard", "Creating Tabs", "Establishing User Identity Through Authentication", "Managing Themes", and "Managing Application Globalization"

Viewing the Workspace Overview Report

Workspace administrators can view a summary report of the current workspace by selecting Workspace Overview on the Manage Services page. Administrators can use this report to view:

- schemas and tablespaces

- schemas utilizing space

- space used within a given tablespace

- applications within the workspace

- developers within the workspace

This section contains the following topic:

- Viewing Workspace Summary Report

- Viewing Available Storage Space

See Also:
"Requesting Additional Storage"

Viewing Workspace Summary Report

To view a summary report about the current workspace:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Workspace, click Workspace Overview.

4. Scroll down to view the report.

Viewing Available Storage Space

The Detailed Tablespace Utilization Report lists space utilization within a specific tablespace.

To view the Detailed Tablespace Utilization Report:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Click Workspace Overview.

4. Scroll down and click the link Detailed Tablespace Utilization Report (may take several seconds).
The resulting report displays the following columns: Tablespace Name, Bytes, Bytes Used, Amount Free, and Percentage Used.

See Also:
"Requesting Additional Storage"

Terminating a Workspace Service

Terminating a workspace service removes all data, database objects, database schemas, tablespaces, applications, scripts, and files from the current Application Express instance.

To submit a request to the Oracle Application Express administrator to terminate workspace service:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Workspace, click Request Service Termination.

4. Click the Request Termination button.

5. Confirm your request by clicking Terminate Service.

Requesting a Database Schema

To submit a request to the Oracle Application Express administrator for a new database schema:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Workspace, click Request Database Schema.

4. For Identify Schema:

a. Specify whether to request a new schema or use an existing schema and then click Next.

b. For Schema Name, enter a new name or select one from the list.

c. Click Next.

5. Review the online instructions and click Finish.

Requesting Additional Storage

To request additional storage space for your workspace you must submit a request to the Oracle Application Express administrator.

See Also:
"Approving or Declining a Pending Change Request"

To submit a request for additional storage space:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under workspace, click Request Storage.

4. Specify the amount of storage to add and click Request Storage.

Tip:
To view a report of available storage space, click Schemas Utilizing Space in Tablespaces and then click the Detailed Tablespace Utilization Report (may take several seconds) link.

Viewing Schema Reports

Schema Reports offer summaries of schema tablespace utilization and database privileges by schema as well as a list of all database schemas available in the current workspace.

To view Schema Reports:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Workspace Schema Reports, click one of the following reports:

- Schema Tablespace Utilization

- Database Privileges by Schema

- Workspace Schemas

See Also:
"Viewing Application Reports"

Managing Log Files

Log entries older then one month are automatically deleted. Workspace administrators can manually purge developer logs and the External Count Clicks log on the Log files page.

Topics in this section include:

- Purging the Developer Activity Log

- Purging the External Click Count Log

See Also:
"Managing Log Entries"

Purging the Developer Activity Log

The Developer Activity Log tracks changes to applications within the current workspace.

To purge the Developer Activity Log:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Logs, click Manage Developer Activity Log.

4. Click Purge Developer Log.

Purging the External Click Count Log

The external Click Count Log counts clicks from an application to an external site. You can implement this functionality using APEX_UTIL.COUNT_CLICK procedure.

See Also:
"COUNT_CLICK Procedure"

To purge the external Click Count Log:

1. Navigate to the Workspace home page.

2. Click Manage Services on the Administration list.
The Manage Services page appears.

3. Under Logs, click Manage Click Count.

4. Click Purge Click Log.

See Also:
"Monitoring Activity within a Workspace"

Managing Application Express Users

Workspace administrators can create new user accounts, manage existing user accounts, and change user passwords. User accounts are particularly useful if you are using Application Express Authentication. Application Express Authentication checks the user name and password against the Oracle Application Express account repository. The Application Express account repository contains account information for developers and administrators when they log in to Oracle Application Express applications.

If the workspace administrator enables the Account Locking/Expiration feature for end user accounts, new account management attributes are exposed. Accounts may be locked, unlocked, or expired. Passwords for those accounts can also have restrictions, such as a fixed lifetime, a maximum number of consecutive incorrect passwords when attempting to log in, and a requirement to be changed on first use.

Topics in this section include:

- Creating New User Accounts

- Editing Existing User Accounts

- Deleting or Locking User Accounts

- Changing an End User Password

- Using Groups to Manage Application Express Users

See Also:
"Exporting Workspace Users", "About Publishing the Application URL" and "Application Express Account Credentials" for information about implementing Application Express Authentication

Creating New User Accounts

Workspace administrators can create three different types of user accounts:

- Developers can create and edit applications as well as view developer activity, session state, workspace activity, application, and schema reports.

- Workspace administrators perform administrator tasks specific to a workspace, such as managing user accounts, managing groups, altering passwords of users within the same workspace, and managing development services.

- End users have no development privileges and can access only applications that do not use an external authentication scheme.

To create a new user account:

1. Navigate to the Workspace home page.

2. From the Administration list, click Manage Application Express Users.
The Manage Application Express Users page appears.

3. Click Create.
The Create User page appears.

4. Under User Identification, enter the appropriate information.

5. Under Developer Privileges:

- Accessible Schemas (null for all) - Enter a colon-delimited list of schemas for which this developer has permissions when using the SQL Workshop. This list of schemas restricts the user to a subset of the full set of schemas provisioned for the workspace and determines what schema names the user sees in SQL Workshop.

- Default Schema - Identifies the default schema used for data browsing, application creation, and SQL script execution.

- User is a developer - To add this user as a developer or workspace administrator, select Yes. For end users, select No.

Developers can create and modify applications and database objects as well as view developer activity, session state, workspace activity, application, and schema reports.

- User is a workspace administrator - To add this user as a workspace administrator, select Yes. For developers or end users, select No.

In addition to having developer privileges, workspace administrators can create and edit user accounts, manage groups, alter passwords of users within the same workspace, and manage development services.

Note:
You create end users by adding them as users but not defining them as either developers or workspace administrators, restricting their privileges.

6. Under Account Control:

- Set Account Availability - Select Unlocked to allow a user to log in to this account. Select Locked to prevent a user from logging in to this account. Select Unlocked to enable the account to be used.

- Require Change of Password on First Use - Select Yes to require the user to change the password immediately after logging in with the current, temporary password.

This rule applies to the use of this account for developers and workspace administrators. It also applies to all users who use this account when logging in to developed applications.

Tip:
An Oracle Application Express administrator can configure these settings for an entire Oracle Application Express instance. See "Enabling Login Controls for All Workspaces".

7. Under User Groups, select an optional user group.
You can use groups to restrict access to various parts of an application. Groups are primarily useful when using Application Express Authentication.

8. Under Additional Attributes, update the user's name or add descriptive information about the user or account.

9. Click Create User or Create and Create Another.

See Also:
"Using Groups to Manage Application Express Users" and "Removing Users from a Group"

Editing Existing User Accounts

Workspace administrators can edit existing user accounts.

To edit an existing user account:

1. Navigate to the Workspace home page.

2. From the Administration list, click Manage Application Express Users.
The Manage Application Express Users page appears.

3. To display the page in a different format, make a selection from the View list and click Go:

- Icons (the default) displays each user as a large icon. Different colors indicate the user role, and a lock indicates a locked account. An hourglass, which indicates an expired password, displays when you create a new user account and specify that the new user must change passwords on first use.

- Details displays each user as a line in a report. To expand the report, select the Show Additional Report Columns check box and click Go.

4. From the Manage Application Express Users page, you can also do the following:

- To narrow the list, select a subset of accounts from the Show list and click Go.

- To search for a user, enter a case insensitive query in the Find field and click Go.

5. Select a user.
The Edit User page appears.

6. Under Edit User, update the username or email address.

7. Under Password, edit the current password by typing a new password in the Password and Confirm Password fields.

8. Under Developer Privileges:

- Accessible Schemas (null for all) - Enter a colon-delimited list of schemas for which this developer has permissions when using the SQL Workshop. This list of schemas restricts the user to a subset of the full set of schemas provisioned for the workspace and determines what schema names the user sees in SQL Workshop.

- Default Schema - Identifies the default schema used for data browsing, application creation, and SQL script execution.

- Specify the privileges for this user:

- User is a developer - Developers create and modify applications and database objects as well as view developer activity, session state, workspace activity, application, and schema reports.

- User is a workspace administrator - In addition to having developer privileges, workspace administrators can create and edit user accounts, manage groups, alter passwords of users within the same workspace, and manage development services.

9. Under Account Control:

- Account Availability - Select Locked to prevent a user from logging in to this account. Select Unlocked to enable the account to be used.

- Developer/Administrator Password and End User Password - Shows the a status of either valid or expired. A password expires when its lifetime span passes.

- Expire Password - Select this option to force the user to enter a new password the next time they log in. This option does not appear for invalid accounts or for workspaces not using the password expiration/account locking functionality.

- Require Change of Password on First Use - Select Yes to require the user to change the password immediately after logging in with the current, temporary password.

This rule applies to the use of this account for developers and workspace administrators. It also applies to all users who use this account when logging in to developed applications.

Tip:
An Oracle Application Express administrator can configure these settings for an entire Oracle Application Express instance. See "Configuring Security Settings".

10. Under User Groups, select an optional user group.
You can use groups to restrict access to various parts of an application. Groups are primarily useful when using Application Express Authentication.

11. Under Additional Attributes, update the user's name or add descriptive information about the user or account.

12. Click Apply Changes.

See Also:
"Using Groups to Manage Application Express Users" and "Removing Users from a Group"

Deleting or Locking User Accounts

Workspace administrators can delete or lock user accounts.

To delete or lock a user account:

1. Navigate to the Workspace home page.

2. From the Administration list, click Manage Application Express Users.
The Manage Application Express Users page appears.

3. To display the page in a different format, make a selection from the View list and click Go:

- Icons (the default) displays each user as a large icon. Different colors indicate the user role, and a lock indicates a locked account. An hourglass, which indicates an expired password, displays when you create a new user account and specify that the new user must change passwords on first use.

- Details displays each user as a line in a report. To expand the report, select the Show Additional Report Columns check box and click Go.

4. From the Manage Application Express Users page, you can also:

- Narrow the list, select a subset of accounts from the Show list and click Go.

- Search for a user, enter a case insensitive query in the Find field and click Go.

5. Select a user.
The Edit User page appears.

6. To delete a user:

a. Click the Delete User button.

b. Confirm your selection and click OK.

7. To lock the account:

a. Scroll down to the Account Controls section.

b. For Account Availability, select Locked.

c. Click Apply Changes.

Changing an End User Password

To change an end user password:

1. Navigate to the Workspace home page.

2. From the Administration list, click Manage Application Express Users.
The Manage Application Express Users page appears.

3. Select a user.

Tip:
To search for an existing user, enter a query in the Find field and click Go.

4. Under Password, type a new password in the Password and Confirm Password fields.

5. Click Apply Changes.

Using Groups to Manage Application Express Users

You can create groups to restrict access to various parts of an application. Keep in mind, however, that groups are not portable over different authentication schemes. Groups are primarily useful when using Application Express Authentication (Internal Cookie User authentication).

Topics in this section include:

- Creating a Group

- Editing an Existing User Group

- Viewing Group Assignment Reports

- Adding Users to a Group

- Removing Users from a Group

See Also:
"Application Express Account Credentials" for information about implementing Application Express Authentication and "Managing Application Express Users"

Creating a Group

To create a new group:

1. Navigate to the Workspace home page.

2. From the Administration list, click Manage Application Express Users.
The Manage Application Express Users page appears.

3. Click the User Groups tab.
The User Groups page appears.

4. On the User Groups page, click Create.
The Create/Edit User Group page appears.

5. Specify a group name and description, and click Create Group.

Editing an Existing User Group

To edit an existing group assignment:

1. Navigate to the Workspace home page.

2. From the Administration list, click Manage Application Express Users.
The Manage Application Express Users page appears.

3. Click the User Groups tab.
The User Groups page appears.

4. Select the group you want to edit.
The Create/Edit User Group page appears.

5. Make the appropriate edits and click Apply Changes.

Viewing Group Assignment Reports

To view a report of user group assignments:

1. Navigate to the Workspace home page.

2. From the Administration list, click Manage Application Express Users.
The Manage Application Express Users page appears.

3. Click the User Groups tab.
The User Groups page appears.

4. From the Manage Groups list, click User Group Assignments.
The User Groups Assignments report appears.

5. To edit a user group assignment, click the Edit icon.
The Edit User page appears.

6. Scroll down to User Groups and select a new group and click Apply Changes.

Adding Users to a Group

To add a user to a group:

1. Navigate to the Workspace home page.

2. From the Administration list, click Manage Application Express Users.
The Manage Application Express Users page appears.

3. Select a user.
The Edit User page appears.

4. Scroll down to User Groups.

5. Select a new group and click Apply Changes.

Removing Users from a Group

To remove a user to a group:

1. Navigate to the Workspace home page.

2. From the Administration list, click Manage Application Express Users.
The Manage Application Express Users page appears.

3. Click Existing Users.
The Existing Users page appears.

4. Select a user.
The Edit User page appears.

5. Scroll down to User Groups.

6. Deselect the group you wish to remove the user from and click Apply Changes.

Monitoring Activity within a Workspace

You can monitor developer activity and changes within your workspace by accessing the Monitor Activity page. The Monitor Activity page over twenty different reports that track changes to page views and applications, including reports on login attempts and external click counts.

Topics in this section include:

- Viewing Developer Activity and Application Change Information

- Viewing Application Changes by Developer

- Viewing Application Changes by Day

- Viewing Active Sessions

See Also:
"Creating Custom Activity Reports Using APEX_ACTIVITY_LOG" and "Monitoring Activity Across a Development Instance"

Viewing Developer Activity and Application Change Information

To view developer activity and application change information from the Monitor Activity page:

1. Navigate to the Workspace home page.

2. From the Administration list, click Monitor Activity.
The Monitor Activity page features activity reports divided into the following sections:

- Page Views - Contains reports of page views organized by view, user, application, or application and page.

- Page View Analysis - Contains reports analyzing page views, such as top page views by application.

- Environment - Contains reports of environments organized by user agent, browser, external clicks, or operating system.

- Application Changes - Contains reports that track application changes by developer, day, or application.

- Sessions - Lists active sessions with the current workspace.

- Login Attempts - Contains reports listing login attempts.

This report includes logins to:

- Application Express environment through the login pages for Oracle Application Express Administration Services or Oracle Application Express

- applications developed using Application Express that use the built-in session management facilities of Application Express

3. Select a report to review.

Viewing Application Changes by Developer

The Application Changes by Developer report displays the number of pages changed by each developer and offers a graphical representation of the information in either a bar chart or pie chart format.

To view Application Changes by Developer:

1. Navigate to the Workspace home page.

2. From the Administration list, click Monitor Activity.

3. Under Application Changes, select By Developer.

4. Make a selection form the Time list to specify a time frame and click Go.

5. To view the data as a bar chart, select Changes by Developer Bar chart. To view the data as pie chart, select Changes by Developer Pie chart.

6. To view additional details, select a user ID.
A detailed report displays the application, date, component, and action by user.

Viewing Application Changes by Day

The Application Changes by Day report displays a summary of the number of application changes by day. You have the option to view this information by month, as a line chart, or by developer.

To view application changes by day:

1. Navigate to the Workspace home page.

2. From the Administration list, click Monitor Activity.

3. Under Application Changes, click By Day or By Day, Monthly View.
The Application Changes by Day page appears.

4. Select the appropriate report:

- Month View offers a listing of application changes by day in a Calendar format.

- Report includes a report of application changes by day.

- Line Chart displays a line chart of application changes. By default, all developers are selected. To view only a specific developer, make a selection from the Developer list and click Go.

- By Developer Report displays application changes by developer. Specify a time frame by making a selection from the Time list and clicking Go. To view additional details, select a developer. To download the report, click the Download link at the bottom of the report.

Viewing Active Sessions

A session is a logical construct that establishes persistence (or stateful behavior) across page views. The Active Sessions report lists active sessions with the current workspace.

Whenever an application is run, the Application Express engine maintains a record in a database table in the Oracle Application Express schema. This table records a numeric identifier (or session ID), the authenticated (or public) user identifier, the creation date, and other information. The session is the key record that enables session state, or persistence, across page requests. By viewing the Active Sessions report, a developer or administrator can see who has been using applications in a workspace. An active session is a session that has not yet been purged from the sessions table. A DBMS job runs every eight hours and purges session records older than 24 hours.

See Also:
"What Is a Session?"

To view active session details:

1. Navigate to the Workspace home page.

2. From the Administration list, click Monitor Activity.

3. Under Sessions, select Active Sessions.

4. Click a session ID to view the Session Details page.

9 Managing User Interface Defaults

User interface defaults enable you to assign default user interface properties to a table, column, or view within a specified schema. When you create a form or report using a wizard, the wizard uses this information to create default values for region and item properties. Utilizing user interface defaults can save valuable development time and has the added benefit of providing consistency across multiple pages in an application.

Because user interface defaults are associated with a table, you can use them with applications created using the form and report wizards.

This section contains the following topics:

- Viewing Tables or Views Utilizing User Interface Defaults

- Editing Column Attributes

- Comparing User Interface Defaults Across Applications

- About Exporting and Importing User Interface Defaults

See Also:
"Leveraging Application Models and User Interface Defaults"

Viewing Tables or Views Utilizing User Interface Defaults

You can view tables or views utilizing user interface defaults by either navigating to the User Interface Defaults page or viewing the UI Defaults report in Object Browser.

Topics in this section include:

- Creating to User Interface Defaults

- Viewing the UI Defaults Report in Object Browser

See Also:
"Managing Database Objects with Object Browser"

Creating to User Interface Defaults

To create user interface defaults:

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

2. Select an application.

3. On the Application, click Shared Components.
The Shared Components page appears.

4. Under User Interface, select User Interface Defaults.
The User Interface Defaults page appears.

The current schema displays to the right of the breadcrumb menu.

5. To narrow the display, use the following controls at the top of the page and click Go:

- Table/View - Enter a case insensitive query for a table or view name within the current schema.

- Display - Determines the types of tables to display.

- View - Make a selection to filter the view:

- Icons (default) displays each table or view as a large icon.

- Details displays each table or view as a line in a report, identifying the table or view name, the object type, and whether or not user interface defaults currently exist.

- Display determines the number of items that display in the report.

6. Select a specific table or view by selecting the name.
The Table Defaults page appears.

7. If no user interface defaults exist, click Create User Interface Defaults.

Tip:
You can also access the User Interface Defaults page by clicking User Interface Defaults on the Tasks list on either the Application Builder home or Applications home pages. See "About the Application Builder Home Page" and "About the Application Home Page".

Viewing the UI Defaults Report in Object Browser

To view the User Interface Details Report in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select either Tables or Views.

3. From the Object Selection pane, select an object.

4. Select the UI Defaults tab.
The User Interface Defaults report appears displaying the following information:

- Column Name - Indicates the name of the column.

- Label - Specifies the default label text for items in a form and the heading for columns in reports.

- Report Sequence - Specifies the sequence of items in a report.

- Report Display - Specifies how the column should be displayed in a report.

- Tabular Form Display - Specifies how an item should display in a tabular form.

- Form Sequence - Specifies the sequence of items in a form.

- Form Display - Specifies how items in a form display.

5. To edit the user interface defaults, click Edit.
The Table Defaults page appears.

6. If no user interface defaults exist, click Create Defaults.

Editing Column Attributes

You define user interface defaults for a specific column by editing column attributes.

To edit column attributes:

1. Navigate to the Table Defaults page:

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

b. Select an application.

c. On the Application, click Shared Components.

d. Under User Interface, select User Interface Defaults.
The User Interface Defaults page appears.

e. Select a specific table or view by selecting the name.
The Table Defaults page appears.

The following information displays at the top of the Table Defaults page:

- Table/View Name identifies the name of the selected table or view.

- Report Region Title and Form Region Title become the default title for all report or form regions. These names are modified versions of Table/View Name in which the first letter is capitalized and any underscores are replaced with spaces.

Column-level User Interface Defaults appear next. By default, a short report displays.

2. To view a complete report, click Detailed Report.

3. To edit select attributes for all displayed columns:

a. Click Grid Edit.

b. Edit the appropriate attributes and click Apply Changes.

4. To edit a specific column, select the column name.
The column defaults appear. Column defaults are divided into two pages:

- Column Definition

- List of Values

The topics that follow describe how to edit specific attributes on these pages.

About the Column Definition

Column Definition is the default page that displays when you edit column attributes. The top of the page displays the selected schema, table or view name, and column name. Click View Database Column Definition to view details about a specific column.

Label Default

This attribute is used in report and forms. Use Label to specify default label text for items in a form and the heading for columns in reports.

Report Defaults

Available attributes include:

- Display - Indicates if the column displays in a report. The default is Yes.

- Display Sequence - Specifies the display sequence of items in a report. The default value is based on the column ID, which is based on the order of the columns in the table.

- Display As - Specifies how the column should be displayed in a report.

- Mask - Indicates if a mask should be applied against the data. This attribute is not applicable for character- based items.

- Alignment - Specifies report alignment (left, center, or right). If the column is a number, the default is Right. Otherwise, the default is Left.

- Searchable - Indicates whether or not the column should be searchable in reports. If the column is VARCHAR2 or CHAR, the default is Yes. If not, the default is No.

- Group By - Indicates whether or not the column should be used for Group By and then the sequence of the grouping. The default is Yes.

- Aggregate By - Indicates whether or not the column should be used for aggregation in reports and charts.

Tabular Form Default

Use Display As to specify how an item should display in a tabular form.

Form Defaults

Available attributes include:

- Display - Indicates if the column displays in a form. The default is Yes.

- Display Sequence - Specifies the sequence of items in a form. The default is based on the column ID, which is based on the order of the columns in the table.

- Display As - Indicates how items in a form display. The default selection is Text Field.

- Mask - Indicates if a mask should be applied against the data in a form. Not used for character-based items.

- Default Value - Specifies the default value associated with this column.

- Width - Specifies the display width.

- maxWidth - Specifies the maximum string length a user is allowed to enter in this item.

- Height - Specifies the display height of an item.

- Required - Used to generate a validation in which the resulting item must not be null. If resulting item is not null, select Yes.

- Help Text - Becomes Item help. By default, this text is pulled from the column hint (if applicable).

About List of Values

You access the List of Values page by clicking the List of Values tab. The top of the page displays the selected schema, table or view name, and column name. Click View Database Column Definition to view details about a specific column.

Use the List of Values Type list to specify if the selected column will include a static or dynamic list of values. Once you select the type, you are prompted to enter either display value and return value pairs, or a list of values query.

About the Database Column Definition Report

You can view details about a specific column by accessing the Column Definition report. The Column Definition report displays the schema, table name, column name, data type, data length, and nullable as well as any check constraints, primary and unique keys, and foreign keys that reference the column. A link to this report appears on both the Column Definition and List of Values pages.

To view the Column Definition report:

1. Navigate to the Table Defaults page:

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

b. Select an application.

c. On the Application, click Shared Components.

d. Under User Interface, select User Interface Defaults.
The User Interface Defaults page appears.

e. Select a specific table or view by selecting the name.

The Table Defaults page appears.

2. Select the column name.

3. Under Schema and Table, click the View Database Column Definition link.

Comparing User Interface Defaults Across Applications

Use the Compare Defaults report to monitor consistency in user interface design across all pages in a single application or multiple applications. Running the Compare Defaults report compares currently defined user interface defaults (or column attributes) against the item attributes set for forms, reports, and tabular forms.

See Also:
"Editing Column Attributes"

To run the Compare Defaults report:

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

2. Select an application.

3. On the Application home page, click Shared Components.
The Shared Components page appears.

4. Under User Interface, select User Interface Defaults.
The User Interface Defaults page appears.

5. On the Tasks list, click Comparison Report.
The current schema displays to the right of the breadcrumb menu.

6. Make sections from the following lists and click Go:

a. Table/View - Restricts the comparison to the selected table or view.

b. Column - Select a column in which to search for form, reports, and tabular forms.

7. Optionally, make sections from the following lists and click Go.

- Display - Select an attribute category.

- Application - Select an application.

A report appears containing the following sections:

- Form Pages Referencing the Selected Column

- Report Regions Referencing the Selected Column

- Tabular Form Regions Referencing the Selected Column

About Exporting and Importing User Interface Defaults

You export user interface defaults in the same way you export any related application file. Exporting user interface defaults from one development instance to another involves the following steps:

1. Export the user interface defaults using the Export User Interface Defaults utility. See "Exporting User Interface Defaults".

2. Import the exported file into the target Oracle Application Express instance. See "Importing User Interface Defaults".

3. Install the exported file from Export Repository. See "Installing Export Files".

When you export user interface defaults, all user interface defaults for the selected schema are exported to a single script. The file contains an API call to create table hints by making calls to the application PL/SQL API. You can use this file to import user interface defaults to another database and Oracle Application Express instance.

10 Debugging an Application

This section describes approaches to debugging an application including viewing Debug Mode, enabling SQL tracing, and viewing page reports. It also describes how to manually remove a control or a component to isolate a problem.

This section contains the following topics:

- About Tuning Performance

- Reviewing Session State

- Accessing Debug Mode

- Enabling SQL Tracing and Using TKPROF

- Monitoring Application and Page Resource Use

- Viewing Reports

- Debugging Problematic SQL Queries

- Removing Controls and Components to Isolate a Problem

See Also:
"Application Builder Concepts" and "Using Application Builder"

About Tuning Performance

For applications having a large number of concurrent users, maintaining optimal performance is critical. To optimize your application's performance, remember to utilize the following features:

- Use bind variables within your application whenever possible. You can reference session state values using bind variable syntax in SQL queries and application logic such as PL/SQL executed from processes and validations. Accessing session state using bind variables is the most efficient way to reference session state.

- Include a #TIMING# substitution string in the region footer so that you can view the timing of each region.

See Also:

- "About Bind Variable Syntax"

- "Understanding Substitution Strings"

Reviewing Session State

Many applications are based on data contained within application controls. For example, buttons can display conditionally based on a value stored in session state. You can view current session state for your application by clicking the Session link on the Developer Toolbar.

See Also:
"About the Developer Toolbar" , "Viewing Session State", "Managing Session State Values", and "Managing Session State and User Preferences"

Accessing Debug Mode

Viewing a page in Debug Mode enables you to track what the Application Express engine is doing as it renders a page. You access Debug mode by clicking the Debug link in the Developer Toolbar.

See Also:
"About the Developer Toolbar"

Debug Mode displays time codes that correspond to specific Application Express engine actions. This can be useful if you want to determine when the engine is setting session state. The Debug view also shows additional details about item names as well as computation and processing points. To exit Debug mode, click No Debug on the Developer Toolbar.

You can also use f?p syntax to run an application in Debug mode. Simply call the page and set the Debug argument to YES. For example:

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

See Also:
"Using f?p Syntax to Link Pages"

Enabling SQL Tracing and Using TKPROF

Tracing your session can be a very effective way to debug an application. From a database perspective, each page request is a single database session. If you enable SQL tracing, then Oracle Application Express creates a temporary file you can then analyze using the TKPROF utility.

You enable SQL tracing in Oracle Application Express by using f?p syntax to set the argument p_trace=YES. For example, to trace the display of page 1 in application 100, you would use the syntax:

http:/.../f?p=100:1&p_trace=YES

To use the TKPROF utility:

1. Log in to SQL*Plus as a privileged user.

2. Execute the following statement:

show parameter USER_DUMP_DEST

3. Navigate to the directory in which the trace file is created.

4. Run the TKPROF utility from the operating system prompt using the following syntax:

tkprof filename1 filename2 [waits=yes|no] [sort=option] [print=n]
[aggregate=yes|no] [insert=filename3] [sys=yes|no] [table=schema.table]
[explain=user/password] [record=filename4] [width=n]

The input and output files are the only required arguments.

5. To view online Help, invoke TKPROF without arguments.

See Also:
"Using Application Tracing Tools" in Oracle Database Performance Tuning Guide for information about using the TKPROF program

Monitoring Application and Page Resource Use

Oracle Application Express facilitates the monitoring of resources used by applications and pages by calling the package DBMS_APPLICATION_INFO. Whenever the Application Express engine renders or processes a page, the module is set to APEX and includes the application ID and page number. Once set, you can query the V$SESSION and V$SQLAREA views to monitor transactions.

Viewing Reports

When isolating an issue within a page, it is important to clearly understand the functions it is performing. To accomplish this goal, Application Builder includes a number of page and application reports.

Viewing Page Reports

To view page reports:

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

2. Click one of the following buttons at the top of the Page Definition:

- Events links to a report that details currently defined page controls and processes. See "About Page Events".

- Objects displays a list of database objects referenced by the current page. See "About Database Object Dependencies".

- History displays a history of recently changed pages. See "About History".

See Also:
"Using the View List on the Page Definition"

Viewing Application Reports

To view application reports:

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

2. Select an application.

3. On the Tasks list, click Application Reports.

4. Select the type of reports to view:

- Shared Components reports offer information on common elements that can display on every page within an application. Reports are grouped by category including Logic, Navigation, Security, User Interface, Globalization, and Files. Report examples include Application Items, Computations, Breadcrumb Entries, Authentication Schemes, and Shortcuts.

- Page Components reports offer detailed information on controls and logic that execute when the page is rendered (for example, branches, buttons, computations, items, and regions).

- Activity Reports offer details about developer activity within the current application. Available reports include Changes by Developer, Changes by Developer by Day, Chart of Changes by Developer, Page Performance, and Recent Changes.

- Cross Application Reports offer information that apply to multiple applications. Available reports include Application Attributes, Application Comments, Build Options, Build Status and Application Status, Page Component Counts, Security Profiles, Authentication Schemes, and Template Defaults by Application.

See Also:
"About the Database Object Dependencies Report" and "About the Search Region Source Report"

Debugging Problematic SQL Queries

If your query does not seem to be running correctly, try running it in SQL*Plus, SQL Developer, or in SQL Commands. Any of these approaches will test your query outside the context of your application, making it easier to determine what the problem is.

Removing Controls and Components to Isolate a Problem

If you have problems running a page, try removing controls and components one at a time. Using this approach, you can quickly determine which control or component may be the source of your problem. You can disable a control or component by selecting the Condition attribute Never.

To remove a control or component using conditional attributes:

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

2. Select the name of the control or component you want to disable.
The appropriate attributes page appears.

3. Scroll down to Condition Type and select Never from the Condition Type list.

4. Click Apply Changes and return to the Page Definition.

5. Try running the page again.

6. Continue to remove controls or components until the page runs correctly.

See Also:
"About the Page Definition", "Editing Page Attributes", "Understanding Conditional Rendering and Processing", and "Running a Page or Application"

11 Managing Application Security

This section describes how to provide security for Oracle Application Express applications. You can provide security for an Oracle Application Express application by utilizing cross-site scripting protection, session state protection, authentication, and authorization.

This section contains the following topics:

- About Cross-Site Scripting Protection

- Enabling Network Services in Oracle Database 11g

- Understanding Session State Protection

- Understanding the Security Risks of File Upload Tables

- Establishing User Identity Through Authentication

- Providing Security Through Authorization

See Also:
"Application Builder Concepts" and "Using Application Builder"

About Cross-Site Scripting Protection

Cross site-scripting (also referred to as XSS) is a security breach that takes advantage of dynamically generated Web pages. In a XSS attack, a Web application is sent a script that activates when it is read by a user's browser. Once activated, these scripts can steal data, even session credentials, and return the information to the attacker.

If malicious code were introduced into an Oracle Application Express application, it could be rendered into HTML regions and other places within the application during normal page rendering. To prevent the introduction of malicious code into session state, the Application Express engine escapes characters in certain cases.

Topics in this section include:

- Protecting HTML Regions and Other Static Areas

- Protecting Dynamic Output

- Protecting Report Regions

- Protecting Form Items

Protecting HTML Regions and Other Static Areas

In HTML regions and other static display areas, you can reference session state using the &ITEM. notation. Examples of static display areas include HTML regions, page headers and footers, region headers and footers, region titles, button labels, help text, form item labels and post-element text, templates, radiogroup (before and after field text), event success messages, event error messages, navigation bar attributes, application static substitution string values, chart labels and legends, breadcrumbs and list framing text, and calendar text, labels, or legends.

About Safe Item Display Types

When session state is referenced in this way, the value emitted to the page will have special characters (<, >, &, ") escaped if the referenced item is one of the following safe item display types:

- Display as Text (does not save state)

- Display as Text (escape special characters, does not save state)

- Display as Text (based on LOV, does not save state)

- Display as Text (based on PL/SQL, does not save state)

- Text Field (Disabled, does not save state)

- Stop and Start HTML Table (Displays label only)

If the referenced item has a display type other than one of the above types, the value emitted to the page will not have special characters escaped. Although application-level items are also considered to have a safe display type, they do not actually have display properties like form items do.

See Also:
"Understanding Page-Level Items"

About the Rules Used to Determine Whether to Escape Values

The Application Express engine uses predefined smart escaping rules to determine if and when to escape values fetched from session state.

The reason for these rules is that items that use the display types listed previously are often for text containing HTML that is intended to be emitted to the browser without being filtered (that is, escaped). The only way this can be made safe is by the enforcement of the rule that these types of items are always escaped on input to the application. For example, if a user passes some text into a safe item using an Oracle Application Express f?p URL syntax, the Application Express engine escapes special characters when saving the value into session state. This has two intended results:

1. If the value contained no special characters, the value passed in is saved into session state exactly as it was provided.

2. If the value contained special characters, those characters are escaped when the value is saved into session state.

In either situation, the item can now safely be referenced using an &ITEM. notation in any HTML region or other static area mentioned previously.

Using Safe Item Types to Hold and Emit HTML Markup

You can use the safe item types listed previously to hold and emit HTML markup to the browser. For example, suppose you have a requirement to render some text in bold face by referencing a safe page item named P1_XXX (using &P1_XXX.) The item P1_XXX is presumed to contain the following HTML:

<b>ABABABAB</b>

You can achieve this by using application controls (computations, processes, item source expressions, item default values, and so on) to store values into these safe items. When values are introduced in this way, you ensure the safety of the content. When you use these methods, the Application Express engine does not escape any special characters when saving the values into session state.

Finally, the safety of safe items is ensured by a rule that prevents those items from being posted on a page and submitted to the Application Express engine as part of a page submission.

Protecting Dynamic Output

Items fetched from session state and rendered using htp.p or other methods should be explicitly escaped by the code where it is appropriate to do so. For example, suppose a PL/SQL dynamic content region on a page uses the following:

htp.p(v('SOME_ITEM'));

If the value of the item fetched from session state could contain unintended tags or scripts, you might want to use the following in the region:

htp.p(htf.escape_sc(v('SOME_ITEM')));

However, if you are confident that the fetched value is safe for rendering, you do not need to escape the value. As a developer, you need to determine when it is appropriate to not escape output.

As a best practice, follow this rule:

- Never emit an item fetched from session state without escaping it unless the item is one of the safe types described in "About Safe Item Display Types".

The reason for this is that as a developer, there is no way you can prevent a hacker from posting a malicious value into a non-safe item. Even if your application does not present these items visibly to ordinary users, be aware that a hacker can mount a XSS attack using your application if you do not follow this rule.

Protecting Report Regions

The Application Express engine escapes data rendered in the body of a report. References to session state in report headings and messages are fetched from session state using the smart escaping rules so that the values of safe item types are not escaped and the values of other item types are escaped.

Protecting Form Items

When form items, including hidden items, obtain their values during the generation of the form page to be sent to the browser, the resulting text is escaped before rendering. Some of the safe item types are exceptions to this rule in order to support the intended behavior of each display type.

Enabling Network Services in Oracle Database 11g

By default, the ability to interact with network services is disabled in Oracle Database 11g release 1 (11.1). Therefore, if you are running Oracle Application Express with Oracle Database 11g release 1 (11.1), you need to use the new DBMS_NETWORK_ACL_ADMIN package to grant connect privileges to any host for the FLOWS_030000 database user. Failing to grant these privileges results in issues with:

- Sending outbound mail in Oracle Application Express.

Users can call methods from the APEX_MAIL package, but issues arise when sending outbound email.

- Using Web services in Oracle Application Express.

- PDF/report printing.

- Searching for content in online Help (that is, using the Find link).

Granting Connect Privileges

The following example demonstrates how to grant connect privileges to any host for the FLOWS_030000 database user.

DECLARE
ACL_PATH  VARCHAR2(4000);
ACL_ID    RAW(16);
BEGIN
-- Look for the ACL currently assigned to '*' and give FLOWS_030000
-- the "connect" privilege if FLOWS_030000 does not have the privilege yet.

SELECT ACL INTO ACL_PATH FROM DBA_NETWORK_ACLS
WHERE HOST = '*' AND LOWER_PORT IS NULL AND UPPER_PORT IS NULL;

-- Before checking the privilege, make sure that the ACL is valid
-- (for example, does not contain stale references to dropped users).
-- If it does, the following exception will be raised:
--
-- ORA-44416: Invalid ACL: Unresolved principal 'FLOWS_030000'
-- ORA-06512: at "XDB.DBMS_XDBZ", line ...
--
SELECT SYS_OP_R2O(extractValue(P.RES, '/Resource/XMLRef')) INTO ACL_ID
FROM XDB.XDB$ACL A, PATH_VIEW P
WHERE extractValue(P.RES, '/Resource/XMLRef') = REF(A) AND
EQUALS_PATH(P.RES, ACL_PATH) = 1;

DBMS_XDBZ.ValidateACL(ACL_ID);
IF DBMS_NETWORK_ACL_ADMIN.CHECK_PRIVILEGE(ACL_PATH, 'FLOWS_030000',
'connect') IS NULL THEN
DBMS_NETWORK_ACL_ADMIN.ADD_PRIVILEGE(ACL_PATH,
'FLOWS_030000', TRUE, 'connect');
END IF;

EXCEPTION
-- When no ACL has been assigned to '*'.
WHEN NO_DATA_FOUND THEN
DBMS_NETWORK_ACL_ADMIN.CREATE_ACL('power_users.xml',
'ACL that lets power users to connect to everywhere',
'FLOWS_030000', TRUE, 'connect');
DBMS_NETWORK_ACL_ADMIN.ASSIGN_ACL('power_users.xml','*');
END;
/
COMMIT;

Troubleshooting an Invalid ACL Error

If you receive an ORA-44416: Invalid ACL error after running the previous script, use the following query to identify the invalid ACL:

REM Show the dangling references to dropped users in the ACL that is assigned
REM to '*'.

SELECT ACL, PRINCIPAL
FROM DBA_NETWORK_ACLS NACL, XDS_ACE ACE
WHERE HOST = '*' AND LOWER_PORT IS NULL AND UPPER_PORT IS NULL AND
NACL.ACLID = ACE.ACLID AND
NOT EXISTS (SELECT NULL FROM ALL_USERS WHERE USERNAME = PRINCIPAL);

Next, run the following code to fix the ACL:

DECLARE
ACL_ID   RAW(16);
CNT      NUMBER;
BEGIN
-- Look for the object ID of the ACL currently assigned to '*'
SELECT ACLID INTO ACL_ID FROM DBA_NETWORK_ACLS
WHERE HOST = '*' AND LOWER_PORT IS NULL AND UPPER_PORT IS NULL;

-- If just some users referenced in the ACL are invalid, remove just those
-- users in the ACL. Otherwise, drop the ACL completely.
SELECT COUNT(PRINCIPAL) INTO CNT FROM XDS_ACE
WHERE ACLID = ACL_ID AND
EXISTS (SELECT NULL FROM ALL_USERS WHERE USERNAME = PRINCIPAL);

IF (CNT > 0) THEN

FOR R IN (SELECT PRINCIPAL FROM XDS_ACE
WHERE ACLID = ACL_ID AND
NOT EXISTS (SELECT NULL FROM ALL_USERS
WHERE USERNAME = PRINCIPAL)) LOOP
UPDATE XDB.XDB$ACL
SET OBJECT_VALUE =
DELETEXML(OBJECT_VALUE,
'/ACL/ACE[PRINCIPAL="'||R.PRINCIPAL||'"]')
WHERE OBJECT_ID = ACL_ID;
END LOOP;

ELSE
DELETE FROM XDB.XDB$ACL WHERE OBJECT_ID = ACL_ID;
END IF;

END;
/

REM commit the changes.

COMMIT;

Once the ACL has been fixed, you need to run the first script in this section to apply the ACL to the FLOWS_030000 user. See "Granting Connect Privileges".

Understanding Session State Protection

Session State Protection is a built-in functionality that prevents hackers from tampering with the URLs within your application. URL tampering can adversely affect program logic, session state contents, and information privacy.

Enabling Session State Protection is a two-step process. First, you enable the feature. Second, you set page and item security attributes.

Topics in this section include:

- How Session State Protection Works

- Enabling Session State Protection

- Configuring Session State Protection

How Session State Protection Works

When enabled, Session State Protection uses the Page Access Protection attributes and the Session State Protection item attributes in conjunction with checksums positioned in f?p= URLs to prevent URL tampering and unauthorized access to and alteration of session state. When Session State Protection is disabled, the page and item attributes related to session state protection are ignored and checksums are not included checksums in generated f?p= URLs.

Enabling Session State Protection

You can enable session state protection from either the Edit Security Attributes page or the Session State Protection page.

Enabling Session State Protection is a two-step process. First, you enable the feature. Second, you set page and item security attributes. You can perform these steps using a wizard, or you can set security attributes for pages and items manually on the Session State Protection page.

Topics in this section include:

- Enabling Session State Protection from Edit Security Attributes

- Enabling Session State Protection from Session State Protection

Enabling Session State Protection from Edit Security Attributes

To enable Session State Protection from the Edit Security Attributes page:

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

2. Select an application.

3. Click the Shared Components icon.

4. Under Security, click Edit Security Attributes.

5. Scroll down to Session State Protection and select Enabled from the Session State Protection list.

6. To configure session Session State Protection, click Manage Session State Protection.
The Session State Projection page appears.

7. Navigate to the Edit Security Attributes page to set page and item security attributes.

Tip:
To disable Session State Protection, perform the same steps again, but select Disabled instead of Enabled. Disabling Session State Protection will not change existing security attribute settings, but those attributes will be ignored at run time.

About the Expire Bookmarks Button

Enabling Session State Protection affects whether or not bookmarked links to the current application will work. Consider the following rules:

1. Bookmarked links created after Session State Protection is enabled will work if the bookmarked link contains a checksum.

2. Bookmarked links created before Session State Protection is enabled will not work if the bookmarked link contains a checksum.

3. Bookmarks that do not contain checksums or contain unnecessary checksums will not be affected by Session State Protection.

During page rendering, the Application Express engine uses a hidden application attribute (a checksum salt) during computation and to verify checksums included in f?p URLs. When you enable Session State Protection, the Application Express engine includes checksums. You can reset the checksum salt attribute by clicking Expire Bookmarks on the Edit Security Attributes page. Note that if you click Expire Bookmarks, bookmarked URLs used to access your application that contain previously generated checksums will fail.

Enabling Session State Protection from Session State Protection

To enable Session State Protection:

1. Navigate to the Shared Components page:

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

b. Select an application.

c. Click Shared Components.

d. Under Security, select Session State Protection.

The Session State Protection page appears. Note the current Session State Protection status (Enabled or Disabled) displays at the top of the page.

2. Click the Set Protection button.
The Session State Protection wizard appears.

3. Under Select Action, select Enable and click Next.
Next, determine whether to set security attributes for pages and items.

4. Select Enable and click Next.

5. Click Enable Session State Protection.

Tip:
To disable Session State Protection, perform the same steps, but select Disable instead of Enable. Disabling Session State Protection will not change existing security attribute settings, but those attributes will be ignored at run time.

Configuring Session State Protection

Once you have enabled Session State Protection, the next step is to configure security attributes. You can configure security attributes in two ways:

- Use a wizard and select a value for specific attribute categories. Those selections will then be applied to all pages and items within the application.

- Configure values for individual pages, items, or application items.

Topics in this section include:

- Reviewing Existing Session State Protection Settings

- Configuring Session State Protection Using a Wizard

- Configuring Session State Protection for Pages

- Configuring Session State Protection for Items

- Configuring Session State Protection for Application Items

Tip:
Before you can configure security attributes, you must first enable Session State Protection. See "Enabling Session State Protection".

Reviewing Existing Session State Protection Settings

You can review a summary of Session State Protection settings for pages, items, and application items on the first page of the Session State Protection wizard.

To view summaries of existing Session State Protection settings:

1. Navigate to the Session State Protection page:

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

b. Select an application.

c. Click Shared Components.

d. Under Security, select Session State Protection.
The Session State Protection page appears.

2. Click Set Protection.

3. Expand the following reports at the bottom of the page:

- Page Level Session State Protection Summary

- Page Item Session State Protection Summary

- Application Item Session State Protection

Configuring Session State Protection Using a Wizard

When you configure Session State Protection using a wizard, you set a value for specific attribute categories. Those selections are then applied to all pages and items within the application.

To configure Session State Protection using a wizard:

1. Navigate to the Session State Protection page:

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

b. Select an application.

c. Click Shared Components.

d. Under Security, select Session State Protection.
The Session State Protection page appears.

2. Click Set Protection.
The Session State Protection wizard appears.

3. Under Select Action, select Configure and click Next.

4. For Page Access Protection, select one of the following:

- Unrestricted - The page may be requested using a URL with or without session state arguments (Request, Clear Cache, Name/Values).

- Arguments Must Have Checksum - If Request, Clear Cache, or Name/Value arguments appear in the URL, a checksum must also be provided. The checksum type must be compatible with the most stringent Session State Protection attribute of all the items passed as arguments.

- No Arguments Allowed - A URL may be used to request the page but no Request, Clear Cache, or Name/Value arguments are allowed.

- No URL Access - The page may not be accessed using a URL; however, the page may be the target of a Branch to Page branch type, which does not do a URL redirect.

5. For Application Item Protection, select one of the following:

- Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

- Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the schema is provided. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

- Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the workspace, application, and user is provided. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

- Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the current session is also provided. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

- Restricted - May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this option when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is applicable only to items that cannot be used as data entry items and is always observed even if Session State Protection is disabled.

Use this attribute for application items or for page items with any of these Display As types:

- Display as Text (escape special characters, does not save state)

- Display as Text (does not save state)

- Display as Text (based on LOV, does not save state)

- Display as Text (based on PLSQL, does not save state)

- Text Field (Disabled, does not save state)

- Stop and Start HTML Table (Displays label only)

6. For Page Data Entry Item Protection, select one of the following:

- Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

- Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the schema is provided. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

- Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the workspace, application, and user is provided. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

- Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the current session is provided. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

7. For Page Display-Only Item Protection, select one of the following:

- Unrestricted - The item may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

- Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the schema is provided. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

- Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the current session is provided. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

- Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the workspace, application, and user is provided. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

- Restricted: May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is always observed, even if Session State Protection is disabled.

This attribute may be used with any of these Display As types:

- Display as Text (escape special characters, does not save state)

- Display as Text (does not save state)

- Display as Text (based on LOV, does not save state)

- Display as Text (based on PLSQL, does not save state)

- Text Field (Disabled, does not save state)

- Stop and Start HTML Table (Displays label only)

8. Click Next.

9. Click Finish.

Configuring Session State Protection for Pages

To configure Session State Protection for Pages:

1. Navigate to the Session State Protection page:

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

b. Select an application.

c. Click Shared Components.

d. Under Security, select Session State Protection.
The Session State Protection page appears.

2. Click the Page icon.

3. To filter the view, use the Page, Display, and Page Access Protection lists at the top of the page.

4. Select a page number.
The Set Page and Item Protection page appears. The following information displays at the top of the page:

- Application ID and name

- Session State Protection status (Enabled or Disabled)

- Page Number

- Page name

5. For Page Access Protection, select one of the following:

- Unrestricted - The page may be requested using a URL with or without session state arguments (Request, Clear Cache, Name/Values).

- Arguments Must Have Checksum - If Request, Clear Cache, or Name/Value arguments appear in the URL, a checksum must also be provided. The checksum type must be compatible with the most stringent Session State Protection attribute of all the items passed as arguments.

- No Arguments Allowed - A URL may be used to request the page but no Request, Clear Cache, or Name/Value arguments are allowed.

- No URL Access - The page may not be accessed using a URL; however, the page may be the target of a Branch to Page branch type, which does not do a URL redirect.

6. For Item Types, select Data Entry Items or Display-only Items.
Data Entry items are items that can be altered using forms and include hidden items. Display-Only items are rendered only and are not submitted with the form.

7. If you select Data Entry Items, select a session state protection level for each item:

- Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

- Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the schema is provided. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

- Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the workspace, application, and user is provided. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

- Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the current session is provided. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

8. If you select Display-only Item, select a session state protection level for each item:

- Unrestricted - The item may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

- Restricted: May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is always observed, even if Session State Protection is disabled. This attribute may be used with any of these Display As types:

- Display as Text (escape special characters, does not save state)

- Display as Text (does not save state)

- Display as Text (based on LOV, does not save state)

- Display as Text (based on PLSQL, does not save state)

- Text Field (Disabled, does not save state)

- Stop and Start HTML Table (Displays label only)

- Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the schema is provided. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

- Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the workspace, application, and user is provided. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

- Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the current session is provided. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

9. Click Apply Changes.

Configuring Session State Protection for Items

To configure Session State Protection for items:

1. Navigate to the Session State Protection page:

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

b. Select an application.

c. Click Shared Components.

d. Under Security, select Session State Protection.
The Session State Protection page appears.

2. Click the Item icon.

3. To filter the view, select from the Page, Display, and Item Session State Protection lists at the top of the page and click Go.

4. Select a page number.
The Edit Session State Protection for Page and Items page appears. The following information displays at the top of the page:

- Application ID and name

- Session State Protection status (Enabled or Disabled)

- page Number

- Page name

5. For Page Access Protection, select a session state protection level for each item:

- Unrestricted - The page may be requested using a URL with or without session state arguments (Request, Clear Cache, Name/Values).

- Arguments Must Have Checksum - If Request, Clear Cache, or Name/Value arguments appear in the URL, a checksum must also be provided. The checksum type must be compatible with the most stringent Session State Protection attribute of all the items passed as arguments.

- No Arguments Allowed - A URL may be used to request the page but no Request, Clear Cache, or Name/Value arguments are allowed.

- No URL Access - The page may not be accessed using a URL, however the page may be the target of a Branch to Page branch type, which does not do a URL redirect.

6. For Item Types, select Data Entry Items or Display-only Items.
Data Entry items are items that can be altered using forms and include hidden items. Display-Only items are rendered only and are not submitted with the form.

7. If you select Data Entry Items, select a session state protection level for each item:

- Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

- Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the schema is provided. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

- Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the workspace, application, and user is provided. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

- Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the current session is provided. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

8. If you select Display-only Item, select a session state protection level for each item:

- Unrestricted - The item may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

- Restricted: May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is always observed, even if Session State Protection is disabled. This attribute may be used with any of these Display As types:

- Display as Text (escape special characters, does not save state)

- Display as Text (does not save state)

- Display as Text (based on LOV, does not save state)

- Display as Text (based on PLSQL, does not save state)

- Text Field (Disabled, does not save state)

- Stop and Start HTML Table (Displays label only)

- Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the schema is provided. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

- Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the workspace, application, and user is provided. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

- Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the current session is provided. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

9. Click Apply Changes.

Configuring Session State Protection for Application Items

To configure Session State Protection for application items:

1. Navigate to the Session State Protection page:

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

b. Select an application.

c. Click Shared Components.

d. Under Security, select Session State Protection.
The Session State Protection page appears.

2. Click the Application Item icon.

3. Select an application item.

4. Under Security, select one of the following from the Session State Protection list:

- Unrestricted - The item's session state may be set by passing the item name/value in a URL or in a form. No checksum is required in the URL.

- Restricted - May not be set from browser - The item may not be altered using the URL or POSTDATA. Use this option when you want to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute is only applicable only to items that cannot be used as data entry items and is always observed even if Session State Protection is disabled. This attribute may be used for application items or for page items with any of these Display As types:

- Display as Text (escape special characters, does not save state)

- Display as Text (does not save state)

- Display as Text (based on LOV, does not save state)

- Display as Text (based on PLSQL, does not save state)

- Text Field (Disabled, does not save state)

- Stop and Start HTML Table (Displays label only)

- Checksum Required: Application Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the schema is provided. A user-level checksum or a session-level checksum will also suffice (see next bullets). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by any user running the same application in the current workspace but in a different session.

- Checksum Required: User Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the workspace, application, and user is provided. A session-level checksum will also suffice (see next bullet). Use this option when you want to allow the item to be set only by URLs having checksums that were generated by the same named user, running the same application in the current workspace but in a different session.

- Checksum Required: Session Level - The item's session state may be set by passing the item name/value in a URL if a checksum specific to the current session is provided. Use this option when you want to allow this item to be set only by URLs having checksums that were generated in the current session.

5. Click Apply Changes.

Understanding the Security Risks of File Upload Tables

Oracle Application Express enables you to easily build an application that enables users to upload files and access uploaded files. These files are uploaded into a common file storage table. Although the database view APEX_APPLICATION_FILES will only show those files associated with your database account (or workspace), authentication is not required to access any of the files stored in the underlying table, including those outside of your database account (or workspace) and owned by other users. Using the various APIs in Oracle Application Express, a user can specify the numeric ID associated with a file in this common file storage table and access it without requiring authentication. Files stored in this table are accessible by anyone.

To implement an Oracle Application Express application that supports file upload but does not expose this security vulnerability, see the Oracle Application Express How To Documents for file upload on OTN at:

http://www.oracle.com/technology/products/database/application_express/howtos/index.html

See Also:
"Differences Between Page Items and Application Items" and "About Item Types" to learn more about creating a File Browse page-level item

Establishing User Identity Through Authentication

Authentication is the process of establishing each user's identify before they can access your application. Authentication may require a user identify a user name and password or could involve the use of digital certificates or a secure key.

When you create an authentication scheme, you have the option of choosing from a number of preconfigured authentication schemes, copying an authentication scheme from an existing application, or creating your own custom authentication scheme.

Topics in this section include:

- Understanding How Authentication Works

- Determining Whether to Include Authentication

- About Preconfigured Authentication Schemes

- Creating an Authentication Scheme

- Using the Authentication Scheme Repository

- Viewing the Current Authentication Scheme for an Application

- Changing the Current Authentication Scheme for an Application

- Viewing Authentication Scheme Utilization

- About Creating an Authentication Scheme from Scratch

Understanding How Authentication Works

You determine how your application interacts with users. If all users have the same rights and privileges, they are referred to as public users. However, if your application needs to track each user individually, you need to specify an authentication method.

Authentication establishes the identity of each user who accesses your application. Many authentication processes require that a user provide some type of credentials such as a user name and password. These credentials are then evaluated and they either pass or fail. If the credentials pass, the user has access to the application. Otherwise, access is denied.

Once a user has been identified, the Application Express engine keeps track of each user by setting the value of the built-in substitution string APP_USER. As a user navigates from page to page, the Application Express engine sets the value of APP_USER to identify the user. The Application Express engine uses APP_USER as one component of a key for tracking each user's session state.

From a programming perspective, you can access APP_USER using the following syntax:

- From PL/SQL:

V('APP_USER')

- As a bind variable from either PL/SQL or SQL:

:APP_USER

You can use APP_USER to perform your own security checks and conditional processing. For example, suppose you created the following table:

CREATE TABLE my_security_table (
user_id   VARCHAR2(30),
privilege VARCHAR2(30));

Once created, you could populate this table with user privilege information and then use it to control the display of pages, tabs, navigation bars, buttons, regions, or any other control or component.

See Also:
"APP_USER" and "Configuring Security Attributes"

Determining Whether to Include Authentication

As you create your application, you need to determine whether to include authentication. You can:

- Choose to not require authentication. Oracle Application Express does not check any user credentials. All pages of your application are accessible to all users.

- Select a built-in authentication scheme. Create an authentication method based on available preconfigured authentication schemes. Depending on which scheme you choose, you may also have to configure the corresponding components of Oracle 10giAS, Oracle Internet Directory, or other external services. See "About Preconfigured Authentication Schemes" and "Changing the Current Authentication Scheme for an Application".

- Create custom authentication scheme. Create a custom authentication method to have complete control over the authentication interface. To implement this approach, you must provide a PL/SQL function the Application Express engine executes before processing each page request. This function's Boolean return value determines whether the Application Express engine processes the page normally or displays a failure page. See "Creating an Authorization Scheme".

About Preconfigured Authentication Schemes

When you select a preconfigured authentication scheme, Oracle Application Express creates an authentication scheme for your application that follows a standard behavior for authentication and session management. The following list describes available preconfigured authentication schemes:

- Open Door Credentials enables anyone to access your application using a built-in login page that captures a user name. This can be useful during application development.

- Oracle Application Express Account Credentials refers to the internal user accounts (also known as "cookie user" accounts) created and managed in the Oracle Application Express user repository. Using this method, your application can easily authenticate against these accounts. See "Application Express Account Credentials".

- Database Account Credentials refers to the use of database schema accounts. When using this method, the user name and password of the database account is used to authenticate the user. See "Database Account Credentials".

- LDAP Credentials Verification requires that you specify configuration parameters about the external Lightweight Directory Access Protocol (LDAP) directory you will be using. See "LDAP Credentials Verification".

- No Authentication (using DAD) gets the user name from the Database Access Descriptor (DAD), either as the value stored in the DAD configuration or, if the account information is not stored in the DAD configuration, as the user name captured using the basic authentication challenge. See "DAD Credentials Verification".

- Oracle Application Server Single Sign-On (Application Express engine as Partner App) delegates authentication to the Oracle AS Single Sign-On (SSO) Server. To use this authentication scheme, your site must have already been registered as a partner application with the SSO server. For more information, contact your administrator. See "About Single Sign-On Server Verification".

- Oracle Application Server Single Sign-On (My application as Partner App) delegates authentication to the SSO server. Requires that you register an application with SSO as a partner application. See "About Single Sign-On Server Verification".

Application Express Account Credentials

Application Express Account Credentials authentication uses internal user accounts (also known as "cookie user" accounts). These user accounts are created and managed in the Oracle Application Express user repository.

See Also:
"Managing Application Express Users"

Application Express Account Credentials is a good solution when:

- You want control of the user account repository

- User name and password-based approach to security is sufficient

- You do not need to integrate into a single sign-on framework

This is an especially good approach when you need to get a group of users up and running on a new application quickly.

Database Account Credentials

Database Account Credentials requires that a database user (schema) exist in the local database for the user to be authenticated. When using this method, the user name and password of the database account is used to authenticate the user.

Database Account Credentials is a good choice if having one database account for each named user of your application is feasible and account maintenance using database tools meets your needs.

LDAP Credentials Verification

Any authentication scheme that uses a login page may be configured to use Lightweight Directory Access Protocol (LDAP) to verify the user name and password submitted on the login page. Application Builder includes wizards and edit pages that explain how to configure this option. These wizards assume that an LDAP directory accessible to your application for this purpose already exists and that it can respond to a SIMPLE_BIND_S call for credentials verification. When you create an LDAP Credentials authentication scheme, the wizard requests and saves the LDAP host name, LDAP port, and the DN string. An optional preprocessing function can be specified to adjust formatting of the user name passed to the API.

DAD Credentials Verification

Database Access Descriptor (DAD) database authentication uses the Oracle database native authentication and user mechanisms to authenticate users using a basic authentication scheme. To use DAD credentials verification:

- Each application user must have a user account in the Oracle database.

- You must configure a PL/SQL DAD for basic authentication (without account information).

This results in one user name/password challenge for browser session for your application users. The user identity token is then made available in the APP_USER item.

DAD database authentication is useful when you need to implement an authentication method that requires minimal setup for a manageable number of users. Ideally these users would already have self-managed accounts in the database and your use of this authentication method would be short lived (for example, during the demonstration or prototyping stages of development).

The main drawback of this approach is burdensome account maintenance, especially if users do not administer their own passwords, or if their database accounts exist only to facilitate authentication to your application.

About Single Sign-On Server Verification

Oracle Application Server Single Sign-On verification delegates authentication to the Oracle AS Single Sign-On (SSO) Server. To use this authentication scheme, your site must have already been registered as a partner application with the SSO server.

Oracle Application Express applications can operate as partner applications with Oracle Application Server's Single Sign-On (SSO) infrastructure. To accomplish this, you must register your application (or register the Application Express engine) as the partner application. To do so, follow the Oracle Application Server instructions for registering partner applications and install the Oracle 9iAS SSO Software Developer Kit (SDK).

If you choose this approach, your application will not use an integrated login page. Instead, when a user accesses your application in a new browser session, the Application Express engine redirects to the Single Sign-On login page. After the user is authentication by SSO, the SSO components redirect back to your application, passing the user identity and other information to the Application Express engine. The user can then continue to use the application until they log off, terminate their browser session, or until some other session-terminating event occurs.

Creating an Authentication Scheme

To create an authentication scheme:

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

2. Select an application.

3. On the Application home page, click Shared Components.
The Shared Components page appears.

4. Under Security, select Authentication Schemes.
The Authentication Schemes page appears.

5. To create a new authentication scheme, click Create.

6. Specify how the scheme should be created by selecting one of the following:

- Based on preconfigured scheme

- As a copy of an existing scheme

- From scratch

7. Follow the on-screen instructions.

See Also:
"About Preconfigured Authentication Schemes" and "About Creating an Authentication Scheme from Scratch"

Using the Authentication Scheme Repository

Once created, available authentication schemes display in the Authentication Schemes Repository.

To navigate to the Authentication Schemes Repository:

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

2. Select an application.

3. On the Application home page, click Shared Components.
The Shared Components page appears.

4. Under Security, select Authentication Schemes.
The Authentication Schemes page appears. You can change the appearance of the page by making a selection from the View list. Available options include:

- Icons (the default) displays each authentication scheme as a large icon. To edit an authentication scheme, click the appropriate icon.

- Details displays each application item as a line in a report.

In Details view you can:

- Edit an authentication scheme by selecting the scheme name

- View a list of the steps performed on each page by clicking the Show icon

- Apply an authentication scheme to an application by clicking the make current link

Viewing the Current Authentication Scheme for an Application

To view the current authentication scheme for an application:

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

2. Select an application.

3. Click Shared Components.

4. Under Security, click Edit Security Attributes.

5. Locate the Authentication section. The current authentication scheme displays next to Authentication Scheme.

6. To link to the Authentication Scheme pages, select the scheme name.

Changing the Current Authentication Scheme for an Application

To change the authentication scheme for an application:

1. Navigate to the Authentication Schemes:

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

b. Select an application.

c. On the Application home page, click Shared Components.
The Shared Components page appears.

d. Under Security, select Authentication Schemes.

2. Click the Change Current tab at the top of the page.

3. Select a new authentication scheme and click Next.

4. Click Make Current.

Viewing Authentication Scheme Utilization

The Authentication Schemes report lists authentication scheme utilization for all applications in the current workspace.

To view the Authentication Schemes report:

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

2. Select an application.
The Application home page appears.

3. On the Tasks list, click View Application Reports.

4. Click Cross Application Reports.

5. Select Authentication Schemes.

6. Click the application ID to link to the appropriate Application home page.

About Creating an Authentication Scheme from Scratch

Creating an authentication scheme from scratch gives you complete control over your authentication interface. This is the best approach for applications when any of the following is true:

- Database authentication or other methods are not adequate.

- You want to develop your own login form and associated methods.

- You want to delegate all aspects of user authentication to external services such as Oracle 10gAS Single Sign-On.

- You want to control security aspects of session management.

- You want to record or audit activity at the user or session level.

- You want to enforce session activity or expiry limits.

- You want to program conditional one-way redirection logic before Oracle Application Express page processing.

- You want to integrate your application with non-Oracle Application Express applications using a common session management framework.

- Your application consists of multiple applications that operate seamlessly (for example, more than one application ID).

See Also:
"APEX_CUSTOM_AUTH" for more information

About Session Management Security

When running custom authentication, Oracle Application Express attempts to prevent two improper situations:

- Intentional attempts by a user to access session state belonging to someone else. However, users can still type in an arbitrary application session ID into the URL.

- Inadvertent access to a stale session state (probably belonging to the same user from an earlier time). This would commonly result from using bookmarks to application pages.

Oracle Application Express checks that the user identity token set by the custom authentication function matches the user identity recorded when the application session was first created. If the user has not yet been authenticated and the user identity is not yet known, the session state being accessed does not belong to someone else. These checks determine whether the session ID in the request can be used. If not, the Application Express engine redirects back the same page using an appropriate session ID.

Building a Login Page

When you create a new application in Oracle Application Express, a login page is created. The alias for the page is 'LOGIN'. You can use this page as the "invalid session page" in an authentication scheme. The page is constructed with processes that call the Oracle Application Express login API to perform credentials verification and session registration.

You can also build your own login pages using the pre-built pages as models and tailoring all of the user interface and processing logic to your requirements.

To create a login page for your application:

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

2. Select an application.

3. Click Create Page.

4. Select Login Page.

5. Specify Login page attributes and click Create.

About Deep Linking

Deep linking refers to the ability to link to an Oracle Application Express page out of context (for example, from a hyperlink in an email or workflow notification). When you link to a page out of context and the application requires the user be authenticated, the user will be taken to the login page. After credentials verification, the Application Express engine automatically displays the page that was referenced in the original link. Deep linking is supported for applications that use authentication schemes.

Providing Security Through Authorization

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

Topics in this section include:

- How Authorization Schemes Work

- Creating an Authorization Scheme

- Attaching an Authorization Scheme to an Application, Page, or Components

- Viewing Authorization Reports

How Authorization Schemes Work

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

An authorization scheme either succeeds or fails. If a component or control level authorization scheme succeeds, the user can view the component or control. If it fails, the user cannot view the component or control. If an application or page level authorization scheme fails, then Oracle Application Express displays a previously defined message.

When you define an authorization scheme, you give it a unique name. Once defined, you can attach it to any component or control in your application. To attach an authorization scheme to a component or control in your application, simply navigate to the appropriate attributes page and select an authorization scheme from the Authorization Scheme list.

Creating an Authorization Scheme

Before you can attach an authorization scheme to an application or an application component or control, you must first create it.

To create an authorization scheme:

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

2. Select an application.

3. On the Application home page, click Shared Components.
The Shared Components page appears.

4. Under Security, select Authorization Schemes.

5. Click Create.

6. Specify how to create an authorization scheme by selecting one of the following:

- From Scratch

- As a Copy of an Existing Authorization Scheme

7. Follow the on-screen instructions.

Editing Attributes of an Existing Authorization Scheme

To edit attributes of an existing authorization scheme:

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

2. Select an application.

3. On the Application home page, click Shared Components.
The Shared Components page appears.

4. Under Security, select Authorization Schemes.
The Authorization Schemes page appears. By default, each scheme displays as an icon.

5. To access a detail view of all schemes, select Details from the View list.
The Authorization Schemes page appears. You can change the appearance of the page by making a selection from the View list. Available options include:

- Icons (the default) displays each authentication scheme as a large icon. To edit an authorization scheme, click the appropriate icon.

- Details displays each application item as a line in a report. To edit an authorization scheme, select the scheme name.

About the Evaluation Point Attribute

You can specify when your authorization scheme is validated in the Evaluation Point attribute. You can choose to have your authorization scheme validated once for each session or once for each page view.

Keep in mind, if you specify that an authorization scheme should be evaluated once for each session and the authorization scheme passes, the underlying code, test, or query will not be executed again for the duration of the application session. If your authorization scheme consists of a test whose results might change if evaluated at different times during the session, then you should specify that the evaluation point be once for each page view.

About Resetting Authorization Scheme State

If an authorization scheme is validated once for each session, Oracle Application Express caches the validation results in each user's session cache. You can reset a session's authorization scheme state by calling the APEX_UTIL.RESET_AUTHORIZATIONS API.

Calling this procedure nulls out any previously cached authorization scheme results for the current session. Be aware that this procedure takes no arguments and is part of the publicly executable APEX_UTIL package.

See Also:
"RESET_AUTHORIZATIONS Procedure"

Attaching an Authorization Scheme to an Application, Page, or Components

Once you have created an authorization scheme you can attach it to an entire application, page, control, or component.

Topics in this section include:

- Attaching an Authorization Scheme to an Application

- Attaching an Authorization Scheme to a Page

- Attaching an Authorization Scheme to a Control or Component

Attaching an Authorization Scheme to an Application

To attach an authorization scheme to an application:

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

2. Select an application.

3. Click the Shared Components icon.
The Shared Components page appears.

4. Under Security, click Edit Security Attributes.

5. Scroll down to Authorization and make a selection from the Authorization Scheme list.

Attaching an Authorization Scheme to a Page

To attach an authorization scheme to a page:

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

2. Select an application.

3. Select a page.

4. Under Page Rendering, locate the section with the title of Page.

5. Click Edit page attributes icon.

6. Scroll down to Security and make a selection from the Authorization Scheme list.

Attaching an Authorization Scheme to a Control or Component

To attach an authorization scheme to a page component or control:

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

2. Select an application.

3. Select a page.

4. Click the name of the component or control to which you want to apply the authorization scheme.

5. Scroll down to Security and make a selection from the Authorization Scheme list.

Viewing Authorization Reports

You can use the Authorization Scheme Subscription and Authorization Scheme Utilization reports to better manage authorization schemes within your application.

To view authorization scheme reports:

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

2. Select an application.

3. On the Application home page, click Shared Components.
The Shared Components page appears.

4. Under Security, select Authorization Schemes.

5. Click the appropriate tab at the top of the page:

- Subscription

- Utilization

Subscription

Use the Authorization Scheme Subscription report to view details about authorization schemes subscription.

Utilization

Use the Authorization Scheme Utilization report to view details about authorization schemes utilization.

To view additional reports indicating which pages having authorization schemes and which do not, select one of the following from the Tasks list:

- Report Pages With Authorization Schemes

- Report Pages Without Authorization Schemes

12 Deploying an Application

This section describes how to package an application built within Application Builder.

Topics:

This section contains the following topics:

- About the Oracle Application Express Application Development Life Cycle

- Understanding the Packaging Process

- How to Move an Application to Another Development Instance

- How to Create a Packaged Application

- Exporting an Application and Related Files

- Importing Export Files

- Installing Export Files

- About Publishing the Application URL

- Using Build Options to Control Configuration

See Also:
"Advanced Programming Techniques" and "Managing Application Express Users"

About the Oracle Application Express Application Development Life Cycle

When developing applications using Application Builder, you need to find a balance between two dramatically different development methodologies:

- Iterative, rapid application development

- Planned, linear style development

The first approach offers so much flexibility that you run the risk of never completing your project. In contrast, the second approach can yield applications that do not meet the needs of end users even if they meet the stated requirements on paper.

System Development Life Cycle Methodologies to Consider

The system development life cycle (SDLC) is the overall process of developing software using a series of defined steps. There are a number of SDLC models that work well for developing applications in Oracle Application Express.

The SDLC waterfall is probably the best known model. In this methodology, the development process is broken down into the following stages:

1. Project Planning

2. Requirements Definition

3. Design

4. Development

5. Integration and Testing

6. Installation and Acceptance

7. Maintenance

This methodology is referred to as a waterfall because the output from one stage is the input for the next stage. One of the primary problems with this approach is that it is assumed that all requirements can be established in advance. Unfortunately, requirements often change and evolve during the development process.

The Oracle Application Express development environment enables developers to take a more iterative approach to development. Unlike many other development environments, creating prototypes is easy. With Oracle Application Express, developers can:

- Use built-in wizards to quickly design an application user interface

- Make protoypes available to users and gather feedback

- Implement changes in real time, creating new prototypes instantly

Other methodologies that work well with Oracle Application Express include:

- Spiral - This approach is actually a series of short waterfall cycles. Each waterfall cycle yields new requirements and enables the development team to create a robust series of prototypes.

- Rapid application development (RAD) life cycle - This approach has a heavy emphasis on creating a prototype that closely resembles the final product. The prototype is an essential part of the requirements phase. One disadvantage of this model is that the emphasis on creating the prototype can cause scope creep; developers can lose sight of their initial goals in the attempt to create the perfect application.

Understanding the Packaging Process

To move an application from one Oracle Application Express instance to another, you need to move both the metadata and supporting objects used by the application as follows:

1. Move the application definition and all associated files. See "How to Move an Application to Another Development Instance".

2. Move the supporting objects. Review the Database Dependencies report to determine what objects to move. See "About the Database Object Dependencies Report" and "How to Create a Packaged Application".

This section contains the following topics:

- Deployment Options to Consider

- Deciding Whether to Copy a Workspace

- Deciding Whether to Copy a Database

- About the Application ID

Deployment Options to Consider

When you develop an application in Application Builder, you create the application within a specific workspace. Each workspace has a unique ID and name. A common scenario is to create the application in a development instance and then deploy it to a production instance.

During the deployment process, you need to decide whether you want to use the existing application ID, the existing workspace, the existing database, the existing Oracle HTTP Server, or create new ones. Deployment options to consider include:

1. Create Application Express End Users. The simplest way to deploy an application is to create Application Express end users and then send the URL and login information to users. This approach works well for applications with a small and tolerant user population. See "About Publishing the Application URL" and "Managing Application Express Users".

2. Use the same workspace and same schema. Export and then import the application and install it using a different application ID. This approach works well when there are few changes to the underlying objects, but frequent changes to the application functionality.

3. Use a different workspace and same schema. Export and then import the application into a different workspace. This is an effective way to prevent a production application from being modified by developers.

4. Use a different workspace and different schema. Export and then import the application into a different workspace and install it so that it uses a different schema. This new schema will need to have the database objects required by your application. See "About the Database Object Dependencies Report".

5. Use a different database with all its variations. Export and then import the application into a different Oracle Application Express instance and install it using a different schema and database.

Deciding Whether to Copy a Workspace

Deciding whether or not to copy an existing workspace is a matter of preference. Keep in mind that the production version must have access to all the appropriate objects. For example, you might want to copy a workspace in the following situations:

- When the application subscribes to other Application Express objects within the workspace.

- When the application relies on Oracle Application Express authentication. Copying the workspace automatically migrates all the required user data.

Deciding Whether to Copy a Database

When deciding whether or not to copy the database, remember that the schema against which the application runs must have access to the same objects as the development instance. The actual name of the schema is unimportant. You can change it during the import process.

About the Application ID

It is not necessary to have matching application IDs for a development version and production version of an application. In fact, as a best practice never hard code the application ID into your application. Instead, use the application alias (defined on the Edit Definition page), or use a built-in substitution string (such as APP_ID and APP_ALIAS). Using a substitution string is the better approach because it enables you to change the application ID without affecting any application functionality.

See Also:
"Name" for information about defining an application alias and "About Built-in Substitution Strings" for information about using APP_ID and APP_ALIAS

Deciding to Install a New HTTP Server

In order to run, Oracle Application Express must have access to either the embedded PL/SQL gateway or Oracle HTTP Server and mod_plsql. Installing a new HTTP server is another way to separate a development version and production version of an application. To learn more about HTTP server configuration options, see "Choosing a HTTP Server" in the appropriate installation guide for your operating environment. See "Related Documents".

How to Move an Application to Another Development Instance

Whether you want to move an application to another workspace or just make a copy of it, deploying involves the following steps:

1. Move the supporting database objects (if appropriate). Review the Database Dependencies report to determine what objects to move. See "About the Database Object Dependencies Report".

2. Package an application definition with its supporting objects to create a packaged application. See "How to Create a Packaged Application".

3. Import the exported files into the target Oracle Application Express instance. See "Importing Export Files".
Note that if the target instance is a different schema, you also need to export and import any required database objects.

4. Install the exported files from Export Repository. See "Installing Export Files".

You can import an application into your workspace regardless of the workspace in which it was developed. See "Deployment Options to Consider".

Tip:
You can also move the application definition and all supporting objects manually. See "Exporting an Application and Related Files".

About Managing Database Objects

Before you export an application and the appropriate related files, you need to determine if you also need to migrate the database objects referenced by the application. If you are unsure of which database objects to move, review the Database Object Dependencies report.

See Also:
"About the Database Object Dependencies Report" and "How to Create a Packaged Application"

If the target schema is different from the schema used in the development environment, you need to migrate the database objects referenced by the application. In many cases, this process can be as simple as using Oracle database export and import utilities to copy the application schema from the development environment to target instance. The following are two common scenarios where this approach does not work:

- When the object development schema refers to tablespaces to which the target instance schema does not have access

- When the development instance schema has sample data that you do not want to migrate to the target instance schema

If a database administrator or an Oracle Application Express administrator is the person responsible for exporting Oracle Application Express applications, be sure to clearly communicate if he or she:

- Should include all data when exporting your application

- Should not include data from specific tables you identify

See Also:
"Loading Data" and "Unloading Data"

How to Create a Packaged Application

You can greatly simplify the steps needed to deploy an application by creating a packaged application on the Supporting Objects page.

Topics in this section include:

- How a Packaged Application Simplifies Deployment

- Creating a Packaged Application

- Adding Installation Scripts for an Image, Cascading Style Sheet, or Static File

- Adding an Access Control List to a Packaged Application

- Installing Supporting Objects

- Deleting Supporting Objects Scripts, Messages, and Installation Options

- Upgrading a Packaged Application

- Deinstalling Supporting Objects

- Viewing an Install Summary

How a Packaged Application Simplifies Deployment

From a user's perspective, importing and installing an application is a complicated process. First, you create the target database objects and seed data. Second, you import and install the application definition and all related files, including images, themes, and any other required static files.

Creating a packaged application using the Supporting Objects utility greatly simplifies this process. Instead of performing numerous steps to create the database objects and then import and install the application and all supporting files, you can define the supporting objects so that the application and supporting files can be migrated in a few easy steps.

After users import and install the application definition, a wizard guides them through a few simple configuration steps. Then, the wizard asks whether or not to install the supporting application objects. Users have the option of installing the supporting application objects then or doing it later.

From a developer's perspective, this feature has a number of advantages:

- Ensures that the supporting objects are created in the correct order.

- Provides users with an automated process for deploying an application quickly using very few steps.

- Gives users the option to install supporting application objects when they import and install the application definition or at a later time. See "Installing Supporting Objects".

- Enables users and developers with a convenient method for removing the application definition, supporting files, and all database objects. See "Deinstalling Supporting Objects".

- Enables users and developers with an easy way to upgrade a previously released packaged application. See "Upgrading a Packaged Application".

Plus, you can also take advantage of the Deinstall and Install features to quickly edit the underlying database objects that support an application. For example, you can deinstall and remove all database objects, edit the underlying database object creation scripts, and reinstall to create the redefined application objects.

Creating a Packaged Application

To create a packaged application, you need to create installation scripts that define your application's supporting objects (including database objects, images, and seed data) as well as any preinstallation validations. You define these objects as well as the installation and deinstallation scripts and the messages that display when the user installs or deinstalls on the Supporting Objects page.

Topics in this section include:

- Accessing the Supporting Objects Page

- About the Supporting Objects Page

Accessing the Supporting Objects Page

You create a packaged application on the Supporting Objects page.

To access the Supporting Objects Page application:

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

2. Select the application.
The Application home page appears.

3. Click the Supporting Objects icon.
The Supporting Objects page appears.

About the Supporting Objects Page

The top of the Supporting Objects page displays the application name and indicates current selections for the following: Check for Objects, Verify System Privileges, Required Free KB, Prompt for License, Substitutions, Build Options, Validations, Installation Scripts, Upgrade Scripts, Deinstallation Script, and Include in Export.

The rest of the page is divided into four categories.

Installation

Use the links under Installation to define the following types of information:

- Prerequisites. Defines built-in checks required prior to installing the application, including required free disk space, required system privileges, and schema object restrictions.

- Application substitution strings. Lists static substitution strings defined for the application. You can define static substitution strings for phrases or labels that occur in many places within an application. See "Substitutions".

When packaging an application, you can include prompts for substitution strings which users can specify when they install the packaged application.

- Build Options. Lists build options defined for this application. You can use build options to conditionally display specific functionality within an application. See "Using Build Options to Control Configuration" and "Exporting Build Options or Build Option Status".

When packaging an application, you can include prompts for specific build options which display when the application is installed.

- Pre-installation Validations. Lists validations defined for the packaged application. Similar to normal page validations, these validations prevent a user from installing database objects if the user-defined conditions are not satisfied. To create a new validation, click Create and follow the on-screen instructions.

- Installation Scripts. Enables a you to define multiple installation scripts that install supporting objects for the application. To create a new script, click Create and follow the on-screen instructions. To edit an existing script, click the Edit icon.

Message

Use the links under Message to define message to display when the user installs or deinstalls the application. Supported HTML tags include <b>, <i>, <u>, <p>, <br>, <hr>, <ul>, <ol>, <li>, and <pre>. Available message types include:

- Welcome

- License

- Application Substitutions

- Build Options

- Validations

- Confirmation

- Post Installation

- Upgrade

- Deinstallation

Note that when these messages display, only a limited set of HTML tags are recognized in order to prevent a cross site-scripting (XSS) attack. See "About Cross-Site Scripting Protection".

Upgrade

Click Upgrade scripts to define scripts to upgrade database objects, images, and seed data when upgrading an existing application. See "Upgrading a Packaged Application".

Deinstallation

Click Deinstallation script to define a script to drop database objects and static files created by the installation scripts. To edit an existing script, click the Edit icon.

Adding Installation Scripts for an Image, Cascading Style Sheet, or Static File

You can create installation scripts for images, cascading style sheets, and static files you have previously uploaded for your application or workspace on the Installation Scripts page. Oracle Application Express uses the name of the file you select as the name for each new script. It also adds corresponding API calls to the end of the deinstallation script (or creates one if one does not already exist), which removes the selected files when the application's supporting objects are deinstalled.

See Also:
"Using Custom Cascading Style Sheets", "Managing Images", and "Managing Static Files"

To create installation scripts for an image, cascading style sheet, or static file:

1. Navigate to the Supporting Objects page:

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

b. Select the application.
The Application home page appears.

c. Click Supporting Objects.
The Supporting Objects page appears.

2. Under Installation, click Installation scripts.
The Installation Scripts page appears.

3. Click Create.

4. At the bottom of the page, click Create Script to Install Files.
A list of available cascading style sheets, images, and static files appears.

5. Select the files to include with your packaged application and click Create Script.

Adding an Access Control List to a Packaged Application

You can control access to an application, individual pages, or page components by creating an access control list.

To add an access control list of a packaged application:

1. Create an access control list. See "Controlling Access to Applications, Pages, and Page Components".

2. Navigate to the Supporting Objects page:

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

b. Select the application.
The Application home page appears.

c. Click Supporting Objects.
The Supporting Objects page appears.

3. Under Installation, click Installation scripts.
The Installation Scripts page appears.

4. Click Create.

5. At the bottom of the page, click Create Scripts for Access Control Tables.
If Access Control tables are defined, the Create Script page displays the tables to be included.

6. Click Create Script.

Installing Supporting Objects

After you edit your supporting objects and create the appropriate scripts, you can run your installation scripts by clicking Install Supporting Objects on the Tasks list.

End users can also use this feature if they elect to not install the packaged application (or supporting objects) after they import and install the application definition.

To install supporting objects:

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

2. Select the application.

3. Click Supporting Objects.
The Supporting Objects page appears.

4. Click the Install Supporting Objects on the Tasks list.

5. To view details about the installation script before running it, click Preview Installation Script.
The Preview Scripts page appears listing summary information, prerequisites, and the actual scripts to be run.

6. To exit the Preview Scripts page and continue, click Close.

7. From Install Supporting Objects, click Yes and click Next.

8. Follow the on-screen instructions.

Deleting Supporting Objects Scripts, Messages, and Installation Options

You can delete the metadata that defines supporting object scripts, messages, and installation options associated with a packaged application by clicking Remove Supporting Object Installation on the Tasks list on the Supporting Objects page.

To delete the metadata that defines supporting object scripts, messages, and installation options:

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

2. Select an application.

3. Click Supporting Objects.
The Supporting Objects page appears.

4. On the Tasks list on the right side of the page, click Remove Supporting Object Installation.

5. Follow the on-screen instructions.

Upgrading a Packaged Application

You can define scripts to upgrade a previously published application on the Upgrade page.

Topics in this section include:

- Defining an Upgrade Script

- Upgrading a Packaged Application

Defining an Upgrade Script

You can use the Upgrade page to define scripts to upgrade database objects, images, and seed data when upgrading an existing application.

To create an upgrade script:

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

2. Select an application.

3. Click Supporting Objects.
The Supporting Objects page appears.

4. Under Upgrade, click Upgrade Scripts.

5. To create a new script, click Create.

Tip:
To enable users to upgrade from various earlier versions of this application, you can add conditions to the upgrade scripts by going to the Script Properties page.

Use the Detect Existing Supporting Objects section to determine if the appropriate objects are installed or need to be upgraded.

6. In Query to Detect Existing Supporting Objects, enter a query in the field provided that returns at least one row if the supporting objects exist.
This query determines whether or not the user who installs the packaged application is prompted to run the installation scripts or the upgrade scripts.

7. Follow the on-screen instructions.

Upgrading a Packaged Application

After you create your upgrade script, you can test it by clicking Upgrade Supporting Objects on Tasks list on the Supporting Object page.

End users can also use this feature to upgrade an existing packaged application.

To upgrade a packaged application:

1. Import a new version of application to be upgraded (if applicable). See "Importing an Application or Page".

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

3. Select the application.

4. Click Supporting Objects.
The Supporting Objects page appears.

5. From the Tasks list, click Upgrade Supporting Objects.

6. Follow the on-screen instructions.

Deinstalling Supporting Objects

Once you create or install a packaged application, you can deinstall it by either:

- Clicking the Deinstall Supporting Objects on the Supporting Objects page

- Clicking Delete this Application on the Application home page

When you deinstall an application, you have the option of removing the current application definition and running the deinstallation script defined in the Supporting Objects.

See Also:
"Creating a Packaged Application".

To deinstall a packaged application:

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

2. Select the application.

3. Click Supporting Objects.
The Supporting Objects page appears.

4. Click Deinstall Supporting Objects.

5. Select a deinstallation option:

- Remove Application Definition removes the current application definition.

- Deinstall Database Objects runs the deinstallation script defined in the deployment attributes for this application.

6. Follow the on-screen instructions.

Viewing an Install Summary

You can view a log of recent installation and deinstallation by clicking View Install Summary on the Tasks list on the Supporting Objects page. Note that this log only displays results from the most recent installation or deinstallation that occurred during the current Application Express session.

To view the Install Summary:

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

2. Select the application.

3. Click Supporting Objects.
The Supporting Objects page appears.

4. On the Tasks list on the right side of the page, click View Install Summary.
A Summary page appears.

Exporting an Application and Related Files

You export and import application definitions and all associated files using the Workspace Users, Application, CSS, Images, Files, Themes, and User Interface Defaults tabs located at the top of the Export page. Note that it is not necessary to export a workspace unless you wish to migrate workspace users or replicate shared component subscriptions in the target instance.

Once you export an application and any related files, you need to import them into the target Oracle Application Express instance and then install them. As a general rule, always import the application first and then the related files. See "How to Move an Application to Another Development Instance".

Tip:
You can simplify the steps needed to deploy an application by creating a packaged application. See "How to Create a Packaged Application".

Topics in this section include:

- Exporting an Application

- Exporting Workspace Users

- Exporting Application Components

- Exporting a Page in an Application

- Exporting Cascading Style Sheets

- Exporting Images

- Exporting Static Files

- Exporting Script Files

- Exporting Themes

- Exporting User Interface Defaults

Exporting an Application

When you export an application, Oracle Application Express generates a text file containing PL/SQL API calls.

See Also:
"Exporting Application Components"

To export an application:

1. Navigate to the Export page:

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

b. Select an application.

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

d. On the Export/Import page, click Export and then click Next.

2. From Application, select the application to be exported.

3. From File Format, select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

4. From Build Status Override, select one of the following:

- Run Application Only - Developers can only run an application

- Run and Build Application - Developers can both run and edit an application

Selecting Run Application Only is an effective way to protect an application from modifications from other developers.

Tip:
If you select Run Application Only, you cannot set the argument p_trace to Yes. See "Using Build Options to Control Configuration". Also, the only way to change this setting after you import the application, is to log in to Oracle Application Express Administration Services. See "Changing Application Build Status SetDuring Deployment".

5. From Supporting Object Definitions, specify whether or not to include packaged installation scripts and configuration options. See "How to Create a Packaged Application".

6. From Export Comments, specify whether or not to export comments for this application. See "Adding Developer Comments".

7. Use the As of field to export your application as it was previously defined. Specify the number of minutes in the field provided.
This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version for which you are looking. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases can have the same UNDO_RETENTION parameter, you are able to go back further in time on a database with fewer transactions because it is not filling the undo tablespace, forcing older data to be archived.

8. Click Export Application.

In addition to exporting the actual application file, you may also need to export other related files such as cascading style sheets, images, and script files.

See Also:
"Enabling SQL Tracing and Using TKPROF"

Exporting Workspace Users

You can make an application available to other users by creating workspace users. When you export workspace users, Oracle Application Express creates an ASCII text SQL script of users and any defined user groups.

To export workspace users:

1. Navigate to the Export page:

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

b. Select an application.

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

d. On the Export/Import page, click Export and then click Next.

2. On the Export page, click the Workspace Users tab.

3. From File Format, select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

4. Click Export Workspace Users.

See Also:
"Managing Application Express Users"

Exporting Application Components

You can export shared components or components of a page on the Component Export page. You can use this wizard to:

- Export shared components or page components to another application or workspace

- Back up a component before editing it

- Create an export to function as a patch to another Oracle Application Express 2.2 instance

See Also:
"Exporting an Application", "Exporting a Page in an Application", "Importing an Application or Page", and "Exporting Build Options or Build Option Status"

To export shared components or page components:

1. Navigate to the Component Export page:

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

b. Select an application.

c. Click Shared Components.

d. From the Tasks list, click Component Export.
The Component Export page appears.

2. Click the following tabs and select the components to be exported:

- Components displays shared application components and entire pages. Use the navigation bar at the top of the page to search for components. See "Working with Shared Components" and "Exporting Build Options or Build Option Status".

- Components by Page lists components of the selected page. Navigate to a specific page by making a selection from the Page. Click Check All to select all components.

- Application Attributes displays application attributes. Press CTRL or SHIFT to select multiple attributes. See "About the Edit Definition Page".

- Build Option Status displays available build options. Use this page to turn build options on and off. See "Exporting Build Options or Build Option Status".

3. Click Add to Export.

4. Click Next.

5. On Components to Export:

a. From File Format, select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

b. Use the As of field to export a page as it was previously defined. Specify the number of minutes in the field provided.
This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version for which you are looking. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases may have the same UNDO_RETENTION parameter, you are able to go back further in time on a database with fewer transactions because it is not filling the undo tablespace, forcing older data to be archived.

c. Click Export Components.

Exporting a Page in an Application

You can also export a specific page within an application by clicking the Export page icon on the Page Definition. When exporting a page, remember that exported pages can only be imported sucessfully if they have the same application ID and workspace ID.

See Also:
"Exporting Application Components", "Exporting an Application", and "Importing an Application or Page"

To export a page in an application:

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

2. On the Page Definition, you can export a page in two ways:

- Click the Export Page icon, the down arrow in the upper right corner. See "Export Page Icon".

- From the View list, select Export and click Go.

The Export Page Wizard appears.

3. From Page, select the page to be exported.

4. From File Format, select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

5. Use the As of field to export a page as it was previously defined. Specify the number of minutes in the field provided.
This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version for which you are looking. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases may have the same UNDO_RETENTION parameter, you are able to go back further in time on a database with fewer transactions because it is not filling the undo tablespace, forcing older data to be archived.

6. Click Export Page.

Exporting Cascading Style Sheets

Use the Export Cascading Style Sheets utility to export uploaded cascading style sheets. Note that you can use this utility to export only uploaded cascading style sheets.

To export related cascading style sheets:

1. Navigate to the Export page:

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

b. Select an application.

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

d. On the Export/Import page, click Export and then click Next.

2. Click the CSS tab at the top of the page.

3. On the Export Cascading Style Sheets page, select the following:

a. Style Sheets - Select the cascading style sheets to export.

b. File Format - Select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

c. Click Export Style Sheets.

See Also:
"Importing Cascading Style Sheets" and "Using Custom Cascading Style Sheets"

Exporting Images

Use the Export Images utility to export uploaded images. When you export images using this utility, the images are converted to a text document. Note that you can use this utility to export only uploaded images.

To export upload images:

1. Navigate to the Export page:

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

b. Select an application.

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

d. On the Export/Import page, click Export and then click Next.

2. Click the Images tab at the top of the page.

3. On the Export Images page, select the following:

a. Export Images in Application - Select an application from which to export images.
Be aware that selecting Workspace Images only exports those images in your repository that are not associated with a specific application. If all of your images are associated with specific applications, then the workspace image export file will be empty.

b. File Format - Select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

4. Click Export Images.

See Also:
"Importing Images", "Managing Images", and "Using the Images Finder"

Exporting Static Files

Use the Export Static Files utility to export static files you have imported. Note that you can use this utility to export only uploaded static files.

To export related static files:

1. Navigate to the Export page:

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

b. Select an application.

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

d. On the Export/Import page, click Export and then click Next.

2. Click the Files tab at the top of the page.

3. On Export Static Files, select the following:

a. Static Files - Select the files to be exported.

b. File Format - Select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

c. Click Export File(s).

About Importing into Another Oracle Application Express Instance

Note that you cannot use the Web interface described in this section to import exported static files into another Oracle Application Express instance. To import exported static files into another Oracle Application Express instance, use SQL*Plus while connected to the database. Note that you must export from and to a workspace having the same name and workspace ID.

Exporting Script Files

You can transfer selected scripts from your current Script Repository to a Script Repository in a different Workspace by using the Export and Import tasks.

To export script files:

1. On the Workspace home page, click the SQL Workshop icon.

2. Click SQL Scripts.

3. On the Tasks list, click Export.

4. Select the appropriate script files and click Add to Export.

5. Review the file name and click Export All.
Select the Remove check box to remove the script.

See Also:
"Using SQL Scripts"

Exporting Themes

Use the Export Theme utility to export themes from one Oracle Application Express development instance to a file.

See Also:
"Importing Themes"and"Managing Themes"

Exporting a Theme from the Export Page

To export an application theme from the Export page:

1. Navigate to the Export page:

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

b. Select an application.

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

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

2. Click the Themes tab at the top of the page.

3. On the Export Application Theme page, select the following:

a. Export Theme - Select the theme to be exported.

b. File Format - Select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

c. Click Export Theme.

Exporting a Theme from the Themes Page

To export an application theme from the Themes page:

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

2. Select an application.

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

4. Under User Interface, select Themes.
The Themes page appears.

5. On the Tasks list, click Export Theme.
The Export page appears.

6. On the Export Theme page, select the following:

a. Export Theme - Select the theme to be exported.

b. File Format - Select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

c. Click Export Theme.

Exporting User Interface Defaults

Exporting User Interface Defaults is useful when you plan to develop on a target system.

When you export User Interface Defaults, all User Interface Defaults for the selected schema are exported to a single SQL Command script. When prompted, save this file to your hard drive. The file contains an API call to create table hints by making calls to the application PL/SQL API. You can use this file to import User Interface Defaults to another database and Oracle Application Express instance.

See Also:
"Importing User Interface Defaults" and "Managing User Interface Defaults"

Exporting User Interface Defaults from the Export Page

To export User Interface Defaults from the Export page:

1. Navigate to the Export page:

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

b. Select an application.

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

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

2. Click the User Interface Defaults tab at the top of the page.

3. On the Export User Interface Defaults page, select the following:

a. Schema - Select the schema that owns the table associated with the User Interface Defaults.

b. File Format - Select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

c. Click Export User Interface Defaults.

Exporting User Interface Defaults from the User Interface Defaults Page

To export User Interface Defaults from the User Interface Defaults page:

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

2. Select an application.

3. On the Application Builder home page, click Shared Components.

4. Under User Interface, select User Interface Defaults.
The User Interface Defaults page appears.

5. From the Tasks list, click Export.

6. On the Export User Interface Defaults page, select the following:

a. Schema - Select the schema that owns the table associated with the User Interface Defaults.

b. File Format - Select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

c. Click Export User Interface Defaults.

Importing Export Files

Once you export an application and any related files, you need to import them into the target Oracle Application Express instance before you can install them. As a general rule, always import the application first and then the related files. See "How to Move an Application to Another Development Instance".

Tip:
You can simplify the steps needed to deploy an application by creating a packaged application. See "How to Create a Packaged Application".

Topics in this section include:

- Importing an Application or Page

- Importing Cascading Style Sheets

- Importing Images

- Importing Themes

- Importing User Interface Defaults

Importing an Application or Page

To import an Application or Page Export into a target Oracle Application Express instance:

1. Navigate to the Import page:

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

b. Select an application.

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

d. On the Export/Import page, click Import and then click Next.

2. For Specify File, specify the following:

a. Import file - Click Browse and navigate to the file.

b. File Type - Select Application, Page, or Component Export.

c. Verify that File Character Set is correct.

d. Click Next.

Once you import a file, you have the option to install it.

3. To install an imported file, click Next.
The Install Application wizard appears.

4. In the Install Application wizard, specify the following:

a. Parse As Schema - Select a schema.
This is the schema against which all of the application's SQL and PL/SQL will be parsed.

b. Build Status - Select one of the following:

- Run Application Only - Users can only run an application.

- Run and Build Application - Users can run an application and developers can both run and edit an application.

Selecting Run Application Only is an effective way to protect an application from modifications from other developers.

Tip:
If you select Run Application Only, the only way to change this setting after you import the application is to log in to Oracle Application Express Administration Services. See "Changing Application Build Status SetDuring Deployment".

c. Install As Application - Select one of the following:

- Auto Assign New Application ID

- Reuse Application ID From Export File

- Change Application ID

Use these options to avoid application ID conflicts. These options come in handy when you need to have two versions of the same application in the same instance. For example, you might be migrating an application to a production instance and still need to maintain the development version.

d. Click Install.
If you are installing a packaged application (that is, one for which you have defined Supporting Objects), the installer prompts you to install the packaged installation scripts. Follow the on-screen instructions.

See Also:
"How to Create a Packaged Application"

Importing Cascading Style Sheets

After you import an application into the target Oracle Application Express instance, you need to import all related files.

To import a CSS Export file:

1. Navigate to the Import page:

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

b. Select an application.

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

d. On the Export/Import page, click Import and then click Next.

2. For Specify File, select the following:

a. Import file - Click Browse and navigate to the file.

b. File Type - Select CSS Export.

c. File Character Set - Verify that File Character Set is correct.

d. Click Next.

Once you import a file, you have the option to install it.

3. To install an imported file, click Next.

4. Click Install CSS.

See Also:
"Using Custom Cascading Style Sheets" and "Exporting Cascading Style Sheets"

Importing Static Files

After you import an application into the target Oracle Application Express instance, you need to import all related files.

To import a static file:

1. Navigate to the Import page:

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

b. Select an application.

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

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

2. For Specify File, select the following:

a. Import file - Click Browse and navigate to the file.

b. File Type - Select File Export.

c. File Character Set - Verify that File Character Set is correct.

d. Click Next.

Once you import a file, you have the option to install it.

3. To install an imported file, click Next.

4. Click Install Static Files.

See Also:
"Exporting Static Files"

Importing Images

After you import an application into the target Oracle Application Express instance, you need to import all related files.

To import an Image Export file:

1. Navigate to the Import page:

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

b. Select an application.

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

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

2. On Import Definition, select the following:

a. Import file - Click Browse and navigate to the file.

b. File Type - Select Image Export.

c. File Character Set - Verify that File Character Set is correct.

d. Click Next.

Once you import a file, you have the option to install it.

3. To install an imported file, click Next.

4. Click Install Image.

See Also:
"Managing Images", "Using the Images Finder", and "Exporting Images"

Importing Themes

After you import an application into the target Oracle Application Express instance, you need to import all related files.

To import a Theme Export file:

1. Navigate to the Import page:

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

b. Select an application.

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

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

2. On Import Definition, select the following:

a. Import file - Click Browse and navigate to the file.

b. File Type - Select Theme Export.

c. File Character Set - Verify that File Character Set is correct.

d. Click Next.

Once you import a file, you have the option to install it.

3. To install an imported file, click Next.

4. Click Install Theme.

See Also:
"Managing Themes" and "Exporting Themes"

Importing User Interface Defaults

User Interface Defaults enables you to assign default user interface properties to a table, column, or view within a specified schema.

After you import an application into the target Oracle Application Express instance, you need to import all related files.

To import User Interface Defaults:

1. Navigate to the Import page:

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

b. Select an application.

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

d. On the Export/Import page, click Import and then click Next.

2. Select an application.

3. On Import Definition, select the following:

a. Import file - Click Browse and navigate to the file.

b. File Type - Select User Interface Defaults.

c. File Character Set - Verify that File Character Set is correct.

d. Click Next.

Once you import a file, you have the option to install it.

4. To install an imported file, click Next.

5. Click Install User Interface Defaults.

See Also:
"Managing User Interface Defaults" and "Exporting User Interface Defaults"

Installing Export Files

After you import an application and any related files into the target Oracle Application Express instance, the files are stored in the Export Repository. Next, you need to install them.

You can install export files in the following ways:

- After you import the export file, click the Install button and follow the on-screen instructions.

- Import the export files into Application Builder and then install the files from the Export Repository.

- Install the export files from SQL*Plus.

Tip:
You can simplify the steps needed to deploy an application by creating a packaged application. See "How to Create a Packaged Application".

Topics in this section include:

- Accessing the Export Repository

- Installing an Application Export from the Export Repository

- Installing Other Files from the Export Repository

- Deleting Files from the Export Repository

- Installing Export Files from SQL*Plus

Accessing the Export Repository

When you import an application and any related files into a target Oracle Application Express instance, the files are stored in the Export Repository.

To access the Export Repository:

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

2. Select an application.

3. On the Tasks list, click Manage Export Repository.
The Export Repository appears.

Tip:
You can also access the Export Repository by clicking Export Repository on the Tasks list on either the Application home or Application Builder home pages.

Installing an Application Export from the Export Repository

After you import an application export into an Oracle Application Express instance, you must install it before it can become active or available in Application Builder.

To install an application export from the Export Repository:

1. Navigate to the Export Repository:

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

b. Select an application.

c. On the Tasks list, click Manage Export Repository.
The Export Repository appears.

2. Select an application export and click Install in the Action column.

3. Specify the following:

a. Parse As Schema - Select a schema.
This is the schema against which all of the application's SQL and PL/SQL will be parsed.

b. Build Status - Select one of the following:

- Run Application Only

- Run and Build Application

Select Run Application Only to run the application in the target instance and make it inaccessible to developers.

Tip:
If you select Run Application Only, the only way to change this setting after you import the application is to log in to Oracle Application Express Administration Services. See "Changing Application Build Status SetDuring Deployment".

c. Install As Application - Select one of the following:

- Reuse Application ID from Export File

- Auto Assign New Application ID

- Change Application ID

Use these options to avoid application ID conflicts. Use these options when you need to have two versions of the same application in the same instance. For example, you might be migrating an application to a production instance and still need to maintain the development version.

d. Click Install.

About Installing a Packaged Application

If you are installing a packaged application, the installer prompts you to install the packaged installation scripts. Follow the on-screen instructions.

See Also:
"How to Create a Packaged Application"

Installing Other Files from the Export Repository

After you import files into an Oracle Application Express instance, you must install them before they can become active or available in Application Builder.

To install files stored in the Export Repository:

1. Navigate to the Export Repository.

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

b. Select an application.

c. On the Tasks list, click Manage Export Repository.
The Export Repository appears.

2. Select the file to be installed and click Install in the Action column.

3. Follow the on-screen instructions and click the Install button.

Deleting Files from the Export Repository

You can delete a file from the Export Repository.

To delete a file from the Export Repository:

1. Navigate to the Export Repository.

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

b. Select an application.

c. On the Tasks list, click Manage Export Repository.
The Export Repository appears.

2. Select the file to be deleted and click Delete Checked.

Installing Export Files from SQL*Plus

You can also install export files from SQL*Plus. Note there are two restrictions:

- The export file must originate from the same user database account as the one into which you are installing.

- If the export file is an application, the application ID will be overwritten. Therefore, the target workspace must own the ID of the application being installed.

- If the export file contains Supporting Object scripts, the scripts are not run when the application is installed. You can either log in to the Application Builder to install Supporting Objects, or copy the installation scripts to a standalone SQL*Plus script and run them from there.

Topics in this section include:

- Verifying If Source and Target Workspace IDs Are Identical

- Using SQL*Plus to Install Export Files

Verifying If Source and Target Workspace IDs Are Identical

You can verify that the source and target workspaces are identical by running a query in SQL Command Processor.

To verify that the source and target workspaces are identical:

1. Log in to the source workspace.

2. Click the SQL Workshop icon on the Workspace home page.

3. Click SQL Commands.

4. Enter the following in the SQL editor pane and click Run:

SELECT &WORKSPACE_ID. FROM DUAL

5. Note the workspace ID.

6. Log in to the target workspace.

7. Repeat steps 2 through 5 to verify the workspace IDs match.

Using SQL*Plus to Install Export Files

To install Oracle Application Express export files from SQL*Plus:

1. Log in to SQL*Plus.

2. Run the export file.
For example, if your export file is names f144.sql by default, you would type @f144 at the command prompt.

About Publishing the Application URL

Once you have deployed your application, loaded data, and created users, you can publish your production URL.

You can determine the URL to your application by positioning the mouse over the Run icon on the Application home page. The URL displays in the status bar at the bottom of the page.

The Run icon gets its value from the Home link attribute on the Edit Security Attributes page. This link is only referenced by this icon and by applications that do not use the Oracle Application Express Login API. Consider the following example:

http://apex.oracle.com/pls/apex/f?p=11563:1:3397731373043366363

Where:

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

- 11563 is the application being called.

- 1 is the page within the application to be displayed.

- 3397731373043366363 is the session number.

To run this example application, you would use the URL:

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

When users log in, they receive unique session numbers.

See Also:
"Accessing the Edit Security Attributes Page"

Using Build Options to Control Configuration

Build options enable you to conditionally display specific functionality within an application.

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.

Topics in this section include:

- Creating Build Options

- Managing Build Options

- Exporting Build Options or Build Option Status

- Viewing the Build Option Utilization Report

See Also:
"Changing Application Build Status SetDuring Deployment"

Creating Build Options

You create a build option for an application on the Build Options page.

To create a build option:

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

2. Select an application.

3. On the Application Builder home page, click Shared Components.

4. Under Application, click Build Options.

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

6. Follow the on-screen instructions.

About the Build Options Page

Once you create a build option, it appears on the Build Options page. You control how the Build Options page displays by making a selection from the View list. Available options include:

- Icons (the default) displays each build option as a large icon. To edit a build option, click the appropriate icon.

- Details displays each build option as a line in a report. Each line includes the application ID, build option name, status, and a link to the Build Option Utilization report. To edit a build option, click the appropriate name.

Managing Build Options

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.

To include or exclude a build option:

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

2. Select an application.

3. On the Application Builder home page, click Shared Components.

4. Under Application, click Build Options.

5. Select the appropriate build option.
The Create/Edit Build Option page appears.

6. For Status, select either INCLUDE or EXCLUDE.

Selecting a Build Option

Once you create a build option, you can select it for a page, a component (report, chart, or form), a specific page control (button, item, list of value), and another shared component (breadcrumb, list, or tab). You apply build options to a page, component, page control, or shared component by navigating to the appropriate attributes page. Most attributes pages contain a Configuration section where you can select defined build options.

See Also:
"Editing Page Attributes"

Exporting Build Options or Build Option Status

You can export build options or build option status on the Component Export page. Exporting build option status is an effective way to toggle build options on or off within another environment. For example, you can use this feature to deploy a production application with a hidden feature.

To accomplish this, you associate the components of the hidden feature with a build option having the status of EXCLUDE. After deployment, you can enable the hidden feature by changing the status of the build option to INCLUDE and then exporting the Build Option Status.

Once you apply the Build Options Status to the production instance, the new feature appears.

See Also:
"How to Create a Packaged Application" and "Exporting Application Components"

To export build options or build option status:

1. Navigate to the Component Export page:

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

b. Select an application.

c. Click Shared Components.

d. From the Tasks list, click Component Export.
The Component Export page appears.

2. Select the build options to be exported:

a. Click the Components tab and select the build options to be exported.

b. Click Add to Export.

3. Select Build Option Status to be exported:

a. Click the Build Options Status tab and select the build options to be exported.

b. Click Add to Export.

4. Click Next.

5. On Components to Export:

a. From File Format, select how rows in the export file will be formatted:

- Choose UNIX to have the resulting file contain rows delimited by line feeds.

- Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

b. Use the As of field to export a page as it was previously defined. Specify the number of minutes in the field provided.
This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version for which you are looking. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases may have the same UNDO_RETENTION parameter, you are able to go back further in time on a database with fewer transactions because it is not filling the undo tablespace, forcing older data to be archived.

c. Click Export Components.

Viewing the Build Option Utilization Report

Once you create a build option, a Utilization tab appears on the Build Options page. This report details build option utilization in the current application.

Note:
The Utilization tab only appears on the Build Options page after you create a build option.

To view the Build Option Utilization report:

1. Navigate to the Build Options page:

a. Navigate to the Workspace home page.

b. Click the Application Builder icon.

c. Select an application.

d. On the Application Builder home page, click Shared Components.

e. Under Application, click Build Options.
The Build Options page appears.

2. On the Build Options page, click Utilization.
The Build Option Utilization report appears.

3. Select a build option and click Go.

13 Advanced Programming Techniques

This section provides information about advanced programming techniques including working with automatic data manipulation language, establishing database links, using collections, running background SQL, utilizing Web services, and managing user preferences.

This section contains the following topics:

- About DML Lockings

- Accessing Data with Database Links

- Sending Email from an Application

- Using Collections

- Creating Custom Activity Reports Using APEX_ACTIVITY_LOG

- Running Background PL/SQL

- Implementing Web Services

See Also:
"Oracle Application Express APIs" and "Deploying an Application"

About DML Lockings

When automatic data manipulation language (DML) is used in Oracle Application Express to update or delete rows of a table, a transaction is initiated to first lock the row, verify if it has changed since it was displayed on the page, and then finally issue the actual UPDATE or DELETE statement for the row.

In some environments where locking of rows is prevalent, you may wish to control the DML operation and determine if the DML operation:

- waits indefinitely

- fails immediately

- waits for a specified period of time

You can set the value of an application substitution string, an application item, or a page item named APEX_DML_LOCK_WAIT_TIME to control this operation. The following values are supported:

- If null (the default), results in the same behavior as previous versions of Oracle Application Express, that is, wait indefinitely.

- If 0, fail immediately if the row is locked by another database session.

- If > 0 and the row is locked, wait for the specified number of seconds.

When set in an application, the value for APEX_DML_LOCK_WAIT_TIME applies to all UPDATE and DELETE DML operations using Automatic DML in the entire application. To control a specific Automatic DML process, update the value of APEX_DML_LOCK_WAIT_TIME before the Automatic DML process and reset it after the Automatic DML process. Note that this does not affect updates and deletes using tabular forms.

Accessing Data with Database Links

Because the Workspace home page runs in an Oracle database, you have access to all distributed Oracle database capabilities. Typically, you perform distributed database operations using database links.

A database link is a schema object in one database that enables you to access objects on another database. Once you have created the database link you can access the remote objects by appending @dblink to the table or view name where dblink is the Database Link Name you specify in the Create Database Object Wizard.

Note:
By default, the CREATE DATABASE LINK system privilege is not granted to a provisioned workspace or database user. To use this feature, a DBA or administrator needs to grant this specific privilege to the database user in the user's workspace. See "Creating Database Links" in Oracle Database Administrator's Guide

To create a database link:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. Select Database Link and click Next.

4. Follow the on-screen instructions.
Note that Database Link names must conform to Oracle naming conventions and cannot contain spaces, or start with a number or underscore.

To view an existing a database link:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Select the object type Database Links at the top of the page.

See Also:
"Managing Database Objects with Object Browser" and "Database Links" in Oracle Database Administrator's Guide

Sending Email from an Application

This section describes how to send email from an Oracle Application Express application.

Topics in this section include:

- About Configuring Oracle Application Express to Send Email

- Sending Email from an Application

See Also:
"Managing Mail"

Tip:
If you are running Oracle Application Express with Oracle Database 11g Release 1 (11.1), you must enable network services in order to send outbound email. See "Enabling Network Services in Oracle Database 11g"

About Configuring Oracle Application Express to Send Email

Before you can send email from an Application Builder application, you must:

1. Log in to Oracle Application Express Administration Services and configure the email settings on the Instance Settings page. See "Configuring Email Settings".

2. If you are running Oracle Application Express with Oracle Database 11g release 1 (11.1), you need to enable outbound mail. In Oracle Database 11g release 1 (11.1), the ability to interact with network services is disabled by default. See "Enabling Network Services in Oracle Database 11g".

Tip:
You can configure Oracle Application Express to automatically email users their login credentials when a new workspace request has been approved. To learn more, see "Specifying a Provisioning Mode".

Sending Email from an Application

You can send an email from an Application Builder application by calling the PL/SQL package APEX_MAIL. This package is built on top of the Oracle supplied UTL_SMTP package. Because of this dependence, in order to use APEX_MAIL, the UTL_SMTP package must be installed and functioning.

See Also:
Oracle Database PL/SQL Packages and Types Reference for more information about the UTL_SMTP package and "APEX_MAIL"

APEX_MAIL contains two procedures for manually sending email:

- Use the APEX_MAIL.SEND procedure to manually send an outbound email message from your application

- Use APEX_MAIL.PUSH_QUEUE to deliver mail messages stored in APEX_MAIL_QUEUE

Oracle Application Express stores unsent email messages in a table named APEX_MAIL_QUEUE. You can deliver mail messages stored in this queue to the specified SMTP gateway by calling the procedure APEX_MAIL.PUSH_QUEUE.

Oracle Application Express logs successfully submitted messages in the table APEX_MAIL_LOG with the timestamp reflecting your server's local time.

The following UNIX/LINUX example demonstrates the use of the APEX_MAIL.PUSH_QUEUE procedure using a shell script.

SQLPLUS / <<EOF
APEX_MAIL.PUSH_QUEUE;
DISCONNECT
EXIT
EOF

See Also:
"APEX_MAIL" for information about using the APEX_MAIL and "Managing Mail"

Using Collections

Collections enable you to temporarily capture one or more nonscalar values. You can use collections to store rows and columns currently in session state so they can be accessed, manipulated, or processed during a user's specific session. You can think of a collection as a bucket in which you temporarily store and name rows of information.

The following are examples of when you might use collections:

- When you are creating a data-entry wizard in which multiple rows of information first need to be collected within a logical transaction. You can use collections to temporarily store the contents of the multiple rows of information, before performing the final step in the wizard when both the physical and logical transactions are completed.

- When your application includes an update page on which a user updates multiple detail rows on one page. The user can make many updates, apply these updates to a collection and then call a final process to apply the changes to the database.

- When you are building a wizard where you are collecting an arbitrary number of attributes. At the end of the wizard, the user then performs a task that takes the information temporarily stored in the collection and applies it to the database.

Topics in this section include:

- About the APEX_COLLECTION API

- Creating a Collection

- Truncating a Collection

- Accessing a Collection

- Deleting a Collection

- Adding Members to a Collection

- Updating Collection Members

- Deleting Collection Members

- Determining Collection Status

- Merging Collections

- Managing Collections

- Clearing Collection Session State

About the APEX_COLLECTION API

Every collection contains a named list of data elements (or members) which can have up to 50 character attributes (VARCHAR2(4000)), and one large character attribute (CLOB). You insert, update, and delete collection information using the PL/SQL API APEX_COLLECTION.

About Collection Naming

When you create a new collection, you must give it a name that cannot exceed 255 characters. Note that collection names are not case-sensitive and will be converted to uppercase.

Once the collection is named, you can access the values in the collection by running a SQL query against the view APEX_COLLECTIONS.

See Also:
"Accessing a Collection"

Creating a Collection

Every collection contains a named list of data elements (or members) which can have up to 50 character attributes (VARCHAR2(4000)), and one large character attribute (CLOB). You use the following methods to create a collection:

- CREATE_COLLECTION

- CREATE_OR_TRUNCATE_COLLECTION

- CREATE_COLLECTION_FROM_QUERY

- APEX_COLLECTION.CREATE_COLLECTION_FROM_QUERY_B

The CREATE_COLLECTION method raises an exception if the named collection already exists, for example:

APEX_COLLECTION.CREATE_COLLECTION(
p_collection_name => collection name );

The CREATE_OR_TRUNCATE_COLLECTION method creates a new collection if the named collection does not exist. If the named collection already exists, this method truncates it. Truncating a collection empties it, but leaves it in place, for example:

APEX_COLLECTION.CREATE_OR_TRUNCATE_COLLECTION(
p_collection_name => collection name,
p_generate_md5    => YES or NO );

The CREATE_COLLECTION_FROM_QUERY method creates a collection and then populates it with the results of a specified query, for example:

APEX_COLLECTION.CREATE_COLLECTION_FROM_QUERY(
p_collection_name => collection name,
p_query           => your query );
p_generate_md5    => YES or NO );

The CREATE_COLLECTION_FROM_QUERY_B method also creates a collection and then populates it with the results of a specified query, for example:

APEX_COLLECTION.CREATE_COLLECTION_FROM_QUERY_B(
p_collection_name => collection name,
p_query           => your query );

The CREATE_COLLECTION_FROM_QUERY_B method offers significantly faster performance than the CREATE_COLLECTION_FROM_QUERY method by performing bulk SQL operations, but has the following limitations:

- No column value in the select list of the query can be more than 2,000 bytes. If a row is encountered that has a column value of more than 2,000 bytes, an error will be raised during execution.

- The MD5 checksum will not be computed for any members in the collection.

About the Parameter p_generate_md5

Use the p_generate_md5 flag to specify if the message digest of the data of the collection member should be computed. By default, this flag is set to NO. Use this parameter to check the MD5 of the collection member (that is, compare it with another member or see if a member has changed).

See Also:
"Determining Collection Status" for information about using the GET_MEMBER_MD5 function

Truncating a Collection

If you truncate a collection, you remove all members from the specified collection, but the named collection remains in place, for example:

APEX_COLLECTION.TRUNCATE_COLLECTION(
p_collection_name => collection name );

Accessing a Collection

You can access the members of a collection by querying the database view APEX_COLLECTIONS. The APEX_COLLECTIONS view has the following definition:

COLLECTION_NAME   NOT NULL VARCHAR2(255)
SEQ_ID            NOT NULL NUMBER
C001                       VARCHAR2(4000)
C002                       VARCHAR2(4000)
C003                       VARCHAR2(4000)
C004                       VARCHAR2(4000)
C005                       VARCHAR2(4000)
...
C050                       VARCHAR2(4000)
CLOB001                    CLOB
MD5_ORIGINAL               VARCHAR2(4000)

Use the APEX_COLLECTIONS view in an application just as you would use any other table or view in an application, for example:

SELECT c001, c002, c003
FROM APEX_collections
WHERE collection_name = 'FIREARMS'

Deleting a Collection

If you delete a collection, you delete the collection and all of its members, for example:

APEX_COLLECTION.DELETE_COLLECTION (
p_collection_name => collection name );

Be aware that if you do not delete a collection, it will eventually be deleted when the session is purged. For example:

Deleting All Collections for the Current Application

Use the DELETE_ALL_COLLECTIONS method to delete all collections defined in the current application, for example:

APEX_COLLECTION.DELETE_ALL_COLLECTIONS;

Deleting All Collections in the Current Session

Use the DELETE_ALL_COLLECTIONS_SESSION method to delete all collections defined in the current session., for example:

APEX_COLLECTION.DELETE_ALL_COLLECTIONS_SESSION;

Adding Members to a Collection

When data elements (or members) are added to a collection, they are assigned a unique sequence ID. As you add members to a collection, the sequence ID will change in increments of 1, with the newest members having the largest ID.

You add new members to a collection using the ADD_MEMBER function. Calling this function returns the sequence ID of the newly added member. The following example demonstrates how to use the ADD_MEMBER function.

APEX_COLLECTION.ADD_MEMBER(
p_collection_name => collection name,
p_c001          => [member attribute 1],
p_c002          => [member attribute 2],
p_c003          => [member attribute 3],
p_c004          => [member attribute 4],
p_c005          => [member attribute 5],
p_c006          => [member attribute 6],
p_c007          => [member attribute 7],
...
p_c050          => [member attribute 50]);
p_clob001       => [CLOB member attribute 1],
p_generate_md5  => YES or NO);

You can also add new members (or an array of members) to a collection using the ADD_MEMBERS method, for example:

APEX_COLLECTION.ADD_MEMBERS(
p_collection_name => collection name,
p_c001          => member attribute array 1,
p_c002          => member attribute array 2,
p_c003          => member attribute array 3,
p_c004          => member attribute array 4,
p_c005          => member attribute array 5,
p_c006          => member attribute array 6,
p_c007          => member attribute array 7,
...
p_c050          => member attribute array 50);
p_generate_md5  => YES or NO);

This method raises an error if the specified collection does not exist with the specified name of the current user and in the same session. Also any attribute exceeding 4,000 characters will be truncated to 4,000 characters. The number of members added is based on the number of elements in the first array.

About the Parameters p_generate_md5 and p_clob001

Use the p_generate_md5 flag to specify if the message digest of the data of the collection member should be computed. By default, this flag is set to NO. Use this parameter to check the MD5 of the collection member (that is, compare it with another member or see if a member has changed).

Use p_clob001 for collection member attributes which exceed 4,000 characters.

See Also:
"Determining Collection Status" for information about using the function GET_MEMBER_MD5

Updating Collection Members

You can update collection members by calling the UPDATE_MEMBER procedure and referencing the desired collection member by its sequence ID, for example:

APEX_COLLECTION.UPDATE_MEMBER (
p_collection_name => collection name,
p_seq             => member sequence number,
p_c001            => member attribute 1,
p_c002            => member attribute 2,
p_c003            => member attribute 3,
p_c004            => member attribute 4,
p_c005            => member attribute 5,
p_c006            => member attribute 6,
p_c007            => member attribute 7,
...
p_c050            => member attribute 50);
p_clob001         => [CLOB member attribute 1],

The UPDATE_MEMBER procedure replaces an entire collection member, not individual member attributes. This procedure causes an error if the named collection does not exist. For example:

Use the p_clob001 parameter for collection member attributes which exceed 4,000 characters.

If you want to update a single attribute of a collection member, use the UPDATE_MEMBER_ATTRIBUTE procedure, for example:

APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE(
p_collection_name       => collection_name,
p_seq                   => member sequence number,
p_attr_number           => member attribute number,
p_attr_value            => member attribute value )

APEX_COLLECTION.UPDATE_MEMBER_ATTRIBUTE(
p_collection_name        => collection_name,
p_seq                    => member sequence number,
p_clob_number            => CLOB member attribute number,
p_clob_value             => CLOB member attribute value );

Calling the UPDATE_MEMBER_ATTRIBUTE procedure causes an error if the named collection does not exist.

Note that the only valid value for the p_clob_number parameter is 1.

Deleting Collection Members

You can delete a collection member by calling the DELETE_MEMBER procedure and referencing the desired collection member by its sequence ID, for example:

APEX_COLLECTION.DELETE_MEMBER(
p_collection_name => collection name,
p_seq             => member sequence number);

Note that this procedure leaves a gap in the sequence IDs in the specified collection. In addition, calling this procedure causes an error if the named collection does not exist.

You can also delete all members from a collection by when an attribute matches a specific value, for example:

APEX_COLLECTION.DELETE_MEMBERS(
p_collection_name => collection name,
p_attr_number     => number of attribute used to match for the specified
attribute value for deletion,
p_attr_value      => attribute value of the member attribute used to
match for deletion);

Note that the DELETE_MEMBER procedure also leaves a gap in the sequence IDs in the specified collection. This procedure causes an error if:

- The named collection does not exist.

- The specified attribute number is outside the range of 1 to 50, or not valid.

If the supplied attribute value is null, then all members of the named collection will deleted.

Determining Collection Status

The p_generate_md5 parameter determines if the MD5 message digests are computed for each member of a collection. The collection status flag is set to FALSE immediately after you create a collection. If any operations are performed on the collection (such as add, update, truncate, and so on), this flag is set to TRUE.

You can reset this flag manually by calling RESET_COLLECTION_CHANGED, for example:

APEX_COLLECTION.RESET_COLLECTION_CHANGED (
p_collection_name => collection name)

Once this flag has been reset, you can determine if a collection has changed by calling COLLECTION_HAS_CHANGED, for example:

l_changed := APEX_COLLECTION.COLLECTION_HAS_CHANGED(
p_collection_name => collection_name);

When you add a new member to a collection, an MD5 message digest is computed against all 50 attributes and the CLOB attribute if the p_generated_md5 parameter is set to YES. You can access this value from the MD5_ORIGINAL column of the view APEX_COLLECTION. You can access the MD5 message digest for the current value of a specified collection member by using the function GET_MEMBER_MD5. For example:

APEX_COLLECTION.GET_MEMBER_MD5 (
p_collection_name => collection name,
p_seq             => member sequence number );
RETURN VARCHAR2;

Merging Collections

You can merge members of a collection with values passed in a set of arrays. By using the p_init_query argument, you can create a collection from the supplied query, for example:

APEX_COLLECTION.MERGE_MEMBERS
p_collection_name => collection_name

Note that if the collection exists, the following occurs:

- Rows in the collection not in the arrays will be deleted.

- Rows in the collection and in the arrays will be updated.

- Rows in the array and not in the collection will be inserted.

Any attribute value exceeding 4,000 characters will be truncated to 4,000 characters. Table 13-1 describes the available arguments you can use when merging collections.

Table 13-1 Available Arguments for Merging Collections

Argument

Description

p_c001

Array of first attribute values to be merged. Maximum length is 4,000 characters. If the maximum length is greater, it will be truncated to 4,000 characters.

The count of elements in the P_C001 PL/SQL table is used as the total number of items across all PL/SQL tables. For example, if P_C001.count = 2 and P_C002.count = 10, only 2 members will be merged. Note that if P_C001 is null, an application error will be raised.

p_c0xx

Attribute of XX attributes values to be merged. Maximum length is 4,000 characters. If the maximum length is greater, it will be truncated to 4,000 characters.

p_collection_name

Name of the collection.

See Also: "About Collection Naming"

p_null_index

Use this argument to identify rows the merge function should ignore. This argument identifies an row as null. Null rows are automatically removed from the collection.

p_null_value

Use this argument in conjunction with the p_null_index. Identifies the null value. If used this value cannot be null. A typical value for this argument is 0.

p_init_query

Use the query defined by this argument to create a collection if the collection does not exist.

Managing Collections

You can use the following utilities to manage collections.

Topics in this section include:

- Obtaining a Member Count

- Resequencing a Collection

- Verifying Whether a Collection Exists

- Adjusting a Member Sequence ID

- Sorting Collection Members

Obtaining a Member Count

Use COLLECTION_MEMBER_COUNT to return the total count of all members in a collection. Note that this count does not indicate the highest sequence in the collection, for example:

l_count := APEX_COLLECTION.COLLECTION_MEMBER_COUNT (
p_collection_name => collection name );

Resequencing a Collection

Use RESEQUENCE_COLLECTION to resequence a collection to remove any gaps in sequence IDs while maintaining the same element order, for example:

APEX_COLLECTION.RESEQUENCE_COLLECTION (
p_collection_name => collection name )

Verifying Whether a Collection Exists

Use COLLECTION_EXISTS to determine if a collection exists, for example:

l_exists := APEX_COLLECTION.COLLECTION_EXISTS  (
p_collection_name => collection name );

Adjusting a Member Sequence ID

You can adjust the sequence ID of a specific member within a collection by moving the ID up or down. When you adjust a sequence ID, the specified ID is exchanged with another ID. For example, if you were to move the ID 2 up, 2 becomes 3, and 3 would become 2.

Use MOVE_MEMBER_UP to adjust a member sequence ID up by one. Alternately, use MOVE_MEMBER_DOWN to adjust a member sequence ID down by one, for example:

APEX_COLLECTION.MOVE_MEMBER_DOWN(
p_collection_name => collection name,
p_seq             => member sequence number);

Note that while using either of these methods an application error displays:

- If the named collection does not exist for the current user in the current session

- If the member specified by the p_seq sequence ID does not exist

However, an application error will not be returned if the specified member already has the highest or lowest sequence ID in the collection (depending on if you are calling MOVE_MEMBER_UP or MOVE_MEMBER_DOWN).

Sorting Collection Members

Use the SORT_MEMBERS method to reorder members of a collection by the column number. This method sorts the collection by a particular column number and also reassigns the sequence IDs for each member to remove gaps, for example:

APEX_COLLECTION.SORT_MEMBERS(
p_collection_name       => collection name,
p_sort_on_column_number => column number to sort by);

Clearing Collection Session State

Clearing the session state of a collection removes the collection members. A shopping cart is a good example of when you might need to clear collection session state. When a user requests to empty the shopping cart and start again, you need to clear the session state for a collection. You can remove session state of a collection by calling the CREATE_OR_TRUNCATE_COLLECTION method or by using f?p syntax.

Calling the CREATE_OR_TRUNCATE_COLLECTION method deletes the existing collection and then recreates it, for example:

APEX_COLLECTION.CREATE_OR_TRUNCATE_COLLECTION(
p_collection_name       => collection name,

You can also use the sixth f?p syntax argument to clear session state, for example:

f?p=App:Page:Session::NO:1,2,3,collection name

See Also:
"Understanding URL Syntax"

Creating Custom Activity Reports Using APEX_ACTIVITY_LOG

The APEX_ACTIVITY_LOG view records all activity in a workspace, including developer activity and application run-time activity. You can use APEX_ACTIVITY_LOG to view to query all activity for the current workspace. For example, you can use this view to develop monitoring reports within a specific application to provide real-time performance statistics.

Table 13-2 describes the columns in the APEX_ACTIVITY_LOG view.

Table 13-2 Columns in APEX_ACTIVITY_LOG

Column

Type

Description

time_stamp

DATE

Date and time that activity was logged at the end of the page view.

component_type

VARCHAR2(255)

Reserved for future use.

component_name

VARCHAR2(255)

Reserved for future use.

component_attribute

VARCHAR2(4000)

Title of page.

information

VARCHAR2(4000)

Reserved for future use.

elap

NUMBER

Elapsed time of page view in seconds.

num_rows

NUMBER

Number of rows processed on page.

userid

VARCHAR2(255)

User ID performing page view.

ip_address

VARCHAR2(4000)

IP address of client.

user_agent

VARCHAR2(4000)

Web browser user agent of client.

flow_id

NUMBER

Application ID.

step_id

NUMBER

Page number.

session_id

NUMBER

Oracle Application Express session identifier.

sqlerrm

VARCHAR2(4000)

SQL Error message.

sqlerrm_component_type

VARCHAR2(255)

Reserved for future use.

sqlerrm_component_name

VARCHAR2(255)

Reserved for future use.

To conserve space in the activity log, only the first log entry of each unique session will contain the IP address and Web browser user agent.

The following example demonstrates how to create a report that displays the total number of page views and the average page view time in the past 24 hours for application 9529, and grouped by userid:

SELECT COUNT(*), AVG(elap), userid
FROM APEX_ACTIVITY_LOG
WHERE time_stamp > (SYSDATE-1)
AND flow_id = 9529
GROUP BY userid

Keep in mind that logging of activity in an Application Express instance is rotated between two different log tables. Because of this, logging information is only as current as the oldest available entry in the logs. If you wish to persist your application specific log information for all time, you need to either copy the log information into your own application table or implement logging directly in your application.

See Also:
"Name" for information on enabling logging on the Edit Definition page

Running Background PL/SQL

You can use the APEX_PLSQL_JOB package to run PL/SQL code in the background of your application. This is an effective approach for managing long running operations that do not need to complete for a user to continue working with your application.

Topics in this section include:

- Understanding the APEX_PLSQL_JOB Package

- About System Status Updates

- Using a Process to Implement Background PL/SQL

Understanding the APEX_PLSQL_JOB Package

APEX_PLSQL_JOB is a wrapper package around DBMS_JOB functionality offered in the Oracle database. Note that the APEX_PLSQL_JOB package only exposes that functionality which is necessary to run PL/SQL in the background. The following is a description of the APEX_PLSQL_JOB package:

SQL> DESC APEX_PLSQL_JOB
FUNCTION JOBS_ARE_ENABLED RETURNS BOOLEAN
PROCEDURE PURGE_PROCESS
Argument Name                  Type                    In/Out Default?
------------------------------ ----------------------- ------ --------
P_JOB                          NUMBER                  IN
FUNCTION SUBMIT_PROCESS RETURNS NUMBER
Argument Name                  Type                    In/Out Default?
------------------------------ ----------------------- ------ --------
P_SQL                          VARCHAR2                IN
P_WHEN                         VARCHAR2                IN     DEFAULT
P_STATUS                       VARCHAR2                IN     DEFAULT
FUNCTION TIME_ELAPSED RETURNS NUMBER
Argument Name                  Type                    In/Out Default?
------------------------------ ----------------------- ------ --------
P_JOB                          NUMBER                  IN
PROCEDURE UPDATE_JOB_STATUS
Argument Name                  Type                    In/Out Default?
------------------------------ ----------------------- ------ --------
P_JOB                          NUMBER                  IN
P_STATUS                       VARCHAR2                IN
P_DESC

Table 13-1 describes the functions available in the APEX_PLSQL_JOB package.

Table 13-3 APEX_PLSQL_JOB Package: Available Functions

Function or Procedure

Description

SUBMIT_PROCESS

Use this procedure to submit background PL/SQL. This procedure returns a unique job number. Because you can use this job number as a reference point for other procedures and functions in this package, it may be useful to store it in your own schema.

UPDATE_JOB_STATUS

Call this procedure to update the status of the currently running job. This procedure is most effective when called from the submitted PL/SQL.

TIME_ELAPSED

Use this function to determine how much time has elapsed since the job was submitted.

JOBS_ARE_ENABLED

Call this function to determine whether or not the database is currently in a mode that supports submitting jobs to the APEX_PLSQL_JOB package.

PURGE_PROCESS

Call this procedure to clean up submitted jobs. Submitted jobs stay in the APEX_PLSQL_JOBS view until either Oracle Application Express cleans out those records, or you call PURGE_PROCESS to manually remove them.

You can view all jobs submitted to the APEX_PLSQL_JOB package using the APEX_PLSQL_JOBS view. The following is the description of APEX_PLSQL_JOBS view:

SQL> DESCRIBE APEX_PLSQL_JOBS
Name                              Null?    Type
--------------------------------- -------- ----------------------------
ID                                         NUMBER
JOB                                        NUMBER
FLOW_ID                                    NUMBER
OWNER                                      VARCHAR2(30)
ENDUSER                                    VARCHAR2(30)
CREATED                                    DATE
MODIFIED                                   DATE
STATUS                                     VARCHAR2(100)
SYSTEM_STATUS                              VARCHAR2(4000)
SYSTEM_MODIFIED                            DATE
SECURITY_GROUP_ID                          NUMBER

Table 13-4 describes the columns available in APEX_PLSQL_JOBS view.

Table 13-4 APEX_PLSQL_JOBS View Columns

Name

Description

ID

A unique identifier for each row.

JOB

The job number assigned to each submitted PL/SQL job. The APEX_PLSQL_JOB.SUBMIT_PROCESS function returns this value. This is also the value you pass into other procedures and functions in the APEX_PLSQL_JOB package.

FLOW_ID

The application from which this job was submitted.

OWNER

The database schema that owns the application. This identifies what schema will parse this code when DBMS_JOB runs it.

ENDUSER

The end user (that is, who logged into the application) that caused this process to be submitted.

CREATED

The date when the job was submitted.

MODIFIED

The date when the status was modified.

STATUS

The user-defined status for this job. Calling APEX_PLSQL_JOB.UPDATE_JOB_STATUS updates this column.

SYSTEM_STATUS

The system defined status for this job.

SYSTEM_MODIFIED

The date when the system status was modified.

SECURITY_GROUP_ID

The unique ID assigned to your workspace. Developers can only see jobs submitted from their own workspace.

About System Status Updates

Submitted jobs can contain any of the following system status settings:

- SUBMITTED indicates the job has been submitted, but has not yet started. The DBMS_JOB does not guarantee immediate starting of jobs.

- IN PROGRESS indicates that the DBMS_JOB has started the process.

- COMPLETED indicates the job has finished.

- BROKEN (sqlcode) sqlerrm indicates there was a problem in your job that resulted in an error. The SQL code and SQL error message for the error should be included in the system status. Review this information to determine what went wrong.

Using a Process to Implement Background PL/SQL

The following example runs a PL/SQL job in the background for testing and explanation:

001  BEGIN
002    FOR i IN 1 .. 100 LOOP
003      INSERT INTO emp(a,b) VALUES (:APP_JOB,i);
004      IF MOD(i,10) = 0 THEN
005        APEX_PLSQL_JOB.UPDATE_JOB_STATUS(
006          P_JOB     => :APP_JOB,
007          P_STATUS  => i || 'rows inserted');
008      END IF;
009      APEX_UTIL.PAUSE(2);
010    END LOOP;
011  END;

In this example, note that:

- Lines 002 to 010 run a loop that inserts 100 records into the emp table.

- APP_JOB is referenced as a bind variable inside the VALUES clause of the INSERT, and specified as the P_JOB parameter value in the call to UPDATE_JOB_STATUS.

- APP_JOB represents the job number which will be assigned to this process as it is submitted to APEX_PLSQL_JOB. By specifying this reserved item inside your process code, it will be replaced for you at execution time with the actual job number.

- Note that this example calls to UPDATE_JOB_STATUS every ten records, INSIDE the block of code. Normally, Oracle transaction rules dictate updates made inside code blocks will not be seen until the entire transaction is committed. The APEX_PLSQL_JOB.UPDATE_JOB_STATUS procedure, however, has been implemented in such a way that the update will happen regardless of whether or not the job succeeds or fails. This last point is important for two reasons:

1. Even if your status shows "100 rows inserted," it does not mean the entire operation was successful. If an error occurred at the time the block of code tried to commit, the user_status column of APEX_PLSQL_JOBS would not be affected because status updates are committed separately.

2. Updates are performed autonomously. You can view the job status before the job has completed. This gives you the ability to display status text about ongoing operations in the background as they are happening.

Implementing Web Services

Web services enable applications to interact with one another over the Web in a platform-neutral, language independent environment. In a typical Web services scenario, a business application sends a request to a service at a given URL by using the protocol over HTTP. The service receives the request, processes it, and returns a response. You can incorporate calls with external Web services in applications developed in Application Builder.

Web services are based on Simple Object Access Protocol (SOAP). SOAP is a World Wide Web Consortium (W3C) standard protocol for sending and receiving requests and responses across the Internet. SOAP messages can be sent back and forth between a service provider and a service user in SOAP envelopes.

SOAP offers two primary advantages:

- SOAP is based on XML, and therefore easy to use.

- SOAP messages are not blocked by firewalls because this protocol uses simple transport protocols, such as HTTP.

Tip:
If you are running Oracle Application Express with Oracle Database 11g Release 1 (11.1), you must enable network services in order to use Web services. See "Enabling Network Services in Oracle Database 11g"

Topics in this section include:

- Understanding Web Service References

- Working with SSL Enabled Web Services

- Creating a Web Service Reference Based on a WSDL

- Using the Web Service Reference Repository

- Testing a Web Service Reference Created from a WSDL

- Testing a Web Service Reference Created Manually

- Creating an Input Form and Report on a Web Service

- Creating a Form on a Web Service

- Invoking a Web Service as a Process

- Editing a Web Service Process

- Viewing a Web Service Reference History

Note:
The SOAP 1.1 specification is a W3C note. (The W3C XML Protocol Working Group has been formed to create a standard that will supersede SOAP.)
For information about Simple Object Access Protocol (SOAP) 1.1 see:

http://www.w3.org/TR/SOAP/

Understanding Web Service References

To utilize Web services in Oracle Application Express, you create a Web service reference using a wizard. Web service references can be based either on a Web Services Description Language (WSDL) document or created manually by supplying information about the service.

When you create a Web service reference based on a WSDL, the wizard analyzes the WSDL and collects all the necessary information to create a valid SOAP message, including:

- The URL used to post the SOAP request over HTTP(S)

- A Universal Resource Identifier (URI) identifying the SOAP HTTP request

- Operations of the Web Service

- Input parameters for each operation

- Output parameters for each operation

When you create a Web service reference manually, you supply the necessary information to create a valid SOAP request, including:

- The URL used to post the SOAP request over HTTP(S)

- A Universal Resource Identifier (URI) identifying the SOAP HTTP request

- The SOAP envelope for the request, including any item substitutions

- Optionally the name of a collection to store the response from the Web service

Accessing the Web Service References Page

You manage Web service references on the Web Service References page.

To access the Web Service References page:

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

2. Select an application.
Application Builder appears.

3. Click Shared Components.
The Shared Components page appears.

4. Under Logic, click Web Service References.
The Web Service References page appears.

Specifying an Application Proxy Server Address

If your environment requires a proxy server to access the Internet, you must specify a proxy server address on the Application Attributes page before you can create a Web service reference.

To specify a proxy address for an application:

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

2. Select an application.
Application home page appears.

3. Click Shared Components.

4. Under Application, click Definition.

5. Under Name, enter the proxy server in the Proxy Server field.

6. Click Apply Changes.

Working with SSL Enabled Web Services

Secure Sockets Layer (SSL) is an industry standard protocol that uses RSA public key cryptography in conjunction with symmetric key cryptography to provide authentication, encryption, and data integrity.

If the Web service that you need to interact with is SSL-enabled (that is, https displays in the URL to the Web service), you must create a wallet. A wallet is a password-protected container that stores authentication and signing credentials (including private keys, certificates, and trusted certificates) needed by SSL.

See Also:
"Configuring Wallet Information"

Creating a Web Service Reference Based on a WSDL

When you create a Web service reference based on a WSDL, you need to decide how to locate the WSDL. You can locate a WSDL in two ways:

- By searching a Universal Description, Discovery and Integration (UDDI) registry

- by entering the URL to the WSDL document

A UDDI registry is a directory where businesses register their Web services.

Topics in this section include:

- Creating a Web Service Reference by Searching a UDDI Registry

- Creating a Web Service Reference by Specifying a WSDL Document

- Creating a Web Service Manually

Creating a Web Service Reference by Searching a UDDI Registry

To create a new Web service by searching a UDDI registry:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".

2. Click Create.

3. When prompted to search a UDDI registry to find a WSDL, click Yes.

4. For UDDI Location you can either:

- Enter a URL endpoint to a UDDI registry.

- Click the List icon and select a UDDI registry.

5. For Search, specify the following:

a. Search Type - Specify whether to search for a business name or a service name. You cannot search for both.

b. Name - Enter the business name or service name to search for. Use the percent (%) symbol as a wildcard character.

c. Optionally indicate if the search should be case-sensitive or an exact match.

d. Click Search.

e. When the search results appear, make a selection and click Next.

A summary page appears describing the selected Web service.

6. Review your selection and click Next to continue.
The URL to the WSDL document displays in the WSDL Location field.

7. Click Finish.

The Web service reference is added to the Web Service References Repository.

Creating a Web Service Reference by Specifying a WSDL Document

To create a new Web service by specifying a URL to a specific WSDL document:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".

2. Click Create.

3. When prompted to search a UDDI registry to find a WSDL, click No.

4. In WSDL Location, enter the URL to the WSDL document.

5. Click Finish.

The Web service reference is added to the Web Service References Repository.

Creating a Web Service Manually

To create a new Web service reference manually:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".

2. Click Create.

3. When prompted to search a UDDI registry to find a WSDL, click No.

4. From the Tasks list, click Create Web Service Reference Manually.
The Create/Edit Web Service page appears.

5. In Name, enter a name to identify the reference.

6. Under Service Description:

a. URL - Enter the URL endpoint of the Web service.

b. Action - Enter the action of the Web service (optional).

c. Proxy - Enter a proxy if you wish to override the application proxy for this service.

d. Basic Authentication - Choose whether the Web service requires authentication. Select Yes or No.

7. For SOAP Envelop, enter the SOAP envelope for this request.

8. For Store Response in Collection, enter the name of a collection to store the response (optional).

9. Click Create.

The Web service reference is added to the Web Service References Repository.

Using the Web Service Reference Repository

Web service references are stored in the Web Service Reference Repository.

To access the Web Service References Repository:

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

2. Select an application.
Application Builder appears.

3. Click Shared Components.
The Shared Components page appears.

4. Under Logic, click Web Service References.
The Web Service Reference page appears.

Use the Navigation bar at the top of the page to search for Web service references or change the page display. Available options include:

- Web Service Reference - Enter a case insensitive query for the reference name and click Go. To view all Web service references, leave the field blank and click Go.

- View - Select a display mode and click Go. Available options include:

- Icons (the default) displays each Web service reference as a large icon. To edit a Web service reference, click the appropriate icon.

- Details displays each Web service reference as a line in a report.

5. Select Details from the View list and click Go.

6. In Details view you can:

- Edit a reference by clicking the reference name.

- Test a reference by clicking the Run icon.

- View details about a reference by clicking the View icon. Note that this option is not available for manually created Web service references.

Testing a Web Service Reference Created from a WSDL

After you have created a Web service reference, you can test it on the Test Web Service Reference page.

To test a Web service reference:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".

2. From View, select Details.

3. Click the Run icon adjacent to the Web Service reference name.
The Test Web Service Reference page appears. The Web service name and URL endpoint display at the top of the page.

4. From Operation, select an operation (that is, the method to be executed).

5. Under Input Parameters, enter the appropriate value.

6. Click Test.
The message request and response appear at the bottom of the page.

Testing a Web Service Reference Created Manually

After you have created a Web service reference, you can test it on the Test Web Service Reference page.

To test a Web service reference:

1. Navigate to the Web Service References page. See "Accessing the Web Service References Page".

2. From View, select Details.

3. Click the Run icon adjacent to the Web Service reference name.
The Test Web Service Reference page appears. The Web service name and URL endpoint display at the top of the page.

4. If required, enter the username and password under Basic Authentication.

5. In SOAP Envelope text area, optionally edit the SOAP request envelope.

6. Click Test.
The message request and response appear at the bottom of the page.

Creating an Input Form and Report on a Web Service

The Create Form and Report on Web Service Wizard creates an input form, a submit button, and a report for displaying results. You can execute this wizard directly after creating the Web service reference from a WSDL, or by adding a new page.

Use this wizard when you expect a nonscalar result from the Web service. The Amazon Web service is a good example. This Web service returns many results based on the search criteria entered in an input form.

Creating a Form and Report After Creating a Reference

To create a form and report after creating a Web Service Reference:

1. Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL".

2. After the Web service reference has been added, select Create Form and Report on Web Service.

3. For Choose Service and Operation:

a. Web Service Reference - Select the Web service reference.

b. Operation - Select the method to be executed.

4. For Page and Region Attributes, review the displayed attributes. If the page you specify does not exist, the wizard creates the page for you.

5. For Input Items:

a. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.

b. If necessary, edit the item label.

6. If applicable, specify the Item Names and Item Labels for basic authentication. Note that this step only appears if basic authentication was specified for this Web service reference when it was created.

7. For Window Service Results:

a. Temporary Result Set Name - Enter a name for the collection that stores the Web service result.

b. Result Tree to Report On - Select the portion of the resulting XML document that contains the information you want to include in the report.

8. For Result Parameters to Display, select the parameters to be included in the report.

9. Click Finish.

Creating a Form and Report by Adding a New Page

If you have an existing Web service reference, you can create an input form and report by adding a new page.

To create a form and report by adding a new page:

1. Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL".

2. Create a new page. See "Managing Pages in an Application".
In the Create Page Wizard:

a. Select Form.

b. Select Form and Report on Web Service.

3. For Choose Service and Operation:

a. Web Service Reference - Select the Web service reference.

b. Operation - Select the method to be executed.

4. For Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.

5. For Input Items:

a. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.

b. If necessary, edit the item label.

6. If applicable, specify the Item Names and Item Labels for basic authentication. Note that this step only appears if basic authentication was specified for this Web service reference when it was created.

7. Follow the on-screen instructions.

8. Click Finish.

Creating a Form on a Web Service

The Create Form on Web Service Wizard creates a form and a submit button. You can execute this wizard after creating the Web service reference from a WSDL, or from the Page Definition.

Use this wizard when you expect a scalar result from the Web service. A Web service that looks up a stock price is a good example because the input is a stock symbol and the output is the scalar value price.

Creating a Form After Creating a Reference

To create a form after creating a Web Service Reference:

1. Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL".

2. After the Web service references has been added, select Create Form on Web Service.

3. For Choose Service and Operation:

a. Web Service Reference - Select the Web service reference.

b. Operation - Select the method to be executed.

4. For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.

5. For Items for Input Parameters:

a. Identify which items to add. To include an item, select Yes in the Create column. Otherwise, select No.

b. If necessary, edit the item label.

6. For Items for Output Parameters:

a. Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.

b. If necessary, edit the item label.

7. If applicable, specify the Item Names and Item Labels for basic authentication.
Note that this step only appears if basic authentication was specified for this Web service reference when it was created.

8. Click Finish.

Creating a Form by Adding a New Page

If you have an existing Web service reference created from a WSDL, you can create form by adding a new page.

To create a form by adding a new page:

1. Create the Web service reference. See "Creating a Web Service Reference Based on a WSDL".

2. Create a new page. See "Managing Pages in an Application".
In the Create Page Wizard:

a. Select Form.

b. Select Form on Web Service.

3. For Web Service Reference and Operation, select the Web service reference and operation (that is, the method to be executed).

4. For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.

5. For Items for Input Parameters:

a. Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.

b. If applicable, specify the Item Names and Item Labels for basic authentication.
Note that this step only appears if basic authentication was specified for this Web service reference when it was created.

6. For Items for Output Parameters:

a. Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.

b. If necessary, edit the item label.

7. Click Finish.

Invoking a Web Service as a Process

You can also implement a Web service as a process on the page. Running the process submits the request to the service provider. You can then display the request results in report.

To invoke a Web service as a process:

1. Create a new page. See "Managing Pages in an Application".
In the Create Page Wizard:

a. Select Blank Page.

b. When prompted to use tabs, select No.

2. Navigate to the Page Definition. See "Accessing a Page Definition".

3. Under Page Rendering, Processes, click the Create icon.
The Create Page Processes Wizard appears.

4. From the process category, select Web Services.

5. Specify a process name, sequence, and processing point.

6. Select the Web service reference.
If the Web reference was created from a WSDL, perform the following additional steps.

7. Select the Web service reference and operation (that is, the method to be executed).

8. Define the process. You can store the results in a collection or in items on the page by selecting options under Web Service Output Parameters.

a. To store the results in a collection:

- For Store Result in, select Collection.

- Enter a name for the collection in the value field.

b. To store the results in items on the page:

- For Store Result in, select Items.

- Enter the appropriate items value in the fields provided.

9. Click Create Process.

Displaying Web Service Results in a Report

To create a report in which to display Web Service request results:

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

2. Under Regions, click the Create icon.
The Create Region Wizard appears.

3. For the region type, select Report.

4. For the report implementation, select Report on collection containing Web service result.On Identify Region Attributes, enter a region title and optionally edit the region attributes.

5. Choose whether the Web reference was created manually or from a WSDL.

6. If the Web service reference was created from a WSDL:

a. For Web Service Reference and Operation, select a Web service reference and an operation (that is, the method to be executed).

b. For Result Tree to Report On, select the portion of the resulting XML document that contains the information you want to include in the report.

c. For Result Parameters:

- In Temporary Result Set Name, enter a name for the collection that stores the Web service result.

- Select and deselect the appropriate parameters.

7. If the Web service reference was created manually:

a. Select the Web service reference.

b. Choose the SOAP style.

c. Choose the message format.

d. Enter the XPath expression to the node to report on.

e. Enter the namespace for the SOAP response envelope and click Next.

f. Enter the name of the collection where the response message is stored.

g. Enter the names of the parameters that you wish to be included in the report.

8. Click Create SQL Report.

Editing a Web Service Process

After you create a process of type Web service on a Web service reference created from a WSDL, you can map input parameters to a static value (for example to pass a key) by editing the Web service process.

To edit a Web service process:

1. Create a Web service process. See "Invoking a Web Service as a Process".

2. Navigate to the Page Definition containing the Web service process.

3. Select the process name.
The Edit Page Process page appears.

4. To map an input parameter to a static value:

a. Scroll down to Web Service Input Parameters.

b. Enter a value in the Value field, adjacent to the appropriate parameter name.

5. Click Apply Changes.

Viewing a Web Service Reference History

The Web Services History displays changes to Web service references for the current application by application ID, Web service references name, developer, and date.

To view a history of Web service reference changes:

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

2. Select an application.
Application Builder appears.

3. Click Shared Components.
The Shared Components page appears.

4. Under Logic, click Web Service References.

5. Click History.

Note:
The History button only appears on the Web Service Reference page after you have created a Web service reference.

14 Managing Application Globalization

This section describes how to translate an application built in Application Builder.

This section contains the following topics:

- About Translating an Application and Globalization Support

- Specifying the Primary Language for an Application

- Understanding the Translation Process

- Translating Messages

- Translating Data That Supports List of Values

- About Supported Globalization Codes

See Also:
"Viewing Installed Translations"

About Translating an Application and Globalization Support

You can develop applications in Application Builder that can run concurrently in different languages. A single Oracle database instance and Oracle Application Express can support multiple database sessions customized to support different languages.

In general, translating an application built in Application Builder involves the following steps:

- Map the primary and target application IDs

- Seed and export the text to a file for translation

- Translate the text in the file

- Apply the translated file

- Publish the translated file

See Also:
"Understanding the Translation Process"

Topics in this section include:

- About Language Identification

- Rules for Translating Applications Built in Application Builder

- How Translated Applications Are Rendered

- About Translatable Components

About Language Identification

After you create an application, you specify a language preference on the Edit Globalization Attributes page. Then you select a primary application language and determine how the Application Express engine determines the application language. You can specify to have the application language based on the user's browser language preference, an application preference, or an item preference.

See Also:
"Specifying the Primary Language for an Application"

Rules for Translating Applications Built in Application Builder

Use the following rules to determine which translated version to use:

- Look for an exact match between the user language preference and the language code of the translated application.

- Look for a truncated match. That is, see if the language and locale exist. For example, if the user language preference is en-us and the translated version of en-us does not exist, look for a translated application that has the language code en.

- Use the primary application language.

For example, suppose you create an application with the primary language of German, de, and you create a translated version of the application with a language code of en-us. Users accessing this application with a browser language of en-us execute the English en-us version of the application. Users accessing the application with a browser language of en-gb view the application in the application's primary language, that is, in German. For this example, you should create the translated English version using language code en to encompass all variations of en.

How Translated Applications Are Rendered

After Oracle Application Express determines the language for an application, the Application Express engine alters the database language for a specific page request. It then looks for a translated application in the appropriate language. If the Application Express engine finds that language, it renders the application using that definition. Otherwise, it renders the application in the base (or primary) application language.

Note that the text that displays within an application is not translated on the fly. Oracle Application Express dynamically collects page attributes from either a base language application definition or an alternative application definition.

See Also:
"About Dynamic Translation Text Strings" and "Translating Data That Supports List of Values"

About Translatable Components

When you build an application in Application Builder, you define a large number of declarative attributes such as field labels, region headings, page header text, and so on. Using the steps described in this section, you can make all the application definition attributes within your application translatable.

About Shortcuts that Support Translatable Messages

Application Builder includes two shortcut types that enable you to reference translatable messages:

- Message. Use this shortcut to reference a translatable message at run time. Note that the name of the shortcut must match the corresponding message name. At run time, the name of the shortcut expands to the text of the translatable message for the current language.

- Message with JavaScript Escaped Single Quotes. Use this shortcut to reference a shortcut inside of a JavaScript literal string and reference a translatable message at run time. This shortcut defines a text string. When the shortcut is referenced, it escapes the single quotation marks required for JavaScript.

See Also:
"Using Shortcuts"

About Messages

If your application includes PL/SQL regions or PL/SQL processes, you may need to translate any generated HTML or text. You may also need to translate messages used in reports if your application uses a language that is not one of the ten languages into which Oracle Application Express is translated.

See Also:
"Translating Messages"

About Dynamic Translation Text Strings

Dynamic translations are used for database data that needs to be translated at run time. For example, you might use a dynamic translation to translate a list of values based on a database query. A dynamic translation consists of a translate-from language string, a language code, and a translate-to string. You can also use the APEX_LANG.LANG API to retrieve dynamic translations programmatically.

See Also:
"Translating Data That Supports List of Values"

About Translating Region Titles

By default, page region titles are included in the generated translation file. However, you can mark a region title as not translatable.

To mark a region title as not translatable:

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

2. On the Page Definition, select the region title.
The Edit Region page appears.

3. Select the exclude title from translation check box.

About Translating Templates

By default, templates are not translatable, and therefore are not included in the generated translation file. Generally, templates do not and should not contain translatable text. However, if you need to mark a template as translatable, select the Translatable check box on the Edit Page Template page.

To identify a template as translatable:

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

2. Select an application.

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

4. Under User Interface, select Templates.
The Templates page appears.

5. Locate the template you want to edit and select the template name.

6. Under Name, select Translatable.

You can include translatable text at the application-level by defining the translatable text using static substitution strings. Because application-level attributes are translated, any text defined as a static substitution string will be included in the generated translation file.

See Also:

- "Editing Templates"

- "Substitutions"

Specifying the Primary Language for an Application

Globalization attributes specify how the Application Express engine determines the primary language of an application.

To edit globalization attributes:

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

2. Select an application.

3. Click Shared Components.

4. Under Globalization, click Edit Attributes.

5. From Application Primary Language, select the language in which the application is being developed.

6. From Application Language Derived From, specify how the Application Express engine determines (or derives) the application language. Available options are described in Table 14-1.

Table 14-1 Application Language Derived From Options

Option

Description

No NLS (Application not translated)

Select this option if the application will not be translated.

Use Application Primary Language

Determines the application's primary language based on the Application Primary Language attribute. (See step 5.)

Browser (use browser language preference)

Determines the application's primary language based on the user's browser language preference.

Application Preference (use FSP_LANGUAGE_PREFERENCE)

Determines the application's primary language based on a value defined using the APEX_UTIL.SET_PREFERENCE API. Select this option to maintain the selected language preference across multiple logins.

See Also: "SET_PREFERENCE Procedure"

Item Preference (use item containing preference)

Determines the application's primary language based on an application-level item called FSP_LANGUAGE_PREFERENCE. Using this option requires Oracle Application Express to determine the appropriate language preference every time the user logs in.

See Also:
"Configuring the Application Definition", "Configuring Globalization Attributes", and "About Supported Globalization Codes"

Using Format Masks for Items

The Application Express engine applies globalization settings for each rendered page. This default behavior can impact the display of certain items such as numbers and dates.

For example, suppose your application determines the application language based on the user's browser language preference. If the Application Express engine determines the users's browser language preference is French, it displays dates and numbers in a format that conforms to French standards. You can override this default behavior and explicitly control how items display by applying a format mask. You apply a format mask by making a selection from the Display As list:

- When you create the item

- After you create the item by editing the item attributes

The following procedure describes how to edit item attributes for items having the source type of Database Column.

To edit item attributes:

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

2. Select an application.

3. Select a page.
The Page Definition appears.

4. Under Items, select the item name.
The Edit Page Item page appears.

5. Under Name, make a selection from the Display As list.

6. Under source, select or enter a format mask.

See Also:
"Items" for information about item attributes.

Translating Applications for Multibyte Languages

If your application needs to run in several languages simultaneously (such as Chinese and Japanese), consider configuring your database with a character set to support all of the languages. The same character set has to be configured in the corresponding database access descriptor (DAD) in mod_plsql. UTF8 and AL32UTF8 are the character sets you can use to support almost all languages around the world.

Understanding the Translation Process

To translate an application developed in Application Builder, you must map the primary and target language, seed and export text to a translation file, translate the text, apply the translation file, and publish the translated application.

Topics in this section include:

- Step 1: Map the Target Language

- Step 2: Seed and Export Text to a Translation File

- Step 3: Translate the XLIFF File

- Step 4: Upload and Apply a Translated XLIFF Document and Publish the Application

- Manually Editing a Translation

See Also:
"Translating Messages" and "Translating Data That Supports List of Values"

Step 1: Map the Target Language

The first step in translating an application is to map the primary and target application language. The primary application is the application to be translated. The target application is the resulting translated application.

To map the primary and target application language:

1. Navigate to the Translate Application page:

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

b. Select an application.

c. Click Shared Components.

d. Under Globalization, click Translate Application.
The Translate Application page appears.

2. Click Map your primary language application to a translated application.
The Application Mappings page appears.

3. Click Create.

4. On the Translation Application Mapping page:

- Translation Application - Enter a numeric application ID to identify the target application. The translated application ID must be an integer and cannot end in zero.

- Translation Application Language Code - Select the language into which you are translating.

- Image Directory - Enter the directory where the images currently reside.

This attribute determines the virtual path for translated images. For example, if your primary language application had an image prefix of /i/, you could define additional virtual directories for other languages, such as /i/de/ for German or /i/es/ for Spanish.

Note that this language specific image directory is typically not needed for most translated applications.

5. Click Create.

Step 2: Seed and Export Text to a Translation File

The second step is to seed the translation table and then export the translation text to a translation file.

Topics in this section include:

- Seeding Translatable Text

- Exporting Text to a Translation File

Seeding Translatable Text

Seeding the translation copies all translatable text into the Translation Text repository. After you specify the language and seed the Translation Text, you can then generate and export an XLIFF file for translation.

The seeding process keeps your primary language application synchronized with the Translation Text repository. You should run the seed process any time your primary language application changes.

To seed translatable text:

1. Navigate to the Translate Application page:

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

b. Select an application.

c. Click Shared Components.

d. Under Globalization, click Translate Application.
The Translate Application page appears.

2. On the Translate Application page, select Seed and export the translation text of your application into a translation file.

3. From Language Mapping, select the appropriate primary and target application ID map.

4. Click Seed Translatable Text.
The XLIFF Export page appears.

Note:
XML Localization Interchange File Format (XLIFF) is an XML-based format for exchanging localization data. For information about the XLIFF or to view the XLIFF specification, see:

http://www.xliff.org

Exporting Text to a Translation File

After you have seeded translatable text, a status box displays at the top of the XLIFF Export page indicating the total number of attributes that may require translation, including the number of:

- Existing updated attributes that may require translation

- New attributes that may require translation

- Purged attributes that no longer require translation

You can use this information to determine if you need to export translatable text for an entire application or just a specific page.

The XLIFF Export page is divided into two sections. Use the upper section of the page to export translatable text for an entire application (that is, all pages, lists of values, messages, and so on). Use the lower section to export translatable text for a specific page.

Exporting Translatable Text for an Entire Application

To export translatable text for an entire application:

1. Seed the translatable text. See "Seeding Translatable Text".

2. Under Step 2, Export XLIFF:

a. From Application, select the appropriate primary and target application ID map.

b. Specify whether or not to include XLIFF target elements.

c. Under Export, specify what translation text is included in your XLIFF file.

d. Click Export XLIFF for Application.

3. Follow the on-screen instructions.

Exporting Translatable Text for a Specific Page

To export translatable text for a specific page:

1. Seed the translatable text as described in "Seeding Translatable Text".

2. Under Export XLIFF for specific Page:

a. From Application, select the appropriate primary and target application ID map.

b. Specify whether or not to include XLIFF target elements.

c. Under Export, specify what translation text is included in your XLIFF file.

d. Click Export XLIFF for Page.

3. Follow the on-screen instructions.

About Including XLIFF Target Elements

When Oracle Application Express generates an XLIFF document, each document contains multiple translation units. Each translation unit consists of a source element and a target element. The XLIFF document can be generated with both the source and target elements for each translation unit. You have the option of generating a file containing only source elements. The updated translations will be applied from the target elements of the translation units.

About Export

Use the options under Export to specify what translation text is included in your XLIFF file. Select All translatable elements to include all translation text for an application. In contrast, select Only those elements requiring translation to include only new elements that have not yet been translated. Only those elements requiring translation produces an XLIFF file containing new or modified translation units. Also, if translation units were intentionally not previously translated (that is, the source of the translation element equals the target of the translation element), those translation units will also be included in the file

Step 3: Translate the XLIFF File

After you export a translatable file to XLIFF format, you can translate it into the appropriate languages. Because XLIFF is an open standard XML file for exchanging translations, most translation vendors should support it. Oracle Application Express only supports XLIFF files encoded in UTF-8 character sets. In other words, it exports XLIFF files for translation in UTF-8 and assumes that the translated XLIFF files will be in the same character set.

Translation is a time-consuming task. Oracle Application Express supports incremental translation so that application development can be done in parallel with the translation. An XLIFF file can be translated and uploaded to Oracle Application Express even when only part of the XLIFF file is translated. For strings that have no translation in the corresponding translated application, Oracle Application Express uses the corresponding ones in the primary language.

See Also:
For more information about the XLIFF, or to view the XLIFF specification, see:

http://www.xliff.org

Step 4: Upload and Apply a Translated XLIFF Document and Publish the Application

After your XLIFF document has been translated, the next step is to upload and then apply it.

Topics in this section include:

- Uploading a Translated XLIFF Document

- Applying an Uploaded XLIFF Document and Publishing an Application

- Deleting an Uploaded XLIFF Document

Uploading a Translated XLIFF Document

To upload a translated XLIFF document:

1. Navigate to the Translate Application page:

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

b. Select an application.

c. Click Shared Components.

d. Under Globalization, click Translate Application.
The Translate Application page appears.

2. Click Apply your translation file and publish.

3. Click Upload XLIFF.

4. On the XLIFF Upload page:

a. Specify a title.

b. Enter a description.

c. Click Browse and locate the file to be uploaded.

d. Click Upload XLIFF File.

The uploaded document appears in the XLIFF Files repository.

Applying an Uploaded XLIFF Document and Publishing an Application

After you upload an XLIFF document, the next step is to apply the XLIFF document and then publish the translated application. When you apply an XLIFF document, the Application Express engine parses the file and then updates the translation tables with the new translatable text.

Publishing your application creates a copy of the base language application, substituting the translated text strings from your translations table. This published application can then be used to render your application in alternate languages.

Remember that in order to run an application in an alternative language, you need to run it with globalization settings that will cause an alternative language version to display. For example, if the language is derived from the browser language, you must set the browser language to the same language as the translated application.

See Also:
"Specifying the Primary Language for an Application"

To apply a translated XLIFF document and publish the application:

1. Navigate to the Translate Application page:

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

b. Select an application.

c. Click Shared Components.

d. Under Globalization, click Translate Application.
The Translate Application page appears.

2. Click Apply your translation file and publish.

3. In the XLIFF Files repository, click the View icon next to the document you want to publish.

4. From Apply to, select the appropriate primary and target application ID map.

5. Click Apply XLIFF Translation File.

6. Click Publish Application.

Deleting an Uploaded XLIFF Document

To delete an uploaded XLIFF document:

1. Navigate to the Translate Application page:

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

b. Select an application.

c. Click Shared Components.

d. Under Globalization, click Translate Application.
The Translate Application page appears.

2. On the Translate Application page, select Apply your translation file and publish.

3. In the XLIFF Files repository, select the check box to the left of the document title.

4. Click Delete Checked.

You should verify the existence of the translated application after it is published. Translated applications do not display in the Available Applications list on the Application Builder home page. Instead, use the Application Navigate list on the left side of the page.

Note that in order for a translated application to appear in Application Builder, you need to make sure that you have correctly configured the application Globalization attributes.

See Also:
"Specifying the Primary Language for an Application"

Manually Editing a Translation

Once you have mapped the target language and seeded the translatable text, you manually edit a translation.

To manually edit a translation:

1. Map the target language. See "Step 1: Map the Target Language".

2. Seed the translatable text. See "Seeding Translatable Text".

3. Navigate to the Translatable Text page:

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

b. Select an application.

c. Click Shared Components.

d. Under Globalization, click Translate Application.

4. From the Translation Utilities list, click Manually Edit Translations.
The Translatable Text page appears. Use the Navigation bar at the top of the page to change the report display. Available options include:

- Language Mappings - Select a language mapping and click Go.

- Page - Enter a page number and click Go.

- Translate - Enter a case insensitive query and click Go.

- Display - Select the number of rows to display and click Go.

5. To edit translatable text, click the Edit icon.
The Translatable Text field appears.

6. Edit the appropriate text and click Apply Changes.

Translating Messages

You may need to translate messages if your application:

- Includes PL/SQL regions or PL/SQL processes or calls PL/SQL package, procedures, or function. If it does, you may need to translate the generated HTML.

- Uses a language that is not one of the ten languages into which Oracle Application Express is translated. If it does, you may need to translate messages used in reports.

Topics in this section include:

- Translating Messages Used in PL/SQL Procedures

- Translating Messages Used Internally by Application Express

Translating Messages Used in PL/SQL Procedures

If your application includes PL/SQL regions or PL/SQL processes or calls PL/SQL package, procedures, or functions, you may need to translate generated HTML. First, you define each message on the Translatable Messages page. Second, you use the APEX_LANG.MESSAGE API to translate the messages from PL/SQL stored procedures, functions, triggers, or packaged procedures and functions.

You create translatable messages on the Translate Messages page.

To define a new translation message:

1. Navigate to the Translate Application page:

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

b. Select an application.

c. Click Shared Components.

d. Under Globalization, click Text Messages.

2. On the Translate Messages page, click Create.

3. On Identify Text Message, specify the following:

a. Name - Enter a name to identify the message.

b. Language - Select the language for which the message would be used.

c. Text - Enter the text to be returned when the text message is called.
For example, you could define the message GREETING_MSG in English as:

Good morning %0

Or, you could define the message GREETING_MSG in German as:

Guten Tag %0

4. Click Create.

About the APEX_LANG.MESSAGE API

Use the APEX_LANG.MESSAGE API to translate text strings (or messages) generated from PL/SQL stored procedures, functions, triggers, packaged procedures, and functions.

Syntax

APEX_LANG.MESSAGE (
p_name    IN    VARCHAR2 DEFAULT NULL,
p0        IN    VARCHAR2 DEFAULT NULL,
p1        IN    VARCHAR2 DEFAULT NULL,
p2        IN    VARCHAR2 DEFAULT NULL,
...
p9        IN    VARCHAR2 DEFAULT NULL,
p_lang    IN    VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 14-2 describes the parameters available in the APEX_LANG.MESSAGE API.

Table 14-2 APEX_LANG.MESSAGE Parameters

Parameter

Description

p_name

Name of the message as defined in Oracle Application Express.

p0

...

p9

Dynamic substitution value: p0 corresponds to 0% in the message; p1 corresponds to 1% in the message; p2 corresponds to 2% in the message, and so on.

p_lang

Language code for the message to be retrieved. If not specified, Oracle Application Express uses the current language for the user as defined in the Application Language Derived From attribute.

See Also: "Specifying the Primary Language for an Application"

Example

The following example assumes you have defined a message called GREETING_MSG in your application in English as Good morning%0 and in German as Guten Tag%1. The following example demonstrates how you could invoke this message from PL/SQL:

BEGIN
--
-- Print the greeting
--
APEX_LANG.MESSAGE('GREETING_MSG', V('APP_USER'));
END;

How the p_lang attribute is defined depends on how the Application Express engine derives the Application Primary Language. For example, if you are running the application in German and the previous call is made to the APEX_LANG.MESSAGE API, the Application Express engine first looks for a message called GREETING_MSG with a LANG_CODE of de. If it does not find anything, then it will revert to the Application Primary Language attribute. If it still does not find anything, the Application Express engine looks for a message by this name with a language code of en-us.

See Also:
"Specifying the Primary Language for an Application" for information about the Application Primary Language attribute

Translating Messages Used Internally by Application Express

Oracle Application Express is translated into German, Spanish, French, Italian, Japanese, Korean, Brazilian Portuguese, Simplified Chinese, and Traditional Chinese. If your application uses a language that is not among the ten languages into which Oracle Application Express is translated, you need to translate messages displayed by the Application Express reporting engine.

For example, if you develop a Russian application and want to include report messages, such as pagination, in Russian, you need to translate the strings used in messages displayed in reports.

To translate messages:

1. Navigate to the Translate Application page:

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

b. Select an application.

c. Click Shared Components.

d. Under Globalization, click Text Messages.

2. On the Translate Messages page, click Create.

3. On Identify Text Message, specify the following:

a. Name - Enter the name of each message that needs to be translated. See Table 14-3.

b. Language - Select the language for which the message would be used.

c. Text - Enter the text to be returned when the text message is called. If the English text message contains positional substitution values (for example, %0, %1), ensure that your defined message also contains the same named and number of positional substitution values.

4. Click Create.

Table 14-3 lists the internal messages that require translation.

Table 14-3 Internal Messages Requiring Translation

Message Name

English Text

FLOW.SINGLE_VALIDATION_ERROR

1 error has occurred

FLOW.VALIDATION_ERROR

%0 errors have occurred

OUT_OF_RANGE

Invalid set of rows requested, the source data of the report has been modified

PAGINATION.NEXT

Next

PAGINATION.NEXT_SET

Next Set

PAGINATION.PREVIOUS

Previous

PAGINATION.PREVIOUS_SET

Previous Set

REPORT_TOTAL

report total

RESET

reset pagination

SINCE_DAYS_AGO

%0 days ago

SINCE_HOURS_AGO

%0 hours ago

SINCE_MINUTES_AGO

%0 minutes ago

SINCE_MONTHS_AGO

%0 months ago

SINCE_SECONDS_AGO

%0 seconds ago

SINCE_WEEKS_AGO

%0 weeks ago

SINCE_YEARS_AGO

%0 years ago

TOTAL

Total

WWV_FLOW_UTILITIES.CAL

Calendar

WWV_FLOW_UTILITIES.CLOSE

Close

WWV_FLOW_UTILITIES.OK

Ok

WWV_RENDER_REPORT3.FOUND_BUT_NOT_DISPLAYED

Minimum row requested: %0, rows found but not displayed: %1

WWV_RENDER_REPORT3.SORT_BY_THIS_COLUMN

Sort by this column

WWV_RENDER_REPORT3.X_Y_OF_MORE_THAN_Z

row(s) %0 - %1 of more than %2

WWV_RENDER_REPORT3.X_Y_OF_Z

row(s)%0 - %1 of %2

WWV_RENDER_REPORT3.X_Y_OF_Z_2

%0 - %1 of %2

Translating Data That Supports List of Values

You create a dynamic translation to translate dynamic pieces of data. For example, you might use a dynamic translation on a list of values based on a database query.

Dynamic translations differ from messages in that you query a specific string rather than a message name. You define dynamic translations on the Dynamic Translations page. You then use the APEX_LANG.LANG API to return the dynamic translation string identified by the p_primary_text_string parameter.

Defining a Dynamic Translation

You define dynamic translations on the Dynamic Translations page. A dynamic translation consists of a translate-from language string, a language code, and a translate-to string.

To define a dynamic translation:

1. Navigate to the Translate Application page:

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

b. Select an application.

c. Click Shared Components.

d. Under Globalization, click Translate Application.

2. On the Translate Application page, select Optionally identify any data that needs to be dynamically translated to support SQL based lists of values.

3. On the Dynamic Translations page, click Create and specify the following:

a. Language - Select a target language.

b. Translate From Text - Enter the source text to be translated.

c. Translate To - Enter the translated text.

4. Click Create.

APEX_LANG.LANG API

Syntax

APEX_LANG.LANG (
p_primary_text_string    IN    VARCHAR2 DEFAULT NULL,
p0                       IN    VARCHAR2 DEFAULT NULL,
p1                       IN    VARCHAR2 DEFAULT NULL,
p2                       IN    VARCHAR2 DEFAULT NULL,
...
p9                       IN    VARCHAR2 DEFAULT NULL,
p_primary_language       IN    VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 14-4 describes the parameters available in the APEX_LANG.LANG API.

Table 14-4 APEX_LANG.LANG Parameters

Parameter

Description

p_primary_string

Text string of the primary language. This will be the value of the Translate From Text in the dynamic translation.

p0

...

p9

Dynamic substitution value: p0 corresponds to 0% in the in the translation string; p1 corresponds to 1% in the translation string; p2 corresponds to 2% in the translation string, and so on.

p_primary_language

Language code for the message to be retrieved. If not specified, Oracle Application Express uses the current language for the user as defined in the Application Language Derived From attribute.

See Also: "Specifying the Primary Language for an Application"

Example

Suppose you have a table that defines all primary colors. You could define a dynamic message for each color and then apply the LANG function to the defined values in a query. For example:

SELECT APEX_LANG.LANG(color)
FROM my_colors

If you were running the application in German, RED was a value for the color column in the my_colors table, and you defined the German word for red, the previous example would return ROT.

About Supported Globalization Codes

If you are building a multilingual application, it is important to understand how globalization codes affect the way in which your application runs. These codes are set automatically based on the application-level Globalization attributes you select.

See Also:
"Specifying the Primary Language for an Application"

NLS_LANGUAGE and NLS_TERRITORY determine the default presentation of numbers, dates, and currencies.

Table 14-5 describes the globalization codes in Oracle Application Express.

Table 14-5 Oracle Application Express Globalization Codes

Language Name

Language Code

NLS_LANGUAGE

NLS_TERRITORY

Afrikaans

af

ENGLISH

SOUTH AFRICA

Arabic

ar

ARABIC

UNITED ARAB EMIRATES

Arabic (Algeria)

ar-dz

ARABIC

ALGERIA

Arabic (Bahrain)

ar-bh

ARABIC

BAHRAIN

Arabic (Egypt)

ar-eg

EGYPTIAN

EGYPT

Arabic (Iraq)

ar-iq

ARABIC

IRAQ

Arabic (Jordan)

ar-jo

ARABIC

JORDAN

Arabic (Kuwait)

ar-kw

ARABIC

KUWAIT

Arabic (Lebanon

ar-lb

ARABIC

LEBANNON

Arabic (Libya)

ar-ly

ARABIC

LIBYA

Arabic (Morocco)

ar-ma

ARABIC

MOROCCO

Arabic (Oman)

ar-om

ARABIC

OMAN

Arabic (Qatar)

ar-qa

ARABIC

QATAR

Arabic (Saudi Arabia)

ar-sa

ARABIC

SAUDI ARABIA

Arabic (Syria)

ar-sy

ARABIC

SYRIA

Arabic (Tunisia)

ar-tn

ARABIC

TUNISIA

Arabic (U.A.E.)

ar-ae

ARABIC

UNITED ARAB EMIRATES

Arabic (YEMEN)

ar-ye

ARABIC

YEMEN

Assamese

as

ASSAMESE

INDIA

Basque

eu

FRENCH

FRANCE

Belarusian

be

RUSSIAN

RUSSIA

Bengali

bn

BANGLA

BANGLADESH

Bulgarian

bg

BULGARIAN

BULGARIA

Catalan

ca

CATALAN

CATALONIA

Chinese

zh

SIMPLIFIED CHINESE

CHINA

Chinese (China)

zh-cn

SIMPLIFIED CHINESE

CHINA

Chinese (Hong Kong SAR)

zh-hk

TRADITIONAL CHINESE

HONG KONG

Chinese (Macau SAR)

zh-mo

TRADITIONAL CHINESE

HONG KONG

Chinese (Singapore)

zh-sg

SIMPLIFIED CHINESE

SINGAPORE

Chinese (Taiwan)

zh-tw

TRADITIONAL CHINESE

TAIWAN

Croatian

hr

CROATIAN

CROATIA

Czech

cs

CZECH

CZECH REPUBLIC

Danish

da

DANISH

DENMARK

Dutch (Belgium)

nl-be

DUTCH

BELGIUM

Dutch (Netherlands)

nl

DUTCH

THE NETHERLANDS

English

en

AMERICAN

AMERICA

English (Australia)

en-au

ENGLISH

AUSTRALIA

English (Belize)

en-bz

ENGLISH

UNITED KINGDOM

English (Canada)

en-ca

ENGLISH

CANADA

English (Ireland)

en-ie

ENGLISH

IRELAND

English (Jamaica)

en-jm

ENGLISH

UNITED KINGDOM

English (New Zealand)

en-nz

ENGLISH

NEW ZEALAND

English (Philippines)

en-ph

ENGLISH

PHILIPPINES

English (South Africa)

en-za

ENGLISH

SOUTH AFRICA

English (Trinidad)

en-tt

ENGLISH

UNITED KINGDOM

English (United Kingdom)

en-gb

ENGLISH

UNITED KINGDOM

English (United States)

en-us

AMERICAN

AMERICA

English (Zimbabwe)

en-zw

ENGLISH

UNITED KINGDOM

Estonian

et

ESTONIAN

ESTONIA

Faeroese

fo

ENGLISH

UNITED KINGDOM

Farsi

fa

ENGLISH

UNITED KINGDOM

Finnish

fi

FINNISH

FINLAND

French (Belgium)

fr-be

FRENCH

BELGIUM

French (Canada)

fr-ca

CANADIAN FRENCH

CANADA

French (France)

fr

FRENCH

FRANCE

French (Luxembourg)

fr-lu

FRENCH

LUXEMBOURG

French (Monaco)

fr-mc

FRENCH

FRANCE

French (Switzerland)

fr-ch

FRANCH

SWITZERLAND

FYRO Macedonian

mk

MACEDONIAN

FYR MACEDONIA

Gaelic

gd

ENGLISH

UNITED KINGDOM

Galician

gl

SPANISH

SPAIN

German (Austria)

de-at

GERMAN

AUSTRIA

German (Germany)

de

GERMAN

GERMANY

German (Liechtenstein)

de-li

GERMAN

GERMANY

German (Luxemgourg)

de-lu

GERMAN

LUXEMBOURG

German (Switzerland)

de-ch

GERMAN

SWITZERLAND

Greek

el

GREEK

GREECE

Gujarati

gu

GUJARATI

INDIA

Hebrew

he

HEBREW

ISRAEL

Hindi

hi

HINDI

INDIA

Hungarian

hu

HUNGARIAN

HUNGARY

Icelandic

is

ICELANDIC

ICELAND

Indonesian

id

INDONESIAN

INDONESIA

Italian (Italy)

it

ITALIAN

ITALY

Italian (Switzerland)

it-ch

ITALIAN

SWITZERLAND

Japanese

ja

JAPANESE

JAPAN

Kannada

kn

KANNADA

INDIA

Kazakh

kk

CYRILLIC KAZAKH

KAZAKHSTAN

Konkani

kok

KOREAN

KOREA

Korean

ko

KOREAN

KOREA

Kyrgyz

kz

RUSSIAN

RUSSIA

Latvian

lv

LATVIAN

LATVIA

Lithuanian

lt

LITHUANIAN

LITHUANIANA

Malay (Malaysia)

ms

MALAY

MALAYSIA

Malayalam

ml

MALAYALAM

INDIA

Maltese

mt

ENGLISH

UNITED KINGDOM

Marathi

mr

ENGLISH

INDIA

Nepali (India)

ne

ENGLISH

UNITED KINGDOM

Norwegian (Bokmal)

nb-no

NORWEGIAN

NORWAY

Norwegian (Bokmal)

no

NORWEGIAN

NORWAY

Norwegian (Nynorsk)

nn-no

NORWEGIAN

NORWAY

Oriya

or

ORIYA

INDIA

Polish

pl

POLISH

POLAND

Portuguese (Brazil)

pt-br

BRAZILIAN PORTUGUESE

BRAZIL

Portuguese (Portugal)

pt

PORTUGUESE

PORTUGAL

Punjabi

pa

PUNJABI

INDIA

Romanian

ro

ROMANIAN

ROMANIA

Russian

ru

RUSSIAN

RUSSIA

Russian (Moldova)

ru-md

RUSSIAN

RUSSIA

Serbia

sr

CYRILLIC SERBIAN

SERBIA AND MONTENEGRO

Slovak

sk

SLOVAK

SLOVAKIA

Slovenian

sl

SLOVENIAN

SLOVENIA

Spanish (Argentina)

es-ar

LATIN AMERICAN SPANISH

ARGENTINA

Spanish (Bolivia)

es-bo

LATIN AMERICAN SPANISH

ARGENTINA

Spanish (Chile)

es-cl

LATIN AMERICAN SPANISH

CHILE

Spanish (Columbia)

ec-co

LATIN AMERICAN SPANISH

COLUMBIA

Spanish (Costa Rica)

es-cr

LATIN AMERICAN SPANISH

COSTA RICA

Spanish (Dominican Republic)

es-do

LATIN AMERICAN SPANISH

PUERTO RICO

Spanish (Ecuador)

es-ec

LATIN AMERICAN SPANISH

ECUDOR

Spanish (El Salvador)

es-sv

LATIN AMERICAN SPANISH

EL SALVADOR

Spanish (Guatemala)

es-gt

LATIN AMERICAN SPANISH

GUATEMALA

Spanish (Honduras)

es-hn

LATIN AMERICAN SPANISH

GUATEMALA

Spanish (Mexico)

es-mx

MEXICAN SPANISH

MEXICO

Spanish (Nicaragua)

es-ni

LATIN AMERICAN SPANISH

Nicaragua

Spanish (Panama)

es-pa

LATIN AMERICAN SPANISH

Panama

Spanish (Paraguay)

es-py

LATIN AMERICAN SPANISH

ARGENTINA

Spanish (Peru)

es-pe

LATIN AMERICAN SPANISH

PERU

Spanish (Peurto Rico)

es-pr

LATIN AMERICAN SPANISH

PEURTO RICO

Spanish (Traditional Sort)

es

LATIN AMERICAN SPANISH

SPAIN

Spanish (United States)

es-us

LATIN AMERICAN SPANISH

AMERICAN

Spanish (Uruguay)

es-uy

LATIN AMERICAN SPANISH

ARGENTINA

Spanish (Venezuela)

es-ve

LATIN AMERICAN SPANISH

VENEZUELA

Swedish

sv

SWEDISH

SWEDEN

Swedish

sv-fi

SWEDISH

FINLAND

Tamil

ta

TAMIL

INDIA

Telugu

te

TELUGU

INDIA

Thai

th

THAI

THAILAND

Turkish

tr

TURKISH

TURKEY

Ukrainian

uk

UKRAINIAN

UKRAINE

Urdu

ur

ENGLISH

UNITED KINGDOM

Uzbek

uz

LATIN UZBEK

UZBEKISTAN

Vietnamese

vi

VIETNAMESE

VIETNAM

Zulu

zu

ENGLISH

UNITED KINGDOM

15 Oracle Application Express APIs

This section describes the APIs available in Oracle Application Express.

Note:
In release 2.2, Oracle Application Express APIs were renamed using the prefix APEX_. Note that API's using the previous prefix HTMLDB_ are still supported to provide backward compatibility. As a best practice, however, use the new API names for new applications unless you plan to run them in an earlier version of Oracle Application Express.

This section contains the following topics:

- APEX_UTIL

- APEX_MAIL

- APEX_ITEM

- APEX_APPLICATION

- APEX_CUSTOM_AUTH

- APEX_LDAP

APEX_UTIL

The APEX_UTIL package provides utilities you can use when programming in the Oracle Application Express environment. You can use the APEX_UTIL package to get and set session state, get files, check authorizations for users, reset different states for users, and also to get and set preferences for users.

Topics in this section include:

- CHANGE_CURRENT_USER_PW Procedure

- CACHE_GET_DATE_OF_PAGE_CACHE Procedure

- CACHE_GET_DATE_OF_REGION_CACHE Procedure

- CACHE_PURGE_BY_APPLICATION Procedure

- CACHE_PURGE_BY_PAGE Procedure

- CACHE_PURGE_STALE Procedure

- CHANGE_PASSWORD_ON_FIRST_USE Function

- CLEAR_APP_CACHE Procedure

- CLEAR_PAGE_CACHE Procedure

- CLEAR_USER_CACHE Procedure

- COUNT_CLICK Procedure

- COUNT_STALE_REGIONS Function

- CREATE_USER Procedure

- CREATE_USER_GROUP Procedure

- CURRENT_USER_IN_GROUP Function

- EDIT_USER Procedure

- EXPIRE_END_USER_ACCOUNT Procedure

- EXPIRE_WORKSPACE_ACCOUNT Procedure

- EXPORT_USERS Procedure

- FETCH_APP_ITEM Function

- FETCH_USER Procedure

- FIND_SECURITY_GROUP_ID Function

- FIND_WORKSPACE Function

- GET_ACCOUNT_LOCKED_STATUS Function

- GET_ATTRIBUTE Function

- GET_AUTHENTICATION_RESULT Function

- GET_CURRENT_USER_ID Function

- GET_DEFAULT_SCHEMA Function

- GET_EMAIL Function

- GET_FILE Procedure

- GET_FILE_ID Function

- GET_FIRST_NAME Function

- GET_GROUPS_USER_BELONGS_TO Function

- GET_GROUP_ID Function

- GET_GROUP_NAME Function

- GET_LAST_NAME Function

- GET_USERNAME Function

- GET_NUMERIC_SESSION_STATE Function

- GET_PREFERENCE Function

- GET_SESSION_STATE Function

- GET_USER_ID Function

- GET_USER_ROLES Function

- IS_LOGIN_PASSWORD_VALID Function

- IS_USERNAME_UNIQUE Function

- KEYVAL_NUM Function

- KEYVAL_VC2 Function

- LOCK_ACCOUNT Procedure

- PASSWORD_FIRST_USE_OCCURRED Function

- PREPARE_URL Function

- PUBLIC_CHECK_AUTHORIZATION Function

- PURGE_REGIONS_BY_APP Procedure

- PURGE_REGIONS_BY_ID Procedure

- PURGE_REGIONS_BY_NAME Procedure

- PURGE_REGIONS_BY_PAGE Procedure

- PURGE_STALE_REGIONS Procedure

- REMOVE_PREFERENCE Procedure

- REMOVE_SORT_PREFERENCES Procedure

- REMOVE_USER Procedure

- RESET_AUTHORIZATIONS Procedure

- RESET_PW Procedure

- SAVEKEY_NUM Function

- SAVEKEY_VC2 Function

- SET_ATTRIBUTE Procedure

- SET_AUTHENTICATION_RESULT Procedure

- SET_CUSTOM_AUTH_STATUS Procedure

- SET_EMAIL Procedure

- SET_FIRST_NAME Procedure

- SET_LAST_NAME Procedure

- SET_PREFERENCE Procedure

- SET_SESSION_STATE Procedure

- SET_USERNAME Procedure

- STRING_TO_TABLE Function

- TABLE_TO_STRING Function

- UNEXPIRE_END_USER_ACCOUNT Procedure

- UNEXPIRE_WORKSPACE_ACCOUNT Procedure

- UNLOCK_ACCOUNT Procedure

- URL_ENCODE Function

- WORKSPACE_ACCOUNT_DAYS_LEFT Function

CHANGE_CURRENT_USER_PW Procedure

This procedure changes the password of the currently authenticated user, assuming Application Express user accounts are in use.

Syntax

APEX_UTIL.CHANGE_CURRENT_USER_PW(
p_new_password IN VARCHAR2);

Parameters

Table 15-1 describes the parameters available in the CHANGE_CURRENT_USER_PW procedure.

Table 15-1 CHANGE_CURRENT_USER_PW Parameters

Parameter

Description

p_new_password

The new password value in clear text

Example

BEGIN
APEX_UTIL.CHANGE_CURRENT_USER_PW ('secret99');
END;

CACHE_GET_DATE_OF_PAGE_CACHE Procedure

This procedure returns the date and time a specified application page was cached either for the user issuing the call, or for all users if the page was not set to be cached by user.

Syntax

APEX_UTIL.CACHE_GET_DATE_OF_PAGE_CACHE (
p_application  IN    NUMBER,
p_page         IN    NUMBER,
RETURN DATE;

Parameters

Table 15-2 describes the parameters available in the CACHE_GET_DATE_OF_PAGE_CACHE procedure.

Table 15-2 CACHE_GET_DATE_OF_PAGE_CACHE Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

p_page

The page number (ID).

CACHE_GET_DATE_OF_REGION_CACHE Procedure

This procedure returns the date and time a specified region was cached either for the user issuing the call, or for all users if the page was not set to be cached by user.

Syntax

APEX_UTIL.CACHE_GET_DATE_OF_REGION_CACHE  (
p_application  IN    NUMBER,
p_page         IN    NUMBER,
p_region_name  IN    VARCHAR2)
RETURN DATE;

Parameters

Table 15-3 describes the parameters available in the CACHE_GET_DATE_OF_REGION_CACHE procedure.

Table 15-3 CACHE_GET_DATE_OF_REGION_CACHE Parameters

Parameter

Description

p_application

The identification number (ID) of the application

p_page

The page number (ID)

p_region_name

The region name

CACHE_PURGE_BY_APPLICATION Procedure

This procedure purges all cached pages and regions for a given application.

Syntax

APEX_UTIL.CACHE_PURGE_BY_APPLICATION (
p_application  IN  NUMBER;

Parameters

Table 15-4 describes the parameters available in the CACHE_PURGE_BY_APPLICATION procedure.

Table 15-4 CACHE_PURGE_BY_APPLICATION Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

CACHE_PURGE_BY_PAGE Procedure

This procedure purges all cached pages and regions for a given application and page.

Syntax

APEX_UTIL.CACHE_PURGE_BY_PAGE (
p_application  IN    NUMBER,
p_page         IN    NUMBER,
p_user_name    IN    VARCHAR2 DEFAULT NULL);

Parameters

Table 15-5 describes the parameters available in the CACHE_PURGE_BY_PAGE procedure.

Table 15-5 CACHE_PURGE_BY_PAGE Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

p_page

The page number (ID).

p_user_name

The user associated with cached pages and regions.

CACHE_PURGE_STALE Procedure

This procedure deletes all cached pages and regions for a specified application that have passed the defined active time period. When you cache a page or region, you specify an active time period (or Cache Timeout). Once that period has passed, the cache will no longer be used, thus removing those unusable pages or regions from the cache.

Syntax

APEX_UTIL.CACHE_PURGE_STALE (
p_application  IN    NUMBER,

Parameters

Table 15-6 describes the parameters available in the CACHE_PURGE_STALE procedure.

Table 15-6 CACHE_PURGE_STALE Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

CHANGE_PASSWORD_ON_FIRST_USE Function

Enables a developer to check whether this property is enabled or disabled for an end user account. This function returns true if the account password must be changed upon first use (after successful authentication) after the password is initially set and after it is changed on the Administration Service, Edit User page. Returns false if the account does not have this property.

This function may be run in a page request context by any authenticated user.

Syntax

APEX_UTIL.CHANGE_PASSWORD_ON_FIRST_USE (
p_user_name IN VARCHAR2
) RETURN BOOLEAN
;

Parameters

Table 15-7 describes the parameters available in the CHANGE_PASSWORD_ON_FIRST_USE function.

Table 15-7 CHANGE_PASSWORD_ON_FIRST_USE Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example demonstrates how to use the CHANGE_PASSWORD_ON_FIRST_USE function. Use this function to check if the password of Application Express user account (workspace administrator, developer, or end user) in the current workspace must changed by the user the first time it is used.

BEGIN
FOR c1 IN (SELECT user_name FROM wwv_flow_users) LOOP
IF APEX_UTIL.CHANGE_PASSWORD_ON_FIRST_USE(p_user_name => c1.user_name) THEN
htp.p('User:'||c1.user_name||' requires password to be changed the first time it is used.');
END IF;
END LOOP;
END;

See Also:
"PASSWORD_FIRST_USE_OCCURRED Function"

CLEAR_APP_CACHE Procedure

This procedure removes session state for a given application for the current session.

Syntax

APEX_UTIL.CLEAR_APP_CACHE (
p_app_id    IN    VARCHAR2 DEFAULT NULL);

Parameters

Table 15-8 describes the parameters available in the CLEAR_APP_CACHE procedure.

Table 15-8 CLEAR_APP_CACHE Parameters

Parameter

Description

p_app_id

The ID of the application for which session state will be cleared for current session

Example

BEGIN
APEX_UTIL.CLEAR_APP_CACHE('100');
END;

CLEAR_PAGE_CACHE Procedure

This procedure removes session state for a given page for the current session.

Syntax

APEX_UTIL.CLEAR_PAGE_CACHE (
p_page IN NUMBER DEFAULT NULL);

Parameters

Table 15-9 describes the parameters available in the CLEAR_PAGE_CACHE procedure.

Table 15-9 CLEAR_PAGE_CACHE Parameters

Parameter

Description

p_page

The ID of the page in the current application for which session state will be cleared for current session

Example

BEGIN
APEX_UTIL.CLEAR_PAGE_CACHE('10');
END;

CLEAR_USER_CACHE Procedure

This procedure removes session state and application system preferences for the current user's session. Run this procedure if you reuse session IDs and want to run applications without the benefit of existing session state.

Syntax

APEX_UTIL.CLEAR_USER_CACHE;

Parameters

None.

Example

BEGIN
APEX_UTIL.CLEAR_USER_CACHE;
END;

COUNT_CLICK Procedure

This procedure counts clicks from an application built in Application Builder to an external site. You can also use the shorthand version, procedure Z, in place of APEX_UTIL.COUNT_CLICK.

Syntax

APEX_UTIL.COUNT_CLICK (
p_url         IN    VARCHAR2,
p_cat         IN    VARCHAR2,
p_id          IN    VARCHAR2    DEFAULT NULL,
p_user        IN    VARCHAR2    DEFAULT NULL,
p_workspace   IN    VARCHAR2    DEFAULT NULL);

Parameters

Table 15-10 describes the parameters available in the COUNT_CLICK procedure.

Table 15-10 COUNT_CLICK Parameters

Parameter

Description

p_url

The URL to which to redirect

p_cat

A category to classify the click

p_id

Secondary ID to associate with the click (optional)

p_user

The application user ID (optional)

p_workspace

The workspace associated with the application (optional)

Example

BEGIN
htp.p('<a href=APEX_UTIL.COUNT_CLICK?p_url=http://yahoo.com&p_cat=yahoo&p_workspace=NNN> Click</a>'); end;

Where NNN equals your workspace ID.

See Also:
"Purging the External Click Count Log"

COUNT_STALE_REGIONS Function

Counts the number of expired regions.

Syntax

APEX_UTIL.COUNT_STALE_REGIONS (
p_application IN NUMBER,
RETURN NUMBER;

Parameters

Table 15-11 describes the parameters available in COUNT_STALE_REGIONS.

Table 15-11 COUNT_STALE_REGIONS Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

CREATE_USER Procedure

This procedure creates a new account record in the Application Express user account table. To execute this procedure, the current user must have administrative privileges.

Syntax

APEX_UTIL.CREATE_USER(
p_user_id                      NUMBER                  IN     DEFAULT NULL
p_user_name                    VARCHAR2                IN
p_first_name                   VARCHAR2                IN     DEFAULT NULL
p_last_name                    VARCHAR2                IN     DEFAULT NULL
p_description                  VARCHAR2                IN     DEFAULT NULL
p_email_address                VARCHAR2                IN     DEFAULT NULL
p_web_password                 VARCHAR2                IN
p_web_password_format          VARCHAR2                IN     DEFAULT NULL
p_group_ids                    VARCHAR2                IN     DEFAULT NULL
p_attribute_01                 VARCHAR2                IN     DEFAULT NULL
p_attribute_02                 VARCHAR2                IN     DEFAULT NULL
p_attribute_03                 VARCHAR2                IN     DEFAULT NULL
p_attribute_04                 VARCHAR2                IN     DEFAULT NULL
p_attribute_05                 VARCHAR2                IN     DEFAULT NULL
p_attribute_06                 VARCHAR2                IN     DEFAULT NULL
p_attribute_07                 VARCHAR2                IN     DEFAULT NULL
p_attribute_08                 VARCHAR2                IN     DEFAULT NULL
p_attribute_09                 VARCHAR2                IN     DEFAULT NULL
p_attribute_10                 VARCHAR2                IN     DEFAULT NULL)

Parameters

Table 15-12 describes the parameters available in the CREATE_USER procedure.

Table 15-12 CREATE_USER Procedure Parameters

Parameter

Description

p_user_id

Numeric primary key of user account

p_user_name

Alphanumeric name used for login

p_first_name

Informational

p_last_name

Informational

p_description

Informational

p_email_address

Email address

p_web_address

Clear text password

p_group_ID

Colon separated list of numeric group IDs

p_attribute_01

...

p_attribute_10

Arbitrary text accessible with an API

Example

BEGIN
APEX_UTIL.CREATE_USER
P_USER_NAME    => 'NEWUSER1',
P_WEB_PASSWORD => 'secret99');
END;

CREATE_USER_GROUP Procedure

Assuming you are using Application Express authentication, this procedure creates a user group. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

APEX_UTIL.CREATE_USER_GROUP(
p_id                       NUMBER                  IN
p_group_name               VARCHAR2                IN
p_security_group_id        NUMBER                  IN
p_group_desc               VARCHAR2                IN);

Parameter

Table 15-13 describes the parameters available in the CREATE_USER_GROUP procedure.

Table 15-13 CREATE_USER_GROUP Parameters

Parameter

Description

p_id

Primary key of group

p_group_name

Arbitrary name

p_security_group_id

Workspace ID

p_group_desc

Descriptive text

Example

BEGIN
APEX_UTIL.CREATE_USER_GROUP (
p_id                => 0 - trigger will assign PK,
p_group_name        => 'Managers',
p_security_group_id => null, -- defaults to current workspace ID
p_group_desc        => 'text');
END;

CURRENT_USER_IN_GROUP Function

This function returns a Boolean result based on whether or not the current user is a member of the specified group. You can use the group name or group ID to identify the group.

Syntax

APEX_UTIL.CURRENT_USER_IN_GROUP(
p_group_name    IN VARCHAR2)
RETURN BOOLEAN;

APEX_UTIL.CURRENT_USER_IN_GROUP(
p_group_id    IN NUMBER)
RETURN BOOLEAN;

Parameters

Table 15-14 describes the parameters available in the CURRENT_USER_IN_GROUP function.

Table 15-14 CURRENT_USER_IN_GROUP Parameters

Parameter

Description

p_group_name

Identifies the name of an existing group in the workspace

p_group_id

Identifies the numeric ID of an existing group in the workspace

Example

DECLARE VAL BOOLEAN;
BEGIN
VAL := APEX_UTIL.CURRENT_USER_IN_GROUP(p_group_name=>'Managers');
END;

EDIT_USER Procedure

This procedure enables a user account record to be altered. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

EDIT_USER (
p_user_id                      NUMBER                  IN
p_user_name                    VARCHAR2                IN
p_first_name                   VARCHAR2                IN     DEFAULT
p_last_name                    VARCHAR2                IN     DEFAULT
p_web_password                 VARCHAR2                IN     DEFAULT
p_new_password                 VARCHAR2                IN     DEFAULT
p_email_address                VARCHAR2                IN     DEFAULT
p_start_date                   VARCHAR2                IN     DEFAULT
p_end_date                     VARCHAR2                IN     DEFAULT
p_employee_id                  VARCHAR2                IN     DEFAULT
p_allow_access_to_schemas      VARCHAR2                IN     DEFAULT
p_person_type                  VARCHAR2                IN     DEFAULT
p_default_schema               VARCHAR2                IN     DEFAULT
p_group_idS                    VARCHAR2                IN     DEFAULT
P_DEVELOPER_ROLES              VARCHAR2                IN     DEFAULT
P_DESCRIPTION                  VARCHAR2                IN     DEFAULTIN);

Parameters

Table 15-15 describes the parameters available in the EDIT_USER procedure.

Table 15-15 EDIT_USER Parameters

Parameter

Description

p_user_id

Numeric primary key of the user account

p_user_name

Alphanumeric name used for login

p_first_name

Informational

p_last_name

Informational

p_web_password

Clear text password

p_start_date

Unused

p_end_date

Unused

p_employee_id

Unused

p_allow_access_to_schemas

A list of schemas assigned to the user's workspace to which the user is restricted

p_person_type

Unused

p_default_schema

A database schema assigned to the user's workspace, used by default for browsing

p_group_ids

Colon-separated list of numeric group IDs

p_developer_privs

Colon-separated list of developer privileges (only ADMIN: has meaning to Application Express)

p_description

Informational

END_USER_ACCOUNT_DAYS_LEFT Function

Returns the number of days remaining before a end user account password expires. This function may be run in a page request context by any authenticated user.

Syntax

APEX_UTIL.END_USER_ACCOUNT_DAYS_LEFT (
p_user_name IN VARCHAR2
)RETURN NUMBER
;

Parameters

Table 15-16 describes the parameters available in the END_USER_ACCOUNT_DAYS_LEFT function.

Table 15-16 END_USER_ACCOUNT_DAYS_LEFT Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the END_USER_ACCOUNT_DAYS_LEFT function. Use this function to determine the number of days remaining before an Application Express end user account in the current workspace will expire.

DECLARE
l_days_left NUMBER;
BEGIN
FOR c1 IN (SELECT user_name from wwv_flow_users) LOOP
l_days_left := APEX_UTIL.END_USER_ACCOUNT_DAYS_LEFT(p_user_name => c1.user_name) THEN
htp.p('End User Account:'||c1.user_name||' will expire in '||l_days_left||' days.');
END LOOP;
END;

EXPIRE_END_USER_ACCOUNT Procedure

Expires the login account for use as a workspace end user. Must be run by an authenticated workspace administrator in a page request context.

Syntax

APEX_UTIL.EXPIRE_END_USER_ACCOUNT (
p_user_name IN VARCHAR2
);

Parameters

Table 15-18 describes the parameters available in the EXPIRE_END_USER_ACCOUNT procedure.

Table 15-17 EXPIRE_END_USER_ACCOUNT Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the EXPIRE_END_USER_ACCOUNT procedure. Use this procedure to expire an Application Express account (workspace administrator, developer, or end user) in the current workspace. This action specifically expires the account with respect to its use by end users to authenticate to developed applications, but it may also expire the account with respect to its use by developers or administrators to log in to a workspace.

Note that this procedure must be run by a user having administration privileges in the current workspace.

BEGIN
FOR c1 IN (select user_name from wwv_flow_users) LOOP
APEX_UTIL.EXPIRE_END_USER_ACCOUNT(p_user_name => c1.user_name);
htp.p('End User Account:'||c1.user_name||' is now expired.');
END LOOP;
END;

EXPIRE_WORKSPACE_ACCOUNT Procedure

Expires developer or workspace administrator login accounts. Must be run by an authenticated workspace administrator in a page request context.

Syntax

APEX_UTIL.EXPIRE_WORKSPACE_ACCOUNT (
p_user_name IN VARCHAR2
);

Parameters

Table 15-18 describes the parameters available in the EXPIRE_WORKSPACE_ACCOUNT procedure.

Table 15-18 EXPIRE_WORKSPACE_ACCOUNT Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the EXPIRE_WORKSPACE_ACCOUNT procedure. Use this procedure to expire an Application Express account (workspace administrator, developer, or end user) in the current workspace. This action specifically expires the account with respect to its use by developers or administrators to log in to a workspace, but it may also expire the account with respect to its use by end users to authenticate to developed applications.

BEGIN
FOR c1 IN (SELECT user_name FROM wwv_flow_users) LOOP
APEX_UTIL.EXPIRE_WORKSPACE_ACCOUNT(p_user_name =>
c1.user_name);
htp.p('Workspace Account:'||c1.user_name||' is now expired.');
END LOOP;
END;

EXPORT_USERS Procedure

When called from an page, this procedure produces an export file of the current workspace definition, workspace users, and workspace groups. To execute this procedure, the current user must have administrative privilege in the workspace.

Syntax

APEX_UTIL.EXPORT_USERS(
p_export_format in VARCHAR2 DEFAULT 'UNIX')

Parameters

Table 15-19 describes the parameters available in the EXPORT_USERS procedure.

Table 15-19 EXPORT_USERS Parameters

Parameter

Description

p_export_format

Indicates how rows in the export file will be formatted. Specify 'UNIX' to have the resulting file contain rows delimited by line feeds. Specify 'DOS' to have the resulting file contain rows delimited by carriage returns and line feeds

Example

BEGIN
APEX_UTIL.EXPORT_USERS;
END;

FETCH_APP_ITEM Function

This function fetches session state for the current or specified application in the current or specified session.

Syntax

APEX_UTIL.FETCH_APP_ITEM(
p_item    IN VARCHAR2,
p_app     IN NUMBER DEFAULT NULL,
p_session IN NUMBER DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 15-20 describes the parameters available in the FETCH_APP_ITEM function.

Table 15-20 FETCH_APP_ITEM Parameters

Parameter

Description

p_item

The name of an application-level item (not a page item) whose current value is to be fetched

p_app

The ID of the application that owns the item (leave null for the current application)

p_session

The session ID from which to obtain the value (leave null for the current session)

Example

DECLARE VAL VARCHAR2(30);
BEGIN
VAL := APEX_UTIL.FETCH_APP_ITEM (p_item=>'F300_NAME',p_app=>300);
END;

FETCH_USER Procedure

This procedure fetches a user account record. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

FETCH_USER (
p_user_id                      NUMBER                  IN
p_workspace                    VARCHAR2                OUT
p_user_name                    VARCHAR2                OUT
p_first_name                   VARCHAR2                OUT
p_last_name                    VARCHAR2                OUT
p_web_password                 VARCHAR2                OUT
p_email_address                VARCHAR2                OUT
p_start_date                   VARCHAR2                OUT
p_end_date                     VARCHAR2                OUT
p_employee_id                  VARCHAR2                OUT
p_allow_access_to_schemas      VARCHAR2                OUT
p_person_type                  VARCHAR2                OUT
p_default_schema               VARCHAR2                OUT
p_groups                       VARCHAR2                OUT
p_developer_role               VARCHAR2                OUT);

Parameters

Table 15-21 describes the parameters available in the FETCH_USER procedure.

Table 15-21 Fetch_User Parameters

Parameter

Description

p_user_id

Numeric primary key of the user account

p_workspace

The name of the workspace

p_user_name

Alphanumeric name used for login

p_first_name

Informational

p_last_name

Informational

p_description

Informational

p_email_address

Email address

p_start_date

Unused

p_end_date

Unused

p_employee_id

Unused

p_allow_access_to_schemas

A list of schemas assigned to the user's workspace to which user is restricted

p_person_type

Unused

p_default_schema

A database schema assigned to the user's workspace, used by default for browsing

p_groups

Unused

p_developer_role

Unused

FIND_SECURITY_GROUP_ID Function

This function returns the numeric security group ID of the named workspace.

Syntax

APEX_UTIL.FIND_SECURITY_GROUP_ID(
p_workspace    IN VARCHAR2
RETURN NUMBER;

Parameters

Table 15-22 describes the parameters available in the FIND_SECURITY_GROUP_ID function.

Table 15-22 FIND_SECURITY_GROUP_ID Parameters

Parameter

Description

p_workspace

The name of the workspace

Example

DECLARE VAL NUMBER;
BEGIN
VAL := APEX_UTIL.FIND_SECURITY_GROUP_ID (p_workspace=>'DEMOS');
END;

FIND_WORKSPACE Function

This function returns the workspace name associated with a security group ID.

Syntax

APEX_UTIL.FIND_WORKSPACE(
p_security_group_id    IN VARCHAR2)
RETURN VARCHAR2;

Parameters

Table 15-23 describes the parameters available in the FIND_WORKSPACE function.

Table 15-23 FIND_WORKSPACE Parameters

Parameter

Description

p_security_group_id

The security group ID of a workspace

Example

DECLARE VAL NUMBER;
BEGIN
VAL := APEX_UTIL.FIND_WORKSPACE (p_security_group_id =>'20');
END;

GET_ACCOUNT_LOCKED_STATUS Function

Returns true if the account is locked and false if the account is unlocked. Must be run by an authenticated workspace administrator in a page request context.

Syntax

APEX_UTIL.GET_ACCOUNT_LOCKED_STATUS (
p_user_name IN VARCHAR2
) return boolean
;

Parameters

Table 15-24 describes the parameters available in the GET_ACCOUNT_LOCKED_STATUS function.

Table 15-24 GET_ACCOUNT_LOCKED_STATUS Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the GET_ACCOUNT_LOCKED_STATUS function. Use this function to check if an Application Express user account (workspace administrator, developer, or end user) in the current workspace is locked.

BEGIN
FOR c1 IN (SELECT user_name FROM wwv_flow_users) loop
IF APEX_UTIL.GET_ACCOUNT_LOCKED_STATUS(p_user_name =>
c1.user_name) THEN
htp.p('User Account:'||c1.user_name||' is locked.');
END IF;
END LOOP;
END;

GET_ATTRIBUTE Function

This function returns the value of one of the attribute values (1 through 10) of a named user in the Application Express accounts table.

Syntax

APEX_UTIL.GET_ATTRIBUTE(
p_username                IN VARCHAR2
p_attribute_number        IN NUMBER)
RETURN VARCHAR2;

Parameters

Table 15-25 describes the parameters available in the GET_ATTRIBUTE function.

Table 15-25 GET_ATTRIBUTE Parameters

Parameter

Description

p_username

User name in the account.

p_attribute_number

Number of attributes in the user record (1 through 10)

Example

DECLARE VAL VARCHAR2(30);
BEGIN
VAL := APEX_UTIL.GET_ATTRIBUTE (
p_username => 'SCOTT',
p_attribute_number => 1);
END;

GET_AUTHENTICATION_RESULT Function

Use this function to retrieve the authentication result of the current session. Any authenticated user can call this function in a page request context.

Syntax

APEX_UTIL.GET_AUTHENTICATION_RESULT
RETURN NUMBER
;

Parameters

None.

Example

The following example demonstrates how to use the post-authentication process of an application's authentication scheme to retrieve the authentication result code set during authentication.

APEX_UTIL.SET_SESSION_STATE('MY_AUTH_STATUS','Authentication result:'||APEX_UTIL.GET_AUTHENTICATION_RESULT);

GET_CURRENT_USER_ID Function

This function returns the numeric user ID of the current user.

Syntax

APEX_UTIL.GET_CURRENT_USER_ID
RETURN NUMBER;

Parameters

None.

Example

DECLARE VAL NUMBER;
BEGIN
VAL := APEX_UTIL.GET_CURRENT_USER_ID;
END;

GET_DEFAULT_SCHEMA Function

This function returns the default schema name associated with the current user.

Syntax

APEX_UTIL.GET_DEFAULT_SCHEMA
RETURN VARCHAR2;

Parameters

None.

Example

DECLARE VAL VARCHAR2;
BEGIN
VAL := APEX_UTIL. GET_DEFAULT_SCHEMA;
END;

GET_EMAIL Function

This function returns the email address associated with the named user.

Syntax

APEX_UTIL.GET_EMAIL(
p_username IN VARCHAR2);
RETURN VARCHAR2;

Parameters

Table 15-26 describes the parameters available in GET_EMAIL function.

Table 15-26 GET_EMAIL Parameters

Parameter

Description

p_username

The user name in the account

Example

DECLARE VAL VARCHAR2;
BEGIN
VAL := APEX_UTIL.GET_EMAIL(p_username => 'SCOTT');
END;

GET_FILE Procedure

This procedure downloads files from the Oracle Application Express file repository.

Syntax

APEX_UTIL.GET_FILE (
p_file_id    IN   VARCHAR2,
p_mime_type  IN   VARCHAR2 DEFAULT NULL,
p_inline     IN   VARCHAR2 DEFAULT 'NO');

Parameters

Table 15-27 describes the parameters available in GET_FILE procedure.

Table 15-27 GET_FILE Parameters

Parameter

Description

p_file_id

ID in APEX_APPLICATION_FILES of the file to be downloaded. APEX_APPLICATION_FILES is a view on all files uploaded to your workspace. The following example demonstrates how to use APEX_APPLICATION_FILES:

DECLARE
l_file_id NUMBER;
BEGIN
SELECT id INTO l_file_id FROM APEX_APPLICATION_FILES
WHERE filename = 'myxml';
--
APEX_UTIL.GET_FILE(
p_file_id   => l_file_id,
p_mime_type => 'text/xml',
p_inline    => 'YES');
END;

p_mime_type

Mime type of the file to download

p_inline

Valid values include YES and NO. YES to display inline in a browser. NO to download as attachment

Example

BEGIN
APEX_UTIL.GET_FILE(
p_file_id   => '8675309',
p_mime_type => 'text/xml',
p_inline    => 'YES');
END;

GET_FILE_ID Function

This function obtains the primary key of a file in the Oracle Application Express file repository.

Syntax

APEX_UTIL.GET_FILE_ID (
p_fname    IN   VARCHAR2)
RETURN NUMBER;

Parameters

Table 15-28 describes the parameters available in GET_FILE_ID function.

Table 15-28 GET_FILE_ID Parameters

Parameter

Description

p_fname

The NAME in APEX_APPLICATION_FILES of the file to be downloaded. APEX_APPLICATION_FILES is a view on all files uploaded to your workspace.

Example

DECLARE
l_name VARCHAR2(255);
l_file_id NUMBER;
BEGIN
SELECT name INTO l_name FROM APEX_APPLICATION_FILES
WHERE filename = 'F125.sql';
--
l_file_id := APEX_UTIL.GET_FILE_ID(p_fname => l_name);
END;

GET_FIRST_NAME Function

This function returns the FIRST_NAME field stored in the named user account record.

Syntax

APEX_UTIL.GET_FIRST_NAME
p_username IN VARCHAR2)
RETURN VARCHAR2;

Parameters

Table 15-29 describes the parameters available in GET_FIRST_NAME function.

Table 15-29 GET_FIRST_NAME Parameters

Parameter

Description

p_username

Identifies the user name in the account

Example

DECLARE VAL VARCHAR2;
BEGIN
VAL := APEX_UTIL.GET_FIRST_NAME(p_username => 'SCOTT');
END;

GET_GROUPS_USER_BELONGS_TO Function

This function returns a colon separated list of group names to which the named user is a member.

Syntax

APEX_UTIL.GET_GROUPS_USER_BELONGS_TO(
p_username IN VARCHAR2);
RETURN VARCHAR2;

Parameters

Table 15-30 describes the parameters available in GET_GROUPS_USER_BELONGS_TO function.

Table 15-30 GET_GROUPS_USER_BELONGS_TO Parameters

Parameter

Description

p_username

Identifies the user name in the account

Example

DECLARE VAL VARCHAR2;
BEGIN
VAL := APEX_UTIL.GET_GROUPS_USER_BELONGS_TO(p_username => 'SCOTT');
END;

GET_GROUP_ID Function

This function returns the numeric ID of a named group in the workspace.

Syntax

APEX_UTIL.GET_GROUP_ID(
p_group_name)
RETURN VARCHAR2;

Parameters

Table 15-31 describes the parameters available in GET_GROUP_ID function.

Table 15-31 GET_GROUP_ID Parameters

Parameter

Description

p_group_name

Identifies the user name in the account

Example

DECLARE VAL NUMBER;
BEGIN
VAL := APEX_UTIL.GET_GROUP_ID(p_group_name => 'Managers');
END;

GET_GROUP_NAME Function

This function returns the name of a group identified by a numeric ID.

Syntax

APEX_UTIL.GET_GROUP_NAME(
p_group_id)
RETURN NUMBER;

Parameters

Table 15-32 describes the parameters available in GET_GROUP_NAME function.

Table 15-32 GET_GROUP_NAME Parameters

Parameter

Description

p_group_id

Identifies a numeric ID of a group in the workspace

Example

DECLARE VAL VARCHAR2;
BEGIN
VAL := APEX_UTIL.GET_GROUP_NAME(p_group_id => 8922003);
END;

GET_LAST_NAME Function

This function returns the LAST_NAME field stored in the named user account record.

Syntax

APEX_UTIL.GET_LAST_NAME(
p_username IN VARCHAR2)
RETURN VARCHAR2;

Parameters

Table 15-33 describes the parameters available in GET_LAST_NAME function.

Table 15-33 GET_LAST_NAME Parameters

Parameter

Description

p_username

The user name in the user account record

Example

DECLARE VAL VARCHAR2;
BEGIN
VAL := APEX_UTIL.GET_LAST_NAME(p_username => 'SCOTT');
END;

GET_USERNAME Function

This function returns the user name of a user account identified by a numeric ID.

Syntax

APEX_UTIL.GET_USERNAME(
p_userid)
RETURN VARCHAR2;

Parameters

Table 15-34 describes the parameters available in GET_USERNAME function.

Table 15-34 GET_USERNAME Parameters

Parameter

Description

p_userid

Identifies the numeric ID of a user account in the workspace

Example

DECLARE VAL VARCHAR2;
BEGIN
VAL := APEX_UTIL.GET_USERNAME(p_userid => 228922003);
END;

GET_NUMERIC_SESSION_STATE Function

This function returns a numeric value for a numeric item. You can use this function in Oracle Application Express applications wherever you can use PL/SQL or SQL. You can also use the shorthand, function NV, in place of APEX_UTIL.GET_NUMERIC_SESSION_STATE.

Syntax

APEX_UTIL.GET_NUMERIC_SESSION_STATE (
p_item     IN VARCHAR2)
RETURN NUMBER;

Parameters

Table 15-35 describes the parameters available in GET_NUMERIC_SESSION_STATE function.

Table 15-35 GET_NUMERIC_SESSION_STATE Parameters

Parameter

Description

p_item

The case insensitive name of the item for which you want to have the session state fetched

Example

DECLARE
l_item_value    Number;
BEGIN
l_item_value := APEX_UTIL.GET_NUMERIC_SESSION_STATE('my_item');
END;

GET_PREFERENCE Function

This function retrieves the value of a previously saved preference for a given user.

Syntax

APEX_UTIL.GET_PREFERENCE (
p_preference  IN    VARCHAR2 DEFAULT NULL,
p_user        IN    VARCHAR2 DEFAULT V('USER'))
RETURN VARCHAR2;

Parameters

Table 15-36 describes the parameters available in the GET_PREFERENCE function.

Table 15-36 GET_PREFERENCE Parameters

Parameter

Description

p_preference

Name of the preference to retrieve the value

p_value

Value of the preference

p_user

User for whom the preference is being retrieved

Example

DECLARE
l_default_view    VARCHAR2(255);
BEGIN
l_default_view := APEX_UTIL.GET_PREFERENCE(
p_preference => 'default_view',
p_user       => :APP_USER);
END;

GET_SESSION_STATE Function

This function returns the value for an item. You can use this function in your Oracle Application Express applications wherever you can use PL/SQL or SQL. You can also use the shorthand, function V, in place of APEX_UTIL.GET_SESSION_STATE.

Syntax

APEX_UTIL.GET_SESSION_STATE (
p_item    IN   VARCHAR2)
RETURN VARCHAR2;

Parameters

Table 15-37 describes the parameters available in GET_SESSION_STATE function.

Table 15-37 GET_SESSION_STATE Parameters

Parameter

Description

p_item

The case insensitive name of the item for which you want to have the session state fetched

Example

DECLARE
l_item_value  VARCHAR2(255);
BEGIN
l_item_value := APEX_UTIL.GET_SESSION_STATE('my_item');
END;

GET_USER_ID Function

This function returns the numeric ID of a named user in the workspace.

Syntax

APEX_UTIL.GET_USER_ID(
p_username)
RETURN VARCHAR2;

Parameters

Table 15-38 describes the parameters available in GET_USER_ID function.

Table 15-38 GET_USER_ID Parameters

Parameter

Description

p_username

Identifies the name of a user in the workspace

Example

DECLARE VAL NUMBER;
BEGIN  VAL := APEX_UTIL.GET_USER_ID(p_username => 'Managers');
END;

GET_USER_ROLES Function

This function returns the DEVELOPER_ROLE field stored in the named user account record.

Syntax

APEX_UTIL.GET_USER_ROLES(
p_username IN VARCHAR2);
RETURN VARCHAR2;

Parameters

Table 15-39 describes the parameters available in GET_USER_ROLES function.

Table 15-39 GET_USER_ROLES Parameters

Parameter

Description

p_username

Identifies a user name in the account

Example

DECLARE VAL VARCHAR2;
BEGIN
VAL := APEX_UTIL.GET_USER_ROLES(p_username=>'SCOTT');
END;

IS_LOGIN_PASSWORD_VALID Function

This function returns a Boolean result based on the validity of the password for a named user account in the current workspace. This function returns true if the password matches and it returns false if the password does not match.

Syntax

APEX_UTIL.IS_LOGIN_PASSWORD_VALID(
p_username IN VARCHAR2,
p_password IN VARCHAR2);
RETURN BOOLEAN;

Parameters

Table 15-40 describes the parameters available in the IS_LOGIN_PASSWORD_VALID function.

Table 15-40 IS_LOGIN_PASSWORD_VALID Parameters

Parameter

Description

p_username

User name in account

p_password

Password to be compared with password stored in the account

Example

DECLARE VAL BOOLEAN;
BEGIN
VAL := APEX_UTIL. IS_LOGIN_PASSWORD_VALID (
p_username=>'SCOTT'
p_password=>'tiger');
END;

IS_USERNAME_UNIQUE Function

This function returns a Boolean result based on whether the named user account is unique in the workspace.

Syntax

APEX_UTIL.IS_USERNAME_UNIQUE(
p_username IN VARCHAR2)
RETURN BOOLEAN;

Parameters

Table 15-41 describes the parameters available in IS_USERNAME_UNIQUE function.

Table 15-41 IS_USERNAME_UNIQUE Parameters

Parameter

Description

p_username

Identifies the user name to be tested

Example

DECLARE VAL BOOLEAN;
BEGIN
VAL := APEX_UTIL.IS_USERNAME_UNIQUE(
p_username=>'SCOTT');
END;

KEYVAL_NUM Function

This function gets the value of the package variable (wwv_flow_utilities.g_val_num) set by APEX_UTIL.SAVEKEY_NUM.

Syntax

APEX_UTIL.KEYVAL_NUM;

Parameters

Table 15-42 describes the parameters available in KEYVAL_NUM function.

Table 15-42 KEYVAL_NUM Parameters

Parameter

Description

p_val

The numeric value previously saved

Example

DECLARE
VAL BOOLEAN;
BEGIN
VAL := APEX_UTIL.KEYVAL_NUM;
END;

See Also:
"SAVEKEY_NUM Function"

KEYVAL_VC2 Function

This function gets the value of the package variable (wwv_flow_utilities.g_val_vc2) set by APEX_UTIL.SAVEKEY_VC2.

Syntax

APEX_UTIL.KEYVAL_VC2;

Parameters

p_val is the VARCHAR2 value previously saved.

Example

DECLARE
VAL VARCHAR2(4000);
BEGIN
VAL := APEX_UTIL.KEYVAL_VC2;

END;

See Also:
"SAVEKEY_VC2 Function"

LOCK_ACCOUNT Procedure

Sets a user account status to locked. Must be run by an authenticated workspace administrator in the context of a page request.

Syntax

APEX_UTIL.LOCK_ACCOUNT (
p_user_name IN VARCHAR2
);

Parameters

Table 15-43 describes the parameters available in the LOCK_ACCOUNT procedure.

Table 15-43 LOCK_ACCOUNT Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the LOCK_ACCOUNT procedure. Use this procedure to lock an Application Express account (workspace administrator, developer, or end user) in the current workspace. This action locks the account for use by administrators, developers, and end users.

BEGIN
FOR c1 IN (SELECT user_name from wwv_flow_users) LOOP
APEX_UTIL.LOCK_ACCOUNT(p_user_name => c1.user_name);
htp.p('End User Account:'||c1.user_name||' is now locked.');
END LOOP;
END;

PASSWORD_FIRST_USE_OCCURRED Function

Returns true if the account's password has changed since the account was created, an Oracle Application Express administrator performs a password reset operation that results in a new password being emailed to the account holder, or a user has initiated password reset operation. This function returns false if the account's password has not been changed since either of the events just described.

This function may be run in a page request context by any authenticated user.

Syntax

APEX_UTIL.PASSWORD_FIRST_USE_OCCURRED (
p_user_name IN VARCHAR2
) RETURN BOOLEAN
;

Parameters

Table 15-44 describes the parameters available in the PASSWORD_FIRST_USE_OCCURRED procedure.

Table 15-44 PASSWORD_FIRST_USE_OCCURRED Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the PASSWORD_FIRST_USE_OCCURRED function. Use this function to check if the password for an Application Express user account (workspace administrator, developer, or end user) in the current workspace has been changed by the user the first time the user logged in after the password was initially set during account creation, or was changed by one of the password reset operations described above.This is meaningful only with accounts for which the CHANGE_PASSWORD_ON_FIRST_USE attribute is set to Yes.

BEGIN
FOR c1 IN (SELECT user_name from wwv_flow_users) LOOP
IF APEX_UTIL.PASSWORD_FIRST_USE_OCCURRED(p_user_name =>
c1.user_name) THEN
htp.p('User:'||c1.user_name||' has logged in and updated the password.');
END IF;
END LOOP;
END;

See Also:
"CHANGE_PASSWORD_ON_FIRST_USE Function"

PREPARE_URL Function

Given a ready-to-render f?p relative URL, this function adds a Session State Protection checksum argument (&cs=) if one is required.

Note:
The PREPARE_URL functions returns the f?p URL with &cs=<large hex value> appended. If you use this returned value, for example in JavaScript, it may be necessary to escape the ampersand in the URL in order to conform with syntax rules of the particular context. One place you may encounter this is in SVG chart SQL queries which might include PREPARE_URL calls.

Syntax

APEX_UTIL.PREPARE_URL (
p_url           IN VARCHAR2
p_url_charset   IN VARCHAR2 default null,
p_checksum_type IN VARCHAR2 default null)
RETURN VARCHAR2;

Parameters

Table 15-45 describes the parameters available in the PREPARE_URL function.

Table 15-45 PREPARE_URL Parameters

Parameter

Description

p_url

An f?p relative URL with all substitutions resolved

p_url_charset

The character set name (for example, UTF-8) to use when escaping special characters contained within argument values

p_checksum type

Null or any of the following six values, SESSION or 3, PRIVATE_BOOKMARK or 2, or PUBLIC_BOOKMARK or 1

Example

DECLARE
l_url varchar2(2000);
l_session number := v('APP_SESSION');
BEGIN
l_url :=
APEX_UTIL.PREPARE_URL('f?p=100:1:'||l_session||'::NO::P1_ITEM:xyz');
END;

PUBLIC_CHECK_AUTHORIZATION Function

Given the name of a security scheme, this function determines if the current user passes the security check.

Syntax

APEX_UTIL.PUBLIC_CHECK_AUTHORIZATION (
p_security_scheme    IN    VARCHAR2)
RETURN BOOLEAN;

Parameters

Table 15-46 describes the parameters available in PUBLIC_CHECK_AUTHORIZATION function.

Table 15-46 PUBLIC_CHECK_AUTHORIZATION Parameters

Parameter

Description

p_security_name

The name of the security scheme that determines if the user passes the security check

Example

DECLARE
l_check_security  BOOLEAN;
BEGIN
l_check_security := APEX_UTIL.PUBLIC_CHECK_AUTHORIZATION('my_auth_scheme');
END;

PURGE_REGIONS_BY_APP Procedure

Deletes all cached regions for an application.

Syntax

APEX_UTIL.PURGE_REGIONS_BY_APP (
p_application IN NUMBER,

Parameters

Table 15-47 describes the parameters available in PURGE_REGIONS_BY_APP.

Table 15-47 PURGE_REGIONS_BY_APP Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

Example

APEX_UTILITIES.PURGE_REGIONS_BY_APP(p_application=>123);

PURGE_REGIONS_BY_ID Procedure

Deletes all cached values for a region.

Syntax

APEX_UTIL.PURGE_REGIONS_BY_ID (
p_application IN NUMBER,
p_region_id   IN NUMBER);

Parameters

Table 15-48 describes the parameters available in PURGE_REGIONS_BY_ID.

Table 15-48 PURGE_REGIONS_BY_ID Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

p_region_id

The identification number of the region for which cached values are deleted.

PURGE_REGIONS_BY_NAME Procedure

Deletes all cached regions identified by the application name and page number.

Syntax

APEX_UTIL.PURGE_REGIONS_BY_NAME (
p_application  IN NUMBER,
p_page      IN NUMBER,
p_region_name  IN VARCHAR2);

Parameters

Table 15-49 describes the parameters available in PURGE_REGIONS_BY_NAME.

Table 15-49 PURGE_REGIONS_BY_NAME Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

p_page

The number of the page containing the region to be deleted.

p_region_name

The region to be deleted.

PURGE_REGIONS_BY_PAGE Procedure

Deletes all cached regions by application and page.

Syntax

APEX_UTIL.PURGE_REGIONS_BY_PAGE (
p_application IN NUMBER,
p_page     IN NUMBER);

Parameters

Table 15-50 describes the parameters available in PURGE_REGIONS_BY_PAGE.

Table 15-50 PURGE_REGIONS_BY_PAGE Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

p_page

The identification number of page containing the region.

PURGE_STALE_REGIONS Procedure

Deletes all cached regions that have expired or are no longer useful.

Syntax

APEX_UTIL.PURGE_STALE_REGIONS (
p_application IN NUMBER,

Parameters

Table 15-51 describes the parameters available in PURGE_STALE_REGIONS.

Table 15-51 PURGE_STALE_REGIONS Parameters

Parameter

Description

p_application

The identification number (ID) of the application.

REMOVE_PREFERENCE Procedure

This function removes the preference for the supplied user.

Syntax

APEX_UTIL.REMOVE_PREFERENCE(
p_preference    IN    VARCHAR2 DEFAULT NULL,
p_user          IN    VARCHAR2 DEFAULT V('USER'));

Parameters

Table 15-52 describes the parameters available in the REMOVE_PREFERENCE procedure.

Table 15-52 REMOVE_PREFERENCE Parameters

Parameter

Description

p_preference

Name of the preference to remove

p_user

User for whom the preference is defined

Example

BEGIN
APEX_UTIL.REMOVE_PREFERENCE(
p_preference => 'default_view',
p_user       => :APP_USER);
END;

REMOVE_SORT_PREFERENCES Procedure

This procedure removes the user's column heading sorting preference value.

Syntax

APEX_UTIL.REMOVE_SORT_PREFERENCES (
p_user  IN   VARCHAR2 DEFAULT V('USER'));

Parameters

Table 15-53 describes the parameters available in REMOVE_SORT_PREFERENCES function.

Table 15-53 REMOVE_SORT_PREFERENCES Parameters

Parameter

Description

p_user

Identifies the user for whom sorting preferences will be removed

Example

BEGIN
APEX_UTIL.REMOVE_SORT_PREFERENCES(:APP_USER);
END;

REMOVE_USER Procedure

This procedure removes the user account identified by the primary key or a user name. To execute this procedure, the current user must have administrative privilege in the workspace.

Syntax

APEX_UTIL.REMOVE_USER(
p_user_id   IN NUMBER,
p_user_name IN VARCHAR2);

Parameters

Table 15-54 describes the parameters available in the REMOVE_USER procedure.

Table 15-54 REMOVE_USER Parameters

Parameter

Description

p_user_id

The numeric primary key of the user account record

p_user_name

The user name of the user account

Example

BEGIN
APEX_UTIL.REMOVE_USER(p_user_id=>'99997');
END;

BEGIN
APEX_UTIL.REMOVE_USER(p_user_name => 'SCOTT');
END;

RESET_AUTHORIZATIONS Procedure

To increase performance, Oracle Application Express caches the results of authorization schemes after they have been evaluated. You can use this procedure to undo caching, requiring each authorization scheme be revalidated when it is next encountered during page show or accept processing. You can use this procedure if you want users to have the ability to change their responsibilities (their authorization profile) within your application.

Syntax

APEX_UTIL.RESET_AUTHORIZATIONS;

Parameters

None.

Example

BEGIN
APEX_UTIL.RESET_AUTHORIZATIONS;
END;

RESET_PW Procedure

This procedure resets the password for a named user and emails it in a message to the email address located for the named account in the current workspace. To execute this procedure, the current user must have administrative privilege in the workspace.

Syntax

APEX_UTIL.RESET_PW(
p_user IN VARCHAR2,
p_msg  IN VARCHAR2);

Parameters

Table 15-55 describes the parameters available in the RESET_PW procedure.

Table 15-55 RESET_PW Parameters

Parameter

Description

p_user

The user name of the user account

p_msg

Message text to be mailed to a user

Example

BEGIN
APEX_UTIL.RESET_PW(
p_user => 'SCOTT',
p_msg => 'Contact help desk at 555-1212 with questions');
END;

SAVEKEY_NUM Function

This function sets a package variable (wwv_flow_utilities.g_val_num) so that it can be retrieved using the function KEYVAL_NUM.

Syntax

APEX_UTIL.SAVEKEY_NUM(
p_val IN NUMBER);

Parameters

Table 15-56 describes the parameters available in the SAVEKEY_NUM procedure.

Table 15-56 SAVEKEY_NUM Parameters

Parameter

Description

p_val

The numeric value to be saved

Example

DECLARE
VAL NUMBER;
BEGIN
VAL := APEX_UTIL.SAVEKEY_NUM(
p_val => 10);
END;

See Also:
"KEYVAL_NUM Function"

SAVEKEY_VC2 Function

This function sets a package variable (wwv_flow_utilities.g_val_vc2) so that it can be retrieved using the function KEYVAL_VC2.

Syntax

APEX_UTIL.SAVEKEY_VC2
p_val IN VARCHAR2);

Parameters

Table 15-57 describes the parameters available in the SAVEKEY_VC2 function.

Table 15-57 SAVEKEY_VC2 Parameters

Parameter

Description

p_val

The is the VARCHAR2 value to be saved

Example

DECLARE
VAL VARCHAR2(4000);
BEGIN
VAL := APEX_UTIL.SAVEKEY_VC2(
p_val => 'XXX');
END;

See Also:
"KEYVAL_VC2 Function"

SET_ATTRIBUTE Procedure

This procedure sets the value of one of the attribute values (1 through 10) of a user in the Application Express accounts table.

Syntax

APEX_UTIL.SET_ATTRIBUTE(
p_userid           IN NUMBER,
p_attribute_number IN NUMBER,
p_attribute_value  IN VARCHAR2);

Parameters

Table 15-58 describes the parameters available in the SET_ATTRIBUTE procedure.

Table 15-58 SET_ATTRIBUTE Parameters

Parameter

Description

p_userid

The numeric ID of the user account

p_attribute_number

Attribute number in the user record (1 through 10)

p_attribute_value

Value of the attribute located by p_attribute_number to be set in the user record

Example

DECLARE VAL VARCHAR2(30);
BEGIN
APEX_UTIL.SET_ATTRIBUTE (
p_userid => apex_util.get_user_id(p_username => 'SCOTT'),
p_attribute_number => 1,
p_attribute_value => 'foo');
END;

SET_AUTHENTICATION_RESULT Procedure

This procedure can be called from an application's custom authentication function (that is, credentials verification function). The status passed to this procedure is logged in the Login Access Log.

See Also:
"Monitoring Activity within a Workspace"

Syntax

APEX_UTIL.SET_AUTHENTICATION_RESULT(
p_code IN NUMBER
);

Parameters

Table 15-18 describes the parameters available in the SET_AUTHENTICATION_RESULT procedure.

Table 15-59 SET_AUTHENTICATION_RESULT Parameters

Parameter

Description

p_code

Any numeric value the developer chooses. After this value is set in the session using this procedure, it can be retrieved using the APEX_UTIL.GET_AUTHENTICATION_RESULT function.

Example

One way to use this procedure is to include it in the application authentication scheme. This example demonstrates how text and numeric status values can be registered for logging. In this example, no credentials verification is performed, it just demonstrates how text and numeric status values can be registered for logging.

Note that the status set using this procedure is visible in the apex_user_access_log view and in the reports on this view available to workspace and site administrators.

CREATE OR REPLACE FUNCTION MY_AUTH(p_username IN VARCHAR2,
p_password IN VARCHAR2)
RETURN BOOLEAN
IS
BEGIN
APEX_UTIL.SET_CUSTOM_AUTH_STATUS(p_status=>'User:
'||p_username||' is back.');
IF UPPER(p_username) = 'GOOD' THEN
APEX_UTIL.SET_AUTHENTICATION_RESULT(24567);
RETURN TRUE;
ELSE
APEX_UTIL.SET_AUTHENTICATION_RESULT(-666);
RETURN FALSE;
END IF;
END;

SET_CUSTOM_AUTH_STATUS Procedure

This procedure can be called from an application's custom authentication function (that is, credentials verification function). The status passed to this procedure is logged in the Login Access Log.

See Also:
"Monitoring Activity within a Workspace"

Syntax

APEX_UTIL.SET_CUSTOM_AUTH_STATUS(
p_status  IN VARCHAR2
);

Parameters

Table 15-60 describes the parameters available in the SET_CUSTOM_AUTH_STATUS procedure.

Table 15-60 SET_CUSTOM_AUTH_STATUS Parameters

Parameter

Description

p_status

Any text the developer chooses to denote the result of the authentication attempt (up to 4000 characters).

Example

One way to use the SET_CUSTOM_AUTH_STATUS procedure is to include it in the application authentication scheme. This example demonstrates how text and numeric status values can be registered for logging. Note that no credentials verification is performed. The status set using this procedure is visible in the apex_user_access_log view and in the reports on this view available to workspace and site administrators.

CREATE OR REPLACE FUNCTION MY_AUTH(p_username IN VARCHAR2,
p_password IN VARCHAR2)
RETURN BOOLEAN
IS
BEGIN
APEX_UTIL.SET_CUSTOM_AUTH_STATUS(p_status=>'User:
'||p_username||' is back.');
IF UPPER(p_username) = 'GOOD' THEN
APEX_UTIL.SET_AUTHENTICATION_RESULT(24567);
RETURN TRUE;
ELSE
APEX_UTIL.SET_AUTHENTICATION_RESULT(-666);
RETURN FALSE;
END IF;
END;

SET_EMAIL Procedure

This procedure updates a user account with a new email address. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

APEX_UTIL.SET_EMAIL(
p_userid IN NUMBER,
p_email  IN VARCHAR2);

Parameters

Table 15-61 describes the parameters available in the SET_EMAIL procedure.

Table 15-61 SET_EMAIL Parameters

Parameter

Description

p_userid

The numeric ID of the user account

p_email

The email address to be saved in user account

Example

BEGIN
APEX_UTIL.SET_EMAIL(
p_userid  => '888883232',
P_email   => 'scott.scott@oracle.com');
END;

SET_FIRST_NAME Procedure

This procedure updates a user account with a new FIRST_NAME value. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

APEX_UTIL.SET_FIRST_NAME(
p_userid      IN NUMBER,
p_first_name  IN VARCHAR2);

Parameters

Table 15-62 describes the parameters available in the SET_FIRST_NAME procedure.

Table 15-62 SET_FIRST_NAME Parameters

Parameter

Description

p_userid

The numeric ID of the user account

p_first_name

FIRST_NAME value to be saved in user account

Example

BEGIN
APEX_UTIL.SET_FIRST_NAME(
p_userid       => '888883232',
P_first_name   => 'Scott');
END;

SET_LAST_NAME Procedure

This procedure updates a user account with a new LAST_NAME value. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

APEX_UTIL.SET_LAST_NAME(
p_userid      IN NUMBER,
p_last_name   IN VARCHAR2);

Parameters

Table 15-63 describes the parameters available in the SET_LAST_NAME procedure.

Table 15-63 SET_LAST_NAME Parameters

Parameter

Description

p_userid

The numeric ID of the user account

p_last_name

LAST_NAME value to be saved in the user account

Example

BEGIN
APEX_UTIL.SET_LAST_NAME(
p_userid       => '888883232',
p_last_name   => 'SMITH');
END;

SET_PREFERENCE Procedure

This procedure sets a preference that will persist beyond the user's current session.

Syntax

APEX_UTIL.SET_PREFERENCE (
p_preference   IN    VARCHAR2 DEFAULT NULL,
p_value        IN    VARCHAR2 DEFAULT NULL,
p_user         IN    VARCHAR2 DEFAULT NULL);

Parameters

Table 15-64 describes the parameters available in the SET_PREFERENCE procedure.

Table 15-64 SET_PREFERENCE Parameters

Parameter

Description

p_preference

Name of the preference (case-sensitive)

p_value

Value of the preference

p_user

User for whom the preference is being set

Example

BEGIN
APEX_UTIL.SET_PREFERENCE(
p_preference => 'default_view',
p_value      => 'WEEKLY',
p_user       => :APP_USER);
END;

SET_SESSION_STATE Procedure

This procedure sets session state for a current Oracle Application Express session.

Syntax

APEX_UTIL.SET_SESSION_STATE (
p_name     IN    VARCHAR2 DEFAULT NULL,
p_value    IN    VARCHAR2 DEFAULT NULL);

Parameters

Table 15-65 describes the parameters available in the SET_SESSION_STATE procedure.

Table 15-65 SET_SESSION_STATE Parameters

Parameter

Description

p_name

Name of the application-level or page-level item for which you are setting sessions state

p_value

Value of session state to set

Example

BEGIN
APEX_UTIL.SET_SESSION_STATE('my_item','myvalue');
END;

SET_USERNAME Procedure

This procedure updates a user account with a new USER_NAME value. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

APEX_UTIL.USERNAME(
p_userid   IN NUMBER,
p_username   IN VARCHAR2);

Parameters

Table 15-66 describes the parameters available in the SET_USERNAME procedure.

Table 15-66 SET_USERNAME Parameters

Parameter

Description

p_userid

The numeric ID of the user account

p_username

USER_NAME value to be saved in the user account

Example

BEGIN
APEX_UTIL.SET_USERNAME(
p_userid       => '888883232',
P_username   => 'USER-XRAY');
END;

STRING_TO_TABLE Function

Given a string, this function returns a PL/SQL array of type APEX_APPLICATION_GLOBAL.VC_ARR2. This array is a VARCHAR2(32767) table.

Syntax

APEX_UTIL.STRING_TO_TABLE (
p_string       IN VARCHAR2,
p_separator    IN VARCHAR2 DEFAULT ':')
RETURN APEX_APPLICATION_GLOBAL.VC_ARR2;

Parameters

Table 15-67 describes the parameters available in the STRING_TO_TABLE function.

Table 15-67 STRING_TO_TABLE Parameters

Parameter

Description

p_string

String to be converted into a PL/SQL table of type APEX_APPLICATION_GLOBAL.VC_ARR2

p_separator

String separator. The default is a colon

Example

DECLARE
l_vc_arr2    APEX_APPLICATION_GLOBAL.VC_ARR2;
BEGIN
l_vc_arr2 := APEX_UTIL.STRING_TO_TABLE('One:Two:Three');
FOR z IN 1..l_vc_arr2.count LOOP
htp.p(l_vc_arr2(z));
END LOOP;
END;

TABLE_TO_STRING Function

Given a a PL/SQL table of type APEX_APPLICATION_GLOBAL.VC_ARR2, this function returns a delimited string separated by the supplied separator, or by the default separator, a colon (:).

Syntax

APEX_UTIL.TABLE_TO_STRING (
p_table       IN     APEX_APPLICATION_GLOBAL.VC_ARR2,
p_string      IN     VARCHAR2 DEFAULT ':')
RETURN VARCHAR2;

Parameters

Table 15-68 describes the parameters available in the TABLE_TO_STRING function.

Table 15-68 TABLE_TO_STRING Parameters

Parameter

Description

p_string

String separator. Default separator is a colon (:)

p_table

PL/SQL table that is to be converted into a delimited string

Example

DECLARE
l_string     VARCHAR2(255);
l_vc_arr2    APEX_APPLICATION_GLOBAL.VC_ARR2;
BEGIN
l_vc_arr2 := APEX_UTIL.STRING_TO_TABLE('One:Two:Three');

l_string := APEX_UTIL.TABLE_TO_STRING(l_vc_arr2);
END;

UNEXPIRE_END_USER_ACCOUNT Procedure

Makes expired end users accounts and the associated passwords usable, enabling a end user to log in to a workspace.

Syntax

APEX_UTIL.UNEXPIRE_END_USER_ACCOUNT (
p_user_name IN VARCHAR2
);

Parameters

Table 15-18 describes the parameters available in the UNEXPIRE_END_USER_ACCOUNT procedure.

Table 15-69 UNEXPIRE_END_USER_ACCOUNT Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the UNEXPIRE_END_USER_ACCOUNT procedure. Use this procedure to renew (unexpire) an Application Express end user account in the current workspace. This action specifically renews the account for use by end users to authenticate to developed applications and may also renew the account for use by developers or administrators to log in to a workspace.

This procedure must be run by a user having administration privileges in the current workspace.

BEGIN
FOR c1 IN (SELECT user_name from wwv_flow_users) LOOP
APEX_UTIL.UNEXPIRE_END_USER_ACCOUNT(p_user_name => c1.user_name);
htp.p('End User Account:'||c1.user_name||' is now valid.');
END LOOP;
END;

See Also:
"EXPIRE_END_USER_ACCOUNT Parameters"

UNEXPIRE_WORKSPACE_ACCOUNT Procedure

Unexpires developer and workspace administrator accounts and the associated passwords, enabling the developer or administrator to log in to a workspace.

Syntax

APEX_UTIL.UNEXPIRE_WORKSPACE_ACCOUNT (
p_user_name IN VARCHAR2
);

Parameters

Table 15-70 describes the parameters available in the UNEXPIRE_WORKSPACE_ACCOUNT procedure.

Table 15-70 UNEXPIRE_WORKSPACE_ACCOUNT Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the UNEXPIRE_WORKSPACE_ACCOUNT procedure. Use this procedure to renew (unexpire) an Application Express workspace administrator account in the current workspace. This action specifically renews the account for use by developers or administrators to login to a workspace and may also renew the account with respect to its use by end users to authenticate to developed applications.

This procedure must be run by a user having administration privileges in the current workspace.

BEGIN
FOR c1 IN (select user_name from wwv_flow_users) loop
APEX_UTIL.UNEXPIRE_WORKSPACE_ACCOUNT(p_user_name => c1.user_name);
htp.p('Workspace Account:'||c1.user_name||' is now valid.');
END LOOP;
END;

See Also:
"EXPIRE_WORKSPACE_ACCOUNT Procedure" and

UNLOCK_ACCOUNT Procedure

Sets a user account status to unlocked. Must be run by an authenticated workspace administrator in a page request context.

Syntax

APEX_UTIL.UNLOCK_ACCOUNT (
p_user_name IN VARCHAR2
);

Parameters

Table 15-71 describes the parameters available in the UNLOCK_ACCOUNT procedure.

Table 15-71 UNLOCK_ACCOUNT Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the UNLOCK_ACCOUNT procedure. Use this procedure to unlock an Application Express account in the current workspace. This action unlocks the account for use by administrators, developers, and end users.This procedure must be run by a user who has administration privileges in the current workspace

BEGIN
FOR c1 IN (SELECT user_name from wwv_flow_users) LOOP
APEX_UTIL.UNLOCK_ACCOUNT(p_user_name => c1.user_name);
htp.p('End User Account:'||c1.user_name||' is now unlocked.');
END LOOP;
END;

See Also:
"LOCK_ACCOUNT Procedure" and "GET_ACCOUNT_LOCKED_STATUS Function"

URL_ENCODE Function

This function encodes (into hexadecimal) all special characters that include spaces, question marks, and ampersands.

Syntax

APEX_UTIL.URL_ENCODE (
p_url   IN    VARCHAR2)
RETURN VARCHAR2;

Parameters

Table 15-72 describes the parameters available in the URL_ENCODE function.

Table 15-72 URL_ENCODE Parameters

Parameter

Description

p_url

The string to be encoded

Example

DECLARE
l_url  VARCHAR2(255);
BEGIN
l_url := APEX_UTIL.URL_ENCODE('http://www.myurl.com?id=1&cat=foo');
END;

WORKSPACE_ACCOUNT_DAYS_LEFT Function

Returns the number of days remaining before the developer or workspace administrator account password expires. This function may be run in a page request context by any authenticated user.

Syntax

APEX_UTIL.WORKSPACE_ACCOUNT_DAYS_LEFT (
p_user_name IN VARCHAR2
RETURN NUMBER
;

Parameters

Table 15-73 describes the parameters available in the WORKSPACE_ACCOUNT_DAYS_LEFT procedure.

Table 15-73 WORKSPACE_ACCOUNT_DAYS_LEFT Parameters

Parameter

Description

p_user_name

The user name of the user account

Example

The following example shows how to use the WORKSPACE_ACCOUNT_DAYS_LEFT function. It can be used in to find the number of days remaining before an Application Express administrator or developer account in the current workspace expires.

DECLARE
l_days_left NUMBER;
BEGIN
FOR c1 IN (SELECT user_name from wwv_flow_users) LOOP
l_days_left := APEX_UTIL.WORKSPACE_ACCOUNT_DAYS_LEFT(p_user_name =>
c1.user_name) THEN
htp.p('Workspace Account:'||c1.user_name||' will expire in '||l_days_left||' days.');
END LOOP;
END;

APEX_MAIL

You can use the APEX_MAIL package to send an email from an Oracle Application Express application. This package is built on top of the Oracle supplied UTL_SMTP package. Because of this dependence, the UTL_SMTP package must be installed and functioning in order to use APEX_MAIL.

See Also:
Oracle Database PL/SQL Packages and Types Reference for more information about the UTL_SMTP package

APEX_MAIL contains two procedures. Use APEX_MAIL.SEND to send an outbound email message from your application. Use APEX_MAIL.PUSH_QUEUE to deliver mail messages stored in APEX_MAIL_QUEUE.

Topics in this section include:

- SEND Procedure

- PUSH_QUEUE Procedure

Note:
The most efficient approach to sending email is to create a background job (using a DBMS_JOB package) to periodically send all mail messages stored in the active mail queue.

See Also:
"Sending Email from an Application"

SEND Procedure

This procedure sends an outbound email message from an application. Although you can use this procedure to pass in either a VARCHAR2 or a CLOB to p_body and p_body_html, the data types must be the same. In other words, you cannot pass a CLOB to P_BODY and a VARCHAR2 to p_body_html.

When using APEX_MAIL.SEND, remember the following:

- No single line may exceed 1000 characters. The SMTP/MIME specification dictates that no single line shall exceed 1000 characters. To comply with this restriction, you must add a carriage return or line feed characters to break up your p_body or p_body_html parameters into chunks of 1000 characters or less. Failing to do so will result in erroneous email messages, including partial messages or messages with extraneous exclamation points.

- Plain text and HTML email content. Passing a value to p_body, but not p_body_html results in a plain text message. Passing a value to p_body and p_body_html yields a multi-part message that includes both plain text and HTML content. The settings and capabilities of the recipient's email client determine what displays. Although most modern email clients can read an HTML formatted email, remember that some users disable this functionality to address security issues.

- Avoid images. When referencing images in p_body_html using the <img /> tag, remember that the images must be accessible to the recipient's email client in order for them to see the image.

For example, suppose you reference an image on your network called hello.gif as follows:

<img src="http://someserver.com/hello.gif" alt="Hello" />]

In this example, the image is not attached to the email, but is referenced by the email. For the recipient to see it, they must be able to access the image using a Web browser. If the image is inside a firewall and the recipient is outside of the firewall, the image will not display. For this reason, avoid using images. If you must include images, be sure to include the ALT attribute to provide a textual description in the event the image is not accessible.

Syntax

APEX_MAIL.SEND(
p_to                        IN    VARCHAR2,
p_from                      IN    VARCHAR2,
p_body                      IN  [ VARCHAR2 | CLOB ],
p_body_html                 IN  [ VARCHAR2 | CLOB ] DEFAULT,
p_subj                      IN    VARCHAR2 DEFAULT)
p_cc                        IN    VARCHAR2 DEFAULT)
p_bcc                       IN    VARCHAR2 DEFAULT);
p_replyto                   IN    VARCHAR2 DEFAULT);

Parameters

Table 15-74 describes the parameters available in the SEND procedure.

Table 15-74 SEND Parameters

Parameter

Description

p_to

Valid email address to which the email will be sent (required). For multiple email addresses, use a comma-separated list

p_from

Email address from which the email will be sent (required). This email address must be a valid address. Otherwise, the message will not be sent

p_body

Body of the email in plain text, not HTML (required). If a value is passed to p_body_html, then this is the only text the recipient sees. If a value is not passed to p_body_html, then this text only displays for email clients that do not support HTML or have HTML disabled. A carriage return or line feed (CRLF) must be included every 1000 characters.

p_body_html

Body of the email in HTML format. This must be a full HTML document including the <html> and <body> tags. A single line cannot exceed 1000 characters without a carriage return or line feed (CRLF)

p_subj

Subject of the email

p_cc

Valid email addresses to which the email is copied. For multiple email addresses, use a comma-separated list

p_bcc

Valid email addresses to which the email is blind copied. For multiple email addresses, use a comma-separated list

p_replyto

Address of the Reply-To mail header. You can use this parameter as follows:

- If you omit the p_replyto parameter, the Reply-To mail header is set to the value specified in the p_from parameter

- If you include the p_replyto parameter, but provide a null value, the Reply-To mail header is set to null. This results in the suppression of automatic email replies

- If you include p_replyto parameter, but provide a non-null value (for example, a valid email address), you will send these messages, but the automatic replies will go to the value specified (for example, the email address)

Examples

The following example demonstrates how to use APEX_MAIL.SEND to send a plain text email message from an application.

-- Example One: Plain Text only message
DECLARE
l_body      CLOB;
BEGIN
l_body := 'Thank you for your interest in the APEX_MAIL
package.'||utl_tcp.crlf||utl_tcp.crlf;
l_body := l_body ||'  Sincerely,'||utl_tcp.crlf;
l_body := l_body ||'  The APEX Dev Team'||utl_tcp.crlf;
apex_mail.send(
p_to       => 'some_user@somewhere.com',   -- change to your email address
p_from     => 'some_sender@somewhere.com', -- change to a real senders email address
p_body     => l_body,
p_subj     => 'APEX_MAIL Package - Plain Text message');
END;
/

The following example demonstrates how to use APEX_MAIL.SEND to send an HTML email message from an application. Remember, you must include a carriage return or line feed (CRLF) every 1000 characters. The example that follows uses utl_tcp.crlf.

-- Example Two: Plain Text / HTML message
DECLARE
l_body      CLOB;
l_body_html CLOB;
BEGIN
l_body := 'To view the content of this message, please use an HTML enabled mail client.'||utl_tcp.crlf;

l_body_html := '<html>
<head>
<style type="text/css">
body{font-family: Arial, Helvetica, sans-serif;
font-size:10pt;
margin:30px;
background-color:#ffffff;}

span.sig{font-style:italic;
font-weight:bold;
color:#811919;}
</style>
</head>
<body>'||utl_tcp.crlf;
l_body_html := l_body_html ||'<p>Thank you for your interest in the <strong>APEX_MAIL</strong> package.</p>'||utl_tcp.crlf;
l_body_html := l_body_html ||'  Sincerely,<br />'||utl_tcp.crlf;
l_body_html := l_body_html ||'  <span class="sig">The HTMLDB Dev Team</span><br />'||utl_tcp.crlf;
apex_mail.send(
p_to        => 'some_user@somewhere.com',   -- change to your email address
p_from      => 'some_sender@somewhere.com', -- change to a real senders email address
p_body      => l_body,
p_body_html => l_body_html,
p_subj      => 'APEX_MAIL Package - HTML formatted message');
END;
/

PUSH_QUEUE Procedure

Oracle Application Express stores unsent email messages in a table named APEX_MAIL_QUEUE. You can manually deliver mail messages stored in this queue to the specified SMTP gateway by invoking the APEX_MAIL.PUSH_QUEUE procedure.

Oracle Application Express logs successfully submitted message in the table APEX_MAIL_LOG with the timestamp reflecting your server's local time. Keep in mind, the most efficient approach to sending email is to create a background job (using a DBMS_JOB package) to periodically send all mail messages stored in the active mail queue.

See Also:
"Sending Email from an Application"

Syntax

APEX_MAIL.PUSH_QUEUE(
p_smtp_hostname             IN    VARCHAR2 DEFAULT,
p_smtp_portno               IN    NUMBER   DEFAULT;

Parameters

Table 15-75 describes the parameters available in the PUSH_QUEUE procedure.

Table 15-75 PUSH_QUEUE Parameters

Parameters

Description

p_smtp_hostname

SMTP gateway host name

p_smtp_portno

SMTP gateway port number

Note that these parameter values are provided for backward compatibility, but their respective values are ignored. The SMTP gateway hostname and SMTP gateway port number are exclusively derived from values entered on the Manage Environment Settings when sending e-mail.

See Also:
"About Configuring Oracle Application Express to Send Email"

Example

The following example demonstrates the use of the APEX_MAIL.PUSH_QUEUE procedure using a shell script. This example only applies to UNIX/LINUX installations.

SQLPLUS / <<EOF
APEX_MAIL.PUSH_QUEUE;
DISCONNECT
EXIT
EOF

See Also:
"Sending Email from an Application"

APEX_ITEM

You can use the APEX_ITEM package to create form elements dynamically based on a SQL query instead of creating individual items page by page.

Topics in this section include:

- CHECKBOX Function

- DATE_POPUP Function

- DISPLAY_AND_SAVE Function

- HIDDEN Function

- MD5_CHECKSUM Function

- MD5_HIDDEN Function

- MULTI_ROW_UPDATE Procedure

- POPUP_FROM_LOV Function

- POPUP_FROM_QUERY Function

- POPUPKEY_FROM_LOV Function

- POPUPKEY_FROM_QUERY Function

- RADIOGROUP Function

- SELECT_LIST Function

- SELECT_LIST_FROM_LOV Function

- SELECT_LIST_FROM_LOV_XL Function

- SELECT_LIST_FROM_QUERY Function

- SELECT_LIST_FROM_QUERY_XL Function

- TEXTAREA Function

- TEXT Function

- TEXT_FROM_LOV Function

- TEXT_FROM_LOV_QUERY Function

CHECKBOX Function

This function creates check boxes.

Syntax

APEX_ITEM.CHECKBOX(
p_idx                       IN    NUMBER,
p_value                     IN    VARCHAR2 DEFAULT,
p_attributes                IN    VARCHAR2 DEFAULT,
p_checked_values            IN    VARCHAR2 DEFAULT,
p_checked_values_delimiter  IN    VARCHAR2 DEFAULT)
RETURN VARCHAR2;

Parameters

Table 15-76 describes the parameters available in the CHECKBOX function.

Table 15-76 CHECKBOX Parameters

Parameter

Description

p_idx

Number that determines which APEX_APPLICATION global variable will be used. Valid range of values is 1 to 50. For example 1 creates F01 and 2 creates F02

p_value

Value of a check box, hidden field, or input form item

p_attributes

Controls HTML tag attributes (such as disabled)

p_checked_values

Values to be checked by default

p_checked_values_delimiter

Delimits the values in the previous parameter, p_checked_values

Examples of Default Check Box Behavior

The following example demonstrates how to create a selected check box for each employee in the emp table.

SELECT APEX_ITEM.CHECKBOX(1,empno,'CHECKED') " ",
ename,
job
FROM   emp
ORDER BY 1

The following example demonstrates how to have all check boxes for employees display without being selected.

SELECT APEX_ITEM.CHECKBOX(1,empno) " ",
ename,
job
FROM   emp
ORDER BY 1

The following example demonstrates how to select the check boxes for employees who work in department 10.

SELECT APEX_ITEM.CHECKBOX(1,empno,DECODE(deptno,10,'CHECKED',null)) " ",
ename,
job
FROM   emp
ORDER BY 1

The next example demonstrates how to select the check boxes for employees who work in department 10 or department 20.

SELECT APEX_ITEM.CHECKBOX(1,deptno,NULL,'10:20',':') " ",
ename,
job
FROM   emp
ORDER BY 1

Creating an On-Submit Process

If you are using check boxes in your application, you might need to create an On Submit process to perform a specific type of action on the selected rows. For example, you could have a Delete button that utilizes the following logic:

SELECT APEX_ITEM.CHECKBOX(1,empno) " ",
ename,
job
FROM   emp
ORDER  by 1

Consider the following sample on-submit process:

FOR I in 1..APEX_APPLICATION.G_F01.COUNT LOOP
DELETE FROM emp WHERE empno = to_number(APEX_APPLICATION.G_F01(i));
END LOOP;

DATE_POPUP Function

Use this function with forms that include date fields. The DATE_POPUP function dynamically generates a date field that has a popup calendar button.

Syntax

APEX_ITEM.DATE_POPUP(
p_idx          IN    NUMBER,
p_row          IN    NUMBER,
p_value        IN    VARCHAR2 DEFAULT,
p_date_format  IN    DATE DEFAULT,
p_size         IN    NUMBER DEFAULT,
p_maxlength    IN    NUMBER DEFAULT,
p_attributes   IN    VARCHAR2 DEFAULT)
RETURN VARCHAR2;

Parameters

Table 15-77 describes the parameters available in the DATE_POPUP function.

Table 15-77 DATE_POPUP Parameters

Parameter

Description

p_idx

Number that determines which APEX_APPLICATION global variable will be used.Valid range of values is 1 to 50. For example, 1 creates F01 and 2 creates F02

p_row

This parameter is deprecated. Anything specified for this value will be ignored

p_value

Value of a field item

p_date_format

Valid database date format

p_size

Controls HTML tag attributes (such as disabled)

p_maxlength

Determines the maximum number of enterable characters. Becomes the maxlength attribute of the <input> HTML tag

p_attributes

Extra HTML parameters you want to add

See Also:
Oracle Database SQL Language Reference for information about the TO_CHAR or TO_DATE functions

Example

The following example demonstrates how to use APEX_ITEM.DATE_POPUP to create popup calendar buttons for the hiredate column.

SELECT
empno,
APEX_ITEM.HIDDEN(1,empno)||
APEX_ITEM.TEXT(2,ename) ename,
APEX_ITEM.TEXT(3,job) job,
mgr,
APEX_ITEM.DATE_POPUP(4,rownum,hiredate,'dd-mon-yyyy') hd,
APEX_ITEM.TEXT(5,sal) sal,
APEX_ITEM.TEXT(6,comm) comm,
deptno
FROM emp
ORDER BY 1

DISPLAY_AND_SAVE Function

Use this function to display an item as text, but save its value to session state.

Syntax

APEX_ITEM.DISPLAY_AND_SAVE(
p_idx         IN    NUMBER,
p_value       IN    VARCHAR2 DEFAULT NULL,
p_item_id     IN    VARCHAR2 DEFAULT NULL,
p_item_label  IN    VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 15-78 describes the parameters available in the DISPLAY_AND_SAVE function.

Table 15-78 DISPLAY_AND_SAVE Parameters

Parameter

Description

p_idx

Number that determines which APEX_APPLICATION global variable will be used.Valid range of values is 1 to 50. For example, 1 creates F01 and 2 creates F02

p_value

Current value

p_item_id

HTML attribute ID for the <input> tag

p_item_label

Label of the text field item

Example

The following example demonstrates how to use the APEX_ITEM.DISPLAY_AND_SAVE function.

SELECT APEX_ITEM.DISPLAY_AND_SAVE(10,empno) c FROM emp

HIDDEN Function

This function dynamically generates hidden form items.

Syntax

APEX_ITEM.HIDDEN(
p_idx     IN    NUMBER,
p_value   IN    VARCHAR2 DEFAULT)
RETURN VARCHAR2;

Parameters

Table 15-79 describes the parameters available in the HIDDEN function.

Table 15-79 HIDDEN Parameters

Parameter

Description

p_idx

Number to identify the item you want to generate. The number will determine which G_FXX global is populated

See Also: "APEX_APPLICATION"

p_value

Value of the hidden input form item

Example

Typically, the primary key of a table is stored as a hidden column and used for subsequent update processing, for example:

SELECT
empno,
APEX_ITEM.HIDDEN(1,empno)||
APEX_ITEM.TEXT(2,ename) ename,
APEX_ITEM.TEXT(3,job) job,
mgr,
APEX_ITEM.DATE_POPUP(4,rownum,hiredate,'dd-mon-yyyy') hiredate,
APEX_ITEM.TEXT(5,sal) sal,
APEX_ITEM.TEXT(6,comm) comm,
deptno
FROM emp
ORDER BY 1

The previous query could use the following page process to process the results:

BEGIN
FOR i IN 1..APEX_APPLICATION.G_F01.COUNT LOOP
UPDATE emp
SET
ename=APEX_APPLICATION.G_F02(i),
job=APEX_APPLICATION.G_F03(i),
hiredate=to_date(APEX_APPLICATION.G_F04(i),'dd-mon-yyyy'),
sal=APEX_APPLICATION.G_F05(i),
comm=APEX_APPLICATION.G_F06(i)
WHERE empno=to_number(APEX_APPLICATION.G_F01(i));
END LOOP;
END;

Note that the G_F01 column (which corresponds to the hidden EMPNO) is used as the key to update each row.

MD5_CHECKSUM Function

This function passes values to APEX_ITEM.MULTI_ROW_UPDATE and is used for lost update detection. Lost update detection ensures data integrity in applications where data can be accessed concurrently.

Syntax

APEX_ITEM.MD5_CHECKSUM(
p_value01   IN    VARCHAR2 DEFAULT,
p_value02   IN    VARCHAR2 DEFAULT,
p_value03   IN    VARCHAR2 DEFAULT,
...
p_value50   IN    VARCHAR2 DEFAULT,
p_col_sep   IN    VARCHAR2 DEFAULT)
RETURN VARCHAR2;

Parameters

Table 15-80 describes the parameters available in the MD5_CHECKSUM function.

Table 15-80 MD5_CHECKSUM Parameters

Parameter

Description

p_value01

...

p_value50

Fifty available inputs. If no parameters are supplied, the default to null

p_col_sep

String used to separate p_value inputs. Defaults to the pipe symbol (|)

Example

SELECT APEX_ITEM.MD5_CHECKSUM(ename,job,sal)
FROM emp

MD5_HIDDEN Function

This function is used for lost update detection. Lost update detection ensures data integrity in applications where data can be accessed concurrently.

This function produces a hidden form field and includes 50 inputs. APEX_ITEM.MD5_HIDDEN also produces an MD5 checksum using the Oracle database DBMS_OBFUSCATION_TOOLKIT:

UTL_RAW.CAST_TO_RAW(DBMS_OBFUSCATION_TOOLKIT.MD5())

An MD5 checksum provides data integrity through hashing and sequencing to ensure that data is not altered or stolen as it is transmitted over a network

Syntax

APEX_ITEM.MD5_HIDDEN(
p_idx       IN    NUMBER,
p_value01   IN    VARCHAR2 DEFAULT,
p_value02   IN    VARCHAR2 DEFAULT,
p_value03   IN    VARCHAR2 DEFAULT,
...
p_value50   IN    VARCHAR2 DEFAULT,
p_col_sep   IN    VARCHAR2 DEFAULT)
RETURN VARCHAR2;

Parameters

Table 15-81 describes the parameters available in the MD5_HIDDEN function.

Table 15-81 MD5_HIDDEN Parameters

Parameter

Description

p_idx

Indicates the form element to be generated. For example, 1 equals F01 and 2 equals F02. Typically the p_idx parameter is constant for a given column

p_value01

...

p_value50

Fifty available inputs. Parameters not supplied default to null

p_col_sep

String used to separate p_value inputs. Defaults to the pipe symbol (|)

Example

The p_idx parameter specifies the FXX form element to be generated. In the following example, 7 generates F07. Also note that an HTML hidden form element will be generated.

SELECT APEX_ITEM.MD5_HIDDEN(7,ename,job,sal), ename, job, sal FROM emp

MULTI_ROW_UPDATE Procedure

Use this procedure within a Multi Row Update process type. This procedure takes a string containing a multiple row update definition in the following format:

OWNER:TABLE:pk_column1,pk_idx:pk_column2,pk_idx2|col,idx:col,idx...

Syntax

APEX_ITEM.MULTI_ROW_UPDATE(
p_mru_string    IN    VARCHAR2 DEFAULT)
RETURN VARCHAR2;

Example

To use this procedure indirectly within an application-level process, you need to create a query to generate a form of database data. The following example demonstrates how to create a multiple row update on the emp table.

SELECT
empno,
APEX_ITEM.HIDDEN(1,empno),
APEX_ITEM.HIDDEN(2,deptno),
APEX_ITEM.TEXT(3,ename),
APEX_ITEM.SELECT_LIST_FROM_QUERY(4,job,'SELECT DISTINCT job FROM emp'),
APEX_ITEM.TEXT(5,sal),
APEX_ITEM.TEXT(7,comm),
APEX_ITEM.MD5_CHECKSUM(ename,job,sal,comm),
deptno
FROM emp
WHERE deptno = 20

Note the call to APEX_ITEM.MD5_CHECKSUM, instead of APEX_ITEM.MD5_HIDDEN. Since APEX_ITEM.MULTI_ROW_UPDATE gets the checksum from APEX_APPLICATION.G_FCS, you need to call APEX_ITEM.MD5_CHECKSUM in order to populate APEX_APPLICATION.G_FCS when the page is submitted. Additionally, the columns in APEX_ITEM.MD5_CHECKSUM must be in the same order those in the MULTI_ROW_UPDATE process. These updates can then processed (or applied to the database) using an after submit page process of Multi Row Update in a string similar to the following:

SCOTT:emp:empno,1:deptno,2|ename,3:job,4:sal,5:comm,7:,:,:,:,

POPUP_FROM_LOV Function

This function generates an HTML popup select list from an application list of values (LOV). Similar from other available functions in the APEX_ITEM package, POPUP_FROM_LOV function is designed to generate forms with F01 to F50 form array elements.

Syntax

APEX_ITEM.POPUP_FROM_LOV(

p_idx              IN    NUMBER,
p_value            IN    VARCHAR2 DEFAULT,
p_lov_name         IN    VARCHAR2,
p_width            IN    VARCHAR2 DEFAULT,
p_max_length       IN    VARCHAR2 DEFAULT,
p_form_index       IN    VARCHAR2 DEFAULT,
p_escape_html      IN    VARCHAR2 DEFAULT,
p_max_elements     IN    VARCHAR2 DEFAULT,
p_attributes       IN    VARCHAR2 DEFAULT,
p_ok_to_query      IN    VARCHAR2 DEFAULT,
p_item_id          IN    VARCHAR2 DEFAULT NULL,
p_item_label       IN    VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 15-82 describes the some parameters in the POPUP_FROM_LOV function.

Table 15-82 POPUP_FROM_LOV Parameters

Parameter

Description

p_idx

Form element name. For example, 1 equals F01 and 2 equals F02. Typically, p_idx is a constant for a given column

p_value

Form element current value. This value should be one of the values in the p_lov_name parameter

p_lov_name

Named LOV used for this popup

p_width

Width of the text box

p_max_length

Maximum number of characters that can be entered in the text box

p_form_index

HTML form on the page in which an item is contained. Defaults to 0 and rarely used.

Only use this parameter when it is necessary to embed a custom form in your page template (such as a search field that posts to a different Web site). If this form comes before the #FORM_OPEN# substitution string, then its index is zero and the form opened automatically by Oracle Application Express must be referenced as form 1. This functionality supports the JavaScript used in the popup LOV that passes a value back to a form element.

p_escape_html

Replacements for special characters that require an escaped equivalent:

- &lt; for <

- &gt; for >

- &amp; for &

Range of values is YES and NO. If YES, special characters will be escaped. This parameter is useful if you know your query will return illegal HTML.

p_max_elements

Limit on the number of rows that can be returned by your query. Limits the performance impact of user searches. By entering a value in this parameter, you force the user to search for a narrower set of results.

p_attributes

Additional HTML attributes to use for the form item.

p_ok_to_query

Range of values is YES and NO. If YES, a popup returns first set of rows for the LOV. If NO, a search is initiated to return rows.

p_item_id

ID attribute of the form element.

p_item_label

Invisible label created for the item.

Example

The following example demonstrates a sample query the generates a popup from an LOV named DEPT.

SELECT APEX_ITEM.POPUP_FROM_LOV (1,deptno,'DEPT_LOV') dt
FROM emp

POPUP_FROM_QUERY Function

This function generates an HTML popup select list from a query. Like other available functions in the APEX_ITEM package, the POPUP_FROM_QUERY function is designed to generate forms with F01 to F50 form array elements.

Syntax

APEX_ITEM.POPUP_FROM_QUERY(

p_idx              IN    NUMBER,
p_value            IN    VARCHAR2 DEFAULT,
p_lov_query        IN    VARCHAR2,
p_width            IN    VARCHAR2 DEFAULT,
p_max_length       IN    VARCHAR2 DEFAULT,
p_form_index       IN    VARCHAR2 DEFAULT,
p_escape_html      IN    VARCHAR2 DEFAULT,
p_max_elements     IN    VARCHAR2 DEFAULT,
p_attributes       IN    VARCHAR2 DEFAULT,
p_ok_to_query      IN    VARCHAR2 DEFAULT,
p_item_id          IN    VARCHAR2 DEFAULT NULL,
p_item_label       IN    VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 15-83 describes the parameters in the POPUP_FROM_QUERY function.

Table 15-83 POPUP_FROM_QUERY Parameters

Parameter

Description

p_idx

Form element name. For example, 1 equals F01 and 2 equals F02. Typically, p_idx is a constant for a given column.

p_value

Form element current value. This value should be one of the values in the p_lov_query parameter.

p_lov_query

SQL query that is expected to select two columns (a display column and a return column). For example:

SELECT dname, deptno FROM dept

p_width

Width of the text box.

p_max_length

Maximum number of characters that can be entered in the text box.

p_form_index

HTML form on the page in which an item is contained. Defaults to 0 and rarely used.

Only use this parameter when it is necessary to embed a custom form in your page template (such as a search field that posts to a different Web site). If this form comes before the #FORM_OPEN# substitution string, then its index is zero and the form opened automatically by Oracle Application Express must be referenced as form 1. This functionality supports the JavaScript used in the popup LOV that passes a value back to a form element.

p_escape_html

Replacements for special characters that require an escaped equivalent.

- &lt; for <

- &gt; for >

- &amp; for &

Range of values is YES and NO. If YES, special characters will be escaped. This parameter is useful if you know your query will return illegal HTML.

p_max_elements

Limit on the number of rows that can be returned by your query. Limits the performance impact of user searches. By entering a value in this parameter, you force the user to search for a narrower set of results.

p_attributes

Additional HTML attributes to use for the form item.

p_ok_to_query

Range of values is YES and NO. If YES, a popup returns the first set of rows for the LOV. If NO, a search is initiated to return rows.

p_item_id

ID attribute of the form element.

p_item_label

Invisible label created for the item.

Example

The following example demonstrates a sample query the generates a popup select list from the emp table.

SELECT APEX_ITEM.POPUP_FROM_QUERY (1,deptno,'SELECT dname, deptno FROM dept') dt
FROM emp

POPUPKEY_FROM_LOV Function

This function generates a popup key select list from a shared list of values (LOV). Similar to other available functions in the APEX_ITEM package, the POPUPKEY_FROM_LOV function is designed to generate forms with F01 to F50 form array elements.

Syntax

APEX_ITEM.POPUPKEY_FROM_LOV(
p_idx              IN    NUMBER,
p_value            IN    VARCHAR2 DEFAULT,
p_lov_name         IN    VARCHAR2,
p_width            IN    VARCHAR2 DEFAULT,
p_max_length       IN    VARCHAR2 DEFAULT,
p_form_index       IN    VARCHAR2 DEFAULT,
p_escape_html      IN    VARCHAR2 DEFAULT,
p_max_elements     IN    VARCHAR2 DEFAULT,
p_attributes       IN    VARCHAR2 DEFAULT,
p_ok_to_query      IN    VARCHAR2 DEFAULT,
RETURN VARCHAR2;

Although the text field associated with the popup displays in the first column in the LOV query, the actual value is specified in the second column in the query.

Parameters

Table 15-84 describes the some parameters in the POPUPKEY_FROM_LOV function.

Table 15-84 POPUPKEY_FROM_LOV Parameters

Parameter

Description

p_idx

Identifies a form element name. For example, 1 equals F01 and 2 equals F02. Typically, p_idx is a constant for a given column

Because of the behavior of POPUPKEY_FROM_QUERY, the next index value should be p_idx + 1. For example:

SELECT APEX_ITEM.POPUPKEY_FROM_LOV (1,deptno,'DEPT') dt,
APEX_ITEM.HIDDEN(3,empno) eno

p_value

Indicates the current value. This value should be one of the values in the P_LOV_NAME parameter.

p_lov_name

Identifies a named LOV used for this popup.

p_width

Width of the text box.

p_max_length

Maximum number of characters that can be entered in the text box.

p_form_index

HTML form on the page in which an item is contained. Defaults to 0 and rarely used.

Only use this parameter when it is necessary to embed a custom form in your page template (such as a search field that posts to a different Web site). If this form comes before the #FORM_OPEN# substitution string, then its index is zero and the form opened automatically by Oracle Application Express must be referenced as form 1. This functionality supports the JavaScript used in the popup LOV that passes a value back to a form element.

p_escape_html

Replacements for special characters that require an escaped equivalent.

- &lt; for <

- &gt; for >

- &amp; for &

This parameter is useful if you know your query will return illegal HTML.

p_max_elements

Limit on the number of rows that can be returned by your query. Limits the performance impact of user searches. By entering a value in this parameter, you force the user to search for a narrower set of results.

p_attributes

Additional HTML attributes to use for the form item.

p_ok_to_query

Range of values is YES and NO. If YES, a popup returns the first set of rows for the LOV. If NO, a search is initiated to return rows.

Example

The following example demonstrates how to generate a popup key select list from a shared list of values (LOV).

SELECT APEX_ITEM.POPUPKEY_FROM_LOV (1,deptno,'DEPT') dt
FROM emp

POPUPKEY_FROM_QUERY Function

This function generates a popup key select list from a SQL query. Similar to other available functions in the APEX_ITEM package, the POPUPKEY_FROM_QUERY function is designed to generate forms with F01 to F50 form array elements.

Syntax

APEX_ITEM.POPUPKEY_FROM_QUERY(
p_idx              IN    NUMBER,
p_value            IN    VARCHAR2 DEFAULT,
p_lov_query        IN    VARCHAR2,
p_width            IN    VARCHAR2 DEFAULT,
p_max_length       IN    VARCHAR2 DEFAULT,
p_form_index       IN    VARCHAR2 DEFAULT,
p_escape_html      IN    VARCHAR2 DEFAULT,
p_max_elements     IN    VARCHAR2 DEFAULT,
p_attributes       IN    VARCHAR2 DEFAULT,
p_ok_to_query      IN    VARCHAR2 DEFAULT,
p_item_id          IN    VARCHAR2 DEFAULT NULL,
p_item_label       IN    VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 15-85 describes the some parameters in the POPUPKEY_FROM_QUERY function.

Table 15-85 POPUPKEY_FROM_QUERY Parameters

Parameter

Description

p_idx

Form element name. For example, 1 equals F01 and 2 equals F02. Typically, p_idx is a constant for a given column.

Because of the behavior of POPUPKEY_FROM_QUERY, the next index value should be p_idx + 1. For example:

SELECT APEX_ITEM.POPUPKEY_FROM_QUERY (1,deptno,'SELECT dname, deptno FROM dept') dt,
APEX_ITEM.HIDDEN(3,empno) eno

p_value

Form element current value. This value should be one of the values in the P_LOV_QUERY parameter.

p_lov_query

LOV query used for this popup.

p_width

Width of the text box.

p_max_length

Maximum number of characters that can be entered in the text box.

p_form_index

HTML form on the page in which an item is contained. Defaults to 0 and rarely used.

Only use this parameter when it is necessary to embed a custom form in your page template (such as a search field that posts to a different Web site). If this form comes before the #FORM_OPEN# substitution string, then its index is zero and the form opened automatically by Oracle Application Express must be referenced as form 1. This functionality supports the JavaScript used in the popup LOV that passes a value back to a form element.

p_escape_html

Replacements for special characters that require an escaped equivalent.

- &lt; for <

- &gt; for >

- &amp; for &

This parameter is useful if you know your query will return illegal HTML.

p_max_elements

Limit on the number of rows that can be returned by your query. Limits the performance impact of user searches. By entering a value in this parameter, you force the user to search for a narrower set of results.

p_attributes

Additional HTML attributes to use for the form item.

p_ok_to_query

Range of values is YES and NO. If YES, a popup returns first set of rows for the LOV. If NO, a search is initiated to return rows.

p_item_id

ID attribute of the form element.

p_item_label

Invisible label created for the item.

Example

The following example demonstrates how to generate a popup select list from a SQL query.

SELECT APEX_ITEM.POPUPKEY_FROM_QUERY (1,deptno,'SELECT dname, deptno FROM dept') dt
FROM emp

RADIOGROUP Function

This function generates a radio group from a SQL query.

Syntax

APEX_ITEM.RADIOGROUP(
p_idx              IN    NUMBER,
p_value            IN    VARCHAR2 DEFAULT,
p_selected_value   IN    VARCHAR2 DEFAULT,
p_display          IN    VARCHAR2 DEFAULT,
p_attributes       IN    VARCHAR2 DEFAULT,
p_onblur           IN    VARCHAR2 DEFAULT,
p_onchange         IN    VARCHAR2 DEFAULT,
p_onfocus          IN    VARCHAR2 DEFAULT,)
RETURN VARCHAR2;

Parameters

Table 15-86 describes the parameters available in the RADIOGROUP function.

Table 15-86 RADIOGROUP Parameters

Parameter

Description

p_idx

Number that determines which APEX_APPLICATION global variable will be used. Valid range of values is 1 to 50.For example 1 creates F01 and 2 creates F02.

p_value

Value of the radio group.

p_selected_value

Value that should be selected.

p_display

Text to display next to the radio option.

p_attributes

Extra HTML parameters you want to add.

p_onblur

JavaScript to execute in the onBlur event.

p_onchange

JavaScript to execute in the onChange event.

p_onfocus

JavaScript to execute in the onFocus event.

Example

The following example demonstrates how to select department 20 from the emp table as a default in a radio group.

SELECT APEX_ITEM.CHECKBOX(1,deptno,'20',dname) dt
FROM   dept
ORDER  BY 1

SELECT_LIST Function

This function dynamically generates a static select list. Similar to other functions available in the APEX_ITEM package, these select list functions are designed to generate forms with F01 to F50 form array elements.

Syntax

APEX_ITEM.SELECT_LIST(
p_idx           IN   NUMBER,
p_value         IN   VARCHAR2 DEFAULT,
p_list_values   IN   VARCHAR2 DEFAULT,
p_attributes    IN   VARCHAR2 DEFAULT,
p_show_null     IN   VARCHAR2 DEFAULT,
p_null_value    IN   VARCHAR2 DEFAULT,
p_null_text     IN   VARCHAR2 DEFAULT,
p_item_id       IN   VARCHAR2 DEFAULT,
p_item_label    IN   VARCHAR2 DEFAULT,
p_show_extra    IN   VARCHAR2 DEFAULT)
RETURN VARCHAR2;

Parameters

Table 15-87 describes the parameters available in the SELECT_LIST function.

Table 15-87 SELECT_LIST Parameters

Parameter

Description

p_idx

Form element name. For example, 1 equals F01 and 2 equals F02. Typically the P_IDX parameter is constant for a given column.

p_value

Current value. This value should be a value in the P_LIST_VALUES parameter.

p_list_values

List of static values separated by commas. Displays values and returns values that are separated by semicolons.

Note that this is only available in the SELECT_LIST function.

p_attributes

Extra HTML parameters you want to add.

p_show_null

Extra select option to enable the NULL selection. Range of values is YES and NO.

p_null_value

Value to be returned when a user selects the null option. Only relevant when p_show_null equals YES.

p_null_text

Value to be displayed when a user selects the null option. Only relevant when p_show_null equals YES.

p_item_id

HTML attribute ID for the <input> tag.

p_item_label

Label of the select list.

p_show_extra

Shows the current value even if the value of p_value is not located in the select list.

Example

The following example demonstrates a static select list that displays Yes, returns Y, defaults to Y, and generates a F01 form item.

SELECT APEX_ITEM.SELECT_LIST(1,'Y','Yes;Y,No;N')
FROM emp

SELECT_LIST_FROM_LOV Function

This function dynamically generates select lists from a shared list of values (LOV). Similar to other functions available in the APEX_ITEM package, these select list functions are designed to generate forms with F01 to F50 form array elements.

Syntax

APEX_ITEM.SELECT_LIST_FROM_LOV(
p_idx           IN   NUMBER,
p_value         IN   VARCHAR2 DEFAULT,
p_lov           IN   VARCHAR2,
p_attributes    IN   VARCHAR2 DEFAULT,
p_show_null     IN   VARCHAR2 DEFAULT,
p_null_value    IN   VARCHAR2 DEFAULT,
p_null_text     IN   VARCHAR2 DEFAULT,
p_item_id       IN   VARCHAR2 DEFAULT,
p_item_label    IN   VARCHAR2 DEFAULT)
RETURN VARCHAR2;

Parameters

Table 15-88 describes the parameters available in the SELECT_LIST_FROM_LOV function.

Table 15-88 SELECT_LIST_FROM_LOV Parameters

Parameter

Description

p_idx

Form element name. For example, 1 equals F01 and 2 equals F02. Typically, the p_idx parameter is constant for a given column.

p_value

Current value. This value should be a value in the p_lov parameter.

p_lov

Text name of an application list of values. This list of values must be defined in your application. This parameter is used only by the select_list_from_lov function.

p_attributes

Extra HTML parameters you want to add.

p_show_null

Extra select option to enable the NULL selection. Range of values is YES and NO.

p_null_value

Value to be returned when a user selects the null option. Only relevant when p_show_null equals YES.

p_null_text

Value to be displayed when a user selects the null option. Only relevant when p_show_null equals YES.

p_item_id

HTML attribute ID for the <input> tag.

p_item_label

Label of the select list.

Example

The following example demonstrates a select list based on an LOV defined in the application.

SELECT APEX_ITEM.SELECT_LIST_FROM_LOV(2,job,'JOB_FLOW_LOV')
FROM emp

SELECT_LIST_FROM_LOV_XL Function

This function dynamically generates very large select lists (greater than 32K) from a shared list of values (LOV). Similar to other functions available in the APEX_ITEM package, these select list functions are designed to generate forms with F01 to F50 form array elements. This function is the same as SELECT_LIST_FROM_LOV, but its return value is CLOB. This enables you to use it in SQL queries where you need to handle a column value longer than 4000 characters.

Syntax

APEX_ITEM.SELECT_LIST_FROM_LOV_XL(
p_idx           IN   NUMBER,
p_value         IN   VARCHAR2 DEFAULT,
p_lov           IN   VARCHAR2,
p_attributes    IN   VARCHAR2 DEFAULT,
p_show_null     IN   VARCHAR2 DEFAULT,
p_null_value    IN   VARCHAR2 DEFAULT,
p_null_text     IN   VARCHAR2 DEFAULT,
p_item_id       IN   VARCHAR2 DEFAULT,
p_item_label    IN   VARCHAR2 DEFAULT)
RETURN CLOB;

Parameters

Table 15-89 describes the parameters available in the SELECT_LIST_FROM_LOV_XL function.

Table 15-89 SELECT_LIST_FROM_LOV_XL Parameters

Parameter

Description

p_idx

Form element name. For example, 1 equals F01 and 2 equals F02. Typically, the p_idx parameter is constant for a given column.

p_value

Current value. This value should be a value in the p_lov parameter.

p_lov

Text name of a list of values. This list of values must be defined in your application. This parameter is used only by the select_list_from_lov function.

p_attributes

Extra HTML parameters you want to add.

p_show_null

Extra select option to enable the NULL selection. Range of values is YES and NO.

p_null_value

Value to be returned when a user selects the null option. Only relevant when p_show_null equals YES.

p_null_text

Value to be displayed when a user selects the null option. Only relevant when p_show_null equals YES.

p_item_id

HTML attribute ID for the <input> tag.

p_item_label

Label of the select list.

Example

The following demonstrates a select list based on an LOV defined in the application.

SELECT APEX_ITEM.SELECT_LIST_FROM_LOV_XL(2,job,'JOB_FLOW_LOV')
FROM emp

SELECT_LIST_FROM_QUERY Function

This function dynamically generates a select list from a query. Similar to other functions available in the APEX_ITEM package, these select list functions are designed to generate forms with F01 to F50 form array elements.

Syntax

APEX_ITEM.SELECT_LIST_FROM_QUERY(
p_idx           IN    NUMBER,
p_value         IN    VARCHAR2 DEFAULT,
p_query         IN    VARCHAR2,
p_attributes    IN    VARCHAR2 DEFAULT,
p_show_null     IN    VARCHAR2 DEFAULT,
p_null_value    IN    VARCHAR2 DEFAULT,
p_null_text     IN    VARCHAR2 DEFAULT,
p_item_id       IN    VARCHAR2 DEFAULT,
p_item_label    IN    VARCHAR2 DEFAULT,
p_show_extra    IN    VARCHAR2 DEFAULT)
RETURN VARCHAR2;

Parameters

Table 15-90 describes the parameters available in the SELECT_LIST_FROM_QUERY function.

Table 15-90 SELECT_LIST_FROM_QUERY Parameters

Parameter

Description

p_idx

Form element name. For example, 1 equals F01 and 2 equals F02. Typically, the p_idx parameter is constant for a given column.

p_value

Current value. This value should be a value in the p_query parameter.

p_query

SQL query that is expected to select two columns, a display column, and a return column. For example:

SELECT dname, deptno FROM dept

Note that this is used only by the SELECT_LIST_FROM_QUERY function.

p_attributes

Extra HTML parameters you want to add.

p_show_null

Extra select option to enable the NULL selection. Range of values is YES and NO.

p_null_value

Value to be returned when a user selects the null option. Only relevant when p_show_null equals YES.

p_null_text

Value to be displayed when a user selects the null option. Only relevant when p_show_null equals YES.

p_item_id

HTML attribute ID for the <input> tag.

p_item_label

Label of the select list.

p_show_extra

Show the current value even if the value of p_value is not located in the select list.

Example

The following example demonstrates a select list based on a SQL query.

SELECT APEX_ITEM.SELECT_LIST_FROM_QUERY(3,job,'SELECT DISTINCT job FROM emp')
FROM emp

SELECT_LIST_FROM_QUERY_XL Function

This function is the same as SELECT_LIST_FROM_QUERY, but its return value is a CLOB. This allows its use in SQL queries where you need to handle a column value longer than 4000 characters. Similar to other functions available in the APEX_ITEM package, these select list functions are designed to generate forms with F01 to F50 form array elements.

Syntax

APEX_ITEM.SELECT_LIST_FROM_QUERY_XL(
p_idx           IN    NUMBER,
p_value         IN    VARCHAR2 DEFAULT,
p_query         IN    VARCHAR2,
p_attributes    IN    VARCHAR2 DEFAULT,
p_show_null     IN    VARCHAR2 DEFAULT,
p_null_value    IN    VARCHAR2 DEFAULT,
p_null_text     IN    VARCHAR2 DEFAULT,
p_item_id       IN    VARCHAR2 DEFAULT,
p_item_label    IN    VARCHAR2 DEFAULT,
p_show_extra    IN    VARCHAR2 DEFAULT)
RETURN CLOB;

Parameters

Table 15-91 describes the parameters available in the SELECT_LIST_FROM_QUERY_XL function.

Table 15-91 SELECT_LIST_FROM_QUERY_XL Parameters

Parameter

Description

p_idx

Form element name. For example, 1 equals F01 and 2 equals F02. Typically the p_idx parameter is constant for a given column.

p_value

Current value. This value should be a value in the p_query parameter.

p_query

SQL query that is expected to select two columns, a display column, and a return column. For example:

SELECT dname, deptno FROM dept

Note that this is used only by the SELECT_LIST_FROM_QUERY_XL function.

p_attributes

Extra HTML parameters you want to add.

p_show_null

Extra select option to enable the NULL selection. Range of values is YES and NO.

p_null_value

Value to be returned when a user selects the null option. Only relevant when p_show_null equals YES.

p_null_text

Value to be displayed when a user selects the null option. Only relevant when p_show_null equals YES.

p_item_id

HTML attribute ID for the <input> tag.

p_item_label

Label of the select list.

p_show_extra

Show the current value even if the value of p_value is not located in the select list.

Example

The following example demonstrates a select list based on a SQL query.

SELECT APEX_ITEM.SELECT_LIST_FROM_QUERY_XL(3,job,'SELECT DISTINCT job FROM emp')
FROM emp

TEXTAREA Function

This function creates text areas.

Syntax

APEX_ITEM.TEXTAREA(
p_idx         IN    NUMBER,
p_value       IN    VARCHAR2 DEFAULT NULL,
p_rows        IN    NUMBER DEAULT 40,
p_cols        IN    NUMBER DEFAULT 4
p_attributes  IN    VARCHAR2 DEFAULT,
p_item_id     IN    VARCHAR2 DEFAULT NULL,
p_item_label  IN    VARCHAR2 DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 15-92 describes the parameters available in the TEXTAREA function.

Table 15-92 TEXTAREA Parameters

Parameter

Description

p_idx

Number to identify the item you want to generate. The number will determine which G_FXX global is populated.

See Also: "APEX_APPLICATION"

p_value

Value of the text area item.

p_rows

Height of the text area (HTML rows attribute)

p_cols

Width of the text area (HTML column attribute).

p_attributes

Extra HTML parameters you want to add.

p_item_id

HTML attribute ID for the <input> tag.

p_item_label

Label of the text area item.

Example

The following example demonstrates how to create a text area based on a SQL query.

SELECT APEX_ITEM.TEXTAREA(3,ename,5,80) a
FROM emp

TEXT Function

This function generates text fields (or text input form items) from a SQL query.

Syntax

APEX_ITEM.TEXT(
p_idx         IN    NUMBER,
p_value       IN    VARCHAR2 DEFAULT NULL,
p_size        IN    NUMBER DEFAULT NULL,
p_maxlength   IN    NUMBER DEFAULT NULL,
p_attributes  IN    VARCHAR2 DEFAULT NULL,
p_item_id     IN    VARCHAR2 DEFAULT NULL,
p_item_label  IN    VARCHAR2 DEFAULT NULL)

Parameters

Table 15-93 describes the parameters available in the TEXT function.

Table 15-93 TEXT Parameters

Parameter

Description

p_idx

Number to identify the item you want to generate. The number will determine which G_FXX global is populated.

See Also: "APEX_APPLICATION"

p_value

Value of a text field item.

p_size

Controls HTML tag attributes (such as disabled).

p_maxlength

Maximum number of characters that can be entered in the text box.

p_attributes

Extra HTML parameters you want to add.

p_item_id

HTML attribute ID for the <input> tag.

p_item_label

Label of the text field item.

Example

The following sample query demonstrates how to generate one update field for each row. Note that the ename, sal, and comm columns use the APEX_ITEM.TEXT function to generate an HTML text field for each row. Also, notice that each item in the query is passed a unique p_idx parameter to ensure that each column is stored in its own array.

SELECT
empno,
APEX_ITEM.HIDDEN(1,empno)||
APEX_ITEM.TEXT(2,ename) ename,
APEX_ITEM.TEXT(3,job) job,
mgr,
APEX_ITEM.DATE_POPUP(4,rownum,hiredate,'dd-mon-yyyy') hiredate,
APEX_ITEM.TEXT(5,sal) sal,
APEX_ITEM.TEXT(6,comm) comm,
deptno
FROM emp
ORDER BY 1

TEXT_FROM_LOV Function

Use this function to display an item as text, deriving the display value of the named LOV.

Syntax

APEX_ITEM.TEXT_FROM_LOV (
p_value       IN    VARCHAR2 DEFAULT NULL,
p_lov         IN    VARCHAR2,
p_null_text   IN    VARCHAR2 DEFAULT '%')
RETURN VARCHAR2;

Parameters

Table 15-94 describes the parameters available in the TEXT_FROM_LOV function.

Table 15-94 TEXT_FROM_LOV Parameters

Parameter

Description

p_value

Value of a field item.

Note that if p_value is not located in the list of values, p_null_text is value displayedf .

p_lov

Text name of a shared list of values. This list of values must be defined in your application.

p_null_text

Value displayed when the value of the field item is NULL.

Example

The following example demonstrates how to derive the display value from a named LOV (EMPNO_ENAME_LOV).

SELECT APEX_ITEM.TEXT_FROM_LOV(empno,'EMPNO_ENAME_LOV') c FROM emp

TEXT_FROM_LOV_QUERY Function

Use this function to display an item as text, deriving the display value from a list of values query.

Syntax

APEX_ITEM.TEXT_FROM_LOV_QUERY (
p_value       IN    VARCHAR2 DEFAULT NULL,
p_query       IN    VARCHAR2,
p_null_text   IN    VARCHAR2 DEFAULT '%')
RETURN VARCHAR2;

Parameters

Table 15-95 describes the parameters available in the TEXT_FROM_LOV_QUERY function.

Table 15-95 TEXT_FROM_LOV_QUERY Parameters

Parameter

Description

p_value

Value of a field item.

p_query

SQL query that is expected to select two columns, a display column and a return column. For example:

SELECT dname, deptno FROM dept

p_null_text

Value to be displayed when the value of the field item is null or a corresponding entry is not located for the value p_value in the list of values query.

Example

The following example demonstrates how to derive the display value from a query.

SELECT APEX_ITEM.TEXT_FROM_LOV_QUERY(empno,'SELECT ename, empno FROM emp') c from emp

APEX_APPLICATION

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

Table 15-96 Global Variables Available in APEX_APPLICATION

Global Variable

Description

G_USER

Specifies the currently logged in user.

G_FLOW_ID

Specifies the ID of the currently running application.

G_FLOW_STEP_ID

Specifies the ID of the currently running page.

G_FLOW_OWNER

Specifies the schema to parse for the currently running application.

G_REQUEST

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

Topics in this section include:

- Referencing Arrays

- Referencing Values Within an On Submit Process

- Converting an Array to a Single Value

Referencing Arrays

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

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

<INPUT TYPE="text" NAME="F01" SIZE="32" MAXLENGTH="32" VALUE="some value">

<TEXTAREA NAME="F02" ROWS=4 COLS=90 WRAP="VIRTUAL">this is the example of a text area.</TEXTAREA>

<SELECT NAME="F03" SIZE="1">
<OPTION VALUE="abc">abc
<OPTION VALUE="123">123
</SELECT>

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

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

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

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

Referencing Values Within an On Submit Process

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

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

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

Converting an Array to a Single Value

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

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

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

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

APEX_CUSTOM_AUTH

You can use the APEX_CUSTOM_AUTH package to perform various operations related to authentication and session management.

Topics in this section include:

- APPLICATION_PAGE_ITEM_EXISTS Function

- CURRENT_PAGE_IS_PUBLIC Function

- DEFINE_USER_SESSION Procedure

- GET_COOKIE_PROPS Procedure

- GET_LDAP_PROPS Procedure

- GET_NEXT_SESSION_ID Function

- GET_SESSION_ID_FROM_COOKIE Function

- GET_USERNAME Function

- GET_SECURITY_GROUP_ID Function

- GET_SESSION_ID Function

- GET_USER Function

- IS_SESSION_VALID Function

- LOGIN Procedure

- LOGOUT Procedure

- POST_LOGIN Procedure

- SESSION_ID_EXISTS Function

- SET_USER Procedure

- SET_SESSION_ID Procedure

- SET_SESSION_ID_TO_NEXT_VALUE Procedure

APPLICATION_PAGE_ITEM_EXISTS Function

This function checks for the existence of page-level item within an application. This function requires the parameter p_item_name. This function returns a Boolean value (true or false).

Syntax

FUNCTION APPLICATION_PAGE_ITEM_EXISTS(
p_item_name   IN    VARCHAR2)
RETURN BOOLEAN;

CURRENT_PAGE_IS_PUBLIC Function

This function checks whether the current page's authentication attribute is set to Page Is Public and returns a Boolean value (true or false)

See Also:
"Editing Page Attributes" and "Security" for information about setting this page attribute

Syntax

FUNCTION CURRENT_PAGE_IS_PUBLIC
RETURN BOOLEAN;

DEFINE_USER_SESSION Procedure

This procedure combines the SET_USER and SET_SESSION_ID functions to create one call.

Syntax

PROCEDURE DEFINE_USER_SESSION(
p_user         IN    VARCHAR2)
p_session_id   IN    NUMBER);

GET_COOKIE_PROPS Procedure

This procedure obtains the properties of the session cookie used in the current authentication scheme for the specified application. These properties can be viewed directly in the Application Builder by viewing the authentication scheme attributes.

Syntax

APEX_CUSTOM_AUTH.GET_COOKIE_PROPS(
p_app_id                       IN  NUMBER,
p_cookie_name                  OUT VARCHAR2,
p_cookie_path                  OUT VARCHAR2,
p_cookie_domain                OUT VARCHAR2);

Parameters

Table 15-97 describes the parameters available in the GET_COOKIE_PROPS procedure.

Table 15-97 GET_COOKIE_PROPS Parameters

Parameter

Description

p_app_id

An application ID in the current workspace.

p_cookie_name

The cookie name.

p_cookie_path

The cookie path.

p_cookie_domain

The cookie domain.

Example

DECLARE
l_cookie_name   varchar2(256);
l_cookie_path   varchar2(256);
l_cookie_domain varchar2(256);
BEGIN
APEX_CUSTOM_AUTH.GET_COOKIE_PROPS (
p _cookie_name   => l_cookie_name,
p _cookie_path   => l_cookie_path,
p _cookie_domain => l_cookie_domain);
END;

GET_LDAP_PROPS Procedure

This procedure obtains the LDAP attributes of the current authentication scheme for the current application. These properties can be viewed directly in Application Builder by viewing the authentication scheme attributes.

Syntax

APEX_CUSTOM_AUTH.GET_LDAP_PROPS(
p_ldap_host                OUT VARCHAR2,
p_ldap_port                OUT NUMBER,
p_ldap_dn                  OUT VARCHAR2,
p_ldap_edit_function       OUT VARCHAR2);

Parameters

Table 15-98 describes the parameters available in the GET_LDAP_PROPS procedure.

Table 15-98 GET_LDAP_PROPS Parameters

Parameter

Description

p_ldap_host

LDAP host name.

p_ldap_port

LDAP port number.

p_ldap_dn

LDAP DN string.

p_ldap_edit_function

LDAP edit function name.

Example

DECLARE
l_ldap_host          varchar2(256);
l_ldap_port          number;
l_ldap_dn            varchar2(256);
l_ldap_edit_function varchar2(256);
BEGIN
APEX_CUSTOM_AUTH.GET_LDAP_PROPS (
p_ldap_host       => l_ldap_host,
p_ldap_port       => l_ldap_port,
p_ldap_dn         => l_ldap_dn,'
p_ldap_edit_function => l_ldap_edit_function);
END;

GET_NEXT_SESSION_ID Function

This function generates the next session ID from the Oracle Application Express sequence generator. This function returns a number.

Syntax

FUNCTION GET_NEXT_SESSION_ID
RETURN NUMBER;

GET_SESSION_ID_FROM_COOKIE Function

This function returns the Oracle Application Express session ID located by the session cookie in the context of a page request in the current browser session.

Syntax

APEX_CUSTOM_AUTH.GET_SESSION_ID_FROM_COOKIE
RETURN NUMBER;

Example

DECLARE VAL NUMBER;
BEGIN
VAL := APEX_CUSTOM_AUTH.GET_SESSION_ID_FROM_COOKIE;
END;

GET_USERNAME Function

This function returns user name registered with the current Oracle Application Express session in the internal sessions table. This user name is usually the same as the authenticated user running the current page.

Syntax

APEX_CUSTOM_AUTH.GET_USERNAME
RETURN VARCHAR2;

Example

DECLARE VAL VARCHAR2(256);
BEGIN
VAL := APEX_CUSTOM_AUTH.GET_USERNAME;
END;

GET_SECURITY_GROUP_ID Function

This function returns a number with the value of the security group ID that identifies the workspace of the current user.

Syntax

FUNCTION GET_SECURITY_GROUP_ID
RETURN NUMBER;

GET_SESSION_ID Function

This function returns APEX_APPLICATION.G_INSTANCE global variable. GET_SESSION_ID returns a number.

Syntax

PROCEDURE GET_SESSION_ID
RETURN NUMBER;

GET_USER Function

This function returns the APEX_APPLICATION.G_USER global variable (VARCHAR2).

Syntax

FUNCTION GET_USER
RETURN VARCHAR2;

IS_SESSION_VALID Function

This function is a Boolean result obtained from executing the current application's authentication scheme to determine if a valid session exists. This function returns the Boolean result of the authentication scheme's page sentry.

Syntax

APEX_CUSTOM_AUTH.IS_SESSION_VALID
RETURN BOOLEAN;

Example

DECLARE VAL BOOLEAN;
BEGIN
VAL := APEX_CUSTOM_AUTH.IS_SESSION_VALID;
END;

LOGIN Procedure

Also referred to as the "Login API," this procedure performs authentication and session registration.

Syntax

APEX_CUSTOM_AUTH.LOGIN(
p_uname                    IN  VARCHAR2,
p_password                 IN  VARCHAR2,
p_session_id               IN  VARCHAR2,
p_app_page                 IN  VARCHAR2,
p_entry_point              IN  VARCHAR2,
p_preserve_case            IN  BOOLEAN);

Parameter

Table 15-99 describes the parameters available in the LOGIN procedure.

Table 15-99 LOGIN Parameters

Parameter

Description

p_uname

Login name of the user.

p_password

Clear text user password.

p_session_id

Current Oracle Application Express session ID.

p_app_page

Current application ID. After login page separated by a colon (:).

p_entry_point

Internal use only.

p_preserve_case

If true, do not upper p_uname during session registration

Example

BEGIN
APEX_CUSTOM_AUTH.LOGIN (
p_uname       => 'SCOTT',
p_password    => 'secret99',
p_session_id  => V('APP_SESSION'),
p_app_page    => :APP_ID||':1');
END;

Note:
:Do not use bind variable notations for p_session_id argument.

LOGOUT Procedure

This procedure effects a logout from the current session by unsetting the session cookie and redirecting to a new location.

Syntax

APEX_CUSTOM_AUTH.LOGOUT(
p_this_app                   IN VARCHAR2,
p_next_app_page_sess         IN VARCHAR2,
p_next_url                   IN VARCHAR2);

Parameter

Table 15-100 describes the parameters available in the LOGOUT procedure.

Table 15-100 LOGOUT Parameters

Parameter

Description

p_this_app

Current application ID.

p_next_app_page_sess

Application and page number to redirect to. Separate multiple pages using a colon (:) and optionally followed by a colon (:) and the session ID (if control over the session ID is desired).

p_next_url

URL to redirect to (use this instead of p_next_app_page_sess).

Example

BEGIN
APEX_CUSTOM_AUTH.LOGOUT (
p_this_app            => '1000',
p_next_app_page_sess  => '1000:99');
END;

POST_LOGIN Procedure

This procedure performs session registration, assuming the authentication step has been completed. It can be called only from within an Oracle Application Express application page context.

Syntax

APEX_CUSTOM_AUTH.POST_LOGIN(
p_uname                    IN  VARCHAR2,
p_session_id               IN  VARCHAR2,
p_app_page                 IN  VARCHAR2,
p_preserve_case            IN  BOOLEAN);

Parameter

Table 15-101 describes the parameters available in the POST_LOGIN procedure.

Table 15-101 POST_LOGIN Parameters

Parameter

Description

p_uname

Login name of user.

p_session_id

Current Oracle Application Express session ID.

p_app_page

Current application ID and after login page separated by a colon (:).

p_preserve_case

If true, do not include p_uname in uppercase during session registration.

Example

BEGIN
APEX_CUSTOM_AUTH.POST_LOGIN (
p_uname       => 'SCOTT',
p_session_id  => V('APP_SESSION'),
p_app_page    => :APP_ID||':1');
END;

SESSION_ID_EXISTS Function

This function returns a Boolean result based on the global package variable containing the current Oracle Application Express session ID. Returns true if the result is a positive number. returns false if the result is a negative number.

Syntax

FUNCTION SESSION_ID_EXISTS
RETURN BOOLEAN;

Example

DECLARE VAL BOOLEAN;
BEGIN
VAL := APEX_CUSTOM_AUTH.SESSION_ID_EXISTS;
END;

SET_USER Procedure

This procedure sets the APEX_APPLICATION.G_USER global variable. SET_USER requires the parameter P_USER (VARCHAR2) which defines a user ID.

Syntax

PROCEDURE SET_USER(
p_user   IN    VARCHAR2)

SET_SESSION_ID Procedure

This procedure sets APEX_APPLICATION.G_INSTANCE global variable. SET_SESSION_ID returns a number. This procedure requires the parameter P_SESSION_ID (NUMBER) which specifies a session ID.

Syntax

PROCEDURE SET_SESSION_ID(
p_session_id    IN    NUMBER)

SET_SESSION_ID_TO_NEXT_VALUE Procedure

This procedure combines the operation of GET_NEXT_SESSION_ID and SET_SESSION_ID in one call.

Syntax

PROCEDURE SET_SESSION_ID_TO_NEXT_VALUE;

APEX_LDAP

You can use APEX_LDAP to perform various operations related to Lightweight Directory Access Protocol (LDAP) authentication.

Topics in this section include:

- AUTHENTICATE Function

- IS_MEMBER Function

- MEMBER_OF Function

- MEMBER_OF2 Function

- GET_USER_ATTRIBUTES Procedure

- GET_ALL_USER_ATTRIBUTES Procedure

AUTHENTICATE Function

The AUTHENTICATE function returns a boolean true if the user name and password can be used to perform a SIMPLE_BIND_S call using the provided search base, host, and port.

Syntax

FUNCTION AUTHENTICATE(
p_username     IN VARCHAR2 DEFAULT NULL,
p_password     IN VARCHAR2 DEFAULT NULL,
p_search_base  IN VARCHAR2,
p_host         IN VARCHAR2,
p_port         IN VARCHAR2 DEFAULT 389)
RETURN BOOLEAN;

Parameters

Table 15-102 describes the parameters available in the AUTHENTICATE function.

Table 15-102 AUTHENTICATE Parameters

Parameter

Description

p_username

Login name of the user.

p_password

Password for p_username.

p_search_base

LDAP search base, for example, dc=users,dc=my,dc=org.

p_host

LDAP server host name.

p_port

LDAP server port number.

Example

IF APEX_LDAP.AUTHENTICATE(
p_username =>'FIRSTNAME.LASTNAME',
p_password =>'abcdef',
p_search_base => 'cn=user,l=amer,dc=my_company,dc=com',
p_host => 'our_ldap_sever.my_company.com',
p_port => 389) THEN
--
dbms_output.put_line('authenticated');
ELSE
dbms_output.put_line('authentication failed');
END IF;

IS_MEMBER Function

The IS_MEMBER function returns a boolean true if the user named by p_username (with password if required) is a member of the group specified by the p_group and p_group_base parameters using the provided auth base, host, and port.

Syntax

FUNCTION IS_MEMBER(
p_username     IN VARCHAR2 DEFAULT NULL,
p_pass         IN VARCHAR2 DEFAULT NULL,
p_auth_base    IN VARCHAR2,
p_host         IN VARCHAR2,
p_port         IN VARCHAR2 DEFAULT 389,
p_group        IN VARCHAR2,
p_group_base   IN VARCHAR2)
RETURN BOOLEAN;

Parameters

Table 15-103 describes the parameters available in the IS_MEMBER function.

Table 15-103 IS_MEMBER Parameters

Parameter

Description

p_username

Login name of the user.

p_pass

Password for p_username.

p_auth_base

LDAP search base, for example, dc=users,dc=my,dc=org.

p_host

LDAP server host name.

p_port

LDAP server port number.

p_group

Name of the group to be search for membership.

p_group_base

The base from which the search should be started.

MEMBER_OF Function

The MEMBER_OF function returns an array of groups the user name designated by p_username (with password if required) belongs to, using the provided auth base, host, and port.

Syntax

FUNCTION MEMBER_OF(
p_username     IN VARCHAR2 DEFAULT NULL,
p_pass         IN VARCHAR2 DEFAULT NULL,
p_auth_base    IN VARCHAR2,
p_host         IN VARCHAR2,
p_port         IN VARCHAR2 DEFAULT 389)
RETURN wwv_flow_global.vc_arr2;

Parameters

Table 15-104 describes the parameters available in the MEMBER_OF function.

Table 15-104 MEMBER_OF Parameters

Parameter

Description

p_username

Login name of the user.

p_pass

Password for p_username.

p_auth_base

LDAP search base, for example, dc=users,dc=my,dc=org.

p_host

LDAP server host name.

p_port

LDAP server port number.

MEMBER_OF2 Function

The MEMBER_OF2 function returns an VARCHAR2 list of groups the user name designated by p_username (with password if required) belongs to, using the provided auth base, host, and port.

Syntax

FUNCTION MEMBER_OF2(
p_username     IN VARCHAR2 DEFAULT NULL,
p_pass         IN VARCHAR2 DEFAULT NULL,
p_auth_base    IN VARCHAR2,
p_host         IN VARCHAR2,
p_port         IN VARCHAR2 DEFAULT 389)
RETURN VARCHAR2;

Parameters

Table 15-105 describes the parameters available in the MEMBER_OF2 function.

Table 15-105 MEMBER_OF2 Parameters

Parameter

Description

p_username

Login name of the user.

p_pass

Password for p_username.

p_auth_base

LDAP search base, for example, dc=users,dc=my,dc=org.

p_host

LDAP server host name.

p_port

LDAP server port number.

GET_USER_ATTRIBUTES Procedure

The GET_USER_ATTRIBUTES procedure returns an OUT array of user_attribute values for the user name designated by p_username (with password if required) corresponding to the attribute names passed in p_attributes, using the provided auth base, host, and port.

Syntax

PROCEDURE GET_USER_ATTRIBUTES(
p_username          IN VARCHAR2 DEFAULT NULL,
p_pass              IN VARCHAR2 DEFAULT NULL,
p_auth_base         IN VARCHAR2,
p_host              IN VARCHAR2,
p_port              IN VARCHAR2 DEFAULT 389,
p_attributes        IN  wwv_flow_global.vc_arr2,
p_attribute_values  OUT wwv_flow_global.vc_arr2);

Parameters

Table 15-106 describes the parameters available in the GET_USER_ATTRIBUTES procedure.

Table 15-106 GET_USER_ATTRIBUTES Parameters

Parameter

Description

p_username

Login name of the user.

p_pass

Password for p_username.

p_auth_base

LDAP search base, for example, dc=users,dc=my,dc=org.

p_host

LDAP server host name.

p_port

LDAP server port number.

p_attributes

An array of attribute names for which values are to be returned.

p_attribute_values

An array of values returned for each corresponding attribute name in p_attributes.

GET_ALL_USER_ATTRIBUTES Procedure

The GET_ALL_USER_ATTRIBUTES procedure returns two OUT arrays of user_attribute names and values for the user name designated by p_username (with password if required) using the provided auth base, host, and port.

Syntax

PROCEDURE GET_ALL_USER_ATTRIBUTES(
p_username          IN VARCHAR2 DEFAULT NULL,
p_pass              IN VARCHAR2 DEFAULT NULL,
p_auth_base         IN VARCHAR2,
p_host              IN VARCHAR2,
p_port              IN VARCHAR2 DEFAULT 389,
p_attributes        OUT  wwv_flow_global.vc_arr2,
p_attribute_values  OUT wwv_flow_global.vc_arr2);

Parameters

Table 15-107 describes the parameters available in the GET_ALL_USER_ATTRIBUTES procedure.

Table 15-107 GET_ALL_USER_ATTRIBUTES Parameters

Parameter

Description

p_username

Login name of the user.

p_pass

Password for p_username.

p_auth_base

LDAP search base, for example, dc=users,dc=my,dc=org.

p_host

LDAP server host name.

p_port

LDAP server port number.

p_attributes

An array of attribute names returned.

p_attribute_values

An array of values returned for each corresponding attribute name returned in p_attributes.

Part III

Database Tools

Part III explains how to use view and manage database objects from a Web browser.

Part III contains the following chapters:

- Chapter 16, "Managing Database Objects with Object Browser"

- Chapter 17, "Building Queries with Query Builder"

- Chapter 18, "Using SQL Scripts"

- Chapter 19, "Using SQL Commands"

- Chapter 20, "Using Application Express Utilities"

- Chapter 21, "Migrating Applications"

16 Managing Database Objects with Object Browser

Object Browser enables developers to browse, create, and edit objects in a database.

This section contains the following topics:

- About Object Browser

- Searching For and Browsing Database Objects

- About Creating New Database Objects

- Managing Tables

- Managing Views

- Managing Indexes

- Managing Sequences

- Managing Types

- Managing Packages

- Managing Procedures

- Managing Functions

- Managing Triggers

- Managing Database Links

- Managing Materialized Views

- Managing Synonyms

See Also:
Oracle Database SQL Language Reference

About Object Browser

The Object Browser page is divided into two sections:

- Object Selection pane displays on the left side of the Object Browser page and lists database objects of a selected type within the current schema. You can further narrow the results by filtering on the object name.

- Detail pane displays to the right of the page and displays detailed information about the selected object. To view object details, select an object in the Object Selection pane. Click the tabs at the top of the Detail pane to view additional details about the current object. To edit an object, click the appropriate button.

Selecting a Schema

A schema is a logical container for database objects. To access objects in another schema, make a selection from the Schema list in the upper right side of the page.

Switching to Another SQL Workshop Component

You can navigate to another SQL Workshop component by selecting one of the following from the Component list located on the upper right side of the page:

- Object Browser. See "Managing Database Objects with Object Browser".

- SQL Commands. See "Using SQL Commands".

- SQL Scripts. See "Using SQL Scripts".

- Query Builder. See "Building Queries with Query Builder".

Accessing Object Browser

To access Object Browser:

1. Log in to the Workspace home page.

2. Click SQL Workshop.

3. To view Object Browser you can either:

- Click SQL Workshop and then Object Browser to drill-down to the Object Browser.

- Click the down arrow on the right side of the SQL Workshop icon to view a drop down menu. Then select the Object Browser menu option.

Note:
For the purposes of consistency, this document uses the primary navigation path (or drill-down approach) when explaining navigation.

Searching For and Browsing Database Objects

The Object Selection pane displays on the left side of the Object Browser page and lists database objects by type with the current schema. You can filter the view by selecting an object type or entering a case insensitive search term.

Topics in this section include:

- Searching For and Selecting Database Objects

- Hiding the Object Selection Pane

- Using the Find Tables Icon

Searching For and Selecting Database Objects

To search for a database object in the Object Selection pane:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Select an object type from the Object list.
The list of objects that appears depends upon the available objects in the current schema. Note that any object having a red bar adjacent to it is invalid.

3. To search for an object name, enter a case insensitive search term in the Search field.

4. To view all objects, leave the search field blank.

Once you locate the database object you want to view, simply select it. The selected object displays in the Detail pane. If no object is selected, the Detail pane is blank.

Hiding the Object Selection Pane

You can hide the Object Selection pane by selecting the Hide Objects control. This control displays on the right side of the Object Selection pane. If the Object Selection pane appears, selecting this control hides it. Similarly, if the Object Selection pane is hidden, selecting this control causes the pane to reappear.

Using the Find Tables Icon

The Find Tables icon resembles a flashlight. Click this icon to view tables within the currently selected schema.

To view tables within the current schema:

1. Navigate to either Object Browser or SQL Commands.

2. From the Schema list, select a schema (optional).

3. Click the Find Tables icon.
The Table Finder appears. A search bar displaying the selected schema displays at the top of the page and contains the following controls:

- Search. Search for a table name. Enter case insensitive keywords in the Search field and click Go. To view all tables, leave the Search field blank and click Go.

- Rows. Determine how many rows display in the resulting report. To change the number of rows that display, make a selection from the list and click Go.

- Views. Select the Views checkbox and click Go to include views in the resulting report.

The Table Finder report appears displaying the table name, the number of rows, last analyzed date, and the object type.

4. Select a table name.

A table definition appears on the right side of the page.

This report displays the column names, data type, length, precision, and scale as well as the SQL necessary to re-create the table appears at the bottom of the page.

About Creating New Database Objects

You can create new database objects using the Create Database Object Wizard. Once you select an object, a set of tabs and buttons appears at the top of the Detail pane. Use the tabs to view different aspects of the current items (for example, a tables indexes). Use the buttons to modify the current object.

To create a new object:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create, located in the upper right corner of the Detail pane.

3. From the list of object types, select the type of object you want to create.

4. Follow the on-screen instructions.

Managing Tables

A table is a unit of data storage in an Oracle database, containing rows and columns. When you view a table in Object Browser, a table description appears that describes each column in the table.

Topics in this section include:

- Creating a Table

- Browsing a Table

- Editing a Table

- Dropping a Table

See Also:

- "Using the Find Tables Icon"

- Oracle Database Administrator's Guide for information on managing tables.

- Oracle Database Concepts for conceptual information on tables types.

- Oracle Database SQL Language Reference for the syntax required to create and alter tables.

Creating a Table

To create a new table:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Table.

4. Enter a table name.
Table names must conform to Oracle naming conventions and not contain spaces or start with a number or underscore.

5. To have the final table name match the case entered in the Table Name field, click Preserve Case.

6. Enter details for each column. For each column:

a. Enter the column name.

b. Select the column type. Available types include NUMBER, VARCHAR2, DATE, TIMESTAMP, CHAR, CLOB, BLOB, NVARCHAR2, BINARY_FLOAT, and BINARY_DOUBLE

c. Enter the following additional information as appropriate:

- Precision

- Scale

d. To specify a column should not be NULL, select the check box in the Not Null column.
To change the order of previously entered columns, click the Up and Down arrows in the Move column. To add additional columns, click Add Column.

e. Click Next.

Next, define the primary key for this table (optional). A primary key is a single field or combination of fields that uniquely identifies a record.

7. For Primary Key, select one of the following and click Next:

- No Primary Key - No primary key is created.

- Populated from a new sequence - Creates a primary key and creates a trigger and a new sequence. The new sequence is used in the trigger to populated the selected primary key column. The primary key can only be a single column.

- Populated from an existing sequence - Creates a primary key and creates a trigger. The selected sequence is used in the trigger to populate the selected primary key column. The primary key can only be a single column.

- Not populated - Defines a primary key but does not have the value automatically populated with a sequence within a trigger. You can also select this option to define a composite primary key (that is, a primary key made up of more than one column).

Next, add foreign keys (optional). A foreign key establishes a relationship between a column (or columns) in one table and a primary or unique key in another table.

8. To add a foreign key:

a. Name - Enter a name of the foreign key constraint that you are defining.

b. Select Key Column(s) - Select the columns that are part of the foreign key. Once selected, click the Add icon to move them to Key Column(s).

c. References Table - Select the table which will be referenced by this foreign key. Then, select the columns to be referenced by this foreign key. Once selected, click the Add icon to move the selected columns to Referenced Column(s).

d. Select one of the following:

- Disallow Delete - Blocks the delete of rows from the referenced table when there are dependent rows in this table.

- Cascade Delete - Deletes the dependent rows from this table when the corresponding parent table row is deleted.

- Set to Null on Delete - Sets the foreign key column values in this table to null when the corresponding parent table row is deleted.

e. Click Add.

f. Click Next.

Next, add a constraint (optional). You can create multiple constraints, but you must add each constraint separately.

9. To add a constraint:

a. Specify the type of constraint (Check or Unique).
A check constraint is a validation check on one or more columns within the table. No records can be inserted or updated in a table which violates an enabled check constraint. A unique constraint designates a column or a combination of columns as a unique key. To satisfy a unique constraint, no two rows in the table can have the same values for the specified columns.

b. Enter the constraint in the field provided. For unique constraints, select the column(s) that are to be unique. For check constraints, enter the expression that should be checked such as flag in ('Y','N').

c. Click Add.

10. Click Finish.
A confirmation page appears. To view the SQL used to create the table, click SQL Syntax.

11. Click Create.
Note that you do not need to follow the steps for creating a table in the order described in the previous procedure. Instead of navigating through the wizard by clicking the Next and Previous button, you can also access a specific step by selecting it in the progress indicator on the left side of the page.

See Also:
"Using the Table Finder" and "Overview of Tables" in Oracle Database Concepts for information about tables

Browsing a Table

When you view a table in Object Browser, the table description appears. While viewing this description, you can add a column, modify a column, rename a column, drop a column, rename the table, copy the table, drop the table, truncate the table, or create a lookup table based upon a column in the current table. Additionally, you have access other reports that offer related information including the table data, indexes, data model, constraints, grants, statistics, user interface defaults, triggers, dependencies, and SQL to produce the selected table.

To view a table description:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Tables.

3. From the Object Selection pane, select a table.
The table description appears.

Summary of Available Views

Click the tabs at the top of the page to view different reports about the table. Table 16-1 describes all available views.

Table 16-1 Available Views for Tables

View

Description

Table

Displays details of the first 31 columns including the column name, data type, nullable status, default value, and primary key. While viewing table details you can add, modify, delete, or rename a column. Additionally, you can drop, rename, copy, or truncate the table as long as the referencing table has no records and create a lookup table.

To export the data as a comma-delimited file (.csv) file, click the Download link.

See Also: "Editing a Table"

Data

Displays a report of the data in the current table. Actions you can perform include:

- Query - Enables you to sort by column. To restrict specific rows, enter a condition in the Column Condition field. Use the percent sign (%) for wildcards. From Order by, select the columns you want to review and click Query.

- Count Rows - Displays a report of the number of rows in the current table.

- Insert Row - Enables you to insert a new row into the table.

- Download - Exports all data in the table to a spreadsheet. Click the download link at the bottom of the page to export all data in the selected table.

Indexes

Displays indexes associated with this table. Actions you can perform include Create and Drop.

See Also: "Managing Indexes"

Model

Displays a graphical representation of the selected table along with all related tables. Related tables are those that reference the current table in a foreign key and those tables referenced by foreign keys within the current table.

You can position the cursor over an underlined table name to view the relationship between that table and the current table. Click an underlined table name to view the model of the related table.

Constraints

Displays a list of constraints for the current table. Actions you can perform include Create, Drop, Enable, and Disable.

Grants

Displays a list of grants on the current table, including the grantee, the privilege, and grant options. Actions you can perform in this view include Grant and Revoke.

Statistics

Displays collected statistics about the current table, including the number of rows and blocks, the average row length, sample size, when the data was last analyzed, and the compression status (enabled or disabled). Click Analyze to access the Analyze Table Wizard.

UI Defaults

Displays user interface defaults for forms and reports. User interface defaults enable developers to assign default user interface properties to a table, column, or view within a specified schema.

Click Edit to edit defined user interface defaults. Click Create to initialize user interface defaults for tables that do not currently have user interface defaults defined.

See Also: "Managing User Interface Defaults"

Triggers

Displays a list of triggers associated with the current table. Actions you can perform include Create, Drop, Enable, and Disable.

To view trigger details, click the trigger name.

See Also: "Managing Triggers"

Dependencies

Displays report showing objects referenced by this table, objects this table references, and synonyms for this table.

SQL

Displays the SQL necessary to re-create this table, including keys, indexes, triggers and table definition.

Editing a Table

While viewing a table description, you can edit it by clicking the buttons above the table description.

To edit a table:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Tables.

3. From the Object Selection pane, select a table.
The table description appears.

4. Click the appropriate button described in Table 16-2.

Table 16-2 Edit Table Buttons

Button

Description

Add Column

Adds a new column to the table. Enter a column name and select a type. Depending upon the column type, specify whether the column requires a value as well as the column length, precision, and scale.

Modify Column

Modifies the selected column.

Rename Column

Renames the selected column.

Drop Column

Drops the selected column.

Rename

Renames the selected table.

Copy

Copies the selected table.

Drop

Drops the selected table.

See Also: "Using the Recycle Bin to View and Restore Dropped Objects"

Truncate

Removes all rows from the selected table. Truncating a table can be more efficient than dropping and re-creating a table. Dropping and re-creating a table may invalidate dependent objects, requiring you to regrant object privileges or re-create indexes, integrity constraints, and triggers.

Create Lookup Table

Creates a lookup table based on the column you select. That column becomes a foreign key to the lookup table.

Dropping a Table

To drop a table:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Tables.

3. From the Object Selection pane, select a table.
The table description appears.

4. Click Drop.

See Also:
"Using the Recycle Bin to View and Restore Dropped Objects"

Managing Views

A view is a logical representation of another table or combination of tables. A view derives its data from the tables on which it is based. These tables are called base tables. Base tables might in turn be actual tables or might be views themselves. All operations performed on a view actually affect the base table of the view. You can use views in almost the same way as tables. You can query, update, insert into, and delete from views, just as you can standard tables.

Topics in this section include:

- Creating a View

- Browsing a View

- Editing a View

- Compiling a View

- Dropping a View

See Also:
Oracle Database Administrator's Guide

Creating a View

To create a new view:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select View.

4. Define the view:

- View Name - Enter a name for the View.

- Query - Specify a query to define the view.

To access Query Builder or SQL Command Processor, click the appropriate link at the bottom of the page. The selected tool appears in a pop-up window. Once you create the appropriate SQL, click Return to automatically close the popup window and return to the wizard with the SQL.

5. Click Next.
A confirmation page appears. To view the SQL used to create the view, click SQL.

6. Click Create.

See Also:
"Building Queries with Query Builder" and "Using SQL Commands"

Browsing a View

When you access a view in Object Browser, the Detail pane displays a report listing the columns in that view.

To browse a view:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Views.

3. From the Object Selection pane, select a view.
The view definition appears displaying the appropriate columns.

Summary of Available Views

Click the tabs at the top of the page to view different reports. Table 16-3 describes all available views.

Table 16-3 Available Views for Views

View

Description

View

(Default) Displays the columns in the current view. Actions you can perform include:

- Compile

- Drop

See Also: "Editing a View", "Compiling a View", and "Dropping a View"

Data

Displays a report of the data in the columns in the view. Actions you can perform include:

- Query - Enables you to sort by column. To restrict specific rows, enter a condition in the Column Condition field. Use the percent sign (%) for wildcards. From Order by, select the columns you want to review and click Query.

- Count Rows - Enables you to count rows in the table.

- Insert Row - Enables you to insert a new row into the table.

Grants

Displays a list of grants associated with the columns in the view. Grant details include grantee, privilege, and grant options. Actions you can perform include Grant and Revoke.

UI Defaults

Displays user interface defaults for forms and reports. User interface defaults enable developers to assign default user interface properties to a table, column, or view within a specified schema.

Click Edit to edit existing user interface defaults. Click Create to initialize user interface defaults for views that do not currently have user interface defaults defined.

See Also: "Managing User Interface Defaults"

Dependencies

Displays a report showing objects referenced by this view, objects this view references, and synonyms for this view.

SQL

Displays the SQL necessary to re-create this view.

Editing a View

When you edit a view you can edit the code manually, perform a search and replace, and compile the view. Additionally, you can save the view as a file or drop it.

Editing a View Manually

To edit a view manually:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Views.

3. From the Object Selection pane, select a view.

4. Select the Code tab.

5. Click Edit to activate manual edit mode.
If you edit and make changes to a view, you need to compile. See "Compiling a View".

Note:
You can expand the Edit pane by clicking the Full Screen icon in the upper right of the pane, beneath the Create button.

Using Find and Replace

Click Find to perform a basic search and replace.

Downloading a View

Click Download to save the current view as a file.

Compiling a View

If you edit and make changes to a view, you need to compile to save your changes. Note that there is no save function since this is just a view of the object within the database.

Click Compile to re-create the current view.

Dropping a View

To drop a view:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Views.

3. From the Object Selection pane, select a view.

4. Select the View tab or the Code tab.

5. Click Drop to delete the current view.

Managing Indexes

An index is an optional structure associated with tables and clusters. You can create indexes on one or more columns of a table to speed access to data on that table.

When you view an index in Object Browser, the Detail pane displays a report containing the index name, index type, table owner, table type, and a listing of the indexed columns.

Topics in this section include:

- Creating an Index

- Browsing an Index

- Dropping an Index

Creating an Index

To create an index:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Index.

4. Select a table and select the type of index you want to create. Available index types include:

- Normal - Indexes one or more scalar typed object attributes of a table

- Text - Creates a text index (Oracle Text)

5. Click Next.

6. Create the index definition. Specify an index name, select one or more columns to be indexed, and click Next.
A confirmation page appears. To view the SQL used to create the index, click SQL.

7. Click Finish.

Browsing an Index

To browse an index:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Indexes.

3. From the Object Selection pane, select an index.
The index appears displaying the index name, type, table owner, and table type as well as a listing of indexed columns.

Summary of Available Views

Click the tabs at the top of the page to view different reports about the index. Table 16-4 describes all available views.

Table 16-4 Available Views for Indexes

View

Description

Object Details

(Default) Displays the index name, index type, table owner, and table type as well as a listing of the indexed columns. Actions you can perform while viewing Object Details include:

- Disable - Disables the current index

- Drop - Drops the current index.x

- Rebuild - Rebuilds the current index

Statistics

Displays collected statistics about the current view, including the number of rows, sample size, when the data was last analyzed, and the compression status (enabled or disabled). Click Analyze to refresh the displayed statistics.

SQL

Displays the SQL necessary to re-create this index.

Dropping an Index

To drop an index:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Indexes.

3. From the Object Selection pane, select an index.

4. Under Object Details, click the Drop tab.

Managing Sequences

A sequence generates a serial list of unique numbers for numeric columns of a database table. Database sequences are generally used to populate table primary keys.

Topics in this section include:

- Creating a Sequence

- Browsing a Sequence

- Dropping a Sequence

Creating a Sequence

To create a sequence:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Sequence.

4. Define the sequence, specify a sequence name, and click Next.
A confirmation page appears. To view the SQL used to create the sequence, click Show SQL.

5. Click Create.

Browsing a Sequence

To browse a sequence:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Sequences.

3. From the Object Selection pane, select a sequence.
The Object Details view appears.

Summary of Available Views

Click the tabs at the top of the page to view different reports about the sequence. Table 16-5 describes all available views.

Table 16-5 Available Views for Sequences

View

Description

Object Details

(Default) Displays details about the current sequence. Actions you can perform in this view include Alter and Drop.

Grant

Displays a list of grants associated with the sequence. Grant details include grantee, privilege, and grant options. Actions you can perform include Grant and Revoke.

Dependencies

Displays a list of objects that use (or depend) upon this sequence.

SQL

Displays the SQL necessary to re-create this sequence.

Dropping a Sequence

To drop a sequence:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Sequences.

3. From the Object Selection pane, select a sequence.
The Object Details view appears.

4. Click Drop.

Managing Types

A type is a user-specified object or collection definition. Oracle Application Express currently only supports collection definitions. There are two categories of Oracle collections (SQL collections):

- Variable-length arrays (VARRAY types)

- Nested tables (TABLE types)

VARRAY types are used for one-dimensional arrays, while nested table types are used for single-column tables within an outer table.

Topics in this section include:

- Creating a Type

- Browsing a Type

- Dropping a Type

See Also:
Oracle Database Concepts and Oracle Database PL/SQL Language Reference for information about collection types

Creating a Type

To create a collection type:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Type.

4. Specify a name and click Next.

5. Select a type, data type, limit, and click Next.
A confirmation page appears. To view the SQL used to create the collection type, click Show SQL.

6. Click Finish.

Browsing a Type

To browse a collection type:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Type.

3. From the Object Selection pane, select a type.
The Object Details view appears.

Summary of Available Views

Click the tabs at the top of the page to view different reports. Table 16-6 describes all available views.

Table 16-6 Available Views for Types

View

Description

Object Details

(Default) Displays details about the selected type. To drop a type, click Drop.

Synonyms

Displays a list of synonyms for the current type.

Grants

Displays a list of grants associated with the type. Grant details include grantee, privilege, and grant options. Actions you can perform include Grant and Revoke.

SQL

Displays the SQL necessary to re-create this type.

Dropping a Type

To drop a collection type:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Type.

3. From the Object Selection pane, select a type.
The Object Details view appears.

4. Click Drop.

Managing Packages

A package is a database object that groups logically related PL/SQL types, items, functions and procedures. Packages usually have two parts, a specification and a body. The specification is the interface to your application. The body implements the specification.

Topics in this section include:

- Creating a Package

- Viewing a Package

- Editing a Package

- Compiling a Package

- Downloading a Package

- Dropping a Package

See Also:

- "Using PL/SQL Packages" in Oracle Database PL/SQL Language Reference for additional information on PL/SQL packages.

- "Using PL/SQL Subprograms" in Oracle Database PL/SQL Language Reference for information on PL/SQL subprograms

Creating a Package

To create a package:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Package.

4. Select the type of package you want to create:

- Specification

- Body

- Package with methods on database tables

5. If you select Specification:

a. Enter a name and click Next.
The wizard creates a dummy package specification and displays it for editing.

b. Edit the specification and click Finish.

6. If you select Body:

a. Select the package you want to create the body for and click Next
The wizard creates a package body with stubbed out calls identified in the specification and displays it for editing.

b. Edit the package body and click Finish.

7. If you select Package with methods on database tables:

a. Enter a name and click Next.

b. Select up to ten tables and click Next.
The wizard creates a specification and body with insert, update, delete, and GET APIs for the selected tables. Note that you have the option to show or download the specification or body.

c. Click Finish.

Viewing a Package

When you access a package in Object Browser the specification appears.

To view a specification:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Packages.

3. From the Object Selection pane, select a package.
The Specification appears. You can copy the code in this view for use in other tools.

Summary of Available Views

Click the tabs at the top of the page to view different reports about the package. Table 16-7 describes all available views.

Table 16-7 Available Views for Packages

View

Description

Specification

(Default) Displays the package specification. This define the interface to your application. Actions you can perform include:

- Edit

- Compile

- Download

- Drop

- Find

Body

Displays the package body, if one exists, for the selected package. Actions you can perform include:

- Edit

- Compile

- Download

- Drop

- Find

Dependencies

Displays objects that use (or depend on) on the current package and objects the package depends on.

Errors

Displays errors related to the current package.

Grants

Lists details of grants for the current package, including privilege, grantee, grantable, grantor, and object name.

Editing a Package

When you edit a package, you can edit the code manually, perform a search and replace, and compile the package.

Editing a Package Manually

To edit a package manually:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Packages.

3. From the Object Selection pane, select a package.
The Specification appears. You can copy the code in this view for use in other tools. Note you can edit both the specification and the body fromObject Browser.

4. Click Edit to activate edit mode.

5. Click Find to perform a basic search and replace.

Note:
You can expand the Edit pane by clicking the Full Screen icon in the upper right of the pane, beneath the Create button.

Compiling a Package

If you edit and make changes to a package, you need to compile in order to save your changes. There is no save function because this is just a view of the object within the database.

To compile a package:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Packages.

3. From the Object Selection pane, select a package.
The Specification appears.

4. Click Compile to compile the current package.
Compiling re-creates the object in the database. If the compile fails, an error message display above the code.

Downloading a Package

To download a package:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Packages.

3. From the Object Selection pane, select a package.
The Specification appears.

4. Click Download to save the current package as a file.

Dropping a Package

To drop a package while viewing the Specification:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Packages.

3. From the Object Selection pane, select a package.
The Specification appears.

4. Click Drop to delete the current package.

To drop a package while viewing the Body:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Packages.

3. From the Object Selection pane, select a package.
The Specification appears.

4. Click the Body tab.

5. Click Drop.

Managing Procedures

A procedure is a subprogram that performs a specific action. You can use Object Browser to view, create, edit, download, and drop procedures.

Topics in this section include:

- Creating a Procedure

- Browsing a Procedure

- Editing a Procedure

- Compiling a Procedure

- Downloading a Procedure

- Dropping a Procedure

See Also:
"Understanding PL/SQL Procedures" in Oracle Database PL/SQL Language Reference

Creating a Procedure

To create a procedure:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Procedures.

4. Enter a procedure name and click Next.

5. Define the arguments by specifying the following information (optional):

- Argument Name

- In/Out (the parameter mode)

- Argument Type (datatype)

- Default (value)

To add additional arguments, click Add Argument.

6. Click Next.

7. Enter PL/SQL block you want to use as the procedure body and click Next.
To view the previously defined arguments, click Defined Arguments.

A confirmation page appears. To view the SQL used to create the procedure, click Show SQL.

8. Click Finish.

Browsing a Procedure

To browse a procedure:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Procedures.

3. From the Object Selection pane, select a procedure.
The Code view appears, displaying the source code for the procedure. You can copy the code in this view for use in other tools.

Summary of Available Views

Click the tabs at the top of the page to view different reports about the procedure. Table 16-8 describes all available views.

Table 16-8 Available Views for Procedures

View

Description

Code

(Default) Displays the source code for the procedure. You can copy the code in this view for use in other tools. Actions you can perform in this view include:

- Edit

- Compile

- Download

- Drop

- Find

See Also: "Editing a Procedure", "Compiling a Procedure", "Downloading a Procedure", and "Dropping a Procedure"

Dependencies

Displays objects that use (or depend) on the current procedure and objects the procedure depends on.

Errors

Lists errors related to the current procedure.

Grants

Lists details of grants for the current procedure, including privilege, grantee, grantable, grantor, and object name.

Editing a Procedure

When you edit a procedure you can edit the code manually or perform a search and replace.

Editing a Procedure Manually

To edit a procedure manually:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Procedures.

3. From the Object Selection pane, select a procedure.
The Code view appears. Be default, you can copy the code in this view for use in other tools.

4. Click Edit to activate edit mode.

5. Click Find to perform a basic search and replace.

Note:
You can expand the Edit pane by clicking the Full Screen icon in the upper right of the pane, beneath the Create button.

Compiling a Procedure

If you edit and make changes to a procedure, you need to compile in order to save your changes. There is no save function because this is just a view of the object within the database.

To compile a procedure:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Procedures.

3. From the Object Selection pane, select a procedure.

4. Click Compile to compile the current procedure.
Compiling re-creates the object in the database. If the compile fails, an error message display above the code.

Downloading a Procedure

To download a procedure:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Procedures.

3. From the Object Selection pane, select a procedure.

4. Click Download to save the current procedure as a file.

Dropping a Procedure

To drop a procedure:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Procedures.

3. From the Object Selection pane, select a procedure.

4. Click Drop to delete the current procedure.

Managing Functions

A function is a subprogram that can take parameters and return a single value.

Topics in this section include:

- Creating a Function

- Browsing a Function

- Editing a Function

- Compiling a Function

- Downloading a Function

- Dropping a Function

See Also:
Oracle Database SQL Language Reference for information about PL/SQL functions and "Understanding PL/SQL Functions" in Oracle Database PL/SQL Language Reference

Creating a Function

To create a function:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Functions.

4. Enter a function name, specify the return datatype, and click Next.

5. Define the arguments and click Next (optional):

- Argument Name

- Argument Type (datatype)

- Default (value)

To add additional arguments, click Add Argument.

6. Enter P/LSQL block you want to use as the function body and click Next.
To link to SQL Commands, click Command Processor. To view the previously defined arguments, click Defined Arguments.

A confirmation page appears. To view the SQL used to create the function, click Show SQL.

7. Click Finish.

Browsing a Function

To view a function in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Functions.

3. From the Object Selection pane, select a function.
The Code view appears. You can copy the code in this view for use in other tools.

Summary of Available Views

Click the tabs at the top of the page to view different reports about the function. Table 16-9 describes all available views.

Table 16-9 Available Views for Functions

View

Description

Code

(Default) Displays the source code for the function. You can copy the code in this view for use in other tools. Actions you can perform in this view include:

- Edit

- Compile

- Download

- Drop

- Find

See Also: "Editing a Function", "Compiling a Function", "Downloading a Function", and "Dropping a Function"

Dependencies

Displays objects that use (or depend) on the current function and objects the function depends on.

Errors

Displays errors related to the current function.

Grants

Lists details of grants for the current function, including privilege, grantee, grantable, grantor, and object name.

Editing a Function

When you edit a function you can edit the code manually, perform a search and replace, and compile the function.

Editing a Function Manually

To edit a function manually:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Functions.

3. From the Object Selection pane, select a function.
The Code view appears. Be default, you can copy code from this view for use in other tools.

4. Click Edit to activate manual edit mode.

5. Click Find to perform a basic search and replace.

Note:
You can expand the Edit pane by clicking the Full Screen icon in the upper right of the pane, beneath the Create button.

Compiling a Function

If you edit and make changes to a function, you need to compile in order to save your changes. There is no save function because this is just a view of the object within the database.

To compile a function in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Functions.

3. From the Object Selection pane, select a function.
The Code view appears.

4. Click Compile to compile the current function.
Compiling re-creates the object in the database. If the compile fails, an error message display above the code.

Downloading a Function

To save a function to a file in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Functions.

3. From the Object Selection pane, select a function.
The Code view appears.

4. Click Download to save the current function as a file.

Dropping a Function

To drop a function in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Functions.

3. From the Object Selection pane, select a function.
The Code view appears.

4. Click Drop to delete the current function.

Managing Triggers

A database trigger is a stored subprogram associated with a database table, view, or event. The trigger can be called once, for example when an event occurs, or many times, for example for each row affected by an INSERT, UPDATE, or DELETE statement.

Topics in this section include:

- Creating Triggers

- Browsing a Trigger

- Editing a Trigger

- Compiling a Trigger

- Downloading a Trigger

- Dropping a Trigger

See Also:

- Oracle Database Concepts

- Oracle Database Advanced Application Developer's Guide

Creating Triggers

To create a trigger in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Trigger.

4. Select a table name and click Next.

5. Select the appropriate trigger attributes, enter the trigger body, and click Next.
A confirmation page appears. To view the SQL used to create the trigger, click SQL.

6. Click Finish.

Browsing a Trigger

To browse a trigger in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Triggers.

3. From the Object Selection pane, select a trigger.
The Details view appears.

Summary of Available Views

Click the tabs at the top of the page to view different reports about the trigger. Table 16-10 describes all available views.

Table 16-10 Available Views for Triggers

View

Description

Object Details

(Default) Lists of the details about the current trigger. Actions you can perform include:

- Compile

- Disable

- Download

- Drop

- Code

See Also: "Editing a Trigger", "Compiling a Trigger", "Downloading a Trigger", and "Dropping a Trigger"

Errors

Displays errors related to the current trigger.

SQL

Displays the SQL necessary to re-create the trigger.

Editing a Trigger

When you edit a trigger you can edit the code manually, perform a search and replace, and compile the trigger.

Editing a Trigger Manually

To edit a trigger manually:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Triggers.

3. From the Object Selection pane, select a trigger.

4. Select the Code tab and then click Edit to activate manual edit mode.

5. Click Find to perform a basic search and replace.

Note:
You can expand the Edit pane by clicking the Full Screen icon in the upper right of the pane, beneath the Create button.

Compiling a Trigger

If you edit and make changes to a function, you need to compile in order to save your changes. There is no save function because this is just a view of the object within the database.

To compile a trigger in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Triggers.

3. From the Object Selection pane, select a trigger.
The Details view appears.

4. Click Compile to compile the current trigger.
Compiling re-creates the object in the database. If the compile fails, an error message display above the code.

Downloading a Trigger

To save the current trigger as a file:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Triggers.

3. From the Object Selection pane, select a trigger.
The Details view appears.

4. Click Download to save the current trigger as a file.

Dropping a Trigger

To save drop a trigger in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Triggers.

3. From the Object Selection pane, select a trigger.
The Details view appears.

4. Click Drop to delete the current trigger.

Managing Database Links

A database link is a schema object in one database that enables you to access objects in another database. Once you create a database link, you can access the remote objects by appending @dblink to the table or view name, where dblink is the name of the database link.

Topics in this section include:

- Creating a Database Link

- Browsing a Database Link

- Dropping a Database Link

Creating a Database Link

To create a database link:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Database Link.

4. Specify the following information and click Next.

- Database Link Name

- Connect To Schema

- Password

- Remote Hostname or IP

- Remove Host Port

- SID or Service Name

A confirmation page appears.

5. To view the SQL used to create the database link, click Show SQL.

6. Click Create.

Browsing a Database Link

To browse a database link:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Database Links.

3. From the Object Selection pane, select a database link.
The Object Details view appears.

Summary of Available Views

Click the tabs at the top of the page to view different reports about the database link. Table 16-11 describes all available views.

Table 16-11 Available Views for Database Links

View

Description

Object Details

(Default) Displays details about the database link. Actions you can perform include:

- Drop - Deletes the database link

- Test - Tests the database link

Dependencies

Displays a list of objects that use (or depend) upon this database link.

SQL

Displays the SQL necessary to re-create this database link.

Dropping a Database Link

To drop a database link in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Database Links.

3. From the Object Selection pane, select a database link.
The Object Details View appears.

4. Click Drop.

Managing Materialized Views

A materialized view provides indirect access to table data by storing the results of a query in a separate schema object. Unlike an ordinary view, which does not take up any storage space or contain any data, a materialized view contains the rows resulting from a query against one or more base tables or views. A materialized view can be stored in the same database as its base tables or in a different database.

Topics in this section include:

- Creating a Materialized View

- Browsing a MaterializedView

- Dropping a Materialized View

See Also:
Oracle Database Concepts for information about materialized views

Creating a Materialized View

To create a materialized view:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Materialized View.

4. Define the materialized view:

a. Materialized View Name - Enter a name.

b. Query - Specify a query to define the view.
To access Query Builder or SQL Command Processor, click the appropriate link at the bottom of the page. The selected tool appears in a pop-up window. Once you generate the appropriate SQL, click Return to automatically close the popup window and return to the wizard with the SQL.

c. Click Next.
A confirmation page appears. To view the SQL used to create the materialized view, click SQL.

5. Click Create.

See Also:
"Building Queries with Query Builder" and "Using SQL Commands"

Browsing a Materialized View

To view a materialized view:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Materialized Views.

3. From the Object Selection pane, select a view.
The Materialized View appears.

Summary of Available Views

Click the tabs at the top of the page to view different reports about the materialized view. Table 16-12 describes all available views.

Table 16-12 Available Views for Materialized View

View

Description

Materialized View

(Default) Displays details about the columns in the materialized view, including:

- Column Name

- Data type

- Nullable flag

- Default value

- Primary key

Click Drop to delete the current materialized view.

Data

Displays a report of the data in the columns. Actions you can perform include:

- Query - Enables you to sort by column. To restrict specific rows, enter a condition in the Column Condition field. Use the percent sign (%) for wildcards. From Order by, select the columns you want to review and click Query.

- Count Rows - Displays a report of the data in the current table.

- Download - Click this link to export the data as a comma-delimited file (.csv) file.

Details

Displays object details stored in DBA_SNAPSHOTS such as updatable and status.

Grants

Displays a list of grants on the current view, including grantee, privilege, and grant options. Actions you can perform in this view include Grant and Revoke.

Dependencies

Displays a list of objects that use (or depend) upon this materialized view.

SQL

Displays the SQL necessary to re-create this materialized view.

Dropping a Materialized View

To drop a materialized view in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Materialized Views.

3. From the Object Selection pane, select a view.
The Materialized View appears.

4. Click Drop.

Managing Synonyms

A synonym is an alias for a schema object. Synonyms can provide a level of security by masking the name and owner of an object and by providing location transparency for remote objects of a distributed database. Also, they are convenient to use and reduce the complexity of SQL statements for database users.

Topics in this section include:

- Creating Synonyms

- Viewing a Synonym

- Dropping a Synonym

See Also:
Oracle Database Administrator's Guide for information about synonyms

Creating Synonyms

To create a synonym:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. Click Create.

3. From the list of object types, select Synonym.

4. Define the synonym:

a. Synonym Name - Enter a name.

b. Public or Private - Specify whether the synonym should be public or private.

c. Schema - Select the database schema (or user name) which owns the object upon which you want to create your synonym.

d. Object - Enter the name of the object upon which you want to create a synonym.

e. Database Link - Enter the name of the database link to use if the synonym is to be create on a remote object.

f. Click Next.

A confirmation page appears. To view the SQL used to create the synonym, click Show SQL.

5. Click Finish.

See Also:
"Managing Synonyms"

Viewing a Synonym

To view a synonym:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Synonyms.

3. From the Object Selection pane, select a synonym.
The Object Details view appears displaying the following:

- Synonym owner

- Synonym name

- Object owner

- Object Name

- Object Status

- Status

Dropping a Synonym

To drop a synonym in Object Browser:

1. On the Workspace home page, click SQL Workshop and then Object Browser.
Object Browser appears.

2. From the Object list, select Synonyms.

3. From the Object Selection pane, select a synonym.

4. Click Drop.

17 Building Queries with Query Builder

Query Builder's graphical user interface enables database developers to build SQL queries without the need for manual SQL coding. Using Query Builder, you can search and filter database objects, select objects and columns, create relationships between objects, view formatted query results, and save queries with little or no SQL knowledge.

This section contains the following topics:

- About Query Builder

- Using the Object Selection Pane

- Selecting Objects

- Specifying Query Conditions

- Creating Relationships Between Objects

- Working with Saved Queries

- Viewing Generated SQL

- Viewing Query Results

See Also:
"Using the Query Finder"

About Query Builder

The Query Builder page is divided into three sections:

- Object Selection pane displays on the left side of the page and contains a list objects from which you can build queries. Only objects in the current schema display.

- Design pane displays to the right of the Object Selection pane and above the Conditions, SQL, Results, and Saved SQL tabs. When you select an object from the Object Selection pane, it appears in the Design pane.

- Output pane displays below the Design pane. Once you select objects and columns, you can create conditions, view the generated SQL, or view query results.

Selecting a Schema

A schema is a logical container for database objects. To access objects in another schema, make a selection from the Schema list in the upper right side of the page.

Switching to Another SQL Workshop Component

You can navigate to another SQL Workshop component by selecting one of the following from the Component list located on the upper right side of the page:

- Object Browser. See "Managing Database Objects with Object Browser".

- SQL Commands. See "Using SQL Commands".

- SQL Scripts. See "Using SQL Scripts".

- Query Builder. See "Building Queries with Query Builder".

Topics in this section include:

- Accessing Query Builder

- Understanding the Query Building Process

Accessing Query Builder

To access Query Builder:

1. Log in to the Workspace home page.

2. Click SQL Workshop.

3. To view Query Builder you can either:

- Click SQL Workshop and then Query Builder.

- Click the down arrow on the right side of the SQL Workshop icon to view a drop down menu. Then select the Query Builder menu option.

Note:
For the purposes of consistency, this document uses the primary navigation path (or drill-down approach) when explaining navigation.

Understanding the Query Building Process

To build a a query in Query Builder, you perform the following steps:

1. Select objects from the Object Selection pane. See "Using the Object Selection Pane" .

2. Add objects to the Design pane and select columns. See "Selecting Objects".

3. Optional: Establish relationships between objects. See "Creating Relationships Between Objects".

4. Optional: Create query conditions. See "Specifying Query Conditions".

5. Execute the query and view results. See "Viewing Query Results".

See Also:
"Viewing Generated SQL" and "Working with Saved Queries"

Using the Object Selection Pane

The Object Selection pane displays on the left side of the Query Builder page and lists tables, views, and materialized views within the current schema.

Topics in this section include:

- Searching and Filtering Objects

- Hiding the Object Selection Pane

Searching and Filtering Objects

Use the Object Selection pane to search for and view tables, views, and materialized views within the current schema.

To search or filter objects:

1. On the Workspace home page, click SQL Workshop and then Query Builder.
Query Builder appears.

2. In the search field at the top of the pane, enter a case insensitive query.

3. To view all tables or views within the currently selected schema, leave the search field blank.

Hiding the Object Selection Pane

You can hide the Object Selection pane by selecting the Hide Table or Views control. By hiding the Object Selection pane, you can increase the size of the Design and Result panes.

The Hide Table or Views control displays on the right side of the Object Selection pane. If the Object list appears, selecting this control hides it. Similarly, if the Object list is hidden, selecting this control causes the pane to reappear.

Selecting Objects

The Design pane displays to the right of the Object Selection pane. When you select an object from the Object Selection pane, it appears in the Design pane. You use the Object Selection pane to select objects (that is, tables, views, and materialized views) and the Design pane to identify how those selected objects will be used in a query.

Topics in this section include:

- About Supported Column Types

- Adding an Object to the Design Pane

- Removing or Hiding Objects in the Design Pane

See Also:
"Creating Relationships Between Objects"

About Supported Column Types

Columns of all types available in Oracle Database 10g Release (10.2) display as objects in the Design pane. Note the following column restrictions:

- You may only select a maximum of 60 columns for each query.

- The following column types are not selectable and cannot be included in a generated query:

- BLOB

- NCLOB

- RAW

- LONG

- LONG RAW

- XMLType

- Any other nonscalar column types

Adding an Object to the Design Pane

You add an object to the Design pane by selecting it from the Object Selection pane.

To add an object to the Design pane:

1. On the Workspace home page, click SQL Workshop and then Query Builder.
Query Builder appears.

2. Select an object from the Object Selection pane.
The selected object appears in the Design Pane. Note that a graphical representation of the datatype displays to the right of the column name.

3. Select the columns to be included in your query by clicking the check box to the left of the column name.
When you select a column you are indicating it will be used in the query. As you select a column, it appears on the Conditions tab. Note that the Show check box on the Conditions tab controls whether a column is included in query results. Be default, this check box is selected.

To select the first twenty columns, click the Table Actions icon in the upper left corner of the object. The Actions window appears. Select Check All.

4. To execute the query and view results, click Run.

Tip:
You can also execute a query by pressing CTRL + ENTER.

The Results pane displays the query results.

See Also:
"Specifying Query Conditions"

Resizing the Design and Results Panes

As you select objects, you can resize Design and Results panes by selecting the grey horizontal rule in the center of the page. Moving the rule up, shrinks the Design pane. Moving the rule down expands the Design pane.

Removing or Hiding Objects in the Design Pane

You remove or hide objects in the Design pane by selecting controls at the top of the object. To remove an object, select the Remove icon in the upper right corner. To temporarily hide the columns within an object, click the Show/Hide Columns icon.

Specifying Query Conditions

Conditions enable you to filter and identify the data you want to work with. As you select columns within an object, you can specify conditions on the Conditions tab. You can use these attributes to modify the column alias, apply column conditions, sort columns, or apply functions.

To specify query conditions:

1. On the Workspace home page, click SQL Workshop and then Query Builder.
Query Builder appears.

2. Select an object from the Object Selection pane.
The selected object appears in the Design Pane.

3. Select the columns to be included in your query by clicking the box to the left of the column name.
When you select a column, you are indicating you want to include it in your query. As you select each column, it appears as a separate row in the Conditions view. Table 17-1 describes the attributes available on the Conditions tab.

Table 17-1 Conditions Tab

Condition Attribute

Description

Up and Down Arrows

Controls the order that the columns to be displayed in the resulting query. Click the arrow buttons to move columns up and down.

See Also: "Viewing Query Results"

Column

Displays the column name.

Alias

Specify an optional column alias. An alias is an alternative column name. Aliases are used to make a column name more descriptive, to shorten the column name, or prevent possible ambiguous references.

Condition

Specify a condition for the column.

The condition you enter modifies the query's WHERE clause. When specifying a column condition, you must include the appropriate operator and operand. Consider the following examples:

>=10
='VA'
IN (SELECT dept_no FROM dept)
BETWEEN SYSDATE AND SYSDATE + 15

Sort Type

Select a sort type. Options include:

- Ascending (Asc)

- Descending (Desc)

Sort Order

Enter a number (1, 2, 3, and so on) to specify the order in which selected columns should display.

Show

Select this check box to include the column in your query results. You do not need to select Show if you need to add a column to the query for filtering only.

For example, suppose you wish to create following query:

SELECT ename FROM emp WHERE deptno = 10

To create this query in Query Builder:

1. From the Object list, select EMP.

2. In the Design Pane, select ename and deptno.

3. For the deptno column, in Condition enter =10 and uncheck the Show check box.

Function

Select an argument function. Available functions include:

- NUMBER columns - COUNT, COUNT DISTINCT, AVG, MAXIMUM,. MINIMUM, SUM

- VARCHAR2, CHAR columns - COUNT, COUNT DISTINCT, INITCAP, LENGTH, LOWER, LTRIM, RTRIM, TRIM, UPPER

- DATE, TIMESTAMP columns - COUNT, COUNT DISTINCT

Group By

Specify columns to be used for grouping when an aggregate function is used. Only applicable for columns included in output.

Delete

Deselect the column, excluding it from the query.

As you select columns and define conditions, Query Builder writes the SQL for you.

4. To view the underlying SQL, click the SQL tab.

Creating Relationships Between Objects

You can create relationships between objects by creating a join. A join identifies a relationship between two or more tables, views, or materialized views.

Topics in this section include:

- About Join Conditions

- Joining Objects Manually

- Joining Objects Automatically

About Join Conditions

When you write a join query, you specify a condition that conveys a relationship between two objects. This condition is called a join condition. A join condition determines how the rows from one object will combine with the rows from another object.

Query Builder supports inner, outer, left, and right joins. An inner join (also called a simple join) returns the rows that satisfy the join condition. An outer join extends the result of a simple join. An outer join returns all rows that satisfy the join condition and returns some or all of those rows from one table for which no rows from the other satisfy the join condition.

See Also:
Oracle Database SQL Language Reference for information about join conditions

Joining Objects Manually

You can create a join manually by selecting the Join column in the Design pane.

To join two objects manually:

1. On the Workspace home page, click SQL Workshop and then Query Builder.
Query Builder appears.

2. From the Object Selection pane, select the objects you want to join.
The objects display in the Design pane.

3. Identify the columns you want to join.
You create a join by selecting the Join column adjacent to the column name. The Join column displays to the right of the datatype, beneath the Remove icon. When your cursor is in the appropriate position, the following help tip displays:

Click here to select column for join

4. Select the appropriate Join column for the first object.
When selected, the Join column displays as a dark gray. To deselect a Join column, simply select is again or press ESC.

5. Select the appropriate Join column for the second object.

Tip:
You can also join two objects by dragging and dropping. Select a column in the first table and then drag and drop it onto a column in another table.

When joined, a green line connects the two columns.

6. Select the columns to be included in your query. You can view the SQL statement resulting from the join by positioning the cursor over the green line.

7. Click Run to execute the query.
The Results pane displays the query results.

Joining Objects Automatically

When you join objects automatically, the Query Builder suggests logical, existing parent and child relationships between existing columns.

To join objects automatically:

1. On the Workspace home page, click SQL Workshop and then Query Builder.
Query Builder appears.

2. From the Object Selection pane, select an object.
The object displays in the Design pane.

3. Click the small icon in the upper left corner of the object. Depending upon the selected object, the icon label displays as Table Actions or View Actions.
The Actions window appears. Use the Actions window to select all columns within the current object or objects related to the current object.

4. In the Actions window, select the appropriate options:

- Check All - Select this option to select the first twenty columns in the current object.

- Add Parent - Displays tables that are referenced as a foreign key to the current object.

- Add Child - Displays tables that reference the current object in a foreign key.

If using Add Parent or Add child, the selected object appears and a green line connects the foreign key columns.

5. Select additional columns to be included in your query.
You can view the SQL statement resulting from the join by positioning the cursor over the green line.

6. Click Run to execute the query.
The Results pane displays the query results.

Working with Saved Queries

As you create new queries, you can save them by clicking the Save button in the Design pane. Once you save a query, you can access it later in the Saved SQL view.

Topics in this section include:

- Saving a Query

- Editing a Saved Query

- Deleting a Saved Query

Saving a Query

To save a query:

1. Build a query:

a. On the Workspace home page, click SQL Workshop and then Query Builder.
Query Builder appears.

b. Select objects from the Object Selection pane.

c. Add objects to the Design pane and select columns.

d. Execute the query.

2. Click Save.

3. Enter a name and description and click Save.
The saved query displays in the Saved SQL view.

Note that Query Builder does not support duplicate query names. If you open an existing query, keep the existing name, and save it again, Query Builder over-writes the existing query. If you change the name of an existing query and save it again,Query Builder saves the query again under the new name.

Editing a Saved Query

Once you save a query, you can access it in the Saved SQL view.

To edit a Saved SQL query:

1. On the Workspace home page, click SQL Workshop and then Query Builder.
Query Builder appears.

2. Select the Saved SQL tab.

3. To filter the display, you can:

- Make a selection from the Owner list and click Go.

- Enter a search query in the Name field and click Go.

4. To edit a query, select the appropriate name.
The saved query appears. The selected objects display in the Design pane and the Conditions view appears.

Deleting a Saved Query

To delete a Saved SQL query:

1. On the Workspace home page, click SQL Workshop and then Query Builder.
Query Builder appears.

2. Select the Saved SQL tab.

3. Select the queries to be deleted and click Delete Checked.

Viewing Generated SQL

The SQL view presents a read-only, formatted representation of the SQL generated by Query Builder. You can copy the SQL code that appears in the SQL View for use in other tools such as SQL Command Processor or Application Builder.

See Also:
"Using SQL Commands"

To access the SQL view:

1. On the Workspace home page, click SQL Workshop and then Query Builder.
Query Builder appears.

2. Select an object from the Object Selection pane.
The selected object appears in the Design Pane.

3. Select the columns to be included in your query.

4. Click the SQL tab.
The SQL code generated by Query Builder appears.

Viewing Query Results

Once you select objects and determine what columns to include in your query, you execute a query by:

- Clicking the Run button (or pressing CTRL + ENTER)

- Selecting the Results tab

The Results view appears, displaying formatted query results. To export the report as a comma-delimited file (.csv) file, click the Download link at the bottom of the page.

18 Using SQL Scripts

This section provides information on how to use SQL Scripts to create, edit, view, run, and delete script files.

This section contains the following topics:

- What is SQL Scripts?

- Accessing SQL Scripts

- Creating a SQL Script

- Using the Script Editor

- Deleting a SQL Script

- Copying a SQL Script

- Executing a SQL Script

- Viewing SQL Script Results

- Exporting and Importing SQL Scripts

- Viewing Script and Result Quotas

What is SQL Scripts?

A SQL script is a set of SQL commands saved as a file in SQL Scripts. A SQL script can contain one or more SQL statements or PL/SQL blocks. You can use SQL Scripts to create, edit, view, run, and delete script files.

When using SQL Scripts, remember the following:

- SQL*Plus commands in a SQL script are ignored at run time.

- There is no interaction between SQL Commands and SQL Scripts.

- You can cut and paste a SQL command from the SQL Script editor to run it in SQL Commands.

- SQL Scripts does not support bind variables.

See Also:
"Using SQL Commands" and "About Long Operations"

Accessing SQL Scripts

To access SQL Scripts:

1. Log in to the Workspace home page.

2. To view SQL Scripts page you can either:

- Click the SQL Workshop icon and then SQL Scripts to drill-down to the SQL Scripts page.

- Click the down arrow on the right side of the SQL Workshop icon to view a drop down menu. Then select the SQL Scripts menu option.

Note:
For the purposes of consistency, this document uses the primary navigation path (or drill-down approach) when explaining navigation.

About the SQL Scripts Page

The SQL Scripts page display all SQL scripts created by the current user. You can control the appearance of the page by making a selection from the View list. The default view, Icons, displays each script as an icon. Details view displays each script as a row in a report.

The SQL Scripts page features the following controls:

- Script. Search for a script by entering the script name, or a partial name, in the Script field and clicking Go. You control how many rows display by making a selection from the Display list.

- Owner. Search for the owner of the script you want to view by entering the user name in the Owner field and clicking Go.

- View. Change the appearance of the SQL Scripts page by making a selection from the View list and clicking Go. Available View options include:

- Icons (default) displays each script as an icon identified by the script name. Click the Show Results check box to additionally display run results as icons identified by the script name.

- Details displays each script as a line in a report. Each line includes a check box to enable the selection of scripts for deletion, an edit icon to enable the script to be loaded into the script editor, the script name, the script owner, when the script was last updated and by who, the size in bytes, the number of times the script has been run linked to the run results, and an icon to enable the script to be run.

Details view offers the following additional controls:

- Delete Checked. In Details view, select the check box associated with the script you want to delete and click Delete Checked. See "Deleting a SQL Script".

- Sort. In Details view, click a column heading to sort the listed scripts by that column.

- Upload. Click Upload to upload a script from your local file system into SQL Scripts. See "Creating a SQL Script".

- Create. Click Create to create a new script in the Script Editor. See "Creating a SQL Script".

Switching to Another SQL Workshop Component

You can navigate to another SQL Workshop component by selecting one of the following from the Component list located on the upper right side of the page:

- Object Browser. See "Managing Database Objects with Object Browser".

- SQL Commands. See "Using SQL Commands".

- SQL Scripts. See "Using SQL Scripts".

- Query Builder. See "Building Queries with Query Builder".

About the Tasks List

A Tasks list displays on the right side of the SQL Scripts page.

The Task list contains the following links:

- Manage Results enables you to view, search, and display results. See "Viewing SQL Script Results".

- Show Quotas displays the Script Quotas page. The Script Quotas page shows the maximum size of a single result, the maximum size of all results, the quota used and the quota free. It also shows the maximum size of a SQL Script.

- Export enables you to export multiple scripts from the current SQL Script Repository for import into SQL Scripts in a different workspace. The scripts you select to export are encoded in a single export script written to your local file system. The export script is named workspace_name_script.sql by default. See "Exporting and Importing SQL Scripts".

- Import enables you to import a script exported by this, or a different workspace. Import only imports scripts encoded in an export script created using Export. The export script to import must be accessible on your local file system. See "Exporting and Importing SQL Scripts".

Creating a SQL Script

You can create a new script in the Script Repository by:

- Creating a new script in the Script Editor

- Uploading a script from your local file system

Topics in this section include:

- Creating a SQL Script in the Script Editor

- Uploading a SQL Script

Creating a SQL Script in the Script Editor

To create a new SQL script in the Script Editor:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. Click the Create button.
The Script Editor appears.

3. Enter a name for the script in the Script Name field.
Script name extensions are optional.

4. Enter the SQL statements, PL/SQL blocks and SQL*Plus commands you want to include in your script.
Remember that SQL Command Line commands are ignored at run time.

5. Click Save to save your script to the repository.
The SQL Scripts page appears listing your newly saved script.

Uploading a SQL Script

To upload a script from your local file system:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. Click the Upload button.
The Upload Script dialog appears.

3. To upload a script you can either:

- Enter the name and path to the script you want to upload to the Script Repository.

- Click Browse to locate the script you want to upload.

4. Optionally rename the script by entering the new name in the Script Name field.
This is the name given to the script in the Script Repository.

5. Click Upload to add the script to the Script Repository.
The SQL Scripts page appears listing your newly uploaded script.

The script is parsed during upload. If it has a syntax error, an error icon appears in place of the run icon in the SQL Scripts page Details view.

If a script of the same name exists in the Script Repository, you are prompted to rename it.

Using the Script Editor

You use the Script Editor to add content to a new script, to edit existing scripts, and to run and delete scripts in the script repository.

Topics in this section include:

- Editing an Existing Script

- Searching and Replacing Text or Regular Expressions

- Summary of Script Editor Controls

Editing an Existing Script

To edit a SQL script:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. You can load a script into the editor as follows:

- In Icons view, click the script icon.

- In Details view, click the Edit icon.

The Script Editor appears.

3. Edit the script.
Note that new lines are automatically indented to the previous line start column. Other features of the Script Editor include:

- Search and Replace. Click Find to display the text and JavaScript regular expression find and replace options. Click Find again to hide the options. See "Searching and Replacing Text or Regular Expressions".

- Line Selection. Click the line number on the left side of the Script Editor to select the associated line of your script for copying or deleting.

- Cut, Copy, and Paste. Use standard edit controls to cut, copy and paste content in the Script Editor.

- Auto indenting lines. New lines automatically indent to the previous line start column.

You can test your script during editing by running the script to reveal errors. The Run Script dialog and the Script Results pages enable you to resume editing the script. See "Executing a SQL Script", and "Viewing SQL Script Results".

4. Click Save to save your script to the Script Repository,
The SQL Scripts page appears.

Searching and Replacing Text or Regular Expressions

Clicking the Find button in the Script Editor displays the Find and Replace with fields at the top of the page. Use these fields to search for and replace text strings and JavaScript regular expressions within a script. To exit Find mode, click Find again.

To access Find mode in the Script Editor:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. Select a script.
The Script Editor appears.

3. Click the Find button.
The Find and Replace fields appear.

4. In the Find field, enter the string you wish to find. In Replace with, enter the new string to be added and then click the appropriate button (Replace, Find Next, or Replace All.)
To further refine your search, select the appropriate check box:

- Match Case

- Match Whole Words

- Match Regular Expression

5. To exit Find mode, click Find.

Summary of Script Editor Controls

Table 18-1describes the buttons and controls available within the Script Editor

Table 18-1 Buttons and Controls within the Script Editor

Button

Descriptions

Cancel

Cancel the editing session and exit the Script Editor without saving changes made since the last save.

Download

Saves a copy of the current script to your local file system. Enter a name for the script on your local file system and a directory path.

Delete

Removes the current script from the Script Repository.

See Also: "Deleting a SQL Script"

Save

Save your changes to the current script to the Script Repository.

Run

Submits the script for execution.

See Also: "Executing a SQL Script"

Undo (Ctrl+Z)

Removes, or undoes, the most recent line edit made in the Script Editor.

Redo (Ctrl+Y)

Repeats the most recent line edit made in the Script Editor.

Find

Click Find to access search and replace mode. Click Find again to exit Find mode.

See Also: "Searching and Replacing Text or Regular Expressions"

Deleting a SQL Script

You can delete scripts from the Script Repository by deleting selected scripts from the SQL Scripts page, or deleting the current script in the Script Editor.

Topics in this section include:

- Deleting Scripts from the SQL Scripts Page

- Deleting a Script in the Script Editor

Deleting Scripts from the SQL Scripts Page

To delete scripts from the SQL Scripts page.

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. From the View list, select Details and click Go.
Details view appears.

3. Select the scripts to be deleted.
To select individual scripts, click the check box to the left of the Edit icon. To select all scripts visible in the current page, click the check box in the column heading.

4. Click Delete Checked to permanently remove the selected scripts from the Script Repository. You are prompted to confirm this action before the script is deleted.
The message "Script(s) deleted" appears above the updated list of Scripts.

Deleting a Script in the Script Editor

To delete a script in the Script Editor:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. Open the script you want to delete in the Script Editor.

3. Click Delete to permanently remove the script from the Script Repository. You are prompted to confirm this action before the script is deleted.
The SQL Scripts page appears. The message "Script(s) deleted" appears above the updated list of scripts.

Copying a SQL Script

You can copy a script in the Script Repository by saving it with a new name.

To copy a script:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. Load the script to copy into the editor.

3. Enter a name for the copied script in the Script Name field.

4. Click Save to save a copy of the script in the Script Repository.
The SQL Scripts page appears listing the newly copied script.

Executing a SQL Script

You can execute scripts stored in the Script Repository. You can submit a script for execution either from the Script Editor, or from the SQL Scripts page.

When you submit a script for execution, the Run Script page appears. It displays the script name, when it was created and by who, when it was last updated and by who, the number of statements it contains, and its size in bytes. It also lists unknown statements such as SQL*Plus commands that it will ignore during execution.

Finally, it lists statements with errors. If there are errors, the Run control does not appear.

Topics in this section include:

- Executing a SQL Script in the Script Editor

- Executing a SQL Script from the SQL Scripts Page

- About the Run Script Page

See Also:
"About Long Operations"

Executing a SQL Script in the Script Editor

To execute a script in the Script Editor:

1. Open the script you want to execute in the Script Editor. See "Using the Script Editor".

2. Click Run in the Script Editor.

3. The Run Script page appears.
The Run Script page displays information about the script and lists statements in error preventing execution, or statements such as SQL*Plus commands that will be ignored when the script is executed.

The Run Script page has three controls:

- Cancel returns you to the SQL Scripts page without executing the script.

- Edit Script loads the script into the Script Editor. Note that Edit Script appears instead of Run when a script has errors.

- Run to submit the script for execution. Note that Run is not available if there are script errors.

4. Click Run to submit the script for execution.
The Manage Script Results page appears listing script results.

5. To view script results, click the View icon under View Results.

See Also:
"Viewing SQL Script Results"

Executing a SQL Script from the SQL Scripts Page

To execute a script from the SQL Scripts page:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. From the View list, select Details and click Go.
Details view appears.

3. Click the Run icon for the script you want to execute. The Run icon is located on the far right side adjacent to the script name.

4. The Run Script page appears.
The Run Script page displays information about the script and lists statements in error preventing execution, or statements such as SQL*Plus commands that will be ignored when the script is executed. The Run Script page has three controls:

Cancel to return to the SQL Scripts page without executing the script.

Edit Script to load the script into the Script Editor. Edit Script appears instead of Run when a script has errors.

Run to submit the script for execution. Run is not available for scripts with errors.

5. Click Run to submit the script for execution.
The Manage Script Results page appears listing available results for the script.

6. Click the View icon for the results you want to view. The View icon is at the right end of the scripts listed in the Manage Script Results page.

See Also:
"Viewing SQL Script Results"

About the Run Script Page

On the Run Script page, you can:

- Cancel the execution. Click Cancel to exit the Run Script page without executing the script. The SQL Scripts page appears.

- Edit the script. Edit Script appears instead of Run when a script has errors. Click Edit Script to load the script into the Script Editor to remove the lines with errors.

- Execute the script. Click Run to execute the script.

Viewing SQL Script Results

You use the Manage Script Results page to view and delete script results.

You can also select script results to view from the Icons view of the SQL Scripts page, and from the Results column of the SQL Scripts page Details view.

Topics in this section include:

- Viewing Results from the SQL Scripts Page

- About the Results Page

Viewing Results from the SQL Scripts Page

To view script results from the SQL Scripts page:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. You can access the Manage Script Results page in the following ways:

- On the Tasks list, click Manage Results.

- In Details view, click the Results number for the script you want to display.

- In Icons view, click the Show Results check box and then the appropriate icon. Results icons only appear in the Icons view if you click the Show Results check box.

The Manage Script Results page appears, listing available results for the script. See "About the Manage Script Results Page".

3. Click the View icon for the results you want to view. The View icons display on the far right side of page under the heading View Results.
The Results page appears. See "About the Results Page".

About the Manage Script Results Page

On the Manage Script Results page you can:

- Search for a result. Enter a result name or partial name in the Script field and click Go. To view all results, leave the Script field blank and click Go. You control how many rows display by making a selection from the Display list.

- Change the Page View. You can change the appearance of the page by making a selection from the View list. Available View options include:

- Icons displays each result as an icon identified by the script name, and time and date stamp.

- Details displays each result as a line in a report. Each line includes a check box to enable the selection of results for deletion, the associated script name which is a link enabling it to be loaded into the Script Editor, who ran the script, when the run started, how long it took to run, whether the run is complete or not, the number of statements executed, the size in bytes, and a View icon to view the results.

- Delete a result. In Details view, select the check box associated with each result you want to delete, and click Delete Checked.

- Sort results. In Details view, click a column heading to sort the listed results by that column.

About the Results Page

The Results page displays the script name and status (Complete, Canceled, Executing or Submitted), and lists the statements executed.

On the Results page you can:

- Choose the view. Click the Detail or Summary radio button and click Go to specify whether to display complete or summarized information.

- Choose the number of rows to display. In Summary view, make a selection from the Display list and click Go to specify the number of rows displayed.

- Sort the statement report. In Summary view, select a column heading to sort the listed values by that column.

- Edit the script. Click Edit Script to load the script into the Script Editor. See "Using the Script Editor".

Exporting and Importing SQL Scripts

You can transfer scripts from your current Script Repository to a Script Repository in a different workspace by using the Export and Import tasks. Exported scripts are encoded in a single file on your local file system. Once exported, you then log in to another workspace and import the file. During import, the file is run to re-create the scripts in the current Script Repository.

By default, the Export SQL Scripts page lists all scripts in the Script Repository created by the current user. There are two panes on the Export SQL Scripts page, the Scripts pane and the Scripts to Export pane. You use the Scripts pane to select scripts to export. Then, you use the Scripts to Export pane to finalize the scripts to export, to choose a name for the export script, and to save the selected scripts in the export script on your local file system. You use the Import Scripts pane to select the export script containing the scripts to import.

Topics in this section include:

- Copying Scripts to an Export Script

- Importing Scripts from an Export Script

Copying Scripts to an Export Script

To copy scripts to an export script:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. On the Tasks list, click Export.
The Export SQL Scripts page appears.

3. Click the check box for each of the scripts you want to export. The check boxes display on the left side adjacent to the script name. To select all displayed scripts for export, click the column head check box.

4. Click Add to Export to create a list of scripts to be added to the export script.
The selected scripts are added to the list of scripts in the Scripts to Export pane.

5. Enter a name for the export script in the File Name field.
The default script name is workspace_name_script.sql.

6. Click Export All to export the scripts to the export script.
You are prompted to enter the directory where you want to save the export script.

About the Scripts Pane

In the Scripts pane you can:

- Search for a script. Enter a script name or partial name in the Find field and click Go. To view all scripts, leave the Find field blank, select - All Users - from the Owner list and click Go. You control how many rows display by making a selection from the Display list.

- Cancel the export. Click Cancel to return to the SQL Scripts page without exporting any scripts, or to return to the SQL Scripts page after saving an export script.

- Selecting scripts to export. Click Add to Export to add scripts to the export script. Scripts added to the export script are no longer listed in the Script pane, but appear in the Scripts to Export pane.

- Sort scripts. Click a column heading to sort the listed scripts by that column.

About the Scripts to Export Pane

In the Scripts to Export pane you can:

- Rename the export script. Enter a name for the export script in the File Name field or leave the default script name.

- Remove scripts. Click the check box adjacent to the scripts you want to remove f and click Remove Checked. Scripts removed are no longer listed in the Scripts to Export pane, but appear in the Scripts pane.

- Save the export script. Click Export All to save the export script to your local file system. You are prompted to enter the directory where you want to save the export script.

Importing Scripts from an Export Script

To import scripts from an export script:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. On the Tasks list, click Import.
The Import Scripts pane appears. See "About the Import Scripts Pane".

3. Enter the name and path to the export script you want to import to the Script Repository, or click Browse to locate the export script you want to import.

4. Click Next to list the scripts in the export script.
The Action column indicates whether the imported script is new, or whether it will replace an existing script of the same name.

5. Click Import Script(s) to import the listed scripts into the current Script Repository.
The SQL Scripts page appears listing the imported scripts.

About the Import Scripts Pane

In the Import Scripts pane you can:

- Enter the export script. Enter the name and path of the script to import in the Import file field, or click Browse to locate the script.

- Cancel the import. Click Cancel to return to the SQL Scripts page without importing scripts.

- Proceed with the import. Click Next to import the scripts in the specified export script. You can review the listed scripts to import.

- Choose another export file. Click Previous to return to the Import Scripts file selection page to choose a different export script.

- Import the scripts. Click Import Script(s) to import the scripts contained in the export script.

Viewing Script and Result Quotas

You can view the script limits in the current workspace on the Script Quotas page.

To view the Script Quotas page:

1. On the Workspace home page, click SQL Workshop and then SQL Scripts.
The SQL Scripts page appears.

2. On the Tasks list, click Show Quotas.
The Script Quotas page appears.

3. Click OK to return to the SQL Scripts page.

About the Script Quotas Page

The Script Quotas page displays the following limits:

- Result Quota in Bytes:

- Maximum Script Result Size. The maximum size in bytes of a single script result.

- Quota for All Script Results. The maximum size in bytes of all results in this workspace.

- Used. The number of bytes currently used in this workspace.

- Free. The number of bytes currently free in this workspace.

- Quota. A usage bar illustrating the percentage of quota currently used.

- Script Quota in Bytes:

- Maximum Script Size. The maximum size in bytes of a single script. The size is set by the Oracle Application Express administrator and cannot be changed from within the Workspace.

- Maximum Script Size. The maximum size in bytes of a single script.

19 Using SQL Commands

This section provides information on how to use SQL Commands to create, edit, view, run, and delete SQL commands.

This section contains the following topics:

- What is SQL Commands?

- Accessing SQL Commands

- About the SQL Commands Home Page

- Using the Command Editor

- Saving a SQL Command

- Copying a Command

- Using Saved Commands

- Using SQL Command History

- Viewing Results

- Using Explain Plan

See Also:

- Oracle Database SQL Language Reference for detailed information about SQL statements and other parts of SQL, such as operators, functions, and format models

- Oracle Database Concepts for conceptual information about SQL

- SQL*Plus User's Guide and Reference for information about SQL*Plus, Oracle's version of SQL

- Oracle Database Sample Schemas for information about the HR sample schema that is used for examples in this chapter

What is SQL Commands?

You can use SQL Commands to create, edit, view, run, and delete SQL commands. A SQL command can contain SQL statements or PL/SQL blocks.

When using SQL Commands, remember the following:

- SQL commands created in the Query Builder can be accessed in SQL Commands.

- Saved SQL commands must have names unique within a given workspace.

- There is no interaction between SQL Commands and SQL Scripts.

- You can cut and paste a SQL command from SQL Commands to run in the SQL Script Editor.

See Also:
"Using SQL Scripts"

Accessing SQL Commands

To access SQL Commands:

1. Log in to the Workspace home page.
The Workspace home page appears.

2. To view the SQL Commands home page you can either:

- Click SQL Workshop and then SQL Commands to drill-down to the SQL Commands home page.

- Click the down arrow on the right side of the SQL Workshop icon to view a drop down menu. Then select the SQL Commands menu option.

Note:
For the purposes of consistency, this document uses the primary navigation path (or drill-down approach) when explaining navigation.

About the SQL Commands Home Page

The SQL Commands home page is divided into two sections: a command editor and a display pane. You use the command editor to execute SQL commands and the display pane to view output, saved command lists, and history lists.

The top of the SQL Commands home page features a command editor and the following controls:

- Autocommit. If available, click the Autocommit check box to enable autocommit and disable transactional commands. See "About Transactions in SQL Commands".

- Display. Make a selection from the Display list to specify the number of rows of output to display at one time up to a maximum of 100,000. All rows of DBMS Output are displayed regardless of the Display list setting.

- Clear Command icon. The Clear Command icon resembles a pencil with an eraser. Use this icon to clear the text in the command editor.

- Find Tables icon. The Find Tables icon resembles a flashlight. Click this icon to view tables and views. See "Using the Find Tables Icon".

- Save. Click the Save button to save the contents of the command editor, or the currently highlighted content to a file. You are prompted to enter a name and an optional description. The new command appears in the Saved SQL list. See "Saving a SQL Command".

- Run. Click the Run button (or press Ctrl+Enter) to run the command in the command editor, or the currently highlighted command in the command editor. See "Running a SQL Command".

See Also:
"Using the Command Editor"

Selecting a Schema

A schema is a logical container for database objects. To access objects in another schema, make a selection from the Schema list in the upper right side of the page.

Switching to Another SQL Workshop Component

You can navigate to another SQL Workshop component by selecting one of the following from the Component list located on the upper right side of the page:

- Object Browser. See "Managing Database Objects with Object Browser".

- SQL Commands. See "Using SQL Commands".

- SQL Scripts. See "Using SQL Scripts".

- Query Builder. See "Building Queries with Query Builder".

About the Display Pane

A display pane displays at the bottom of the SQL Commands home page.

The display pane features five tabs:

- Results. Click the Results tab to see the results from the last successfully executed SQL command. Click DBMS Output at the bottom of the displayed results to display lines of DBMS output. This control only appears when there is DBMS output to display. Click Download to export results to a comma-separated file on your local file system. See "Viewing Results".

- Explain. Click the Explain tab to examine the execution plan used by the optimizer for statements that make changes to the database. Objects in the output are linked to the Object Browser. Click the linked object to view its properties in the Object Browser. See "Using Explain Plan".

- Describe. Enter Describe object_name and click Run to display column definitions for a table or view, or specifications for a function or procedure in the Describe tab. Select links in the Describe results to write that information into the command editor. For example, click a table name to add owner.table, click a column name to add the column name, click a procedure or function name to add the object call with parameters, or click a package name to add the package call.

- Saved SQL. Click the Saved SQL tab to display a list of all SQL commands saved in the current workspace. Click the command title to load it into the command editor. See "Using Saved Commands"

- History. Click the History tab to list your recently executed commands. Your last 200 executed commands are saved. See "Using SQL Command History".

Using the Command Editor

You use the command editor in SQL Commands to execute SQL commands within Application Express.

Topics in this section include:

- Running a SQL Command

- About Transactions in SQL Commands

- About Unsupported SQL*Plus Commands

- About Command Termination

- Using Bind Variables

Running a SQL Command

To execute a SQL Command:

1. On the Workspace home page, click SQL Workshop and then SQL Commands.
The SQL Commands page appears.

2. Enter the SQL command you want to run in the command editor.

3. Click Run (Ctrl+Enter) to execute the command.

Tip:
To execute a specific statement, select the statement you wish to run and click Run.

The results appear in the Results pane.

4. To export the resulting report as a comma-delimited file (.csv) file, click the Download link.

See Also:
"Viewing Results"

About Transactions in SQL Commands

To disable transactional SQL commands in SQL Commands, check the Autocommit check box. Attempting to use any transactional SQL commands such as COMMIT or ROLLBACK when transactional mode is disabled returns an error message.

To enable transactional SQL commands, clear the Autocommit check box. Oracle Application Express verifies that the necessary system resources are available before entering the transactional mode. If resources are unavailable, an error message is displayed.

Transactional mode is a stateful transaction mode where you can, for example, perform an update, select data for review, and COMMIT or ROLLBACK changes. It is implemented using DBMS_JOBS.

Consider the following behavior in transactional mode:

- Actions are not committed to the database until you enter an explicit COMMIT command.

- Exiting SQL Commands terminates and rolls back the current transaction.

- A session timeout terminates and rolls back the current transaction.

Note that the Environment Setting, SQL Commands Maximum Inactivity in minutes, sets the time before an inactive session times out. The default timeout is 60 minutes. See "Configuring SQL Workshop".

- The CSV Export option is not available.

About Unsupported SQL*Plus Commands

SQL Commands does not support SQL*Plus commands. If you attempt to enter a SQL Command Line command such as SET ECHO or DEFINE in SQL Commands, an error message displays.

About Command Termination

You can terminate a command in SQL Commands using a semicolon (;), a forward slash (/), or with nothing. Consider the following valid alternatives:

SELECT * from emp;

SELECT * from emp
/

SELECT * from emp

The first example demonstrates the use of a semicolon (;), the second example demonstrates the use of forward slash (/), and the final example demonstrates a command with no termination.

Using Bind Variables

Bind variables are supported. You are prompted to enter values for bind variables during command execution. Bind variables are prefixed with a colon.

For example

SELECT * from emp where deptno = :dept

In earlier versions of Oracle Application Express, you could check your Workspace ID by running the command:

SELECT :WORKSPACE_ID FROM dual

In this release, run the following SQL command to check your Workspace ID:

SELECT v('WORKSPACE_ID') FROM dual

Saving a SQL Command

You can save commands you enter in SQL Commands.

To save a SQL command:

1. On the Workspace home page, click SQL Workshop and then SQL Commands.
The SQL Commands page appears.

2. Enter the command in the command editor.

3. Click Save to save the command.
You are prompted to enter a name and description for the command.

4. Click Save, or click Cancel to return to the command editor without saving.
The saved command is listed in the display area.

Copying a Command

To copy a SQL command:

1. On the Workspace home page, click SQL Workshop and then SQL Commands.
The SQL Commands page appears.

2. Click the Saved SQL tab.
The Saved SQL list of commands appears in the display pane.

3. Click the title of the command to load it into the command editor

4. Click Save to save the command.

5. Enter a new name for the command in the Name field and click Save.
The command is copied to the new name.

Using Saved Commands

You can access the commands you save and commands saved by other users in the same workspace. You can also access SQL commands you and other users of the same workspace saved from the Query Builder.

Topics in this section include:

- Accessing Saved Commands

- About the Saved SQL Pane

Accessing Saved Commands

To access saved SQL commands:

1. On the Workspace home page, click SQL Workshop and then SQL Commands.
The SQL Commands page appears.

2. Click the Saved SQL tab.
The Saved SQL list of commands appears in the display pane.

3. Click the title of the command to load it into the command editor.
The command appears in the editor.

4. Click Run to execute the command.

About the Saved SQL Pane

The Saved SQL pane displays a list of all commands saved under the current workspace. The list displays commands saved from SQL Commands and SQL commands saved from Query Builder. Saved SQL commands must have unique names in the current workspace. The same name cannot be used in the Query Builder and SQL Commands.

Each command entry shows the owner name, the command name, the first characters of the SQL command, a description if it exists, who last updated the command and when.

On the Saved SQL pane you can:

- Show commands by owner. Make a selection from the Owner list to specify the user whose commands you want to display. To view all scripts select -All Users-.

- Search for a command. Enter a command name or partial name, or enter a code snippet in the Find field and click Go. To view all scripts, leave the Find field blank and click Go. You control how many rows display by making a selection from the Rows list.

- Set the Number of Output Rows. Make a selection from the Display list to specify the number of Saved SQL commands to display at one time.

- Delete a command. Click the check box associated with each command you want to delete, and click Delete Checked.

- Sort commands. Click a column heading to sort the listed commands by that column.

Using SQL Command History

Commands you have executed are stored in the command history regardless of whether you explicitly save them. You use SQL Command History to access commands you have executed in SQL Commands.

Topics in this section include:

- Accessing a Command from Command History

- About the History Pane

Accessing a Command from Command History

To access history commands:

1. On the Workspace home page, click SQL Workshop and then SQL Commands.
The SQL Commands page appears.

2. Click the History tab.
The list of commands in History appears in the display pane.

3. Click the partial command displayed in the SQL column.
The command appears in the editor.

About the History Pane

The History pane displays a list of commands you have executed.

Each history entry shows the time the command was last executed, the first characters of the command, and the schema in which it was executed.

On the History pane you can:

- Load a command. Click the partial command displayed in the SQL column to load the command into the command editor. When the command loads, it also sets the schema in which it was last executed.

- Sort by time. Click the Time column heading to sort the command history by least recent or most recent.

Viewing Results

When you execute a SQL command, the results are displayed. The results of the last executed command are available until you execute another SQL command, or leave SQL Commands.

Topics in this section include:

- Accessing the Results Pane

- About the Results Pane

Accessing the Results Pane

To display SQL command results:

1. On the Workspace home page, click SQL Workshop and then SQL Commands.
The SQL Commands page appears.

2. Click the Results tab.

The HTML formatted results appear in the display pane.

3. Click DBMS Output to display plain text DBMS output results.
The DBMS Output control only appears if there is DBMS output in addition to HTML formatted results. It does not appear if there is only DBMS output, or if there is only HTML formatted output.

About the Results Pane

The Results pane displays SQL command results as HTML formatted table. The number of rows returned appears at the end of the output, and the time taken. DBMS output appears as plain text after the HTML formatted results.

On the Results pane you can:

- Display DBMS output. Click DBMS Output at the bottom of the displayed results to display lines of DBMS output. This control only appears when there is DBMS output to display.

- Export results. Click CSV Export to export results to a comma-separated file on your local file system. You are prompted to enter a name and directory for the file.

Using Explain Plan

You can view the explain plan the Oracle Optimizer uses to run your SQL command. You do not need to execute the command to view the explain plan.

Topics in this section include:

- Viewing an Explain Plan

- About Explain Plan Pane

Viewing an Explain Plan

To view the Explain Plan:

1. On the Workspace home page, click SQL Workshop and then SQL Commands.
The SQL Commands page appears.

2. Enter or load the command whose plan you want to view.

3. Click the Explain tab.
The explain plan used by the optimizer appears in the display pane.

About Explain Plan Pane

The Explain Plan pane shows the plan used by the Oracle Optimizer to run your SQL command. It typically displays the Query Plan, Index Columns and Table Columns used.

On the Explain Plan pane you can:

- View object definitions. Click the object name in Query Plan to display the object definition in the Object Browser.

- View index definitions. Click the index name in Table Columns to display the index definition in the Object Browser.

20 Using Application Express Utilities

This section describes how to use Oracle Application Express utilities to load and unload data from an Oracle database, generate DDL, view object reports, and restore dropped database objects.

This section contains the following topics:

- About Importing, Exporting, Loading, and Unloading Data

- Loading and Unloading Data from the Database

- Generating DDL

- Viewing Object Reports

- Using the Recycle Bin to View and Restore Dropped Objects

- Reviewing Application Express Views

- Comparing Schemas

- Monitoring the Database

- Viewing Database Details

About Importing, Exporting, Loading, and Unloading Data

You have a number of options when copying data between Oracle databases or between an Oracle database and external files. Data copying is accomplished by exporting and importing data, and by unloading and loading data. The following table defines these terms.

Term

Definition

Exporting

Copying database data to external files for import into another Oracle database only. The files are in a proprietary binary format.

Importing

Copying data into the database from external files that were created by exporting from another Oracle database.

Unloading

Copying database data to external text files for consumption by another Oracle database or another application (such as a spreadsheet application). The text files are in an industry-standard format such as tab-delimited or comma-delimited (CSV).

Loading

Copying data into the database from external text files that are in either a standard delimited format or in any of the formats that are supported by the Oracle SQL*Loader utility.

You can export data from any Oracle Database edition (Express Edition, Standard Edition, and Enterprise Edition) into any other edition.

This section contains the following topics:

- Choosing the Right Import/Export/Load/Unload Option

Choosing the Right Import/Export/Load/Unload Option

The Oracle Database and Oracle Application Express provide a number of powerful options for importing, exporting, loading, and unloading data. Table 20-1 provides a summary of these options.

Table 20-1 Summary of Oracle Application Express Import/Export Options

Feature or Utility

Description

Data Load/Unload wizards in Oracle Application Express

- Easy to use graphical interface

- Loads/unloads from and to external text files (delimited fields) or XML files

- Loads/unloads tables only, one table at a time

- Access only to schema of logged-in user

- No data filtering

SQL*Loader utility

- Command-line interface, invoked with sqlldr command

- Bulk-loads data into the database from external files

- Supports numerous input formats, including delimited, fixed record, variable record, and stream

- Loads multiple tables simultaneously

- Powerful data filtering capabilities

Data Pump Export and Data Pump Import utilities

- Command-line interface, invoked with expdp and impdp commands

- Exports and imports from one Oracle database to another (proprietary binary format)

- Imports/exports all schema object types

- Imports/exports entire database, entire schema, multiple schemas, multiple tablespaces, or multiple tables

- Powerful data filtering capabilities

- High speed

- Does not support XMLType data

Export and Import utilities

- Command-line interface, invoked with exp and imp commands

- Exports and imports from one Oracle database to another (proprietary binary format)

- Supports XMLType data

- Does not support the FLOAT and DOUBLE data types

- Capabilities similar to Data Pump; Data Pump is preferred unless you must import or export XMLType data

Table 20-2 provides a number of load, unload, import, and export scenarios and suggests the appropriate option to use for each.

Table 20-2 Import/Export Scenarios and Recommended Options

Import/Export Scenario

Recommended Option

You have fewer than 10 tables to load, the data is in spreadsheets or tab- or comma-delimited text files, and there are no complex data types (such as objects or multivalued fields).

Data Load/Unload wizards in Oracle Application Express

You have to load data that is not delimited. The records are fixed length, and field definitions depend on column positions.

SQL*Loader

You have tab-delimited text data to load, and there are more than 10 tables.

SQL*Loader

You have text data to load, and you want to load only records that meet certain selection criteria (for example, only records for employees in department number 3001).

SQL*Loader

You want to import or export an entire schema from or to another Oracle database. There is no XMLType data in any of the data.

Data Pump Export and Data Pump Import

You want to import or export data from or to another Oracle database. The data contains XMLType data and contains no FLOAT or DOUBLE data types.

Import (imp) and Export (exp)

See Also:
Oracle Database Utilities for more information on Data Pump, the Import and Export utilities, and SQL*Loader

Loading and Unloading Data from the Database

The Data Load/Unload wizards in Oracle Application Express enable you to easily load and unload delimited text data to and from the database. The step-by-step wizards have the following features:

- You can load or unload XML files or delimited-field text files (such as comma-delimited (.csv) or tab-delimited files).

- You can load by copying and pasting from a spreadsheet.

- You can omit (skip) columns when loading or unloading.

- You can load into an existing table or create a new table from the loaded data.

- When loading into a new table, the primary key can be taken from the data or generated from a new or existing Oracle sequence.

- When loading into a new table, column names can be taken from the loaded data.

- Each time that you load from a file, file details are saved in a Text Data Load Repository. You can access these files from within the repository at any time.

Limitations include the following:

- The wizards load and unload table data only. They do not load or unload other kinds of schema objects.

- You can load and unload to and from your own schema only. This is also true for users with administrator privileges.

- You can load or unload only a single table at a time.

- There are no data type limitations for unloading to text or XML files, or for loading from XML files. However, when loading from spreadsheets (through copy and paste) or from text files, only the following data types are supported: NUMBER, DATE, VARCHAR2, CLOB, BINARY_FLOAT, and BINARY_DOUBLE.

Supported unload formats include:

- Text such as comma-delimited or tab-delimited data

- XML documents

This section contains the following topics:

- Accessing the Data Load/Unload Page

- Loading Data

- Unloading Data

- Using Text Data Load Repository

Accessing the Data Load/Unload Page

To access the Data Load/Unload page:

1. On the Workspace home page, click the Utilities icon.

2. Click Data Load/Unload.
The Data Load/Unload page appears.

3. Click the appropriate icon to load data, unload data, or view the repository.

Loading Data

You can load data into the Oracle Application Express database in the following ways:

- Copy and paste data from a spreadsheet.

- Upload a spreadsheet file in a delimited format (such as comma-delimited (.csv) or tab-delimited).

- Upload a text file containing comma-delimited or tab-delimited data.

Topics in this section include:

- Loading a Text File

- Loading an XML Document

- Loading Spreadsheet Data

See Also:
"Choosing the Right Import/Export/Load/Unload Option"

Loading a Text File

For files smaller than 30KB, you can copy and paste tab-delimited data directly into the Load Data Wizard. For files larger than 30KB, you must upload a separate file.

To load a text file:

1. On the Workspace home page, click the Utilities icon.

2. Click Data Load/Unload.

3. Click Load.

4. Click Load Text Data.
The Load Data Wizard appears.

5. Under Load To, select either Existing table or New table.

6. Under Load From, select either Upload file or Copy and paste.

7. Follow the on-screen instructions.

Loading Spreadsheet Data

You can load spreadsheet data by either copying and pasting text, or by loading a file. To copy and paste text, the spreadsheet file must be less than 30KB. For files larger than 30KB, you can import the file in a delimited format (such as comma-delimited (.csv) or tab-delimited), upload the file, and then load the data into a new or existing table.

To load spreadsheet data:

1. On the Workspace home page, click the Utilities icon.

2. Click Data Load/Unload.

3. Click Load.

4. Click Load Spreadsheet Data.
The Load Data Wizard appears.

5. Under Load To, select either Existing table or New table.

6. Under Load From, select either Upload file or Copy and paste.

7. Follow the on-screen instructions.

Loading an XML Document

Oracle Application Express supports XML documents in Oracle's canonical XML format.

In Oracle's canonical XML format, each element represents a column value, each element is named after the column, all elements that are part of the same row are children of a <ROW> element, and all <ROW> elements are children of a <ROWSET> element.

To load an XML document:

1. On the Workspace home page, click the Utilities icon.

2. Click Data Load/Unload.

3. Click Load.

4. Click Load XML Data.
The Load XML Data Wizard appears.

5. Follow the on-screen instructions.

Unloading Data

You can use the Unload page to export the contents of a table to a text file or XML document.

Topics in this section include:

- Unloading a Text File

- Unloading to an XML Document

See Also:
"Choosing the Right Import/Export/Load/Unload Option"

Unloading a Text File

Use the Unload to Text Wizard to export the contents of a table to a text file. For example, you could export an entire table to a comma-delimited file (.csv).

To unload a table to a text file:

1. On the Workspace home page, click the Utilities icon.

2. Click Data Load/Unload.

3. Click Unload.

4. Click Unload To Text.
The Unload to Text Wizard appears.

5. Follow the on-screen instructions.

You select the schema and choose the table and columns to be exported. You can also specify the type of separator to be used to separate column values as well as whether column text strings are identified using single or double quotation marks.

Unloading to an XML Document

Use the Unload to XML Wizard to export the contents of a table to an XML document adhering to the Canonical XML specification.

To unload a table to an XML document:

1. On the Workspace home page, click the Utilities icon.

2. Click Data Load/Unload.

3. Click Unload.

4. Click Unload to XML.
The Unload to XML Wizard appears.

5. Follow the on-screen instructions.

You select the schema and choose the table and columns to be exported.

Using Text Data Load Repository

Loaded text data files are stored in the Text Data Load Repository.

To access the Text Data Load Repository:

1. On the Workspace home page, click the Utilities icon.

2. Click Data Load/Unload.

3. Click Repository.

4. To filter the display, make a selection from the Show list and click Go.

5. To view information about a specific file, click the View icon.

6. To delete an imported file, select it and click Delete Checked.

Generating DDL

With Oracle Application Express, you can generate Data Definition Language (DDL) statements from the Oracle data dictionary. These scripts can be used to create or re-create database schema objects. The scripts can be generated to display inline or saved as a script file. You can generate the create scripts for all objects for a specific schema, specific object types, or specific objects.

If you are running Oracle Application Express with Oracle Database 10g release 1 (10.1) or higher, you can generate Data Definition Language (DDL) statements from the Oracle data dictionary. These scripts can be used to create or recreate database schema objects. The scripts can be generated to the screen, or they can be saved as a SQL Script. You can generate the create scripts for all objects for a specific schema, specific object types, or specific objects.

To generate a DDL statement:

1. On the Workspace home page, click the Utilities icon.

2. Click Generate DDL.
The Generate DDL page appears.

3. Click Create Script.
The Generate DDL Wizard appears.

4. Select a database schema and click Next.

5. Define the object type:

a. Output - Specify an output format. Select either Display Inline or Save As Script File.

b. Check All - Select this option to include all object types for which to generate DDL.

c. Object Type - Select the object types for which to generate DDL.

d. To select object names for the selected object types, click Next and follow the on-screen instructions.

6. Click Generate DDL.

See Also:

- Oracle Database SQL Language Reference for information about DDL statements

- "The Data Dictionary" in Oracle Database Concepts for information about the data dictionary

Viewing Object Reports

Utilities includes a variety of object reports to help you better manage the objects in your database.

Topics in this section include:

- Table Reports

- Security Reports

- PL/SQL Reports

- Exception Reports

- All Object Reports

Table Reports

Use the Table reports to view specific details about the tables within your database.

To view the Table reports:

1. On the Workspace home page, click the Utilities icon.

2. Click Object Reports.
The Object Reports page appears.

3. In the Table Reports section, select the report you want to view:

- Table Columns

- Table Comments

- Table Constraints

- Table Statistics

- Table Storage Sizes

4. To filter a report, enter search criteria in the fields provided or make selections from the lists, and click Go.

5. To view reports for a different schema, select the schema from the Schema list on the upper right side of the page.

Security Reports

Use the Security reports to view object or column privileges granted on database objects owned by other schemas. You can also use these reports to view database role and system privileges.

To view the Security reports:

1. On the Workspace home page, click the Utilities icon.

2. Click Object Reports.
The Object Reports page appears.

3. In the Security Reports section, click the report you want to view:

- Object Grants - View the privileges for an existing schema as well as understand what privileges have been granted from the selected schema to other schemas.

- Column Privileges - View the privileges for an existing schema as well as understand what privileges have been granted from the selected schema to other schemas.

- Role Privileges - View the database roles that have been granted to a selected schema. Roles are collections of various privileges.

- System Privileges - View the database privileges that have been granted to a selected schema.

4. If available, you can filter the report by making a selection from the Show list and clicking Go.

5. To view reports for a different schema, select the schema from the Schema list on the upper right side of the page.

PL/SQL Reports

Use the PL/SQL reports to view program unit arguments or unit line counts as well as to search PL/SQL source code.

Topics in this section include:

- Program Unit Arguments

- Unit Line Counts

- Search PL/SQL Source Code

Program Unit Arguments

Use the Program Unit Arguments report to view package input and output parameters.

To view the PL/SQL Unit Arguments report:

1. On the Workspace home page, click the Utilities icon.

2. Click Object Reports.
The Object Reports page appears.

3. In the PL/SQL Reports section, click Program Unit Arguments.

4. To filter the report, enter a query in PL/SQL Package or Program Unit and click Go.

5. To view reports for a different schema, select the schema from the Schema list on the upper right side of the page.

Unit Line Counts

Use the Unit Line Counts report to view the number of lines of code for each object. Use this report to identify larger PL/SQL program units.

To view the Unit Line Counts report:

1. On the Workspace home page, click the Utilities icon.

2. Click Object Reports.
The Object Reports page appears.

3. In the PL/SQL Reports section, click Unit Line Counts.

4. To filter the report, enter an object name and click Go.

Search PL/SQL Source Code

Use the Search PL/SQL Source code page to search the text within your PL/SQL code. Use this report to find references to tables or functions you might be thinking of deleting. You can also use this page to locate code when you can only recall a code snippet.

To search for PL/SQL source code:

1. On the Workspace home page, click the Utilities icon.

2. Click Object Reports.
The Object Reports page appears.

3. In the PL/SQL Reports section, click Search PL/SQL Source Code.

4. To filter the report:

a. In Object Name, enter a query.

b. In Text, enter the PL/SQL code you want to search for.

c. In From/To Line, enter the range of lines you want to search.

d. Click Go.

5. To view reports for a different schema, select the schema from the Schema list on the upper right side of the page.

Exception Reports

Use the Exception Reports to view unindexed foreign keys and tables without primary keys, indexes, or triggers.

To view Exception reports:

1. On the Workspace home page, click the Utilities icon.

2. Click Object Reports.
The Object Reports page appears.

3. In the Exception Reports section, click the report you want to view.

- Tables without Primary Keys

- Tables without Indexes

- Unindexed Foreign Keys

- Tables without Triggers

4. To filter the report, enter a table name and click Go.

All Object Reports

Use the All Object reports to view objects for the selected schema.

To view the All Object reports:

1. On the Workspace home page, click the Utilities icon.

2. Click Object Reports.
The Object Reports page appears.

3. In the All Object Reports section, select the report you want to view:

- All Objects - Sort objects by creation date as well as last DDL (data definition language).

- Invalid Objects - View all invalid objects in the database by object type.

- Object Creation Calendar - View all objects in a calendar format based on the date each database object was created.

- Object Counts by Type - View the number of database objects by type for the selected schema.

- Data Dictionary - View the data dictionary for this database.

An Oracle data dictionary is a set of tables and views used as a read-only reference about the database. For example, a data dictionary stores information about both the logical and physical structure of the database.

A data dictionary also stores information about valid Oracle database users, integrity constraints for tables in the database, and the amount of space allocated for a schema object as well as how much of it is being used.

4. For All Objects and Invalid Objects reports, you can filter the report:

a. Select an object type.

b. Enter an object name.

c. Click Go.

5. For the Data Dictionary report, you can query for details about database objects:

a. Click the Data Dictionary View Name.
The Data Dictionary Browser appears. Use this page to query the Oracle Data Dictionary for details about database objects.

b. On the Data Dictionary Browser page, select the specific columns you want to see data for or Check All.

c. Click Query.
A report appears.

d. To begin a new query on the same data dictionary view, click New Query.

e. To browse another data dictionary view, click Browse Another View.

See Also:
Oracle Database Concepts for information about the data dictionary

Using the Recycle Bin to View and Restore Dropped Objects

You can use the Recycle Bin to view and restore dropped database objects. When you drop a table, the space associated with the table is not immediately removed. The Oracle database renames the table and places it and any associated objects in the Recycle Bin. You can recover objects in the Recycle Bin at a later time.

This section contains the following topics:

- Managing Objects in the Recycle Bin

- Emptying the Recycle Bin Without Viewing the Objects

Note:
The Recycle Bin feature is only available if you are running with an Oracle 10g or higher database.

See Also:
"Backing Up and Recovering the Database" in Oracle Database Express Edition 2 Day DBA

Managing Objects in the Recycle Bin

You can view objects in the Recycle Bin on the Dropped Objects page. Once you select an object and view the Object Details page, you can choose to purge the object or restore the object by clicking the appropriate button.

To view objects in the Recycle Bin:

1. On the Workspace home page, click the Utilities icon.

2. Click Recycle Bin and then Dropped Objects.
The Dropped Objects page appears.

3. To filter the report, select an object type, enter the object name in the Original Name field, and click Go.

4. To view object details, click the object name.
The Object Details page appears.

5. To restore the current object, click Restore Object.

6. To permanently delete the current object, click Purge Object.

Emptying the Recycle Bin Without Viewing the Objects

To empty the Recycle Bin without viewing the objects:

1. On the Workspace home page, click the Utilities icon.

2. Click Recycle Bin.

3. Click Purge Recycle Bin.
The Purge Recycle Bin page appears.

4. Confirm your request by clicking Purge Recycle Bin again.

Reviewing Application Express Views

You can review Application Express views as well as run queries within a view to find specific information.

To review Application Express views:

1. On the Workspace home page, click the Utilities icon.

2. Click APEX Views.
The Application Express Views page appears.

3. To change the appearance of the page, make a selection from the View list and click Go:

- Icons (the default) displays each Application Express view as a large icon.

- Tree displays each Application Express view in a hierarchy.

- Report displays each view as a line in a report.

4. Click the view you want to review or query.
The Application Express View Details page appears.

5. To run a query:

a. Under Query Columns, select the columns to query.
For a description of each column, read the information in the Description section on this page.

b. (Optional) Under Query Conditions, specify the column, condition, and value for the query.

c. Scroll to the top and click Go.

d. Scroll down to the Data section to view the results of the query. Note that the SQL Query section shows the SQL query resulting from your selections.

Comparing Schemas

You can run a report that compares database objects in two schemas, displaying differences between them. You can compare all objects in the schemas or limit your report to specific objects. To compare two schemas, both must be available to your workspace.

Examples:

- Compare DEMO_ objects by searching for that naming convention. The report indicates if the object exists in each of the two schemas.

- Analyze the object details in the two schemas to determine why one implementation is different. For example, the report might show that an index in one schema has an additional column or a column with a different data type.

To compare schemas:

1. On the Workspace home page, click the Utilities icon.

2. Click Schema Comparison.

3. On the Schema Comparison page, make the appropriate selections to run the comparison:

- Schema 1 and Schema 2 - Select the schemas to compare.

- Compare - Restrict the report to show one object type or select All to show all database objects.

- Search - Enter a case insensitive query for the object name.

- Display - To change the number of rows that appear in the report, make a selection from the Display list.

- Go - Click Go to find the results matching your selections.

- Show Differences Only or Show Details - Select the type of information you want to review.

Monitoring the Database

The reports available on the Database Monitor page provide a database-wide view of the database sessions, system statistics, SQL statements, and longer operations. You can use these reports to identify poorly preforming SQL and to better understand the workload of the database.

To access any of the icons on the Database Monitor page, you must have an account that has been granted an administrator role.

This section contains the following topics:

- Sessions

- About System Statistics

- About Top SQL

- About Long Operations

Sessions

A session is the connection of a user to an Oracle database instance. A session lasts from the time the user connects until the time the user disconnects or exits the database application.

You must have database administrator privileges in order to access the Sessions page.

To access reports on the Sessions page:

1. On the Workspace home page, click the Utilities icon and then Database Monitor.

2. Click Sessions.

3. If prompted, enter the appropriate administrator user name and password and click Login.
The Sessions page appears.

4. To view a report, select one of the following tabs at the top of the page:

- Sessions

- Locks

- Waits

- I/O

- SQL

- Open Cursors

The sections that follow describe each report.

Sessions Report

The Sessions Report displays information about the current sessions in the database. Use the controls at the top of page to narrow the view:

- Search. Enter search criteria and click Go. For search details, click the Search label.

- Status. Select a status and click Go.

- Show. Select how many columns to display and click Go.

- Display. Select the number of rows to appear in the report and click Go.

To view session details, click the Session ID (SID). The Session Details page appears. To remove the current session, navigate to the Session Details page and click Kill Session.

Locks Report

The Locks report displays a report of sessions which have locks that are blocking other session(s). To control the number of rows that appear, make a selection from the Display list and click Go.

Waits Report

The Waits report displays the wait events for each session. Use the controls at the top of page to narrow the view:

- Search. Enter search criteria and click Go. For search details, click the Search label.

- Status. Select a status and click Go.

- Show. Select how many columns to display and click Go.

- Display. Select the number of rows to appear in the report and click Go.

To view session details, click the Session ID (SID). The Session Details page appears. To remove the current session, click Kill Session.

I/O Report

The I/0 report displays details about the I/O for each session. Use the controls at the top of page to narrow the view:

- Search. Enter search criteria and click Go. For search details, click the Search label.

- Display. Select the number of rows to appear in the report and click Go.

To view session details, click the Session ID (SID). The Session Details page appears. To remove the current session, click Kill Session.

SQL Report

The SQL report displays details about the current or last SQL statement executed for each session. Use the controls at the top of page to narrow the view:

- Search. Enter search criteria and click Go. For search details, click the Search label.

- Status. Select a status and click Go.

- Show. Select how many columns to display and click Go.

- Display. Select the number of rows to appear in the report and click Go.

To view session details, click the Session ID (SID). The Session Details page appears. To remove the current session, click Kill Session.

Open Cursors

The Open Cursors report displays details about the number of open cursors for each session. Use the controls at the top of page to narrow the view:

- Search. Enter search criteria and click Go. For search details, click the Search label.

- Status. Select a status and click Go.

- Display. Select the number of rows to appear in the report and click Go.

To view details about a specific open cursor count, click the numeric link under the Open Cursor Count column.

To view session details, click the Session ID (SID). The Session Details page appears. To remove the current session, click Kill Session.

About System Statistics

The System Statistics page displays statistics for:

- Physical I/O. A physical I/O is an I/O that requires disk access. This report displays disk access statistics for physical reads and writes.

- Logical I/O. An logical I/O is an I/O that is satisfied in memory or disk. Displays the sum of buffer reads which might be consistent gets or current mode gets. Redo is the buffer in the SGA that contains information about changes.

- Memory Statistics. Displays memory consumption of the database.

- Time Statistics. Shows various times consumed by the database.

- SQL Cursor Statistics. Displays statistics about the cursors in the Oracle database.

- Transaction Statistics. Shows the number of transactions performed.

To view the System Statistics page:

1. On the Workspace home page, click the Utilities icon and then Database Monitor.

2. Click System Statistics.

3. If prompted, enter the appropriate administrator user name and password and click Login.
The System Statistics page appears.

Additional controls on the System Statistics page include:

- Refresh Report - Refresh the System Statistics report.

- Save Statistics - Save the current report.

- Show delta between current and saved values - Click this check box to display actual statistic values, or display deltas between an saved value and the current value.

See Also:
"Memory Configuration and Use" in Oracle Database Performance Tuning Guide

About Top SQL

The "top" SQL statements represent the SQL statements that are executed most often, that use more system resources than other SQL statements, or that use system resources more frequently than other SQL statements.

Use the Top SQL page to identify poorly performing SQL.

To view the Top SQL page:

1. On the Workspace home page, click the Utilities icon and then Database Monitor.

2. Click Top SQL.

3. If prompted, enter the appropriate administrator user name and password and click Login.
The Top SQL page appears. Use the search fields and lists and the top of the page and click Go to narrow the display. For details on each field or list, click the Search label.

4. To access the SQL Plan page, click the View icon.

The SQL Plan page appears, containing the following sections:

- Query Plan - Contains a color coded explain plan. Note that unindexed columns display in red.

- SQL Text - Displays the full text of the SQL statement.

- Indexes - Displays all indexes on the table in the query. There is a checkmark when that index is used in the query.

- Table Columns - Shows all columns on all tables or views in the query.

About Long Operations

The Long Operations page displays the status of various operations that run for longer than 6 seconds (in absolute time). These operations currently include many backup and recovery functions, statistics gathering, and query execution, and more operations are added for every Oracle release.

To view the Long Operations page:

1. On the Workspace home page, click the Utilities icon and then Database Monitor.

2. Click Long Operations.

3. If prompted, enter the appropriate administrator user name and password and click Login.

4. See Also:
"V$SESSION_LONGOPS" in Oracle Database Reference

Viewing Database Details
You can view details about your database on the About Database page.
To access details about your database:

1. On the Workspace home page, click the Utilities icon and then Database Monitor.

2. Click About Database.

3. If prompted, enter the appropriate administrator user name and password and click Login.
The About Database page appears. The About Database page is divided into two sections: Database and Version.

4. To view additional information about installed options, currently used features, or National Language Support, select one of the following check boxes and click Go:

- Version

- Settings

- Options

- National Language Support

- CGI Environment

- Parameters

21 Migrating Applications

This section describes the steps to migrate applications from Microsoft Access to Oracle Application Express.

This section contains the following topics:

- About Application Migration

- Preparation Checklist for Migrating Applications

- How to Migrate Your Applications

- Step 1: Export Microsoft Access Metadata

- Step 2: Migrate the Microsoft Access Database to Oracle

- Step 3: Create an Oracle Application Express Workspace

- Step 4: Create a Migration Project

- Step 5: Review Your Retrieved Objects

- Step 6: Generate the Oracle Application Express Application

- Managing Your Migration Projects

About Application Migration

Oracle Application Express Application Migration Workshop (Application Migration) enables you to migrate a Microsoft Access application and generate an Oracle Application Express application from the retrieved objects.

This migration begins with exporting your Microsoft Access metadata, using the Exporter tool together with Oracle Migration Workbench. After that initial step, you want to use Application Migration to review the retrieved objects and resolve any issues regarding invalid objects. As the final step, you have the option of generating either an application based on valid forms and reports or a maintenance application based on valid tables and views.

Once the application is generated, you can take advantage of all the functionality in Application Express to further develop and publish the migrated application.

Forum for Application Migration

In addition to Oracle support, you can post questions on the Microsoft Access Migration to Oracle Application Express:

http://forums.oracle.com/forums/forum.jspa?forumID=356

See Also:
"Preparation Checklist for Migrating Applications"

Preparation Checklist for Migrating Applications

Before you begin the migration process, verify that your system meets these requirements:

- Oracle Application Express version 3.0

You must have installed Application Express 3.0. You use the Application Migration feature within Application Express to download the Exporter tool as well as to migrate Microsoft Access forms and reports to Application Express.

- Oracle Migration Workbench version 10.1.0.4.0 or higher (available in English only)

You must have installed Oracle Migration Workbench version 10.1.0.4.0 or higher. You use the Migration Workbench to migrate the Microsoft Access schema and data to Oracle.

- Exporter tool version 10.2.0.2.0 (available in English only)

If you are using Oracle Migration Workbench version 10.1.0.4.0, you must install the Exporter tool using the Download Exporter link within Application Express. For instructions, see "Step 1: Export Microsoft Access Metadata".

If you are using a version higher than 10.1.0.4.0, you can access the Exporter directly from Oracle Migration Workbench.

- Microsoft Access

Your local system must have Microsoft Access installed, and it must be installed where the Exporter tool and .mdb file reside.

- Microsoft Data Access Components (MDAC)

Your local system should have the latest version of Microsoft Data Access Components (MDAC) installed. You can download the latest version from the Microsoft Web site.

- Printer

Your local system must have a printer installed so that a report can be opened in design view. This is a requirement for exporting your Reports information from an .mdb file.

- Analyze your .mdb file before you export your database. Follow the instructions in the next section.

Analyze Your .MDB File in Microsoft Access

Using Microsoft Access, you should analyze your .mdb file before you export your database. Performing these steps will minimize errors in the migration.

1. In Microsoft Access, analyze the objects in your .mdb file:

a. From the Microsoft Access menu bar, select Tools, Analyze, and then Documenter.

b. Select the All Object Types tab, and then click the Select All button to select all the objects within the application for analysis.

c. Remove or resolve any erroneous objects reported by the Documenter.

2. Ensure the application contains no missing references:

a. In Microsoft Access, launch the design IDE (press Alt+F11 keys).

b. From the menu bar, select Tools and then References.

c. Remove or resolve any missing references.

3. Ensure the application compiles successfully:

a. From the menu bar in the IDE view, select Debug and then Compile.

b. Resolve any reported errors.

4. Perform a compact and repair on the database:

- From the menu bar in Microsoft Access, select Tools, Database Utilities, and then Compact and Repair Database.

5. Ensure that all linked tables are valid links:

a. From the menu bar in Microsoft Access, select Tools, Database Utilities, and then Linked Table Manager.

b. Verify that all links are up-to-date and pointing to an existing .mdb file that is not read-only.

See Also:
"How to Migrate Your Applications" and "Step 1: Export Microsoft Access Metadata"

How to Migrate Your Applications

Before you begin

Read "Preparation Checklist for Migrating Applications".

To migrate applications from Microsoft Access to Oracle Application Express, you need to perform the steps described in this section. This graphic outlines the entire process:

The migration process consists of the following steps:

Step 1: Export Microsoft Access Metadata

Step 2: Migrate the Microsoft Access Database to Oracle

Step 3: Create an Oracle Application Express Workspace

Step 4: Create a Migration Project

Step 5: Review Your Retrieved Objects

Step 6: Generate the Oracle Application Express Application

Important:
You must follow the steps in the exact sequence presented in this section.

Step 1: Export Microsoft Access Metadata

To export your metadata from Microsoft Access, download the correct version of the Exporter tool, as explained in this section. Then, run the Exporter and extract the metadata from the Microsoft Access .mdb file. The metadata contains the necessary database and application schema information.

The export process creates two output files:

- database (.xml file)

- application (.sql file)

Downloading the Exporter Tool

Note:
Follow the instructions in this section if you are using Oracle Migration Workbench version 10.1.0.4.0. If you are using a higher version, access the Exporter directly from Oracle Migration Workbench and skip this task.

To download the Exporter tool for Microsoft Access:

1. Log in to Oracle Application Express 3.0.

2. Under Migrations on the right side of the Workspace home page, click Application Migrations.

3. Under Tasks on the right side of the page, click Download Exporter for Microsoft Access.

4. In the Download column, click the zip file that corresponds to your version of Microsoft Access. For example, download the omwb2003.zip file if you are using Microsoft Access 2003.

5. Save the file.

6. Unzip the file. You must replace the following files with the updated versions in the msaccess_exporter directory where you unzipped Oracle Migration Workbench:

- schema.dtd file

- Exporter tool file: omwb<version>.mde

- online help file: omwb.chm

Be sure to invoke the export from this directory.

Exporting Your Metadata

To export your metadata, follow the instructions found in the help file for the Exporter tool. To find the instructions, do one of the following:

- Launch the Exporter tool, and click the Help button.

- Open the help file (omwb.chm) contained in the Exporter zip file.

The instructions appear in the topic called Exporter Overview.

See Also:
"Step 2: Migrate the Microsoft Access Database to Oracle" and "How to Migrate Your Applications"

Step 2: Migrate the Microsoft Access Database to Oracle

To migrate the Microsoft Access database to Oracle:

1. Log in to Oracle Migration Workbench 10.1.0.4.0 or higher.

2. Load the database metadata (.xml file) resulting from Step 1. This migrates the schema and data to Oracle.
If you are using version 10.1.0.4.0 of Oracle Migration Workbench, make sure that you have updated the /omwb/msaccess_exporter folder with the latest version of the schema.dtd from the zip file in Step 1.

Important:
When using the Oracle Migration Workbench, you must verify that the Destination Database in the Migration wizard is the same instance where Application Express 3.0 is installed. If you do not, you are not able to complete the next step.

For more information about Oracle Migration Workbench, see:

http://www.oracle.com/technology/tech/migration/index.html

See Also:
"Step 3: Create an Oracle Application Express Workspace" and "How to Migrate Your Applications"

Step 3: Create an Oracle Application Express Workspace

The method for creating workspaces depends on your Application Express configuration. For more information, see "Quick Start".

While creating your workspace, be sure to associate it with the newly created schema from Step 2.

If you are new to Application Express, also see the Oracle Database 2 Day + Application Express Developer's Guide.

See Also:
"Step 4: Create a Migration Project" and "How to Migrate Your Applications"

Step 4: Create a Migration Project

To create a migration project:

1. Log in to Oracle Application Express.
Make sure you log in to the workspace you created for your migration project (Step 3).

2. Under Migrations on the right side of the Workspace home page, click the Application Migrations link.

3. On the Application Migrations page, click Create Project.
The Create Migration Project wizard appears. Note that the steps included in the wizard appear in a flowchart on the left of the page.

4. Enter the project details:

a. Project Name - Enter a unique name. You might want to use the same name as the Microsoft Access .mdb file you used to create the project.

b. Type - Select Access.

c. Description - Enter a meaningful description for this project. You might want to describe the Microsoft Access .mdb file that you used to create the project.

d. Migration Export File - Click Browse and select the .sql file created by the Exporter tool for Microsoft Access.

e. Schema - Select the schema.
The default schema is the schema associated with your workspace. If more than one schema is associated with your workspace, all associated schemas appear in the select list, arranged in alphabetical order. When this situation exists, select the schema associated with the SQL script you want to upload.

f. Click Next.

5. Review the project details, and click Finish.
The project page appears.

See Also:
"About the Project Page", "Step 5: Review Your Retrieved Objects", and "How to Migrate Your Applications"

About the Project Page

The project page initially shows a high-level overview of the Microsoft Access objects retrieved from your Microsoft Access database.

Specifically, the project page shows the status of these objects in your database:

- tables

- queries (now Oracle views)

- forms

- reports

Additionally, for reference purposes only, the project page shows:

- databases

- modules

- pages

Note that your project might not include all object types. The project page lists only object types that exist in your database.

After you generate applications from this migration project, an application list is created on the project page. To review the list, click Applications. This opens the list box where you can review application information or run an application.

See Also:
"Step 5: Review Your Retrieved Objects" and "How to Migrate Your Applications"

Step 5: Review Your Retrieved Objects

Next, you want to select the objects to include in the migration. The initial list consists of the Microsoft Access application metadata that is retrieved, both valid and invalid.

To include an object, it must have a status of Valid. By default, all objects with a Valid status are selected. From within Application Migration, you can fix objects identified as invalid so that they can be included. Since the Application Migration also identifies tables without primary keys and objects without user interface defaults, you can correct those situations to maximize application design recovery.

Tip:
Extensive Oracle documentation is available for broadening your knowledge of database concepts and objects. For example, to learn more about primary keys and constraints, see Oracle Database Concepts or Oracle Database Application Developer's Guide - Fundamentals, which you can download from:
http://www.oracle.com/technology/documentation/index.html

This section includes these topics:

- Reviewing Retrieved Tables

- Reviewing Retrieved Queries

- Reviewing Retrieved Forms

- Reviewing Retrieved Reports

- Reviewing Database, Module, and Pages Information

Reviewing Retrieved Tables

Next, review the Oracle tables retrieved from the Microsoft Access database. Application Migration identifies invalid tables without primary keys as well as those without user interface defaults, which you can add before migrating.

After you update the tables, select the ones you want to include in the migration. If you do not include a table, all forms and reports based on the table are excluded from the migration.

To review retrieved tables:

1. From the project page, click Tables.
The Tables page appears, showing the status of the objects ready for migration.

For each Microsoft Access table, the Tables page shows:

- Oracle Table - The corresponding Oracle table, which defaults to the Microsoft Access table name in all capital letters.

Note that the name might also differ from the original one because of the collision management facility in Oracle Migration Workbench. For information about naming guidelines and restrictions, click Help in Oracle Migration Workbench and go to the Frequently Asked Questions section.

If the Microsoft Access object was not successfully migrated to Oracle, then this field will not have a corresponding Oracle table name. Instead, it will contain a link to a page where you can create a corresponding Oracle table.

- Primary Key - Indicates if a primary key exists for the table.

A table without a primary key is considered invalid in Application Migration. You can create a primary key at this point. All tables you want to migrate should have a primary key.

- Foreign Key - Indicates if a foreign key exists for the table.

If you know a relationship exists between two tables, you should create a foreign key. You can do this through SQL Workshop, a component of Application Express. For more information about SQL Workshop, see the Oracle Application Express User's Guide or the Application Express online Help.

- UI Defaults - Indicates if user interface defaults are set for the table.

User interface defaults are used by Application Express to populate initial values for region and item properties. Using user interface defaults provides consistency across multiple applications or across multiple pages in an application.

- Status - Table status as either Valid or Invalid.

Only valid tables can be included in the migration.

2. To create a table:

a. On the Tables page, click the link in the Oracle Table column for the table you want to create.
The Object Browser opens.

b. Click the Create button.

c. From the list of object types, select Table.

d. Follow the on-screen instructions.

3. To add a primary key:

a. On the Tables page, click the Oracle table name.

b. In the Tasks list on the right, click Create Primary Key.

c. For Constraint Details, fill in the information.

Tip:
To review the list of existing columns or constraints, click the Existing Columns or Existing Constraints links.

d. Click Next.

e. Confirm the information and click Finish.

4. To add an index:

a. On the Tables page, click the Oracle table name.

b. In the Tasks list on the right, click Create Index.

c. Select the type of index you want to create on this table.
For indexing NUMBER, VARCHAR, and DATE, select Normal. For indexing CLOB columns, select Text.

d. Click Next.

e. For Index Definition, fill in the information.
The following graphic shows the fields to fill out if you selected Normal as the type of index.

Tip:
To review the list of existing table indexes or columns, click the Table Indexes or Table Columns links.

f. Click Next.

g. Confirm the information and click Finish.

5. To set user interface defaults:

a. On the Tables page, click the Oracle table name.

b. In the Tasks list on the right, click UI Defaults.

c. On the UI Defaults page, click Create Defaults.
The Table Defaults page appears, listing column information as it will appear in forms and reports. Note that you are now working within Application Builder, the component of Application Express where you can build and modify your applications.

d. To edit the information, click Grid Edit. You can update the column label, change the sequence the columns will appear by default, and so on.

e. Click Apply Changes to save your updates.

6. To include tables in the migration, select them in the left column.

7. Click Apply Changes to save your selections.

See Also:
"Reviewing Retrieved Queries", "Step 5: Review Your Retrieved Objects", and "How to Migrate Your Applications"

Reviewing Retrieved Queries

Next, review the queries retrieved from the Microsoft Access export. Application Migration identifies invalid queries as well as those without user interface defaults, which you can set before migration.

After you update the views, select the ones you want to include in the migration. If you do not include a query, any forms or reports based on the query are excluded from the migration.

To review retrieved queries:

1. From the project page, click Queries.
The Queries page appears, showing the status of the objects ready for migration.

For each Microsoft Access query, the Queries page shows:

- Oracle View - The corresponding Oracle view, which defaults to the Microsoft Access query name in all capital letters.

If the Microsoft Access object was not successfully migrated to Oracle, then this field will not have a corresponding Oracle view name. Instead, it will contain a link to a page where you can create a corresponding Oracle view.

- Status - Query status as either Valid or Invalid.

Only valid queries can be included in the migration.

- UI Defaults - Indicates if user interface defaults are set for the query.

User interface defaults are used by Application Express to populate initial values for region and item properties. Using user interface defaults provides consistency across multiple applications or across multiple pages in an application.

2. To run a bulk process that attempts to compile all invalid queries, click Attempt to compile invalid queries.
Using this option can validate some queries that show a status of invalid when initially migrated.

3. To create a view:

a. On the Queries page, click the link in the Oracle View column for the view you want to create.
The Object Browser opens.

b. Click the Create button.

c. From the list of object types, select View.

d. Follow the on-screen instructions.

4. To edit a query:

a. On the Queries page, click the Oracle view you want to edit.

b. Click Compile to find the invalid part of the query.
The Microsoft Access Query syntax appears in the edit window. It may require some modification to make it valid Oracle syntax.

c. Click Access Query to review the initial query and compare it to the converted query.

d. Click Edit.

e. Update the query and recompile it.

f. When it is validated, click the Queries breadcrumb.

g. To include this validated query, select it in the left column on the Queries page and click Apply Changes.

5. To set user interface defaults:

a. On the Queries page, click the Oracle view.

b. In the Tasks list on the right, click UI Defaults.

c. On the UI Defaults page, click Create Defaults.
The Table Defaults page appears, listing column information as it will appear in forms and reports. Note that you are now working in Application Builder, the component within Application Express where you build and modify applications.

d. To edit the information, click the Grid Edit button.
You can update the column label, change the sequence the columns will appear by default, and so on.

e. Click Apply Changes to save your updates.

f. To return to the Application Migration, click the Home breadcrumb. Then, select the Application Migrations link on the right, select your migration project, and click Queries.

6. To include queries in the migration, select them in the left column.

7. Click Apply Changes to save your selections.

See Also:
"Reviewing Retrieved Forms", "Step 5: Review Your Retrieved Objects", and "How to Migrate Your Applications"

Reviewing Retrieved Forms

Next, review the forms retrieved from the Microsoft Access export. Application Migration identifies invalid forms and lists additional information, such as the form's source type and source name.

For valid forms with a source type of table, you can select the type of object you want the form to become within Application Express: form (default), report and form, or tabular form.

Microsoft Access forms based on a query are migrated to Application Express forms. Microsoft Access forms based on a SQL query are migrated to Application Express reports.

After you update the forms, select the ones you want to include in the migration.

To review retrieved forms:

1. From the project page, click Forms.
The Forms page appears, showing the status of the objects ready for migration.

For each Microsoft Access form, the Forms page shows the following information, if available:

- Source type:

- Table

- Query - The Oracle view that was migrated from the Microsoft Access query.

- SQL Query - The original Microsoft Access SQL query that the Microsoft Access form is based on. Note that this query has not been parsed by the Oracle Migration Workbench. Therefore, you might need to edit it to make it valid Oracle SQL syntax.

- Nothing - The form has no underlying source type.

- Source name - The Oracle table or view name if the source type is a table or query.

- Status - Form status as Valid or Invalid. The source of the form must have a status of Valid before you can select it for migration.

A form's status is based on two factors: status of its underlying source object and inclusion of the source object in the migration. Specifically, a form has a status of valid if either one of these situations exists:

- Its Source Type object (table, query, or SQL query) is valid, and it has been included in the migration. Its check box is enabled and can be selected.

- Its Source type object has a status of valid, but the source object was not included in the migration. Its check box is disabled.

A form has a status of invalid if either one of these situations exists:

- No Source Type is listed. Its check box is disabled.

- Its Source Type object (table, query, or SQL query) is invalid. Its check box is disabled.

- Startup form - Identifies the form that displays when you open your Microsoft Access database.

- Parent form - Indicates the form/subform relationship that existed in your Microsoft Access database. For example, the CallListSub form shows Contacts as its Parent Form.

- Migrate to: Form, Tabular Form, or Report and Form - The select list appears if the source type is a valid table.

2. To run a bulk process that attempts to compile all invalid SQL queries, click Attempt to compile invalid SQL queries.
Using this option can validate some SQL queries that show a status of invalid. Note that SQL queries from Microsoft Access forms are not loaded into the Oracle Migration Workbench, and are therefore not parsed.

3. To edit a SQL query:

a. On the Forms page, click the SQL Query you want to edit.

b. Click Validate to find the invalid part of the SQL query.

c. Click Edit.

d. Update the query and validate it.

e. When it is validated, click the project name breadcrumb.

f. To include the validated query, click Forms on the project page to go to the Forms page. Then select the newly validated query in the left column and click Apply Changes.

4. To edit a query:

a. On the Forms page, click Query for the form you want to edit.

b. Click Compile to find the invalid part of the query.

c. Click Access Query to review the initial query and compare it to the converted query.

d. Click Edit.

e. Update the query and recompile it.

f. When it is validated, click the Queries breadcrumb.

g. To include this validated query, select it in the left column on the Queries page and click Apply Changes.

5. To review details about a form, click the link in the Access Form column.

6. To include forms in the migration, select them in the left column.

7. Click Apply Changes to save your selections.

See Also:
"Reviewing Retrieved Reports", "Step 5: Review Your Retrieved Objects", and "How to Migrate Your Applications"

Reviewing Retrieved Reports

Next, review the reports retrieved from the Microsoft Access export. Application Migration identifies invalid reports and lists additional information, such as the report's source type and source name.

After you update the reports, select the ones you want to include in the migration. To include a report, the source of the report must have a status of Valid.

To review retrieved reports:

1. From the project page, click Reports.
The Reports page appears, showing the status of the objects ready for migration.

For each Microsoft Access report, the Reports page shows the following information, if available:

- Source type:

- Table

- Query - The Oracle view that was migrated from the Microsoft Access query.

- SQL Query - The original Microsoft Access SQL query that the Microsoft Access form is based on. Note that this query has not been parsed by the Oracle Migration Workbench. Therefore, you might need to edit it to make it valid Oracle SQL syntax.

- Nothing - The report has no underlying source type.

- Source name

- Status of the report: Valid or Invalid. The source of the report must have a status of Valid before you can select it for migration.

A report's status is based on two factors: status of its underlying source object and inclusion of the source object in the migration. Specifically, a report has a status of valid if either one of these situations exists:

- Its Source Type object (table, query, or SQL query) is valid, and it has been included in the migration. Its check box is enabled and can be selected.

- Its Source type object has a status of valid, but the source object was not included in the migration. Its check box is disabled.

A report has a status of invalid if either one of these situations exists:

- No Source Type is listed. Its check box is disabled.

- Its Source Type object (table, query, or SQL query) is invalid. Its check box is disabled.

2. To run a bulk process that attempts to compile all invalid SQL queries, click Attempt to compile invalid SQL queries.
Using this option can validate some SQL queries that show a status of invalid. Note that SQL queries from Microsoft Access forms are not loaded into the Oracle Migration Workbench and are therefore not parsed.

3. To edit a SQL query:

a. On the Reports page, click the SQL Query link you want to edit.

b. Click Validate to find the invalid part of the SQL query.

c. Click Edit.

d. Update the query and validate it.

e. When it is validated, click the project name breadcrumb.

f. To include the validated query, click Reports on the project page to go to the Reports page. Then select the newly validated SQL query in the left column and click Apply Changes.

4. To edit a query:

a. On the Reports page, click Query for the report you want to edit.

b. Click Compile to find the invalid part of the query.

c. Click Access Query to review the initial query and compare it to the converted query.

d. Click Edit.

e. Update the query and recompile it.

f. When it is validated, click the Queries breadcrumb.

g. To include this validated query, select it in the left column on the Queries page and click Apply Changes.

5. To review details about a report, click the link in the Access Report column.

6. To include reports in the migration, select them in the left column.

7. Click Apply Changes to save your selections.

See Also:
"Reviewing Database, Module, and Pages Information", "Step 5: Review Your Retrieved Objects", and "How to Migrate Your Applications"

Reviewing Database, Module, and Pages Information

From the project page, you can drill down to see information about the database, modules, and pages for the migration project.

- Database - Displays summary information about the Microsoft Access database, including the full path and size of the .mdb file.

- Modules - Displays the Visual Basic Code, enabling you to extract embedded SQL statements for you to use or edit in your Application Express application.

- Pages - Displays information for reference purposes.

See Also:
"Step 6: Generate the Oracle Application Express Application" and "How to Migrate Your Applications"

Step 6: Generate the Oracle Application Express Application

After validating and updating objects, you now need to generate the application in Application Express. You can create an application based on valid forms and reports, or a maintenance application based on valid tables and views.

When creating an application, a home page is defined by default. You have the option to create additional blank pages so that you can introduce further navigation possibilities.

You can then choose which user interface theme your application should be based on. By default, the application uses one level of tabs.

As a shortcut, you can also set some application defaults. These defaults are used whenever you create new applications.

Setting Up Application Defaults

To set up application defaults (optional):

1. On the right side of the project page, click Generate Application Defaults in the Tasks list.

2. Select the options you want to use as defaults.
For information, click Help or click the item label. Clicking the item label opens a separate window describing the item and its options.

3. Click Apply Changes.
The project page appears.

Generating Applications

To generate either type of application:

1. On the right side of the project page, click one of the following in the Tasks list:

- Generate Application - This option generates an application based on the forms and reports you selected to include.

- Generate Maintenance Application - This option generates an application based on the tables and queries you selected to include.

2. In the Selected Application Objects section, you can customize specific pages.
For example:

- To rename a page, click the page link and enter the new name on the New Page Definition page that appears.

- To select the type of navigation on the application's home page, click the Home Page link.

On the New Page Definition page that appears, select Vertical Unordered List with Bullets, Vertical Images List or Horizontal Images List for Navigation.

- To display an image on a parent page, click the page link.

On the New Page Definition page that appears, go to the Page Icon field and select the image you want to appear on that page. You can either select an image from the select list or click the Find icon (flashlight) to open a page of options.

Repeat this step for each parent page. If you do not explicitly select an image for a page, the default image appears for that page.

Note that for the image to appear in your application, you must have selected either Vertical Images List or Horizontal Images List for the Home page navigation.

3. To add a blank page to the application, scroll down to the Add Page section and click Add Page.
Note that the new page appears at the bottom of the list in the Selected Application Objects section.

4. Click Next to select a theme for the application, or click Create to skip the theme selection step.
If you skip the theme step, the default is used.

5. Select a theme for the application and click Next.
A theme is a collection of templates that define the layout and style of an application, including buttons and pages.

6. Confirm your selections and click Create.

7. To preview the application, click Run Application.

8. Log in using your Application Express workspace credentials.
Your application now appears as a separate application in Application Express.

9. To customize your application, scroll down to the Developer toolbar and click Edit Application.
You might want to do the following customizations immediately after you generate your application:

- Rename the application. Each application has a unique ID, but the migration project name becomes the application name by default. To more easily identify an application, you might want to change its name to something more meaningful by editing the application attributes.

- Change the authentication scheme. By default, the authentication scheme is Application Express authentication. You can change this by editing the application attributes.

See Also:
For instructions on editing application attributes, adding pages, deploying your application, and so on, see the Oracle Database Application Express User's Guide or the Application Express online Help.

Managing Your Migration Projects

If you upload a newer version of the export file and create a new migration project from that, you might want to delete the previous migration project.

When you delete a migration project, you delete only the metadata associated with the migration project. Deleting a migration project does not delete or impact applications you have generated from the project or any objects, such as tables or views, in the schemas associated with your workspaces.

To delete a migration project:

1. Log in to Oracle Application Express.

2. Under Migrations on the right side of the Workspace home page, click the Application Migrations link.

3. On the Application Migrations page, click the project you want to delete.

4. On the project page, click Delete Project from the Tasks list on the right.

5. Click the Delete Project button and confirm the deletion.

Part IV

Administration

Part IV describes tasks performed by an Oracle Application Express administrator. An Oracle Application Express administrator manages an entire Oracle Application Express instance using the Oracle Application Express Administration Services application. Common Oracle Application Express administrator tasks include managing service, schemas, workspace requests, change requests, users, and existing workspaces as well as monitoring activity across a development instance.

Part IV contains the following chapter:

- Chapter 22, "Managing an Oracle Application Express Hosted Service"

22 Managing an Oracle Application Express Hosted Service

This section describes tasks an Oracle Application Express administrator performs when administering an Oracle Application Express hosted service.

This section contains the following topics:

- What Is an Oracle Application Express Administrator?

- Logging in to Oracle Application Express Administration Services

- Managing Service

- Managing Environment Settings

- Managing Schemas

- Creating Workspaces

- Managing Workspace Requests

- Managing Change Requests

- Managing Users in an Oracle Application Express Instance

- Managing Existing Workspaces

- Managing Applications

- Monitoring Activity Across a Development Instance

What Is an Oracle Application Express Administrator?

Oracle Application Express administrators are responsible for managing an entire Oracle Application Express instance.

In the Oracle Application Express development environment, users log in to a shared work area called a workspace. These users are divided into three primary roles:

- Developers create and edit applications.

- Workspace administrators are developers who also perform administrator tasks specific to their workspace such as managing user accounts, monitoring workspace activity, and viewing log files. See "Understanding Application Administration".

- Oracle Application Express administrators are superusers that manage the entire hosted instance using the Oracle Application Express Administration Services application.

See Also:
Refer to the appropriate installation guide for your platform for information about installing Oracle Application Express

Logging in to Oracle Application Express Administration Services

Oracle Application Express administrators are responsible for managing an entire Oracle Application Express instance. To perform these tasks, an Oracle Application Express administrator logs in to the Oracle Application Express Administration Services application.

To log in to Oracle Application Express Administration Services:

1. In a Web browser, navigate to the Oracle Application Express Administration Services application. By default, Oracle Application Express Administration Services installs to the following location:

- If your setup uses the embedded PL/SQL gateway, go to:

http://hostname:port/apex/apex_admin

Where:

- hostname is the name of the system where Oracle XML DB HTTP Server is installed.

- port is the port number assigned to Oracle XML DB HTTP Server. In a default installation, this number is 8080. You can find information about your Oracle HTTP Server installation's port number from the following file:

ORACLE_BASE\ORACLE_HOME\install\portlist.ini

However, be aware that if you change a port number, it is not updated in the portlist.ini file, so you can only rely on this file immediately after installation.

- apex is the database access descriptor (DAD) defined in the configuration file.

For users who have upgraded from earlier releases, or who have a custom configuration, this value may be htmldb or something else. Verify your DAD with your Oracle Application Express administrator.

- If your setup uses Apache and mod_plsql, go to:

http://hostname:port/pls/apex/apex_admin

Where:

- hostname is the name of the system where Oracle HTTP Server is installed.

- port is the port number assigned to Oracle HTTP Server. In a default installation, this number is 7777. You can find information about your Oracle HTTP Server installation's port number from either of the following files:

ORACLE_BASE\ORACLE_HOME\install\portlist.ini
ORACLE_BASE\ORACLE_HTTPSERVER_HOME\Apache\Apache\conf\httpd.conf

- pls is the indicator to use the mod_plsql cartridge.

- apex is the database access descriptor (DAD) defined in the mod_plsql configuration file.

For users who have upgraded from earlier releases, or who have a custom configuration, this value may be htmldb or something else. Verify your DAD with your Oracle Application Express administrator.

The Login page appears.

2. In Username, enter admin.

Tip:
admin is the default Oracle Application Express administrator account. To create additional Oracle Application Express administrator accounts, see "Creating New User Accounts"

3. In Password, enter the Oracle Application Express administrator account password you specified when you installed Oracle Application Express.

4. Click Login.
Oracle Application Express Administration Services appears.

See Also:
"Managing Oracle Database Port Numbers" in Oracle Database Installation Guide or refer to the appropriate installation guide for information about installing Oracle Application Express

Managing Service

Oracle Application Express administrators use the settings under Manage Service to create a site-specific tasks list, manage activity log entries, manage session state, monitor the mail queue, and view a report of installed translations.

Topics in this section include:

- Creating a Site-Specific Tasks List

- Managing Log Entries

- Managing Session State

- Managing Mail

- Viewing Installed Translations

Creating a Site-Specific Tasks List

The Site-Specific Tasks list is a list of links that appears on the Workspace home page. If links are defined, a Site-Specific Tasks region appears. If no Site-Specific Tasks are defined, the region does not display. This feature enables Oracle Application Express administrators to customize the Workspace home page for an entire development instance. Typical uses for the Site-Specific Tasks list include links to training, discussion forums, and user feedback applications.

Topics in this section include:

- Adding a New Task

- Editing an Existing Task

- Deleting a Task

Adding a New Task

To add a new task to a Site-Specific Tasks list:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Site-Specific Tasks.
The Site-Specific Tasks page appears.

4. To create a new link, click Create.

5. On the Create/Edit Site-Specific Tasks page, you can specify the following:

a. Display Sequence - Indicate the relative order of this task within the list.

b. Display Location - Indicate the page on which the task should display (that is, the Workspace Login page or Workspace home page).

c. Task Name - Enter a name for this task.

d. Tasks Link - Enter the link target for this task using either a relative URL (for example, using f?p syntax) or an absolute URL (such as http://otn.oracle.com).

e. Displayed - Select Yes to display the task link.

6. Click Create.

See Also:
"Using f?p Syntax to Link Pages"

Editing an Existing Task

To edit an existing task:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Site-Specific Tasks.
The Site-Specific Tasks page appears.

4. Select the task name.

5. On the Create/Edit Site-Specific Tasks page, edit the appropriate attributes.

6. Click Apply Changes.

Deleting a Task

To delete an existing task:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Site-Specific Task Lists.
The Site-Specific Tasks page appears.

4. Select the task name.

5. Click Delete.

Managing Log Entries

Oracle Application Express administrators can delete log entries on the Logs page.

Topics in this section include:

- Deleting SQL Workshop Logs

- Deleting Page View Activity Log Entries

- Deleting Developer Activity Log Entries

- Deleting Click Counting Log Entries

- Deleting Mail Log Entries

- Deleting the Login Access Log

Deleting SQL Workshop Logs

The SQL Workshop logs maintain a history of recent commands and scripts run in the SQL Commands

To delete log files entries:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Logs.
The Logs page appears.

4. Click SQL Workshop logs.

5. Click one of the following:

- Script File executions log entries

- SQL Command Processor history entries

6. On the Clean up Logs page:

- To delete entries by age, specify the age of the entries to be deleted and click Delete Entries.

- To delete all entries, click Truncate Log.

See Also:
"Accessing a Command from Command History"

Deleting Page View Activity Log Entries

Page view activity logs track user activity for an application. Developers enable logging within their application using the Logging attribute on the Edit Definition page.

See Also:
"About the Edit Definition Page"

The Application Express engine actually uses two logs to track user activity. At any given time, one log is designated as current. For each rendered page view, the Application Express engine inserts one row into the log file. A log switch occurs at the interval listed on the Manage Activity Logs page. At that point, the Application Express engine removes all entries in the noncurrent log and designates it as current.

To truncate the activity logs manually:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Logs.
The Logs page appears.

4. Click Page View Activity Log, with option to truncate.

5. Click Truncate Logs.

6. Click either Truncate Log 1 or Truncate Log 2.

See Also:
"Monitoring Activity within a Workspace"

Deleting Developer Activity Log Entries

The Developer Activity Log tracks changes to applications within an individual workspace. Log entries older than one month are automatically deleted.

To delete Developer Activity Log entries:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Logs.
The Logs page appears.

4. Click Developer Activity Logs, with option to delete entries.

5. On the Developer Activity Log page, click Manage.

6. Specify the age of the entries to be deleted and click Delete Entries.

See Also:
"Viewing Application Changes by Developer" for information about the Developer Activity Log

Deleting Click Counting Log Entries

The External Clicks Log counts clicks from an Oracle Application Express application to an external site. You can implement this functionality using the APEX_UTIL.COUNT_CLICK procedure.

To delete click counting log entries:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Logs.
The Logs page appears.

4. Click External Click Counting Log, with option to truncate.

5. On the External Click Counting Log page, click Manage.

6. Specify the age of the entries to be deleted and click Delete Entries.

See Also:
"COUNT_CLICK Procedure"

Deleting Mail Log Entries

The Oracle Application Express Mail Log records the message header information and send date of successfully sent mail message.

To truncate the mail log:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Logs.
The Mail Logs page appears.

4. To control the number of rows that display, make a selection from the Display list and click Go.

5. Click Mail Log.

6. On the Mail Log page, click Truncate.

See Also:
"Managing Mail"

Deleting the Login Access Log

This table records authentication events by developers and administrators accessing the Application Express environment and by end users of Application Express applications that use the built-in login APIs available to developers. Log entries are aged out of the log tables and purged periodically.

To truncate the Login Access log:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Login Access Log.
The Login Access Log page appears.

4. Click Manage.

5. On the Manage Login Access Log page, click Delete Entries.

Managing Session State

A session is a logical construct that is used to establish persistence (or stateful behavior) across page views. Each session is assigned a unique ID, which the Application Express engine uses to store and retrieve an application's working set of data (or session state) before and after each page view. An automatic process clears sessions older than 24 hours every eight hours. Oracle Application Express administrators can also purge them manually.

An Oracle Application Express administrator can view session state statistics and purge the session state on the Session State page.

Topics in this section include:

- Purging Sessions by Age

- Viewing Session Details Before Purging

- Viewing Session Statistics Before Purging

See Also:
"Understanding Session State Management" and "Managing Session State"

Purging Sessions by Age

Using the Purge Session page, Oracle Application Express administrators can purge sessions by age.

To view specific session details:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Session State.

4. Click Purge Sessions, by age.

5. On the Purge Sessions page, specify:

- The maximum number of sessions to be purged

- The age of sessions to be purged

6. To view a report of session statistics, click Count Sessions.

7. To purge the selected sessions, click Purge Sessions.

Viewing Session Details Before Purging

Before purging sessions, Oracle Application Express administrators can use the Recent Sessions page to first view a listing of recent sessions and then drill down on session details.

To purge sessions by age:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Session State.

4. Click Recent Sessions, with drill down to session details.

5. On the Recent Sessions page, you can:

- Click a session number to view additional details.

- Click Purge Sessions to delete the displayed sessions.

Viewing Session Statistics Before Purging

On the Session State Statistics page, Oracle Application Express administrators can view statistics about current sessions prior to purging.

To view session state statistics:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Session State.

4. Select Session State Statistics.

5. Click Purge Sessions to delete the current sessions.

Managing Mail

Oracle Application Express administrators can manage email sent from applications by monitoring email messages in the mail queue and Mail Log.

Topics in this section include:

- Viewing the Mail Queue

- Viewing the Mail Log

See Also:
"Sending Email from an Application", "Enabling Network Services in Oracle Database 11g", and "Deleting Mail Log Entries"

Viewing the Mail Queue

Oracle Application Express administrators can use the Manage Mail Queue page to monitor email messages in the mail queue.

To monitor messages in the mail queue:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Mail Queue.
The Mail Queue page appears.

4. To send email messages, click Send All Mail.

5. To delete email messages, select the messages to be deleted and click Delete.

Viewing the Mail Log

The Oracle Application Express Mail Log records the message header information and send date of successfully sent mail message.

To view the mail log:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Logs.
The Logs page appears.

4. Click Mail log.
The Mail Log appears.

5. To control the number of rows that display, make a selection from the Display list and click Go.

6. To delete all log entries, click Truncate.

Viewing Installed Translations

Oracle Application Express administrators can view a page showing what translated languages have been installed within the current development instance.

To view the list of installed translations:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Service, click Installed Translations.
The Installed Translations page appears, displaying a list of languages and indicating if the translations have been loaded.

See Also:
"Managing Application Globalization"

Managing Environment Settings

Environment settings control Oracle Application Express configuration and apply to all workspaces within the current Oracle Application Express instance.

Topics in this section include:

- Disabling PL/SQL Program Unit Editing for an Instance

- Disabling the Creation of Demonstration Applications in a New Workspace

- Configuring SQL Workshop

- Enabling Database Monitoring

- Configuring Security Settings

- Configuring Email Settings

- Configuring Wallet Information

- Configuring Report Printing

- Managing Login and System Messages

- Configuring Report Printing

See Also:
"Specifying a Provisioning Mode" to learn more about the Self Service section of the Instance Settings page

Disabling PL/SQL Program Unit Editing for an Instance

By default, developers can change and compile PL/SQL source code when browsing database procedures, packages, and functions in Object Browser. As an Oracle Application Express administrator, you can control PL/SQL program unit editing for an entire instance by making a selection from Allow PL/SQL Program Unit Editing.

To disable PL/SQL program unit editing:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Feature Configuration.

4. Locate the Application Development section.

5. For Allow PL/SQL Program Unit Editing, select No.

6. Click Apply Changes.

See Also:
"Disabling PL/SQL Program Unit Editing for a Workspace" for information about disabling PL/SQL program unit editing for a specific workspace

Disabling the Creation of Demonstration Applications in a New Workspace

When an Oracle Application Express administrator creates a new workspace, Oracle Application Express automatically creates a demonstration application within the workspace.

To disable the creation of demonstration applications:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Feature Configuration.

4. Locate the Application Development section.

5. For Create demonstration objects in new workspaces, select No.

6. Click Apply Changes.

Configuring SQL Workshop

As an Oracle Application Express administrator, you can use the attributes under SQL Workshop to configure basic SQL Workshop behavior.

To configure SQL Workshop:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Feature Configuration.

4. Under SQL Workshop, enter the attributes described in Table 22-1.

Table 22-1 SQL Workshop Attributes

Attribute

Description

SQL Commands Maximum Inactivity in minutes

Identify the maximum amount of time a transactional command in the SQL Command Processor waits before timing out.

SQL Scripts Maximum Script Output Size in bytes

Identify the maximum amount of output a single SQL script can generate. SQL scripts are run from the SQL Workshop.

SQL Scripts Maximum Workspace Output Size in bytes

Identify the maximum amount of space all scripts within a workspace may consume. SQL script results are the output generated when running SQL scripts from the Script Editor or from the SQL Scripts home page.

SQL Scripts Maximum Script Size in bytes

Identify the maximum size of a SQL script used within the SQL Workshop.

Enable Transactional SQL Commands

Select Yes to enable transactional SQL commands for the entire Oracle Application Express instance. Enabling this feature permits SQL Command Processor users to issue multiple SQL commands within the same physical database transaction.

When you select Yes, an Autocommit check box appears on the SQL Command Processor page. By default, this option is set to No.

5. Click Apply Changes.

Enabling Database Monitoring

Before you can access the Database Monitoring page, an Oracle Application Express administrator must enable database monitoring.

To enable database monitoring:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Feature Configuration.

4. Scroll down to Monitoring.

5. For Enable Database Monitoring, select Yes.

6. Click Apply Changes.

Note:
Only users having a database user account that has been granted a DBA role can access the Database Monitor page.

Configuring Security Settings

Oracle Application Express administrators can configure security settings, such as turning off cookies used to populate the login form in Application Express, controlling access to accounts, and setting up password policies.

Topics in this section include:

- Turning Off Cookies Used to Populate the Login Form for Application Express

- Excluding Domains from Regions of Type URL and Web Services

- Enabling Login Controls for All Workspaces

- About Password Policies

- Configuring Password Policies

- Disabling Access to Oracle Application Express Administration Services

- Disabling Access to Oracle Application Express Internal Applications

- Restricting User Access by IP Address

Turning Off Cookies Used to Populate the Login Form for Application Express

Oracle Application Express administrators can control if a convenience cookie is sent to the user's computer whenever a developer or administrator logs in to a workspace from the Application Express Login page. By default, the Set Workspace Cookie option is set to Yes.

If selected, Application Express sends a persistent cookie that:

- combines the last used workspace name and user name

- has a lifetime of six months

- is read to populate the Application Express Workspace Login form (but not the Oracle Application Express Administration Services Login form)

Note:
If your computer has already received this cookie, you can physically remove it from its persistent location on disk using browser tools or system utilities. The cookie is named ORACLE_PLATFORM_REMEMBER_UN and may exist for each Application Express service accessed having distinct hostname and path components.

To prevent a cookie from being sent to the user's computer when logging in:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Security.

4. Locate the Security section.

5. For Set Workspace Cookie, select No.

6. Click Apply Changes.

Excluding Domains from Regions of Type URL and Web Services

It is possible to restrict regions of type URL and Web services for the entire Oracle Application Express instance. The Oracle Application Express administrator defines excluded domains and regions of type URL. If a Web reference or region of type URL contains an excluded domain, an error displays informing the user that it is restricted.

To exclude a domain from regions of type URL and Web services:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Security.

4. In Domain Must Not Contain, enter a colon-delimited list of excluded domains.

5. Click Apply Changes.

Enabling Login Controls for All Workspaces

By default, no login controls are enabled across an Oracle Application Express instance. Oracle Application Express administrators can enable login controls for all accounts in all workspaces across an entire development instance. Account login controls include:

- Require user account expiration and locking

- Set up a maximum number of failed login attempts

- Set the lifetime of a password before prompted for a new one

If the Oracle Application Express administrator does not enable login controls for an entire instance then each Workspace administrator can enable the following controls on a workspace-by-workspace basis. See "Enabling Login Controls for a Workspace".

Note that Account Login control affect applications that use the Application Express user account creation facilities and authentication against those accounts.

To enable login controls for all workspaces:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Security.

4. Scroll down to Account Login control.

5. Under Account Login Control:

a. Require User Account Expiration and Locking - Select Yes to enable this feature for all workspaces across an entire Oracle Application Express instance. This feature applies to end-user accounts created using the Application Express end-user account management interface.
Select No to relinquish control to each Workspace administrator.

b. Maximum Login Failures Allowed - Enter a number for the maximum number of consecutive unsuccessful authentication attempts allowed before a developer or administrator account is locked. If you do not specify a value in this field, the default value is 4 is.
This setting applies to Application Express administrator and developer accounts. It does not apply to end user accounts.

The value you enter is used as the default for the workspace-level Maximum Login Failures Allowed preference, if the Workspace administrator does not specify a value. That preference is used for end-user accounts within the respective workspace.

c. Account Password Lifetime (days) - Enter a number for the maximum number of days a developer or administrator account password may be used before the account expires. If you do not specify a value in this field, a default value is 45 days.
This setting applies to accounts used to access the Application Express administration and development environment only. It does not apply to end-user accounts used by applications developed in Application Express.

The value you enter is used as the default workspace-level End User Account Lifetime preference, if the Workspace administrator specifies no value. That preference is used for end-user accounts within the respective workspace.

6. Click Apply Changes.

Tip:
This feature applies only to accounts created using the Application Express user creation and management facilities. It provides additional authentication security for applications. See "Managing Application Express Users".

About Password Policies

Oracle Application Express administrators can enable password policies for:

- All users across all workspaces (that is, Workspace administrators, developers, and end users).

Oracle Application Express administrators can set up restrictions for all users, including password characters, lengths, words, and differences in consecutive passwords.

- Users logging in to Oracle Application Express Administration Services

Turning on the strong password requirement for Oracle Application Express adds another layer of security to prevent hackers from determining an administrator's password. When this option is selected, passwords must meet these requirements:

- consist of at least six characters

- contain at least one lowercase alphabetic character, one uppercase alphabetic character, one numeric digit, and one punctuation character

- cannot include the username

- cannot include the word Internal

- cannot contain any words shown in the Must Not Contain Workspace Name field in this section

Configuring Password Policies

To configure password policies:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Security.

4. To set up a password policy for Workspace administrators, developers, and end users, scroll down to Workspace Password Policy and specify the attributes described in Table 22-2.

Table 22-2 Workspace Password Policy Attributes

Attribute

Description

Minimum Password Length

Enter a number for the minimal character length for passwords.

Minimum Password Differences

Enter a positive integer or 0.

When users change their password, the new password must differ from the old password by this number of characters. The old and new passwords are compared, character-by-character, for differences such that each difference in any position common to the old and new passwords counts toward the required minimum difference.

Must Contain At Least One Alphabetic Character

Select Yes to require that user passwords contain at least one alphabetic character. The Alphabetic Characters field lists the letters considered alphabetic characters.

Must Contain At Least One Numeric Character

Select Yes to require that user passwords contain at least one Arabic numeric character: 0,1,2,3,4,5,6,7,8, 9.

Must Contain At Least One Punctuation Character

Select Yes to require that user passwords contain at least one punctuation character. The Punctuation Characters field lists the symbols considered punctuation characters.

Must Contain At Least One Upper Case Character

Select Yes to require that user passwords contain at least one uppercase alphabetic character.

Must Contain At Least One Lower Case Character

Select Yes to require that passwords for users contain at least one lowercase alphabetic character.

Must Not Contain Username

Select Yes to prevent user passwords from containing the username, regardless of case.

Must Not Contain Workspace Name.

Select Yes to prevent user passwords from containing the workspace name, regardless of case.

Must Not Contain

Enter words, separated by colons, that may not be included in user passwords. These words may not appear in the password in any combination of uppercase or lowercase.

This feature improves security by preventing the creation of some simple, easy-to-guess passwords based on words like hello, guest, welcome, and so on.

Alphabetic Characters

Enter new text or edit the existing text. This is the set of characters used in password validations involving alphabetic characters.

Punctuation Characters

Enter new text or edit the existing text. This is the set of characters used in password validations involving punctuation characters.

Next, set up a password policy for service administrators.

5. Scroll down to the Service Administrator Password Policy and specify one of the following:

a. Use policy specified in Workspace Password Policy - Applies the password rules specified above in Workspace Password Policy to service administrator passwords.

b. Use default strong password policy - Applies the default strong password policy to service administrator passwords. To learn more, see item Help.

6. Click Apply Changes.

Disabling Access to Oracle Application Express Administration Services

Oracle Application Express administrators can restrict user access to Oracle Application Express Administration Services. This prevents any user from logging in to Oracle Application Express Administration Services.

To disable user access to Oracle Application ExpressAdministration Services:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Security.

4. For Disable Administrator Login, select Yes.

5. Click Apply Changes.

Setting this value and logging out prevents anyone from logging in to Oracle Application Express Administration Services.

To reverse this setting, connect in SQL*Plus or SQL Developer as the Application Express engine schema and execute the following:

BEGIN
WWV_FLOW_API.SET_SECURITY_GROUP_ID(p_security_group_id=>10);
WWV_FLOW_PLATFORM.SET_PREFERENCE(
p_preference_name => 'DISABLE_ADMIN_LOGIN',
p_preference_value => 'N' );
end;
/

commit
/

Disabling Access to Oracle Application Express Internal Applications

The applications that constitute Oracle Application Express (such as Application Builder and SQL Workshop) exist within a workspace named Internal. To restrict user access to Internal applications, select Yes from Disable Workspace Login. Selecting Yes in production environments prevents all users from running applications (such as Application Builder and SQL Workshop) in the Internal workspace. Administrators who use this feature should also consider disabling user access to Oracle Application Express Administration Services.

See Also:
"Disabling Access to Oracle Application Express Administration Services"

To disable user access to the Internal workspace:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Security.

4. From Disable Workspace Login, select Yes.
Selecting Yes prevents users from logging in to the Internal workspace.

5. Click Apply Changes.

Restricting User Access by IP Address

Oracle Application Express administrators can restrict user access to an Oracle Application Express instance by creating a Runtime setting named RESTRICT_IP_RANGE.

To restrict user access by IP address:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Security.

4. For Disable Administrator Login, select No.

5. In Restrict Access by IP Address, enter a comma-delimited list of IP addresses. Use an asterisk (*) to specify a wildcard.
You can enter IP addresses from one to four levels. For example:

141, 141.* ...
192.128.23.1 ...

Note:
When using wildcards, do not include additional numeric values after wildcard characters. For example, 138.*.41.2.

6. Click Apply Changes.

Configuring Email Settings

To enable Oracle Application Express to send mail, an Oracle Application Express administrator must configure a email settings on the Instance Settings page.

Additionally, if you are running Oracle Application Express with Oracle Database 11g release 1 (11.1), you need to enable outbound mail. In Oracle Database 11g release 1 (11.1), the ability to interact with network services is disabled by default. For more information, see "Enabling Network Services in Oracle Database 11g".

Tip:
You can configure Oracle Application Express to automatically email users their login credentials when a new workspace request has been approved. To learn more, see "Specifying a Provisioning Mode".

To configure Oracle Application Express to send mail:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Instance Settings.

4. Under Email, enter the following:

a. SMTP Host Address - Defines the server address of the SMTP server. By default on installation, this is set to localhost. If you are using another server as an SMTP relay, change this parameter to that server's address.

b. SMTP Host Port - Defines the port the SMTP server listens to for mail requests. The default setting is 25.

c. Administration Email Address - Defines the "from" address for administrative tasks that generate email, such as approving a provision request or resetting a password.

5. Click Apply Changes.

See Also:
"Sending Email from an Application" and "Managing Mail"

Configuring Wallet Information

Secure Sockets Layer (SSL) is an industry standard protocol that uses RSA public key cryptography in conjunction with symmetric key cryptography to provide authentication, encryption, and data integrity. When SSL is enabled, https displays in the URL.

If you call a SSL-enabled URL (for example, by invoking a Web service), or create a region of type URL that is SSL-enabled, you must create a wallet. A wallet is a password-protected container that stores authentication and signing credentials (including private keys, certificates, and trusted certificates) needed by SSL.

To create a wallet:

1. The database administrator must create a wallet on the Oracle Application Express database instance. See "Using Oracle Wallet Manager" in Oracle Database Advanced Security Administrator's Guide.

2. The Oracle Application Express administrator configures the Wallet section of the Instance Settings page to specify the file system path to the wallet and the wallet password (if required.

See Also:
"Working with SSL Enabled Web Services" and "Using Oracle Wallet Manager" in Oracle Database Advanced Security Administrator's Guide

To specify wallet settings:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Instance Settings.

4. Scroll down to Wallet.

5. In Wallet, enter the path on the file system where the wallet is located using the following format:

file:directory-path

6. If a password is required to open the wallet:

a. Enter a password in the Wallet Password field.

b. Select Check to confirm that you wish to change the wallet password.

7. Click Apply Changes.

Configuring Report Printing

Oracle Application Express provides several features so that end users can download and print reports in various formats, including PDF. To set up this functionality, different users need to configure the printing settings:

1. Site Level: Oracle Application Express service administrators must specify the level of functionality (Standard or Advanced) for an entire Oracle Application Express instance, as described in this section. See "Setting Up Region Report Printing for an Instance"

2. Application Level: Workspace administrators and developers can define Report Queries and Report Layouts. Report Queries and Report Layouts are stored under Shared Components and are not tied to a specific page. See "About Report Queries".

3. Page/Region Level: Developers can edit the Report regions on specific pages to enable printing. This, in turn, enables end users to print regions as reports in various formats. See "Configuring Report Region Print Attributes".

See Also:
"Printing Report Regions"

Tip:
If you are running Oracle Application Express with Oracle Database 11g Release 1 (11.1), you must enable network services in order to use report printing. See "Enabling Network Services in Oracle Database 11g"

Setting Up Region Report Printing for an Instance

To configure the printing of reports at a development instance:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Instance Settings.

4. Scroll down to Report Printing:

5. For Oracle BI Publisher, select one of the following:

- Standard Support - This is the default setting. Standard Support enables you to print report regions and report queries using either the built-in templates provided with Oracle Application Express or other XSL-FO compatible formats you provide. This setting does not support RTF (rich text format).

Standard Support provides declarative formatting of report regions and report queries with basic control over page attributes, including orientation, size, column heading formats, page header, and page footer.

- Advanced Support - Requires a valid license of Oracle BI Publisher (also known as Oracle XML Publisher). Advanced Support provides you with all the capabilities of the Standard setting plus the ability to define RTF-based report layouts developed using the BI Publisher Word Template Builder.

To learn more about installing and configuring Oracle BI Publisher, see PDF Printing in Application Express 3.0.

6. For Print Server Protocol, select the protocol that the print server uses.

7. For Print Server Host Address, specify the host address of the print server engine.

8. For Print Server Port, define the port of the print server engine. By default, this is set to 8888 when the report server is installed.

9. For Print Server Script, define the script that is the print server engine. The default setting is:

/xmlpserver/convert

10. Click Apply Changes.

Configuring Workspace Size Options for Requests

Oracle Application Express administrators can configure the workspace sizes available when users request:

- a new workspace and schema

- additional space for an existing workspace

To configure workspace size options:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Instance Settings.

4. Scroll down to New Workspace Request Size and Workspace Change Request Size, specify the appropriate information:

- Size in Megabytes - Edit the default numbers to change the size options.

- Display - Select Yes for all the size options you want to appear in the select list for workspace size.

- Default - Select the default value to appear in the storage field for workspace and change requests.

5. Click Apply Changes.

Managing Login and System Messages

Oracle Application Express administrators can communicate with all users in an Oracle Application Express instance by creating login and system messages. Typically, administrators use a login message in conjunction with a system message to communicate with all system users, such as regarding privacy notices or access restrictions.

Topics in this section include:

- Managing a Login Message

- Managing a System Message

Managing a Login Message

A login message displays on the Oracle Application Express login page. Oracle Application Express administrators can create a login message using the Login Message section of the Messages page.

To create a login message:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Messages.

4. For Login Message, select Custom Message.

5. In Message, enter a message. The message can contain any text and can optionally include HTML formatting.

6. Click Apply Changes.

To disable a login message:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Messages.

4. For Login Message, select No Message.

5. Click Apply Changes.

Managing a System Message

System messages display on the Workspace home page, Application Builder home page, Application home page, SQL Workshop home page, and the Application Express Utilities page.

Oracle Application Express administrators can create a system message using the System Message section of the Messages page.

Create a System Message

To create a system message:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Messages.

4. For System Message, select Custom Message.

5. In Message, enter a message. The message can contain any text and can optionally include HTML formatting.

6. Click Apply Changes.

Disable a System Message

To disable a system message:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Messages.

4. For System Message, select No Message.

5. Click Apply Changes.

Managing Schemas

This section describes how to manage the schemas within an Oracle Application Express instance.

Topics in this section include:

- Determining the Application Express Engine Schema

- Understanding Oracle Default Schema Restrictions

- Managing Workspace to Schema Assignments

Determining the Application Express Engine Schema

A schema is a logical container for the database objects. Oracle Application Express administrators may need to perform certain actions within the Application Express engine schema. For example, in order for an Oracle Application Express administrator to have the ability to assign Oracle default schemas, the database administrator (DBA) must explicitly grant the privilege by running the APEX_SITE_ADMIN.UNRESTRICT_SCHEMA procedure within the Application Express engine.

See Also:
"Understanding Oracle Default Schema Restrictions" for information about the APEX_SITE_ADMIN.UNRESTRICT_SCHEMA procedure

To determine the current Application Express engine schema for your Oracle Application Express instance:

1. Use SQL*Plus to connect to the database.

2. Run the following query in a schema with DBA privileges (for example, SYSTEM).

SELECT TABLE_OWNER FROM all_synonyms
WHERE SYNONYM_NAME = 'WWV_FLOW' and OWNER = 'PUBLIC'

Understanding Oracle Default Schema Restrictions

When Oracle Application Express installs, the Oracle Application Express administrator does not have the ability to assign Oracle default schemas to workspaces. Default schemas (such as SYS, SYSTEM, and RMAN) are reserved by Oracle for various product features and for internal use. Access to a default schema can be a very powerful privilege. For example, a workspace with access to the default schema SYSTEM can run applications that parse as the SYSTEM user.

In order for an Oracle Application Express administrator to have the ability to assign Oracle default schemas to workspaces, the database administrator (DBA) must explicitly grant the privilege using SQL*Plus to run a procedure within the APEX_SITE_ADMIN_PRIVS package.

Note:
All schema and workspace names used as arguments to procedures in the APEX_SITE_ADMIN_PRIVS package are used exactly as they are provided by the caller.
For example, if you pass an argument value such as p_schema =>'system', the lower-case schema name 'system' will be recorded and referenced. This example could return unexpected results if you really meant to reference the common schema name SYSTEM, which would be referenced using upper case.

Topics in this section include:

- Granting the Privilege to Assign Oracle Default Schemas

- Revoking the Privilege to Assign Oracle Default Schemas

- Working with Restricted Schemas

Granting the Privilege to Assign Oracle Default Schemas

The DBA can grant an Oracle Application Express administrator the ability to assign Oracle default schemas to workspaces by using SQL*Plus to run the APEX_SITE_ADMIN_PRIVS.UNRESTRICT_SCHEMA procedure from within the Application Express engine schema. For example:

EXEC FLOWS_030000.APEX_SITE_ADMIN_PRIVS.UNRESTRICT_SCHEMA(p_schema => 'SYSTEM');
COMMIT;

This example would enable the Oracle Application Express administrator to assign the SYSTEM schema to any workspace.

See Also:
"Determining the Application Express Engine Schema"

Revoking the Privilege to Assign Oracle Default Schemas

The DBA can revoke this privilege using SQL*Plus to run the APEX_SITE_ADMIN_PRIVS.RESTRICT_SCHEMA procedure from within the Application Express engine schema. For example:

EXEC FLOWS_030000.APEX_SITE_ADMIN_PRIVS.RESTRICT_SCHEMA(p_schema => 'SYSTEM');
COMMIT;

This example would prevent the Oracle Application Express administrator from assigning the SYSTEM schema to any workspace. It does not, however, prevent workspaces that have already had the SYSTEM schema assigned to them from using the SYSTEM schema.

See Also:
"Determining the Application Express Engine Schema"

Working with Restricted Schemas

If a schema has been designated as restricted using the RESTRICT_SCHEMA procedure, the DBA can designate specific workspaces as exceptions by running the APEX_SITE_ADMIN_PRIVS.CREATE_EXCEPTION procedure. For example:

EXEC FLOWS_030000.APEX_SITE_ADMIN_PRIVS.CREATE_EXCEPTION(p_schema => 'SYSTEM', p_workspace=> 'DBA_WORKSPACE');
EXEC FLOWS_030000.APEX_SITE_ADMIN_PRIVS.CREATE_EXCEPTION(p_schema => 'SYSTEM', p_workspace  => 'AUDITOR_WORKSPACE');
COMMIT;

This example would prevent the Oracle Application Express administrator from assigning the SYSTEM schema to the workspace named AUDITOR_WORKSPACE. However this restriction only applies to workspace provisioning requests processed after the REMOVE_EXCEPTION procedure has been run. If the AUDITOR_WORKSPACE already had the SYSTEM schema assigned to it, this method would not prevent that workspace from continuing to use the schema.

Removing Workspace Exceptions for a Schema

The DBA can remove all workspace exceptions for a schema by using SQL*Plus to run the APEX_SITE_ADMIN_PRIVS.REMOVE_WORKSPACE_EXCEPTIONS procedure from within the Application Express engine schema. For example:

EXEC FLOWS_030000.APEX_SITE_ADMIN_PRIVS.REMOVE_WORKSPACE_EXCEPTIONS(p_schema => 'SYSTEM');
COMMIT;

This example would prevent the Oracle Application Express administrator from assigning the SYSTEM schema to any workspaces if the SYSTEM schema were already restricted, but had one or more exceptions previously created for it.

Removing Schema Exceptions for a Workspace

The DBA can remove all schema exceptions for a workspace by using SQL*Plus to run the REMOVE_SCHEMA_EXCEPTIONS procedure from within the Application Express engine schema. For example:

EXEC FLOWS_030000.APEX_SITE_ADMIN_PRIVS.REMOVE_WORKSPACE_EXCEPTIONS(p_workspace => 'AUDITOR_WORKSPACE');
COMMIT;

This example would prevent the Oracle Application Express administrator from assigning any restricted schemas to the workspace named AUDITOR_WORKSPACE if that workspace had exceptions previously created for it with respect to any restricted schemas.

Determining the Privilege Status

The DBA can determine the current status of the privilege by using SQL*Plus to run the APEX_SITE_ADMIN_PRIVS.REPORT procedure. For example:

SET SERVEROUTPUT ON
EXEC FLOWS_030000.APEX_SITE_ADMIN_PRIVS.REPORT;

This example would display the text of a query that dumps the tables that defines the schema and workspace restrictions.

SELECT a.schema "SCHEMA",b.workspace_name "WORKSPACE" FROM WWV_FLOW_RESTRICTED_SCHEMAS a, WWV_FLOW_RSCHEMA_EXCEPTIONS b WHERE b.schema_id (+)= a.id;

When reviewing the output of this query, remember the following:

- A schema name in the SCHEMA column indicates that the schema is restricted.

- Schemas that are not listed are not restricted and may be assigned to any workspace.

- A workspace name next to a schema name means that an exception exists for the schema for the named workspace.

You can run this query in SQL*Plus as shown above, or you can change it and format the output.

Creating Workspaces

When users log in to Oracle Application Express, they log in to a shared work area called a workspace. A workspace is a virtual private database allowing multiple users to work within the same Oracle Application Express installation while keeping their objects, data and applications private. Each workspace has a unique numeric ID and name.

In order to make changes to their workspace, Workspace administrators submit change requests to an Oracle Application Express administrator. Only an Oracle Application Express administrator can approve change requests or provision new workspaces.

Topics in this section include:

- About Workspace Provisioning

- Specifying a Provisioning Mode

- Creating a Workspace Manually

- Managing Workspace to Schema Assignments

See Also:
"Managing Workspace Requests" and "Managing Existing Workspaces"

About Workspace Provisioning

When an Oracle Application Express administrator creates a new workspace with a new schema, a new tablespace and datafile are created for that schema. The datafile for the new tablespace is managed by Oracle-managed files if Oracle-managed files is enabled.

Using Oracle-managed files simplifies the administration of the Oracle database and eliminates the need for the database administrator (DBA) to directly manage the operating system files that comprise the database. Using Oracle-managed files, the DBA specifies operations in terms of database objects rather than file names. The datafile for the new tablespaces are named according to the Oracle-managed files conventions. The placement of these files is determined by the database initialization parameter DB_CREATE_FILE_DEST.

If the Oracle-Managed Files is not enabled, the datafile is created in the same directory as the first datafile of the tablespace in which Oracle Application Express is installed.

See Also:
"Using Oracle Managed Files" in Oracle Database Administrator's Guide

Specifying a Provisioning Mode

As an Oracle Application Express administrator, you determine how the process of provisioning (or creating) a workspace works for your Oracle Application Express development instance.

In Manual provision mode, an Oracle Application Express administrator creates new workspaces and notifies the Workspace administrator of the login information. In Request or Email Verification provision modes, users request workspaces directly in a self-service fashion. In this scenario, users use a link on the login page to access a request form. After the workspace request has been granted, users are automatically emailed the appropriate login information.

To specify a provisioning mode:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Service.

3. Under Manage Environment Settings, click Instance Settings.

4. Under Self Service, select a provisioning status:

- Manual - An Oracle Application Express administrator manually creates new workspaces and notifies the Workspace administrator of the login information.

- Request - Users request workspaces directly in a self-service fashion. Selecting this option displays a link on the Login page enabling users to request a workspace. When a user requests a workspace, each request is submitted to a queue for approval. When the request is approved, the user is sent an email containing login credentials (the workspace name, User ID, and password).

- Email Verification - Works similar to Request except each user receives an initial email containing a verification link. Clicking this link validates the user's email address and then the request is processed. Then another email is sent to the user containing login credentials (that is, the workspace name, User ID, and password).

5. If you select Request or Email Verification in the previous step, enter a URL in Development Service URL (optional).
The value you enter is used in the email when the request is approved. This setting defines the URL for the service. If this setting is not present, the URL is derived from your environment.

6. Click Apply Changes.

Note:
To enable users to request a workspace using a link on the Login page, an Oracle Application Express administrator must choose the provisioning status of Request or Email Verification as described in the previous procedure. If the provisioning status is set to Manual, no link appears on the login page.

See Also:
"Configuring Email Settings" and "Managing Workspace Requests"

Creating a Workspace Manually

Oracle Application Express administrators can provision a workspace manually by running the Create Workspace Wizard.

To create a workspace manually:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Create Workspace.
The Create Workspace Wizard appears.

4. For Identify Workspace, enter a workspace name and description and click Next.For Identify Schema, specify whether you are re-using an existing schema or creating a new one.
If you are using an existing schema:

a. For Re-use existing schema, select Yes.

b. Select a schema from the list.

c. Click Next.

If you creating a new schema:

a. For Re-use existing schema, select No.

b. Enter a schema name and password.

c. Specify a space quota.

d. Click Next.

5. For Identify Administrator, enter the Workspace administrator information and click Next.

6. Confirm your selections and click Create.

Managing Workspace to Schema Assignments

When users log in to Oracle Application Express, they log in to a shared work area called a workspace. Each workspace can have multiple associated schemas. By associating a workspace with a schema, developers in that workspace can:

- Build applications that interact with the database objects in that schema.

- Create new database objects in that schema.

Topics in this section include:

- Viewing the Existing Schema and Workspace Assignment

- Editing an Existing Schema and Workspace Assignment

- Associating Additional Schemas to a Workspace

- Creating a New Schema

Viewing the Existing Schema and Workspace Assignment

Oracle Application Express administrators can view the existing schema to workspace assignment on the Manage Workspace to Schema Assignments page.

To view the existing schema to workspace assignment:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Manage Workspace to Schema Assignments.
The Manage Workspace to Schema Assignments page appears. It lists all workspaces in your environment along with its most recently associated schema. Note that only one schema appears for each workspace in this list.

Tip:
You can view all schemas associated with a workspace on the Workspace home page or by viewing the Workspace Details report. See "About Workspace Schemas" and "Viewing Workspace Details"

Editing an Existing Schema and Workspace Assignment

To edit an existing schema and workspace assignment:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Manage Workspace to Schema Assignments.
The Manage Workspace to Schema Assignments page appears.

4. To edit an existing workspace to schema assignment:

a. Select the workspace name.
The Edit Schema to Workspace Assignment page appears.

b. Select a new workspace or schema.

c. Click Apply Changes.

Associating Additional Schemas to a Workspace

Oracle Application Express administrators can associate additional existing schemas to a workspace.

To associate additional schemas to a workspace:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Manage Workspace to Schema Assignments.
The Manage Workspace to Schema Assignments page appears.

4. Click Create.
The Add Schema wizard appears.

5. For New or Existing Schema, select Existing and click Next.

6. Follow the on-screen instructions to associate the existing schema to a workspace.

7. To verify that the new schema is added to the workspace:

a. Log in to the workspace on Oracle Application Express.

b. Review the Workspace Schemas list on the Workspace home page. The list shows all schemas currently associated with this workspace.

Creating a New Schema

Oracle Application Express administrators can create a new schema and associate it with a workspace.

To create a new schema for a workspace:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Manage Workspace to Schema Assignments.
The Manage Workspace to Schema Assignments page appears.

4. Click Create.
The Add Schema wizard appears.

5. For New or Existing Schema, select New and click Next.

6. For Choose Workspace, select the workspace that you want to associate the new schema with and click Next.

7. For Identify Schema:

a. Schema - Enter a unique name containing only letters.

Tip:
To verify that the new schema name is unique, open the select list and search for the name.

b. Password - Enter a case-sensitive password.

c. Default Tablespace - Identify the default tablespace that you want this schema to use.

d. Temporary Tablespace - Identify the temporary tablespace you want this schema to use.

e. Click Next.

8. Confirm the information and click Add Schema.

9. To verify that the new schema is added to the workspace:

a. Log in to the workspace on Oracle Application Express.

b. Review the Workspace Schemas list on the Workspace home page. The list shows all schemas associated with this workspace.

Managing Workspace Requests

An Oracle Application Express administrator is responsible for reviewing requests for a new workspace. In order to manage workspace requests, you need to have selected either the Request or Email Verification provisioning status.

With either Request or Email Verification provisioning status, users request workspaces directly in a self-service fashion. For example, users could click a link on the login page to access a request form. Once the workspace request has been approved, each user is emailed the appropriate login information.

See Also:
"Specifying a Provisioning Mode"

Topics in this section include:

- Viewing a Pending Workspace Request on the Notifications List

- Viewing Requests from the Workspace Requests Page

- Approving or Declining a Pending Workspace Request

- Changing the Status of an Existing Workspace Request

- Deleting a Workspace Request

Viewing a Pending Workspace Request on the Notifications List

The Notifications list on the Oracle Application Express Administration Services home page displays pending or approved workspace requests.

Figure 22-1 Notifications List

To view workspace requests on the Notifications list:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. On the right side of the Administration Services home page, review the Notifications list.
The Notifications list displays a summary of total and pending workspace requests.

3. To view additional details, click the appropriate workspace request number.

Viewing Requests from the Workspace Requests Page

To view workspace requests from the Workspace Requests page:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Requests, click Workspace Requests.
The Workspace Requests page appears.

4. To filter the report, make a selection from the Status list and click Go.

5. To view request details, click the Edit icon for the appropriate request.

Approving or Declining a Pending Workspace Request

To approve or decline a pending workspace request:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Requests, click Workspace Requests.
The Workspace Requests page appears.

4. From the Status list, select Requested and click Go.

5. Locate a request to review.

6. To edit or review the request details, click the Edit icon. On the Provision Request page you can:

- Edit the request and click Apply Changes.

- Delete the request by clicking Delete.

7. Return to the Workspace Requests page.

8. To approve a request:

a. Click Provision in the Actions column.

b. On the Provisioning Administration page, click Approve.

c. Review the email message.

d. If needed, update the message and click Approve and Send Email.
If you selected the Provisioning Status, Email Verification, an email containing a verification link is sent to the user. In order to create the workspace, the user must click the verification link to create the workspace. See "Specifying a Provisioning Mode".

9. To decline a request:

a. Click Provision in the Actions column.

b. On the Provisioning Administration page, click Decline.

c. Review the email message.

d. To add information, such as the reason for declining a request, update the message and then click Decline and Send Email.
The email is sent to the user notifying them the request was declined.

More About the Approval Process

If you are using Email Verification, when an Oracle Application Express administrator approves a workspace request, the following events occur:

1. An email containing a verification link is sent to the user.

2. When user clicks the verification link, the workspace is created.

3. Another email is sent to the user containing login credentials (that is, the workspace name, User ID, and password).

4. The status of the workspace request changes from Accepted to Approved.

If the user fails to click the verification link, you can quickly delete the request by clicking the DELETE link in the Action column.

When an Error Occurs

If an error occurs during the workspace creation process, the status of the request reverts to Requested and an email is sent to the user containing the following message:

Please contact administrator.

Once the issue is resolved, the administrator can again repeat the previous procedure and approve the request.

Changing the Status of an Existing Workspace Request

To change the status of an existing workspace request:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Requests, click Workspace Requests.
The Workspace Requests page appears.

4. To filter the report, make a selection from the Status list and click Go.

5. Locate a request to review.

6. Click the link in the Actions column.
The Adjust Request page appears.

7. From the Project Status list, select a new status.

8. Click Apply Changes.

Note:
Be careful when setting the Project Status to Requested. Although Requested enables you to reprovision a workspace, it could result in data corruption due to the manner in which accounts are provisioned. The provisioning system assumes Requested workspace requests do not have the corresponding schemas and dictionary entries for a Workspace administrator or developers. If you need to change the Project Status for an Approved workspace to Requested, terminate the service first and then change the status to Requested.

Deleting a Workspace Request

To delete a workspace request:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Requests, click Workspace Requests.
The Workspace Requests page appears.

4. From Status, select the type of request you want to delete.

5. Click the Edit icon for the request you want to delete.

6. On the Provision Request page, click the appropriate button:

- If the request Status is Approved, click Terminate or Delete.

- If the request Status is Declined, Requested, Terminated, or Accepted, click Delete.

7. Click Delete Request.

Managing Change Requests

Oracle Application Express administrators can modify a workspace (for example, add a new schema or increase the disk space limit) by approving a change request.

Topics in this section include:

- Viewing a Pending Change Request from the Notifications List

- Viewing a Change Request from the Workspace Utilization Report

- Viewing Requests from the Change Requests Page

- Approving or Declining a Pending Change Request

Viewing a Pending Change Request from the Notifications List

Oracle Application Express administrator can view existing workspace requests and change requests from the Notifications list on the Oracle Application Express Administration Services home page.

Figure 22-2 Notifications List

To view change requests from the Notifications list:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. On the right side of the Administration Services home page, review the Notifications list.
The Notifications list displays a summary of total and pending change requests.

3. To view additional details, click the appropriate change request number.
The appropriate Change Requests page appears.

Viewing a Change Request from the Workspace Utilization Report

To view pending requests from the Workspace Utilization Report:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Workspace Reports, click Workspace Details.

4. From the Workspace list, select the workspace and click Go.
The Workspace Details page appears.

5. Scroll down to the Change Requests section.

Viewing Requests from the Change Requests Page

To view change requests from the Workspace Requests page:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspace.

3. Under Manage Requests, click Change Requests.

4. From Status, select the type of requests you want to view and click Go.

Approving or Declining a Pending Change Request

To approve or decline a pending change request:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspace.

3. Under Manage Requests, click Change Requests.

4. Locate the request and click View Request under the Action column.
The View Change Request page appears. Note that the buttons that display depend upon the nature of the change request.

5. Select one of the following:

- To approve a request for a schema, click Create Schema.

- To approve a request for additional disk space, click Add Space.

- To approve a request to terminate the service, click Terminate Service.

- To deny a request, click Deny Request.

- To delete a request and deny it, select Delete this request if denying? and then click Deny Request.

Managing Users in an Oracle Application Express Instance

Oracle Application Express administrators can manage all user accounts within an Oracle Application Express instance on the Manage Developers and Users page. User accounts are particularly useful if a workspace utilizes Application Express Authentication.

When setting up user accounts, Oracle Application Express administrators can take advantage of some manageability attributes, such as allowing the accounts to be locked, their password to have a fixed lifetime, and their password to require change on first use.

See Also:

- "Understanding Application Administration"

- "Managing Application Express Users"

- "Application Express Account Credentials" for information about implementing Application Express Authentication

Topics in this section include:

- Creating New User Accounts

- Editing an Existing User Account

- Deleting User Accounts

Creating New User Accounts

To create a new user account:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Manage Developers and Users.
The Manage Developers and Users page appears.

4. Click Create.
The Create/Edit User page appears.

5. Under User Attributes, enter the appropriate information.

Tip:
To learn more about a specific attribute, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

6. Under Password, type a case-sensitive password for this account.
If your organization has set up a password policy, be sure the password meets the requirements. See "About Password Policies".

7. Under Developer Privileges:

- User is a developer - To add this user as a developer or Workspace administrator, select Yes. For end users, select No.

Developers can create and modify applications and database objects as well as view developer activity, session state, workspace activity, application, and schema reports.

- User is a workspace administrator - To add this user as a Workspace administrator, select Yes. For developers or end users, select No.

In addition to having developer privileges, workspace administrators can create and edit user accounts, manage groups, alter passwords of users within the same workspace, and manage development services.

Note:
You create end users by adding them as users but not defining them as either developers or Workspace administrators, restricting their privileges.

8. Under Account Control:

- Account Availability - Select Unlocked to enable a user to log in to this account. Select Unlocked to enable the account to be used.

- Require Change of Password on First Use - Select Yes to require the user to change the password immediately after logging in with the current, temporary password.

This rule applies to the use of this account for developers and Workspace administrators. It also applies to all users who use this account when logging in to developed applications.

Tip:
An Oracle Application Express administrator can configure these settings for an entire Oracle Application Express instance. See "Enabling Login Controls for All Workspaces".

9. Click Create User or Create and Create Another.

Editing an Existing User Account

To edit an existing user account:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Manage Developers and Users.

4. Locate a user:

- To narrow the list, select a workspace from the Workspace list and click Go.

- To locate a specific user, type a user name or partial string in the Find User field and click Go.

- To view all users, leave the Find User field blank and click Go.

5. To edit account details, select the user name.
To learn more about a specific attribute, click the item label. When Help is available, the item label changes to red when you pass your cursor over it and the cursor changes to an arrow and question mark. See "About Field-Level Help".

6. Make the appropriate changes.

7. Click Apply Changes.

See Also:
"Creating New User Accounts"

Deleting User Accounts

To delete a user account:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Manage Developers and Users.

4. Locate a user:

- To narrow the list, select a workspace from the Workspace list and click Go.

- To locate a specific user, type a user name or partial string in the Find User field and click Go.

- To view all users, leave the Find User field blank and click Go.

5. Select a user.
The Create/Edit User page appears.

6. Click Delete User.

7. Confirm your selection and click OK.

Managing Existing Workspaces

This section describes how Oracle Application Express administrators can manage existing workspaces within an Oracle Application Express instance.

Topics in this section include:

- Viewing Existing Workspaces

- Viewing Workspace Details

- Viewing Workspace Database Privileges

- About Deleting Inactive Workspaces

- Removing a Workspace

- Locking a Workspace

- Exporting and Importing a Workspace

See Also:
"Creating Workspaces", "Managing Schemas", "Managing Users in an Oracle Application Express Instance"

Viewing Existing Workspaces

Use the Existing Workspaces page to view a report of existing workspaces, delete an existing workspace, or create a new workspace.

To view existing workspaces:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Workspace Reports, click Existing Workspaces.
The Existing Workspaces page appears with a navigation bar at the top:

- Search - To search for a workspace, enter a case insensitive query in the Search field and click Go.

- Display - To change the number of workspaces that appear in the list, make a selection from the Display list and click Go.

4. To create a new workspace, click Create Workspace and follow the on-screen instructions.

5. To view workspace details, click the workspace name. See "About the Workspace Details Page".

Viewing Workspace Details

Oracle Application Express administrators can view and edit workspace information on the Workspace Details page.

To view workspace details:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Workspace Reports, click Workspace Details.
The Workspace Details page appears.

4. Make a selection from the Workspace list at the top of the page and click Go.
The Workspace Details page appears.

About the Workspace Details Page

The Workspace Details page is divided into the following sections:

- Name. Displays high-level information about the workspace: ID, Short Name, and the First Schema Provisioned. To edit the workspace name, click Edit Attributes and follow the on-screen instructions.

- Schemas. Displays the default tablespace for each workspace schema.

When users log in to Oracle Application Express, they log in to a shared work area called a workspace. Each workspace can have multiple associated schemas. By associating a workspace with a schema, developers can build applications that interact with the objects in that schema as well as create new database objects in that schema. To edit workspace to schema assignments, click Workspace to Schema Assignments. See "Managing Schemas".

- Privileges. Lists the database system privileges for each workspace schema.

- Role Privileges. Lists the database roles granted to each workspace schema.

- Table Utilization. Displays the tablespace used with each workspace schema.

- Applications. Lists all applications within the workspace.

- Developers. Lists all application developers within the workspace. To edit a developer, click Manage Application Developers. See "Managing Users in an Oracle Application Express Instance".

- Application Express Users. Lists all defined users within the workspace. To edit a user, click Manage Users. See "Managing Users in an Oracle Application Express Instance".

- Objects by Type. Lists objects used by the schemas in the workspace.

- Change Requests. Lists all change requests in an Oracle Application Express instance.

- User Activity. Lists user activity by date.

- Developer Activity. Lists developer activity by developer name and application.

Viewing Workspace Database Privileges

Oracle Application Express administrators can view a summary of workspace database privileges on the Workspace Database Privileges page.

To view workspace database privileges:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Workspace Reports, click Workspace Database Privileges.
The Workspace Database Privileges page appears.

4. To search for a workspace, enter a case insensitive query in the Find field and click Go.

5. To control the number of workspaces that display, make a selection from the Display list and click Go.

6. To view workspace details, click the workspace name.
The Workspace Details page appears. See "Viewing Workspace Details".

About Deleting Inactive Workspaces

If you are managing a large hosted Oracle Application Express instance, periodically purging inactive workspaces can free up resources for other users. The process of purging inactive workspaces consists of the following steps:

1. Identify inactive workspaces.

2. Remove the resources associated with each inactive workspace.

3. Delete the inactive workspaces.

Topics in this section include:

- Identifying Inactive Workspaces

- Removing the Resources Associated with Inactive Workspaces

- Deleting Inactive Workspaces

Identifying Inactive Workspaces

The first step in determining if a workspace is inactive is to establish some basic rules. A common approach is to base the rules on the Oracle Application Express activity records found in the current Application Express engine schema.

See Also:
"Determining the Application Express Engine Schema"

The following DDL (data definition language) creates a table of all workspaces requested before June 28, 2004 but that have been inactive since June 10, 2004. In this example, inactivity is determined by checking a key within the Application Express engine schema for the most recent updates by each workspace.

ALTER SESSION SET CURRENT_SCHEMA = FLOWS_030000;
CREATE TABLE ws_to_purge AS
SELECT c.security_group_id, c.company_name, c.admin_email, c.request_date,
SYSDATE last_updated_on, 'Y' ok_to_delete
FROM wwv_flow_provision_company c
WHERE
c.request_date <= to_date('20040628','YYYYMMDD') AND
(  not exists
(SELECT NULL /* Activity Log */
FROM wwv_flow_activity_log l
WHERE l.security_group_id = c.security_group_id
AND l.time_stamp > to_date('20040610','YYYYMMDD'))
)
AND NOT EXISTS
(SELECT NULL /* workspace applications */
FROM wwv_flows f
WHERE f.security_group_id = c.security_group_id
AND f.last_updated_on > to_date('20040610','YYYYMMDD'))
AND NOT EXISTS
(SELECT NULL /* Pages */
FROM wwv_flow_steps s
WHERE s.security_group_id = c.security_group_id
AND s.last_updated_on > to_date('20040610','YYYYMMDD'))
AND NOT EXISTS
(SELECT NULL /* Regions */
FROM wwv_flow_page_plugs p
WHERE p.security_group_id = c.security_group_id
AND p.last_updated_on > to_date('20040610','YYYYMMDD'))
AND NOT EXISTS
(SELECT NULL /* Items */
FROM wwv_flow_step_items i
WHERE i.security_group_id = c.security_group_id
AND i.last_updated_on > to_date('20040610','YYYYMMDD'))
AND NOT EXISTS
(SELECT NULL /* Templates */
FROM wwv_flow_templates t
WHERE t.security_group_id = c.security_group_id
AND t.last_updated_on > to_date('20040610','YYYYMMDD'))
AND NOT EXISTS
(SELECT NULL /* Files uploaded */
FROM wwv_flow_file_objects$ o
WHERE o.security_group_id = c.security_group_id
AND o.created_on > to_date('20040610','YYYYMMDD'))
AND NOT EXISTS
(SELECT NULL /* SQL Workshop history */
FROM wwv_flow_sw_sql_cmds s
WHERE s.security_group_id = c.security_group_id
AND s.created_on > to_date('20040610','YYYYMMDD'));

After you identify inactive workspaces, you can purge them. Purging inactive workspaces is a two-step process:

- First, remove the resources (that is, the database schemas, tablespaces, and data files) associated with each inactive workspace.

- Second, drop the inactive workspaces from Oracle Application Express.

Removing the Resources Associated with Inactive Workspaces

After you have identified inactive workspaces in a single table, the next step is to remove them.

Note:
Before removing the schemas, tablespaces, or data files associated with inactive workspaces, make sure these resources are not being used in any other workspace or application.

To remove the resources associated with inactive workspaces:

1. Identify the schemas used by the workspaces to be deleted by joining the table containing the identified inactive workspaces to wwv_flow_company_schemas.

2. Drop the schemas, tablespaces, and data files used exclusively by the inactive workspaces from the database. You can identify the schemas to drop by running a query similar to the following:

SELECT s.schema
FROM ws_to_purge ws,
wwv_flow_company_schemas s
WHERE s.security_group_id = ws.security_group_id
AND ws.ok_to_delete = 'Y';

Deleting Inactive Workspaces

Once you remove the resources associated with an inactive workspace, you can delete the workspace. You can delete inactive workspaces manually using the Oracle Application Express Administration Services application. Or, you can delete them programmatically as shown in the following PL/SQL example.

BEGIN
FOR c1 IN (SELECT security_group_id
FROM ws_to_purge
WHERE ok_to_delete = 'Y')
LOOP
WWV_FLOW_PROVISIONING.TERMINATE_SERVICE_BY_SGID(c1.security_group_id);
END LOOP;
END;

Removing a Workspace

Removing a workspace does not remove any of the associated database objects. To remove the associated schemas, a database administrator (DBA) must use a standard database administration tool, such as Oracle Enterprise Manager or SQL*Plus.

See Also:

- SQL*Plus User's Guide and Reference

- "Viewing Workspace Details"

- "Creating Workspaces"

To remove a workspace:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Workspace Reports, click Existing Workspaces.

4. Under the Action column, click Delete.

5. Follow the on-screen instructions.

Locking a Workspace

Oracle Application Express administrators can lock a workspace to address security or performance issues. Locking a workspace immediately locks all workspace administrator, developer and user accounts in the workspace. It also changes the status of all applications in the workspace to Unavailable.

Warning:
Locking a workspace makes it permanently inaccessible.

To lock a workspace:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Lock Workspace.

4. For Workspace, select the workspace you want to lock and click Next.

5. Review the information about applications and users and click Lock Workspace.

Exporting and Importing a Workspace

To move a workspace and all associated users to a new Oracle Application Express instance, an Oracle Application Express administrator must export the workspace. When you export a workspace, Oracle Application Express generates a text file. This file contains information about your workspace, all the users in your workspace, and any groups in your workspace (if applicable). You can use this file to import your workspace into another Oracle Application Express instance.

Keep in mind, this method only imports workspace, users, and groups. This file does not contain:

- The schemas associated with this workspace or the objects in those schemas.

- Any applications, images, cascading style sheets, and static text files.

These items must be exported separately.

See Also:

- "How to Move an Application to Another Development Instance"

- "About Importing, Exporting, Loading, and Unloading Data"

- "About Managing Database Objects"

- "Using Custom Cascading Style Sheets"

Topics in this section include:

- Exporting a Workspace

- Importing a Workspace

Exporting a Workspace

To export a workspace:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Export Workspace.

4. Select a workspace and then click Export Workspace.

5. To export the selected workspace, click Save File.

6. Follow the on-screen instructions.

Importing a Workspace

To import a workspace:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Workspaces.

3. Under Manage Workspaces, click Import Workspace.

4. Click Browse, select a workspace export file, and click Next.

5. To install the workspace, click Install.

6. Follow the on-screen instructions.

Managing Applications

Oracle Application Express administrators can use the Manage Applications page to view reports on key attributes of applications in all workspaces across a development instance.

Topics in this section include:

- Viewing Application Attributes

- Changing Application Build Status SetDuring Deployment

- Viewing the Parse As Schemas Report

Viewing Application Attributes

Oracle Application Express administrators can view applications by workspace on the Application Attributes page.

To view the Application Attributes page:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Applications.

3. Click Application Attributes.
The Application Attributes page appears.

4. Use the Navigation bar at the top of the page to filter the page view. Make a selection from the Display, Application, and Workspace lists and click Go.

5. To sort by column, select a column heading.

Changing Application Build Status Set During Deployment

Every Oracle Application Express application has an application-level attribute called Build Status. You can use this attribute to prevent an application from being modified by other developers. Build Status has two settings:

- Run and Build Application - Developers can both run and edit an application.

- Run Application Only - Developers can only run an application.

Setting the Build Status to Run Application Only is an effective way to prevent other developers from modifying it.

You can change the Build Status by:

- Changing the Build Status attribute on the Edit Definition page. See "Availability".

- Changing the Build Status during the deployment process. See "How to Move an Application to Another Development Instance".

Note that if you select Build Application Only during deployment, the only way to change this setting is change it on the Build Status page in Oracle Application Express Administration Services.

To change a Build Status set during deployment:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Applications.

3. Click Build Status.
The Build Status page appears.

4. Locate an application by making selections from the Build Status, Application, and Workspace lists and clicking Go.

5. Click the Edit icon adjacent to the appropriate application.
The Edit Build Status page appears.

6. Select an alternate build status and click Apply Changes.

Viewing the Parse As Schemas Report

To view the Parse As Schemas report:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Manage Applications.

3. Click Parse as Schemas.
The Parse As Schemas page appears.

4. Filter the display by making selections from the Parse As, Application, and Workspace lists and clicking Go.

Monitoring Activity Across a Development Instance

Oracle Application Express administrators can monitor end user and developer activity for an Oracle Application Express instance on the Monitor Activity page.

To monitor user activity:

1. Log in to Oracle Application Express Administration Services. See "Logging in to Oracle Application Express Administration Services".

2. Click Monitor Activity.

3. Select report to review. Categories include:

- Page Views

- Calendar Reports

- Login Attempts

- Developer Activity

- Environment Reports

See Also:
Monitoring Activity within a Workspace

A Available Conditions

A condition is a small unit of logic that helps you control the display of regions, items, buttons, and tabs as well execute processes, computations and validations. When you apply a condition to a control or component, the condition is evaluated. Whether a condition passes or fails determines whether a control or component displays, or page processing executes.

You can specify conditions by selecting a condition type when you create the control (region, button, or item) or component (tab, list, or navigation bar), or by making a selection under the Condition attribute.

See Also:
"Understanding Conditional Rendering and Processing"

Table A-1 describes many Application Builder conditions. To view a complete listing of all available conditions for a given control or component, click the View icon to the right of the Condition Type list. Shortcuts to common selections appear directly beneath the Type list. If your condition requires an expression, type it in the appropriate field.

Table A-1 describes the conditions available in Application Builder.

Table A-1 Available Conditions

Condition

Description

Always

Always returns true. Used primarily for the read-only conditions of a page item

Current Language != Expression 1

Verifies the language setting in which the client browser is not currently running. Evaluates to true if the current language is contained within the string entered in Expression 1.

Current Language = Expression

Verifies the language setting in which the client browser is currently running. Evaluates to true if the current language matches the value entered in Expression 1.

Current Language is contained within Expression 1

Determines whether the browser current language is contained within a string. Evaluates to true if the current language matches the string entered in Expression 1.

For example, to check if the current language is either en-US or en-GB, choose this condition and enter the following string in Expression 1:

en-us,en-gb

Current Language is not contained within Expression 1

Verifies the application's current language is not contained within a specified string. Evaluates to true if the current language is not contained within the string entered in Expression 1.

Current page != Expression 1

Evaluates to true if the current page does not equal the page you specify in Expression 1.

Current Page != Page Submitted (this page was not the page posted)

Determines if the specified page was not posted. Evaluates to true if the current page does not match the value entered in Expression 1.

Current page = Expression 1

Evaluates to true if the current page equals the page you specify in Expression 1.

Current Page = Page Submitted (this page was posted)

Verifies the whether the specified page was posted. Evaluates to true if the current page matches the value entered in Expression 1.

Current Page is contained within Expression 1 (comma-delimited list of pages)

Verifies if the current page is part of the list of pages you specify in Expression 1. To check if the current page is in either page 1, 2, 3 or 4, select this condition type and enter the following string in Expression 1:

1,2,3,4

Current page is in Printer Friendly mode

Only displays certain page control or components when the user has selected printer friendly mode. If the current page is in printer friendly mode, then the condition evaluates to true. Use f?p syntax to specify printer friendly mode.

Current page is not in Printer Friendly mode

Hides page controls or components when printer friendly mode is selected. Use f?p syntax to specify printer friendly mode.

See Also: "Using f?p Syntax to Link Pages" for information about f?p syntax

Current Page not in Expression 1 (comma-delimited list of pages)

Verifies if the current page is not part of the comma-separated list of pages specified in Expression 1.

Exists (SQL query returns at least one row)

This condition 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 a within an 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" for information about bind variables

Never

This condition type is hard wired to always fail. It is useful in temporarily preventing controls or components (such as regions, buttons, or items) from being rendered on a page, or to prevent processes, computations and validations from running.

NOT Exists (SQL query returns no rows)

This condition is expressed as a SQL query. If the query does not return any rows, it evaluates as true.

PLSQL Expression

A PL/SQL expression is any expression in valid PL/SQL syntax that evaluates to true or false. For example:

nvl(:MY_FLOW_ITEM,'NO') = 'YES'

If the value of MY_FLOW_ITEM is YES then the condition evaluates as true. Otherwise it evaluates as false.

PLSQL Function Body returning a Boolean

The body of a PL/SQL function that returns true or false. For example:

BEGIN
IF :P1_DAY = 'MONDAY' THEN
RETURN TRUE;
ELSE
RETURN FALSE;
END IF:
END;

Request != Expression 1

REQUEST is an internal attribute that tracks how a page is submitted. By default, when a page is submitted, the value of the application attribute REQUEST is set according the name of the object that caused the page to be submitted. For a regular button, REQUEST is set as the name of the button (such as CANCEL or SAVE) not the label of the button. You can also set request using f?p syntax.

For example, the event could be when a user clicks a button or selects a tab menu. Depending upon the event, you can perform different operations by referencing the value of the REQUEST application attribute.

This condition evaluates as true if REQUEST does not equal the value entered in Expression 1.

See Also: "Understanding URL Syntax", "REQUEST", and "Understanding the Relationship Between Button Names and REQUEST"

Request = Expression 1

This condition is the opposite of Request != Expression 1.

This condition evaluates as true if REQUEST equals the value entered in Expression 1. From PL/SQL you can also reference the application attribute using the following syntax:

V('REQUEST')

See Also: "Understanding URL Syntax", "REQUEST", and "Understanding the Relationship Between Button Names and REQUEST"

Request is contained within Expression 1

REQUEST is an internal application attribute that tracks of how a page is submitted. By default, when a page is submitted, the value of REQUEST is set according to the event that caused the page to be submitted. For example, the event could be when a user clicks a button or selects a tab. Depending upon the event, you can perform different operations by referencing the value of the REQUEST application attribute.

Use this condition to specify a list of allowed requests (such as SAVE or UPDATE) in Expression 1. The condition evaluates to true if the value of REQUEST is contained in the list.

See Also: "REQUEST", and "Understanding the Relationship Between Button Names and REQUEST"

Request is not contained within Expression 1

This condition is the opposite of Request is contained within Expression 1. Evaluates to true if the value of the REQUEST is not contained within Expression 1.

See Also: "REQUEST", and "Understanding the Relationship Between Button Names and REQUEST"

SQL Expression

SQL Expressions are evaluated as a WHERE clause in a SQL statement. For example suppose your expression is :MY_ITEM = 'ABC'.

The Application Express engine processes the following:

select 1 from dual where :MY_ITEM = 'ABC'

This condition evaluates to true if a row is returned.

SQL Reports (OK to show the back button)

Use this condition for reports having pagination. It automatically determines when it is appropriate to include a button that pages back in the result set.

SQL Reports (OK to show the forward button)

Use this condition for reports having pagination. It automatically determines when it is appropriate to include a button that pages forward in the result set.

Text in Expression 1 != Expression 2 (includes &ITEM substitutions)

Use this expression to compare two expressions containing strings. Either expression may contain references to session state using &MY_ITEM syntax.

See Also: "Understanding Substitution Strings" for information about &MY_ITEM syntax

Text in Expression 1 = Expression 2 (includes &ITEM substitutions)

This condition is the opposite of Text in Expression 1 != Expression 2 (includes &ITEM substitutions). Compares two expressions containing strings. Either expression may contain references to session state using the &ITEM. syntax.

To check if the item F100_P2_DAY_DATE equals "Wednesday", select this condition enter the following in Expression 1 and Expression 2:

- Expression 1: F100_P2_DAY_DATE

- Expression 2: Wednesday

See Also: "Understanding Substitution Strings" for information about &MY_ITEM syntax

User is authenticated (not public)

Verifies whether the current user was authenticated using one of the built-in authentication schemes or a custom authentication scheme.

See Also: "Establishing User Identity Through Authentication" for information about authentication

User is the public user (user has not authenticated)

The public user is defined as an application attribute. To set the public user for a specific application, navigate to the Application Builder home page and click the edit link corresponding to your application.

A public user is a user used for multiple users. Sometimes applications have pages that are public and thus require authentication and log in. This condition returns true if the user is the public user (that is, the user is authenticated as themselves or some other user not equal to the public user identified in the application attribute Public User.

See Also: "Authentication" for information about Public User

Value of Item in Expression 1 != zero

Verifies if the value of the item in Expression 1 does not equal zero.

Value of item in Expression 1 = Expression 2

Compares the value of an item with a specific string. Comparisons using this condition are case-sensitive.

For example, to verify whether the value of an item F100_P2_WORD is contained within the string "the quick brown fox", enter the following in the Expression 1 and Expression 2 fields:

- Expression 1: F100_P2_WORD

- Expression 2: the quick brown fox

Value of Item in Expression 1 = zero

Verifies if the value of the item in Expression 1 does equal zero.

Value of item in Expression 1 contains no spaces

Evaluate to true if the value of the item specified in Expression 1 contains no spaces.

Value of Item in Expression 1 is alphanumeric

Evaluates to true when the string in Expression 1 contains only alphanumeric characters.

Value of Item in Expression 1 is contained within colon-delimited list in Expression 2

Use this condition type to check whether a certain string is contained within the value of a session state item. Verifies whether the string specified in Expression 1 is contained in the value of the item specified in Expression 2.

Value of Item in Expression 1 is NOT contained within colon-delimited list in Expression 2

Evaluates to true when the value specified in Expression 1 contains a string that lists elements delimited by colons.

To check if the item P1_TODAY is either "Monday", "Tuesday", or "Wednesday", select this condition and enter the following in Expression 1 and Expression 2:

- Expression 1: P1_TODAY

- Expression 2: Monday: Tuesday:Wednesday

Value of Item in Expression 1 is NOT NULL

In Expression 1, enter the name (uppercase) of the application or page item. Evaluates as true, if the current cache value of the item is not null and has a value. If not, the condition evaluates as false.

Value of Item in Expression 1 is NULL

Evaluates as true if the item in Expression 1 has no value.

Value of Item in Expression 1 is NULL or zero

Evaluates as true if the item in Expression is either NULL or zero.

Value of item in Expression 1 is numeric

Evaluates to true if the value of the Item in Expression 1 is numeric.

Value of user preference in Expression 1 != Expression 2

This condition is the opposite of Value of user preference in Expression 1 = Expression 2. Evaluates to true if the name of the user preference specified in Expression 1 is not equal to the string in Expression 2.

Value of user preference in Expression 1 = Expression 2

Verifies the value of a user preferences. Evaluates to true if the name of the user preference specified in Expression 1 is equal to the string in Expression 2.

When any item in comma-delimited list of items has changed

Evaluates to true when the value of any nonnull session state item in the list of items specified in Expression 1 has changed.

When any item in comma-delimited list of pages has changed

Evaluates to true when the value of any nonnull session state item in the list of pages specified in Expression 1 has changed.

When any item in current application has changed

This condition passes when the value of any nonnull session state item in the current application has changed.

When any item in current page has changed

Evaluate to true when the value of any nonnull session state item in the current page has changed.

When any item in current session has changed

Evaluates to true when the value of any nonnull session state item in the current session has changed.

When cgi_env DAD_NAME != Expression 1

This condition is the opposite of When cgi_env DAD_NAME = Expression 1.

Checks for the data access descriptor (DAD) that is being used in the URL to call the current page in the application and compares it to Expression 1. Evaluate to true, when the DAD is not the same as Expression 1.

When cgi_env DAD_NAME = Expression 1

Checks for the data access descriptor (DAD) that is being used in the URL to call the current page in the application and compares it to Expression 1. Evaluate to true, when the DAD is the same as Expression 1.

When cgi_env HTTP_HOST != Expression 1

This condition is the opposite of When cgi_env HTTP_HOST = Expression 1.

Checks for the value of the common gateway interface (CGI) environment variable HTTP_HOST that is the value returned by owa_util.get_cgi_env ('HTTP_HOST'). Evaluate to true, when this value is not equal to the string in Expression 1.

When cgi_env HTTP_HOST = Expression 1

Checks for the value of the common gateway interface (CGI) environment variable HTTP_HOST that is the value returned by owa_util.get_cgi_env ('HTTP_HOST'). Evaluate to true, when this value is equal to the string in Expression 1.

When cgi_env SERVER_NAME != Expression 1

This condition is the opposite of When cgi_env SERVER_NAME = Expression 1.

This condition checks for the value of the common gateway interface (CGI) environment variable SERVER_NAME, that is the value returned by owa_util.get_cgi_env ('SERVER_NAME'). Evaluate to true, when this value is not equal to the string in Expression 1.

When cgi_env SERVER_NAME = Expression 1

This condition checks for the value of the common gateway interface (CGI) environment variable SERVER_NAME, that is the value returned by owa_util.get_cgi_env ('SERVER_NAME'). Evaluate to true, when this value is equal to the string in Expression 1.

B Privileges Granted to PUBLIC

This section describes public synonyms that exist and for which the execute privilege is granted to PUBLIC for the packages, procedures, functions, tables, and views owned by the Oracle Application Express product schema, (for example, FLOWS_030000).

This section contains the following topics:

- Packages

- Procedures

- Functions

- Tables

- Views

Packages

Public synonyms exist and execute privilege is granted to PUBLIC for the following packages owned by the Oracle Application Express product schema, (for example, FLOWS_030000):

HTMLDB_CUSTOM_AUTH

HTMLDB_ITEM

HTMLDB_LANG

HTMLDB_UTIL

WWV_FLOW

WWV_FLOW_API

WWV_FLOW_AUDIT

WWV_FLOW_CSS_API

WWV_FLOW_COLLECTION

WWV_FLOW_CUSTOM_AUTH

WWV_FLOW_CUSTOM_AUTH_LDAP

WWV_FLOW_CUSTOM_AUTH_SSO

WWV_FLOW_CUSTOM_AUTH_STD

WWV_FLOW_CUSTOMIZE

WWV_FLOW_DML

WWV_FLOW_EPG_INCLUDE_MODULES

WWV_FLOW_FILE_MGR

WWV_FLOW_FND_USER_API

WWV_FLOW_GLOBAL

WWV_FLOW_HELP

WWV_FLOW_HINT

WWV_FLOW_HTML_API

WWV_FLOW_ID

WWV_FLOW_IMAGE_API

WWV_FLOW_ITEM

WWV_FLOW_ITEM_HELP

WWV_FLOW_LANG

WWV_FLOW_LDAP

WWV_FLOW_LOOKUP_TABLES

WWV_FLOW_MAIL

WWV_FLOW_PLSQL_JOB

WWV_FLOW_PREFERENCES

WWV_FLOW_RANDOM

WWV_FLOW_RENDER_SHORTCUT

WWV_FLOW_REWRITE_QUERY

WWV_FLOW_USER_API

WWV_FLOW_UTILITIES

WWV_FLOW_SVG

WWV_FLOW_WEB_SERVICES

WWV_MIG_ACC_LOAD

WWV_RENDER_CALENDAR2

WWV_RENDER_CHART2

WWV_SPELING

Execute privilege is granted to PUBLIC for the following packages owned by the Oracle Application Express product schema, (for example, FLOWS_030000):

APEX_SITE_ADMIN_PRIVS

HTMLDB_SITE_ADMIN_PRIVS

WWV_CALCULATOR

WWV_FLOW_FLASH_CHART

WWV_FLOW_GENERATE_DDL

WWV_FLOW_IMAGE_GENERATOR

WWV_FLOW_TREE_GLOBAL_VARS

Procedures

Public synonyms exist and execute privilege is granted to PUBLIC for the following procedures owned by the Oracle Application Express product schema, (for example, FLOWS_030000):

APEX

APEX_ADMIN

DEVELOPMENT_SERVICE_HOME

DEVELOPMENT_SERVICE_HOME_LOGIN

DEVELOPMENT_SERVICE_SIGNUP

F

HTMLDB

HTMLDB_ADMIN

HTMLDB_LOGIN

P

WWV_FLOW_INIT_HTP_BUFFER

Z

Functions

Public synonyms exist and execute privilege is granted to PUBLIC for the following functions owned by the Oracle Application Express product schema, (for example, FLOWS_030000):

NV

V

WWV_FLOW_HOT_HTTP_LINKS

Execute privilege is granted to PUBLIC for the following function owned by the Oracle Application Express product schema, (for example, FLOWS_030000):

WWV_POPUP_FILTER

Tables

Public synonyms exist and select privilege is granted to PUBLIC for the following tables owned by the Oracle Application Express product schema, (for example, FLOWS_030000):

WWV_FLOW_DUAL100

WWV_FLOW_TEMP_TABLE

WWV_FLOW_LOV_TEMP

Views

Public synonyms exist and select privilege is granted to PUBLIC for the following views owned by the Oracle Application Express product schema, (for example, FLOWS_030000):

APEX_APPLICATIONS

APEX_APPLICATION_ALL_AUTH

APEX_APPLICATION_AUTH

APEX_APPLICATION_AUTHORIZATION

APEX_APPLICATION_BC_ENTRIES

APEX_APPLICATION_BREADCRUMBS

APEX_APPLICATION_BUILD_OPTIONS

APEX_APPLICATION_COMPUTATIONS

APEX_APPLICATION_FLASH_CHARTS

APEX_APPLICATION_FLASH_SERIES

APEX_APPLICATION_ITEMS

APEX_APPLICATION_LISTS

APEX_APPLICATION_LIST_ENTRIES

APEX_APPLICATION_LOVS

APEX_APPLICATION_LOV_ENTRIES

APEX_APPLICATION_NAV_BAR

APEX_APPLICATION_PAGES

APEX_APPLICATION_PAGE_BRANCHES

APEX_APPLICATION_PAGE_BUTTONS

APEX_APPLICATION_PAGE_COMP

APEX_APPLICATION_PAGE_DB_ITEMS

APEX_APPLICATION_PAGE_ITEMS

APEX_APPLICATION_PAGE_MAP

APEX_APPLICATION_PAGE_PROC

APEX_APPLICATION_PAGE_REGIONS

APEX_APPLICATION_PAGE_RPT_COLS

APEX_APPLICATION_PAGE_VAL

APEX_APPLICATION_PARENT_TABS

APEX_APPLICATION_PROCESSES

APEX_APPLICATION_SHORTCUTS

APEX_APPLICATION_SUPP_OBJECTS

APEX_APPLICATION_SUPP_OBJ_BOPT

APEX_APPLICATION_SUPP_OBJ_CHCK

APEX_APPLICATION_SUPP_OBJ_SCR

APEX_APPLICATION_TABS

APEX_APPLICATION_TEMPLATES

APEX_APPLICATION_TEMP_BC

APEX_APPLICATION_TEMP_BUTTON

APEX_APPLICATION_TEMP_CALENDAR

APEX_APPLICATION_TEMP_LABEL

APEX_APPLICATION_TEMP_LIST

APEX_APPLICATION_TEMP_PAGE

APEX_APPLICATION_TEMP_POPUPLOV

APEX_APPLICATION_TEMP_REGION

APEX_APPLICATION_TEMP_REPORT

APEX_APPLICATION_THEMES

APEX_APPLICATION_TRANSLATIONS

APEX_APPLICATION_TREES

APEX_APPLICATION_WEB_SERVICES

APEX_DICTIONARY

APEX_WORKSPACES

APEX_WORKSPACE_ACTIVITY_LOG

APEX_WORKSPACE_APEX_USERS

APEX_WORKSPACE_CLICKS

APEX_WORKSPACE_DEVELOPERS

APEX_WORKSPACE_FILES

APEX_WORKSPACE_LOG_SUMMARY

APEX_WORKSPACE_LOG_SUMMARY_USR

APEX_WORKSPACE_SCHEMAS

APEX_WORKSPACE_SESSIONS

APEX_WORKSPACE_SQL_SCRIPTS

WWV_FLOW_CLICKTHRU_LOG

WWV_FLOW_COLLECTIONS

WWV_FLOW_FILES

WWV_FLOW_GROUP_USERS

WWV_FLOW_HOURS_12

WWV_FLOW_HOURS_24

WWV_FLOW_LISTS_OF_VALUES$_V

WWV_FLOW_LIST_OF_VALUES_DATA_V

WWV_FLOW_MINUTES

WWV_FLOW_MINUTES_5

WWV_FLOW_MONTHS_MON

WWV_FLOW_MONTHS_MONTH

WWV_FLOW_PLSQL_JOBS

WWV_FLOW_USERS

WWV_FLOW_USER_ACTIVITY_LOG

WWV_FLOW_USER_MAIL_LOG

WWV_FLOW_USER_MAIL_QUEUE

WWV_FLOW_YEARS

Index
A  B  C  D  E  F  G  H  I  J  L  M  N  O  P  Q  R  S  T  U  V  W  X

A

Accept Page, 3.2.1

access control

authorization schemes, 5.16.4

access control list

about, 5.16

adding users, 5.16.3.2

creating, 5.16.2

removing users, 5.16.3.3

selecting an application mode, 5.16.3

selecting user privileges, 5.16.3.2

Action Bar, 4.3.1

about, 4.5.2.2

Comment icon, 4.5.2.2

Export Page icon, 4.5.2.2

Find icon, 4.5.2.2

Lock icon, 4.5.2.2

Run Page icon, 4.5.2.2

Shared Components icon, 4.5.2.2

activity log, 13.5 activity reports

creating custom reports, 13.5

Administration list, 1.5

About Application Express, 1.5

Change Password, 1.5

Manage Application Express Users, 1.5

Manage Services, 1.5

Monitor Activity, 1.5

Administration Services

disabling access, 22.4.5.6

logging in to, 22.2

restricting access, 22.4.5.6

administrator

roles, 8.1

APEX_ACTIVITY_LOG view, 13.5 APEX_APPLICATION

global variables, 15.4

package, 15.4

APEX_APPLICATION.G_F01

referencing, 15.4.1

APEX_COLLECTION, 13.4.1

ADD_MEMBER, 13.4.6

COLLECTION_EXISTS, 13.4.11.3

COLLECTION_MEMBER_COUNT, 13.4.11.1

CREATE_COLLECTION, 13.4.2

CREATE_COLLECTION_FROM_QUERY, 13.4.2

CREATE_COLLECTION_FROM_QUERY_B, 13.4.2

CREATE_OR_TRUNCATE_COLLECTION, 13.4.2, 13.4.12

DELETE_ALL_COLLECTIONS, 13.4.5.1

DELETE_ALL_COLLECTIONS_SESSION, 13.4.5.2

DELETE_COLLECTION, 13.4.5

DELETE_MEMBER, 13.4.8

DELETE_MEMBERS, 13.4.8

GET_MEMBER_MD5, 13.4.9

MOVE_MEMBER_DOWN, 13.4.11.4

RESEQUENCE_COLLECTION, 13.4.11.2

RESET_COLLECTION_CHANGED, 13.4.9

SORT_MEMBERS, 13.4.11.5

TRUNCATE_COLLECTION, 13.4.3

UPDATE_MEMBER, 13.4.7

UPDATE_MEMBER_ATTRIBUTE, 13.4.7, 13.4.7

APEX_CUSTOM_AUTH, 15.5

APPLICATION_PAGE_ITEM_EXISTS function, 15.5.1

CURRENT_PAGE_IS_PUBLIC function, 15.5.2

DEFINE_USER_SESSION procedure, 15.5.3

GET_COOKIE_PROPS, 15.5.4

GET_LDAP_PROPS, 15.5.5

GET_NEXT_SESSION_ID function, 15.5.6

GET_SECURITY_GROUP_ID function, 15.5.9

GET_SESSION_ID function, 15.5.10

GET_SESSION_ID_FROM_COOKIE, 15.5.7

GET_USER function, 15.5.11

GET_USERNAME, 15.5.8

IS_SESSION_VALID, 15.5.12

LOGIN

Login API, 15.5.13

LOGOUT, 15.5.14 POST_LOGIN, 15.5.15 SESSION_ID_EXISTS function, 15.5.16 SET_SESSION_ID procedure, 15.5.18 SET_SESSION_ID_TO_NEXT_VALUE procedure, 15.5.19 SET_USER procedure, 15.5.17 APEX_ITEM, 15.3

CHECKBOX function, 15.3.1

DATE_POPUP function, 15.3.2

DISPLAY_AND_SAVE, 15.3.3

HIDDEN function, 15.3.4

MD5_CHECKSUM function, 15.3.5

MD5_HIDDEN function, 15.3.6

MULTI_ROW_UPDATE procedure, 15.3.7

POPUP_FROM_LOV function, 15.3.8

POPUP_FROM_QUERY function, 15.3.9

POPUPKEY_FROM_LOV function, 15.3.10

POPUPKEY_FROM_QUERY function, 15.3.11

RADIOGROUP function, 15.3.12

SELECT_LIST function, 15.3.13

SELECT_LIST_FROM_LOV function, 15.3.14

SELECT_LIST_FROM_LOV_XL function, 15.3.15

SELECT_LIST_FROM_QUERY function, 15.3.16

SELECT_LIST_FROM_QUERY_XL function, 15.3.17

TEXT function, 15.3.19

TEXT_FROM_LOV function, 15.3.20

TEXT_FROM_LOV_QUERY function, 15.3.21

TEXTAREA function, 15.3.18

APEX_LANG

LANG, 14.5.2

MESSAGE API, 14.4.1.1

APEX_LDAP

AUTHENTICATE, 15.6.1

GET_ALL_USER_ATTRIBUTES, 15.6.6

GET_USER_ATTRIBUTES, 15.6.5

IS_MEMBER, 15.6.2

MEMBER_OF, 15.6.3

MEMBER_OF2 Function, 15.6.4

APEX_LDAP APIs

APEX_LDAP, 15.6

APEX_MAIL, 15.2 APEX_MAIL_QUEUE

sending email in queue, 15.2.2

APEX_MAIL.PUSH_QUEUE, 15.2.2 APEX_MAIL.SEND, 15.2.1 APEX_PLSQL_JOB, 13.6.1 APEX_SITE_ADMIN_PRIVS, 22.5.2

CREATE_EXCEPTION, 22.5.2.3

REMOVE_WORKSPACE_EXCEPTIONS, 22.5.2.3.1

REPORT, 22.5.2.4

RESTRICT_SCHEMA, 22.5.2.2

UNRESTRICT_SCHEMA, 22.5.2.1

APEX_UTIL, 15.1

CACHE_GET_DATE_OF_PAGE_CACHE procedure, 15.1.2, 15.1.3

CACHE_PURGE_BY_APPLICATION procedure, 15.1.4

CACHE_PURGE_BY_PAGE procedure, 15.1.5

CACHE_PURGE_STALE procedure, 15.1.6

CHANGE_CURRENT_USER_PW procedure, 15.1.1

CHANGE_PASSWORD_ON_FIRST_USE, 15.1.7

CLEAR_APP_CACHE procedure, 15.1.8

CLEAR_PAGE_CACHE procedure, 15.1.9

CLEAR_USER_CACHE procedure, 15.1.10

COUNT_CLICK procedure, 15.1.11

COUNT_STALE_REGIONS function, 15.1.12

CREATE_USER procedure, 15.1.13

CREATE_USER_GROUP procedure, 15.1.14

CURRENT_USER_IN_GROUP function, 15.1.15

EDIT_USER procedure, 15.1.16

END_USER_ACCOUNT_DAYS_LEFT, 15.1.17

EXPIRE_END_USER_ACCOUNT, 15.1.18

EXPIRE_WORKSPACE_ACCOUNT, 15.1.19

EXPORT_USERS procedure, 15.1.20

FETCH_APP_ITEM function, 15.1.21

FETCH_USER procedure, 15.1.22

FIND_SECURITY_GROUP_ID function, 15.1.23

FIND_WORKSPACE function, 15.1.24

GET_ACCOUNT, 15.1.25

GET_ATTRIBUTE function, 15.1.26

GET_AUTHENTICATION_RESULT, 15.1.27

GET_CURRENT_USER_ID function, 15.1.28

GET_DEFAULT_SCHEMA, 15.1.29

GET_EMAIL, 15.1.30

GET_FILE procedure, 15.1.31

GET_FILE_ID function, 15.1.32

GET_FIRST_NAME, 15.1.33

GET_GROUP_ID, 15.1.35

GET_GROUP_NAME, 15.1.36

GET_GROUPS_USER_BELONGS_TO, 15.1.34

GET_LAST_NAME, 15.1.37

GET_NUMERIC_SESSION_STATE function, 15.1.39

GET_PREFERENCE function, 15.1.40

GET_SESSION_STATE function, 15.1.41

GET_USER_ID, 15.1.42

GET_USER_ROLES, 15.1.43

GET_USERNAME, 15.1.38

IS_LOGIN_PASSWORD_VALID, 15.1.44

IS_USERNAME_UNIQUE, 15.1.45

KEYVAL_NUM, 15.1.46

KEYVAL_VC2, 15.1.47

LOCK_ACCOUNT, 15.1.48, 15.1.77

PASSWORD_FIRST_USE_OCCURRED, 15.1.49

PREPARE_URL, 15.1.50

PUBLIC_CHECK_AUTHORIZATION function, 15.1.51

PURGE_REGIONS_BY_APP procedure, 15.1.52

PURGE_REGIONS_BY_ID procedure, 15.1.53, 15.1.55

PURGE_REGIONS_BY_NAME procedure, 15.1.54

PURGE_STALE_REGIONS procedure, 15.1.56

REMOVE_PREFERENCE procedure, 15.1.57

REMOVE_SORT_PREFERENCES procedure, 15.1.58

REMOVE_USER, 15.1.59

RESET_AUTHORIZATIONS procedure, 15.1.60

RESET_PW, 15.1.61

SAVEKEY_NUM, 15.1.62

SAVEKEY_VC2, 15.1.63

SET_ATTRIBUTE, 15.1.64

SET_AUTHENTICATION_RESULT, 15.1.65

SET_CUSTOM_AUTH_STATUS, 15.1.66

SET_EMAIL, 15.1.67

SET_FIRST_NAME, 15.1.68

SET_LAST_NAME, 15.1.69

SET_PREFERENCE procedure, 15.1.70

SET_SESSION_STATE procedure, 15.1.71

STRING_TO_TABLE function, 15.1.73

TABLE_TO_STRING function, 15.1.74

UNEXPIRE_END_USER_ACCOUNT, 15.1.75

UNEXPIRE_WORKSPACE_ACCOUNT, 15.1.76

URL_ENCODE function, 15.1.78

USERNAME, 15.1.72

WORKSPACE_ACCOUNT_DAYS_LEFT, 15.1.79

APIs

APEX_APPLICATION, 15.4

APEX_COLLECTION, 13.4.1

APEX_CUSTOM_AUTH, 15.5

APEX_ITEM, 15.3

APEX_LANG, 14.4.1.1, 14.5.2

APEX_MAIL, 15.2

APEX_PLSQL_JOB, 13.6.1

APEX_UTIL, 15.1

application

adding a page, 5.2

adding content from Web sites, 7.6

based on queries, 5.1.2.1

based on spreadsheet data, 5.1.3

controlling navigation using branches, 6.6

copying, 4.3, 5.1.5

creating, 5.1

creating on tables, 5.1.2.1

debugging, 10

defining primary language, 14.2

deleting, 4.2, 4.3, 5.1.6

demonstration, 5.1.4

demonstrations, 2.1

deploying, 12.2, 12.3, 12.5.1

exporting, 12.3, 12.5.1

hiding features, 12.9.3

importing export file, 12.6

importing from SQL*Plus, 12.7.5

language preference, 14.1.1

performance tuning, 10.1

reports, 8.17

resource use, 10.5

running, 5.2.6

sending email from, 13.3.2

sending messages in APEX_MAIL_QUEUE, 15.2.2

sending outbound email, 15.2.1

switching active theme, 7.7.4

translatable components, 14.1.3

translating, 14.1

translating components, 14.1.4

translating multibye languages, 14.2.2

translation rendering, 14.1.3

Application Administration page, 8.2 Application Alias attribute, 4.4.1.2.1 application attributes

Application Alias, 4.4.1.2.1

Application Template Defaults, 4.4.1.2.8

Availability, 4.4.1.2.2

Build Options, 4.4.1.2.6

Build Status, 4.4.1.2.2

Component Defaults, 4.4.1.2.9

Debugging, 4.4.1.2.1

Default Page Template, 4.4.1.2.8

editing, 4.4.1

Error Page Template, 4.4.1.2.8

Exact Substitutions, 4.4.1.2.1

exporting, 12.5.3

Global Notifications, 4.4.1.2.3

Image Prefix, 4.4.1.2.1

Logging, 4.4.1.2.1

Logo, 4.4.1.2.5

Message for unavailable application, 4.4.1.2.2

Name attribute, 4.4.1.2.1

Parsing Schema, 4.4.1.2.1

Print Mode Page Template, 4.4.1.2.8

Proxy Server, 4.4.1.2.1

restrict access, 4.4.1.2.2

Status, 4.4.1.2.2

Substitutions, 4.4.1.2.4

Theme, 4.4.1.2.7

Version, 4.4.1.2.1

Virtual Private Database, 4.4.2.2.5

Application Builder

accessing, 4.1

home page, 4.2

Page Definition, 3.1

Application Builder Defaults, 8.9.1

configuring, 8.9.2

Application Builder home page, 4.1, 4.2 Application Builder home Task list

Application Builder Defaults, 4.2

application computations

about, 4.12.1

Application Computations page, 4.12.2.1

creating, 4.12.2

executing On New Instance, 4.12.1.1

history report, 4.12.3

application definition

editing, 4.4.1

Application Express

about, 8.2.3

Application Express Account Credentials, 11.5.3, 11.5.3.1

about, 11.5.3.1

Application Express end users

change password on first use, 8.16.2

changing user password, 8.16.4

creating accounts, 8.16.1

deleting accounts, 8.16.3

editing accounts, 8.16.2

locking accounts, 8.16.2

managing, 8.16

password expiration, 8.16.2

Application Express engine

determining schema for, 22.5.1

Application Express user groups

adding users, 8.16.5.4, 8.16.5.5

creating, 8.16.5.1

editing, 8.16.5.2

report, 8.16.5.3

Application Express users

controlling account availability, 22.9.1

creating, 22.9.1

deleting accounts, 22.9.3

editing accounts, 22.9.2

grouping, 8.16.5

requiring password change, 22.9.1

Application home page, 4.3

adding a page, 5.2.2

copying a page, 5.2.5

Export/Install icon, 4.3

Run Application icon, 4.3

running demonstration applications, 2.2.2

Shared Components icon, 4.3

Application home Task list

Application Reports, 4.3

Copy this Application, 4.3

Delete this Application, 4.3

Manage Export Repository, 4.3

Page Groups, 4.3

Page Locks, 4.3

User Interface Defaults, 4.3

application item

about, 5.10.1, 5.11

creating, 5.11.1

editing attributes, 5.11.3

history, 5.11.2

Application Items, 4.10.2.2.4 Application Items page, 5.11.1.1 application language

determining, 4.4.3

Application Language Derived From attribute, 4.4.3.2.2, 14.2 application layout

LOV driving another LOV, 5.13

multiple columns, 7.4

print preview mode, 7.9

shortcuts, 5.14

application logic

editing all, 4.7.1

Application Migration

about, 21, 21.1

checklist, 21.2

forum, 21.1

introduction, 21.1

preparing for migration, 21.2

Project page, 21.7.1

application models, 5.1.2.2

deleting, 8.7

leveraging, 5.1.2.3

Application Primary Language attribute, 4.4.3.2.1, 14.2 application processes

Application Process page, 4.11.3.1, 4.11.3.1

creating, 4.11.3

example, 4.11.2

History report, 4.11.4.2

On Demand, 4.11.1

reports, 4.11.4

understanding, 4.11

Utilization report, 4.11.4.1

application reports

activity, 4.13.4

cross application, 4.13.5

page components, 4.13.3

shared components, 4.13.2

viewing, 4.13, 10.6

applications

managing demonstration, 8.8

migrating to Oracle, 21

architecture, 1.2 attribute values

setting, 15.1.64

authenticated user

create user group, 15.1.14

authentication, 3.2.3, 11.5

Authentication Schemes Repository, 11.5.5

creating a scheme from scratch, 11.5.9

creating an authentication scheme, 11.5.4

preconfigured authentication schemes, 11.5.3

scheme session cookies, 15.5.4

security attributes, 4.4.2.2.1

viewing current scheme, 11.5.6

Authentication Scheme attribute, 4.4.2.2.1 authorization, 3.2.4 Authorization attributes, 4.4.2.2.2 authorization scheme

of an application, 4.4.2.2.2

specifying, 4.4.2.2.2

authorization schemes, 11.6.1

attaching to application, 11.6.3.1

attaching to component, 11.6.3.3

attaching to control, 11.6.3.3

attaching to page, 11.6.3.2

creating, 11.6.2

for controlling access, 5.16.4

Automatic CSV Encoding attribute, 4.4.3.2.3

B

background PL/SQL, 13.6

APEX_PLSQL_JOB, 13.6.1

using a process, 13.6.3

bind variables

using in PL/SQL procedures, 3.4.4.2

using in regions, 3.4.4.1

branch

about, 4.7.10

creating, 6.6, 6.6

When Button Pressed attribute, 3.6.2.20.3

branching

action, 4.7.10.1

branch point, 4.7.10.1

Branch Point list, 4.7.10.1

making conditional, 4.7.10.2

on load, before header, 4.7.10.1

on submit, after processing, 4.7.10.1

on submit, before computation, 4.7.10.1

on submit, before processing, 4.7.10.1

on submit, before validation, 4.7.10.1

using buttons, 5.9.6

breadcrumb template, 7.8.6

Comments, 7.8.6.2.6

Definition, 7.8.6.2.4

Name, 7.8.6.2.1

Subscription, 7.8.6.2.2

Substitution Strings, 7.8.6.2.7

Template Attributes, 7.8.6.2.5

Template Type, 7.8.6.2.3

breadcrumbs, 4.7.6.3

about, 6.3.1

adding entries, 6.3.2.2.3

adding to a page, 6.3.2.2.4

creating, 6.3, 6.3.2

creating dynamic, 6.3.2.2.5

editing, 6.3.3

navigations, 7.8.6.1

reparenting entries, 6.3.4

reports, History, 6.3.5

reports, Utilization, 6.3.5

shared components, 4.7.6.3

build option status

exporting, 12.9.3

build options, 12.9

changing status, 12.9.2

creating, 12.9.1

excluding, 12.9.2

exporting, 12.9.3

including, 12.9.2

reports, 12.9.4

view options, 12.9.1.1

Build Options attribute, 4.4.1.2.6 build status

changing as an administrator, 22.11.2

Build Status attribute, 4.4.1.2.2 built-in substitution strings, 3.6.2 Bulk Edit Item Help report, 5.18.2.3 button

about, 4.7.4.3, 5.9.1

branching, 5.9.6

creating, 5.9, 5.9.2

creating multiple at once, 5.9.3

delete multiple, 5.9.4.2.1

displaying conditionally, 5.9.7

editing, 5.9.4

editing attributes, 5.9.4.1

editing multiple, 5.9.4.2

names, 5.9.5

template, 7.8.7

using Reorder Buttons icon, 5.9.4.3

button template

Comments, 7.8.7.1.4

Definition, 7.8.7.1.3

Name, 7.8.7.1.1

Subscription, 7.8.7.1.2

Substitution Strings, 7.8.7.1.5

C

caching

regions, 7.3.3.5

calendar

adding to a page, 5.7.2.1

adding to new page, 5.7.2.2

converting Easy to SQL, 5.7.6

creating, 5.7, 5.7.2

creating a column link, 5.7.4.2.3

creating a day link, 5.7.4.2.4

defining calendar interval, 5.7.4.2.2

defining display attributes, 5.7.4.2.2

Easy Calendar, 5.7.1

editing attributes, 5.7.4

editing title, 5.7.3

formatting, 5.7.4.2.1

SQL Calendar, 5.7.1

supported substitution strings, 5.7.1.1

types, 5.7.1

upgrading, 5.7.5

calendar attributes

accessing, 5.7.4.1

Calendar Display, 5.7.4.2.1

Column Link, 5.7.4.2.3

Day Link, 5.7.4.2.4

Display Attributes, 5.7.4.2.2

calendar template, 7.8.8

Comments, 7.8.8.1.3

Daily Calendar, 7.8.8.1.3

Monthly Calendar, 7.8.8.1.3

Name, 7.8.8.1.1

Template Subscription, 7.8.8.1.2

Weekly Calendar, 7.8.8.1.3

cascading style sheets

about, 7.8.1

exporting, 12.5.5

importing, 12.6.2

referencing for SVG charts, 5.8.4.5

referencing in page template, 7.10.2

referencing inline (SVG charts), 5.8.4.6

searching for, 5.15.8

uploading, 7.10.1

using custom, 7.10

viewing, 5.15.8

change requests, 22.8

approving, 22.8.4

managing, 22.8

Change Requests page, 22.8.3 charts

about Flash, 5.8.1.1

about SVG, 5.8.1.2

about wizards, 5.8.2

altering display, 5.8.6

asynchronous updates, 5.8.8

candlestick syntax, 5.8.2

creating, 5.8

dial chart syntax, 5.8.2

displaying in other languages, 5.8.9

editing attributes, 5.8.6

Flash, 5.8.5

HTML chart, 5.8.3

migrating all SVG charts to Flash, 5.8.5.3.3

migrating SVG to Flash, 5.8.5.3.2

monitoring information, 5.8.8

multiple series syntax, 5.8.2

providing a SQL query, 5.8.2

range syntax, 5.8.2

scatter syntax, 5.8.2

SQL query syntax, 5.8.2

supported types, 5.8.1

SVG chart, 5.8.4

types, 5.8.2

check box, 5.10.3.3

creating, 15.3.1

clicks

counting, 15.1.11

Collection Showcase, 2.1, 5.1.4.1 collections, 13.4

accessing, 13.4.4

adding members, 13.4.6

APEX_COLLECTION API, 13.4.1

clearing session state, 13.4.12

creating, 13.4.2

deleting, 13.4.5

deleting members, 13.4.8

determining status, 13.4.9

managing, 13.4.11

merging, 13.4.10

naming, 13.4.1.1

truncating, 13.4.3

updating members, 13.4.7

column definition

editing, 9.2

columns templates

using JavaScript, 7.8.14.4

command termination

in SQL Commands, 19.4.4

Comments attribute, 4.8.2.12 Component Defaults, 4.4.1.2.9

Breadcrumb, 4.4.1.2.9

Breadcrumb Region, 4.4.1.2.9

Button, 4.4.1.2.9

Calendar, 4.4.1.2.9

Chart Region, 4.4.1.2.9

Form Region, 4.4.1.2.9

Label, 4.4.1.2.9

List, 4.4.1.2.9

List Region, 4.4.1.2.9

Region, 4.4.1.2.9

Report, 4.4.1.2.9

Report Region, 4.4.1.2.9

Tabular Form Region, 4.4.1.2.9

Wizard Region, 4.4.1.2.9

components

about translating, 14.1.4

controlling access to, 3.2.4

displaying on all pages, 7.2

displaying on every page, 7.1

translating messages, 14.4, 14.4.1, 14.4.2

condition types

common, 3.2.2

conditional

processing, 3.2.2

rendering, 3.2.2

conditions

displaying regions, 7.3.3.2

list of, A

using, 3.2.2

using with buttons, 5.9.7

configuration

controlling, 12.9

controls

controlling access to, 3.2.4

Copy icon, 4.7.2 Create Application Wizard, 5.1 Create Branch Wizard, 6.6, 6.6 Create Breadcrumb Wizard, 6.3.2.2 Create Button Wizard, 5.9.2 Create icon, 4.7.2 Create Lookup Table, 16.4.3 Create Navigation Bar Entry Wizard, 6.5.2 Create Page Computation Wizard, 4.7.7.1, 13.7.9 Create Page Process Wizard, 4.7.9.1 Create Page Wizard

about, 5.2.1

Create Region Wizard, 5.7.2.1, 6.3.2.2.4, 7.3.4 Create Validations Wizard, 4.7.8.1, 5.6.5.1 Create Workspace Wizard, 22.6.3 cross site-scripting

about, 11.1

dynamic output, 11.1.2

form items, 11.1.4

HTML region, 11.1.1

report regions, 11.1.3

static display areas, 11.1.1

CSS classes

SVG charts, 5.8.4.4

CSS Finder, 5.15, 5.15.8 CSS Repository, 7.10.1.1

D

DAD Credentials Verification

about, 11.5.3.4

data

exporting from database, 20.2.3

loading, 20.2

loading into database, 20.2.2

unloading, 20.2, 20.2.3

data dictionary

browsing, 20.4.5

database

about version, 8.2.3

loading data into, 20.2

monitoring, 20.8

unloading data from, 20.2

Database Account Credentials, 11.5.3, 11.5.3.2 database definition language

generating DDL statements, 20.3

database link, 13.2

browsing, 16.13.2

creating, 16.13.1

testing, 16.13.2.1

Database Monitor

I/O, 20.8.1.4

Locks, 20.8.1.2

Long Operations, 20.8.4

Open Cursors, 20.8.1.6

Sessions, 20.8.1, 20.8.1.1

SQL, 20.8.1.5

Top SQL, 20.8.3

Waits, 20.8.1.3

database monitoring

enabling, 22.4.4

system statistics, 20.8.2

Database Object Dependencies

Next button, 4.6.3

Page field, 4.6.3

Previous button, 4.6.3

View list, 4.6.3

database objects

purging, 20.5

restoring, 20.5

viewing, 2.5

database schema

of an application, 4.4.2.2.3

specifying, 4.4.2.2.3

Database Schema attributes, 4.4.2.2.3 database security

Column Privileges report, 20.4.2

Role Privileges report, 20.4.2

System Privileges report, 20.4.2

date picker, 5.10.3.3

alternate format for an application, 5.10.9

alternate format for an item, 5.10.10

DBMS_APPLICATION_INFO, 10.5 DDL

generating, 20.3

Debug Mode, 10.3 debugging, 10

debug mode, 10.3

isolating a problem, 10.8

SQL queries, 10.7

SQL tracing, 10.4

viewing reports, 10.6

Debugging attribute, 4.4.1.2.1 deep linking, 11.5.9.3 Default Page Template attribute, 4.4.1.2.8 deleting

migration projects, 21.10

deleting export files, 12.7.4 demonstration application

about Collection Showcase, 2.1, 5.1.4.1

about Sample Application, 2.1, 2.3, 5.1.4.1

editing, 2.4, 2.4.2

installing, 2.1

modifying, 2.4, 2.4.2

running from Application home page, 2.2.2

running from Demonstration Applications page, 2.2.1

viewing, 2.1

demonstration applications

disabling creation of, 22.4.2

managing, 8.8

Demonstration Applications page, 2.1, 5.1.4.1

editing an application, 2.4.2

running an application, 2.2.1

deployment, 12.3

creating supporting objects, 12.4.2

exporting a page, 12.5.4

exporting application definition, 12.5.1

exporting cascading style sheets, 12.5.5

exporting images, 12.5.6

exporting scripts, 12.5.8

exporting static files, 12.5.7

exporting themes, 12.5.9

exporting user interface defaults, 12.5.10

importing application from SQL*Plus, 12.7.5

importing export files, 12.6

importing files, 12.6

installing application export, 12.7.2

installing files, 12.7.3

managing database objects, 12.3.1

of an application, 12.2

options, 12.2.1

packaging an application, 12.2

publishing the URL, 12.8

Developer activity log

deleting, 22.3.2.3

Developer Comment icon, 4.3.1.4, 4.5.2.2.3 developer comments

about, 5.4

adding to a page, 5.4.1

adding to an application, 5.4.1

deleting, 5.4.3

editing, 5.4.2

viewing, 5.4.2

viewing reports, 5.4.4

Developer Comments report

accessing, 5.4.4.1

deleting a comments, 5.4.4.3

deleting multiple comments, 5.4.4.4

downloading, 5.4.4.5

editing comments, 5.4.4.2

developer logs

purging, 8.15.1

developer preferences

configuring, 4.2.1

Developer toolbar

about, 2.4.1

Activity, 2.4.1

Activity link, 4.9

Create link, 4.9

creating a page, 5.2.4

Debug link, 4.9

Edit Application link, 4.9

Edit Page link, 4.9

Hide Edit Links, 4.9

Home link, 4.9

Session, 3.3.3

Session link, 4.9

Show Edit Links, 4.9

using, 4.9

development life cycle, 12.1 dial chart

syntax, 5.8.2

Display list

configuring defaults, 4.2.1

DML

about locking, 13.1

Drag and Drop Layout

about, 5.10.5.2

accessing, 5.10.5.1

creating new items, 5.10.5.3

deleting items, 5.10.5.5

editing items, 5.10.5.4

dynamic translation, 14.5

E

Edit Definition page

Virtual Private Database, 4.4.2.2.5

Edit Globalization Attributes

Application Language Derived From, 4.4.3.2.2

Application Primary Language, 4.4.3.2.1

Automatic CSV Encoding, 4.4.3.2.3

Edit Globalization Attributes page, 4.4.3 Edit Page icon, 4.3.1.2 Edit Security Attributes, 4.4.2

Authentication, 4.4.2.2.1

Authorization, 4.4.2.2.2

Database Schema, 4.4.2.2.3

Session State Protection, 4.4.2.2.4

email

configuring environment settings, 13.3.1

configuring for an instance, 22.4.6

email log, 13.3

email queue, 13.3

mail queue, 22.3.4

managing, 13.3

sending from an application, 13.3.2

sending messages in APEX_MAIL_QUEUE, 15.2.2

sending outbound, 15.2.1

viewing mail log, 22.3.4

embedded PL/SQL gateway, 1.2 engine

Application Express, 1.2

environment

configuring, 1.4.2

environment settings

access to Administration Services, 22.4.5.6

configuring email, 13.3.1

configuring workspace size options, 22.4.9

defining, 22.4

disabling access to Internal applications, 22.4.5.7

enabling database monitoring, 22.4.4

including demonstration applications, 22.4.2

PL/SQL program unit editing, 22.4.1

restricting access by IP address, 22.4.5.8

SQL Workshop attributes, 22.4.3

Error Page Template attribute, 4.4.1.2.8 Exact Substitutions attribute, 4.4.1.2.1 Excel

importing, 20.2.2.2

Explain Plan

using, 19.10, 19.10.2

Export

Page field, 4.6.5

View list, 4.6.5

export

a page, 4.6.5

an application, 12.5

application attributes, 12.5.3

build option status, 12.5.3

CSS, 12.5.5

images, 12.5.6

managing database objects, 12.3.1

page, 12.5.4

related files, 12.5

script files, 12.5.8

shared components

export, 12.5.3

static files, 12.5.7 text for translations, 14.3.2 themes, 12.5.9 translation options, 14.3.2.2.4 user interface defaults, 12.5.10 workspace, 22.10.7 export file

of workspace, 15.1.20

Export icon, 4.5.2.2.5 Export Repository, 12.7.2, 12.7.3, 12.7.4

accessing, 12.7.1

Export XML Wizard, 20.2.3.2 exported application

importing, 12.6

exporting data

summary of available methods, 20.1.1

Export/Install icon, 4.3 External click counting log

deleting, 22.3.2.4

External Clicks Log

purging, 8.15.2

F

f?p syntax, 3.5.2

facilitating bookmarking, 3.5.5

F01, 15.4.1 features

new, Preface

file repository

downloading files, 15.1.31

obtaining primary key, 15.1.32

file upload table

security risks, 11.4

files

deleting uploaded files, 7.12.4

downloading uploaded files, 7.12.3

editing uploaded files, 7.12.2

managing, 7.12

uploading, 7.12.1

Find icon, 4.3.1.5, 4.5.2.2.6, 5.15, 5.15.1 Flash chart

adding to existing page, 5.8.5.1

adding to new page, 5.8.5.2

candlestick syntax, 5.8.2

multiple series syntax, 5.8.2

range syntax, 5.8.2

scatter syntax, 5.8.2

using custom XML, 5.8.7

footer

substitution strings, 7.3.3.3

form wizard

Form and Report on Web Service, 5.6.1

Form on a Procedure, 5.6.1

Form on a SQL Query, 5.6.1

Form on a Table with Report, 5.6.1

Form on Table or View, 5.6.1

Form on Web Service, 5.6.1

Master Detail Form, 5.6.1

Summary Page, 5.6.1

Tabular Form, 5.6.1

forms

Automatic Row Processing (DML) process, 5.6.4.2

creating, 5.6

creating a master detail, 5.6.3

creating a tabular form, 5.6.2

creating manually, 5.6.4

creating using a wizard, 5.6.1

page types, 5.6.1

populating, 5.6.4.5

understanding processing, 5.6.4.1

validating input, 5.6.5

forum

Application Migration, 21.1

function

browsing, 16.11.2

compiling, 16.11.4

creating, 16.11.1

downloading, 16.11.5

dropping, 16.11.6

editing, 16.11.3

functions

searching for, 5.15.6

G

Global Notifications attribute, 4.4.1.2.3

globalization

attributes, 14.2

determining application language, 4.4.3

format masks, 14.2.1

understanding, 14.1

graphics

managing, 7.11

referencing, 7.11.2

uploading, 7.11.1

Groups

Display, 4.6.6

Page field, 4.6.6

View list, 4.6.6

groups

adding users, 8.16.5.4

creating, 8.16.5.1, 8.16.5.1, 8.16.5.1

editing, 8.16.5.2, 8.16.5.2

managing Application Express users, 8.16.5

of pages, 5.2.7

removing users, 8.16.5.5

report, 8.16.5.3

GUI

about, 1.1

H

Help

creating, 5.18

creating navigation bar entry, 5.18.3

editing, 5.10.4.2.2, 5.18.2.3

online Help system, 1.7

page Help, 1.7

searching, 1.7

using, 1.7

Help text

defining for item, 5.18.2.2

defining for page, 5.18.2.1

editing items, 5.18.2.3

History

Display, 4.6.4

Next button, 4.6.4

Page field, 4.6.4

Previous button, 4.6.4

View list, 4.6.4

Home Link attribute, 4.4.2.2.1, 4.4.2.2.1 HTMDB03013|Setting Session State, 3.4.2 HTMDB03015|About Bind Variable Syntax, 3.4.4 HTMDB16048|compiling triggers, 16.12.4 HTMDB21005|schemas, determining, 22.5.1 HTML

generated using custom PL/SQL, 7.13

not handled by Application Express, 7.13

HTML chart

adding to existing page, 5.8.3.1

adding to new page, 5.8.3.2

I

Image Finder, 5.15

Image Prefix

about, 7.11.2

Image Prefix attribute, 4.4.1.2.1 Image Repository, 7.11, 7.11.1 images

exporting, 12.5.6

importing, 12.6.4

managing, 7.11

referencing, 7.11.2

searching for, 5.15.7

uploading, 7.11.1

viewing available, 5.15.7

Images Finder, 5.15.7 imported text data

viewing, 20.2.4

importing

application, 12.6.1

application using SQL*Plus, 12.7.5

cascading style sheets, 12.6.2

export files, 12.6, 12.6

images, 12.6.4

page, 12.6.1

static files, 12.6.3

themes, 12.6.5

User Interface Defaults, 12.6.6

importing data

summary of available methods, 20.1.1

index

browsing, 16.6.2

creating, 16.6.1

disabling, 16.6.2, 16.6.2.1

dropping, 16.6.3

rebuilding, 16.6.2, 16.6.2.1

statistics about, 16.6.2.1

Installed Translations page, 22.3.5 installing

application files, 12.7.2

demonstration applications, 2.1

export files, 12.7.3

installing application export, 12.7.2 installing export files, 12.7.3 Internal

disabling access, 22.4.5.7

I/O report, 20.8.1.4 item

about, 4.7.4.4

about Application Items page, 5.11.1.1

alternate date picker format, 5.10.9, 5.10.10

conditional, 5.10.7

multiple select list item, 5.10.8

naming conventions, 5.10.3.2

PICK_DATE_FORMAT_MASK, 5.10.9

read-only, 5.10.7

referencing item values, 5.10.6

referencing using JavaScript, 5.17.1

referencing values, 5.10.6

searching for, 5.15.2

using format masks when translating, 14.2.1

using Reorder Items icon, 5.10.2.2

item attributes

affecting layout, 7.5

Begin On New Field, 7.5

Begin On New Line, 7.5

ColSpan, 7.5

Columns, 7.5

Condition Type and Expressions, 7.5

Horizontal/Vertical Alignment, 7.5

HTML Table Cell Attributes, 7.5

Label, 7.5

Post Element Texts, 7.5

Pre Element Texts, 7.5

Read Only Condition Type, 7.5

Region, 7.5

RowSpan, 7.5

Sequence, 7.5

Template, 7.5

Item Finder, 5.15, 5.15.2 item Help

editing, 5.18.2.3

item type

Check box, 5.10.3.3

Date Picker, 5.10.3.3

Display Only, 5.10.3.3

File Browse, 5.10.3.3

Hidden, 5.10.3.3

List Manager, 5.10.3.3

Multiple Select, 5.10.3.3

Password, 5.10.3.3

Popup List of Values, 5.10.3.3

Radio, 5.10.3.3

Select list, 5.10.3.3

Shuttle, 5.10.3.3

Stop and Start Table, 5.10.3.3

Text, 5.10.3.3

Text Area, 5.10.3.3

J

JavaScript, 7.8.11.1, 7.8.11.1

calling from button, 5.17.3

in row templates, 7.8.14.4

including in HTML Header attribute, 5.17.2.1

including in .js file, 5.17.2.2

including in page template, 5.17.2.2

incorporating, 5.17

libraries, 7.8.11.1

on load events, 4.8.2.5

page specific, 4.8.2.4

referencing items, 5.17.1

setting focus on item, 4.8.2.2

JavaScript Finder, 5.15

L

label template

Comments, 7.8.9.1.5

Definition, 7.8.9.1.3

editing, 7.8.9

Error Display, 7.8.9.1.4

Name, 7.8.9.1.1

Subscription, 7.8.9.1.2

Substitution Strings, 7.8.9.1.6

language

defining for application, 14.2

multibyte, 14.2.2

preference, 14.1.1

layout

altering using item attributes, 7.5

controlling, 7

LDAP attributes

obtaining, 15.5.5

LDAP Credentials Verification, 11.5.3, 11.5.3.3 linking

deep, about, 11.5.9.3

list

adding list entries, 6.2.1.3

adding sublists, 6.2.1.3

adding to a page, 6.2.2

changing parents of list entries, 6.2.1.4

creating, 6.2.1

creating hierarchical, 7.8.10.1

editing, 6.2.3

editing multiple, 6.2.4

example, 6.2

Lists page, 6.2.3

removing parents of orphaned entries, 6.2.1.5

reports, 6.2.5

list of values, 4.7.6.2

bulk edit of static LOVs, 5.12.3.2

creating, 5.12

creating at application-level, 5.12.1

creating dependent LOVs, 5.13

editing, 5.12.3

List of Values History report, 5.12.6.4

List of Values page, 5.12.1.1

List of Values Subscription report, 5.12.6.2

List of Values Utilization report, 5.12.6.3

named, 5.12.1

referencing null values in items, 5.12.5

referencing session state, 5.12.4

reports, 5.12.6

Search Dynamic Lists of Values report, 5.12.6.1

shared, 5.12.1

static, 5.12.2

translating, 14.5

List of Values page, 5.12.1.1 list reports

History, 6.2.5

Unused Lists, 6.2.5

Utilization, 6.2.5

list template

After List Entry, 7.8.10.2.8

After Sub List Entry, 7.8.10.2.7

Before List Entry, 7.8.10.2.3

Before Sub List Entry, 7.8.10.2.5

Comments, 7.8.10.2.9

editing, 7.8.10

Name, 7.8.10.2.1

Sub List Entry, 7.8.10.2.6

Subscription, 7.8.10.2.2

Substitution Strings, 7.8.10.2.10, 7.8.11.2.12

Template Definition, 7.8.10.2.4

lists, 4.7.6.4 Lists page, 6.2.3 Lists Wizard, 6.2.1 Load Data Wizard, 20.2.2.1 Load XML Wizard, 20.2.2.3 loaded text data

deleting, 20.2.4

Lock icon, 4.5.2.2.4 locks

determining lock status, 5.2.8.1

for pages, 5.2.8

Locks report, 20.8.1.2 Logging attribute, 4.4.1.2.1 logging in to

Oracle Application Express, 1.4.3

logging out, 1.4.3.5 Login Access log

deleting entries, 22.3.2.6

Login controls

enabling for workspace, 8.6.2

login controls

configuring, 22.4.5.3

login credentials, 1.4.3.2 login message

creating, 22.4.10.1

disabling, 22.4.10.1

login page, 1.4

building, 11.5.9.2

understanding login credentials, 1.4.3.2

Login URL attribute, 4.4.2.2.1 Logo attribute, 4.4.1.2.5 logs

purging, 8.15

M

mail log

deleting entries, 22.3.2.5

viewing, 22.3.4.2

mail queue

viewing, 22.3.4.1

Manage Services page, 8.3 managing

migration projects, 21.10

master detail form

creating, 5.6.3

materialized view

browsing, 16.14.2

creating, 16.14.1

dependent objects, 16.14.2.1

dropping, 16.14.3

list of grants, 16.14.2.1

report of data, 16.14.2.1

sort by column, 16.14.2.1

viewing object details, 16.14.2.1

.mdb file, 21.2 Message for unavailable application, 4.4.1.2.2 messages

login, 22.4.10

system, 22.4.10

translating, 14.4, 14.4.1

translating internal, 14.4.2

messages in PL/SQL procedures, 14.4.1

translating, 14.4.1

messages in reports, 14.4.2

translating, 14.4.2

Microsoft Access

migrating to Oracle, 21

migrating

preparation, 21.2

migrating applications, 21

create migration project, 21.7

create workspace, 21.6

export metadata, 21.4

generate applications, 21.9

migrate database, 21.5

review database, 21.8.5

review forms, 21.8.3

review module, 21.8.5

review objects, 21.8

review page information, 21.8.5

review queries, 21.8.2

review reports, 21.8.4

review tables, 21.8.1

step overview, 21.3

migration projects

deleting, 21.10

managing, 21.10

N

navigation

alternatives, 1.6

branch, 6.6

breadcrumb, 6.3

breadcrumbs, 1.6

drop down menus, 1.6

icons, 1.6

list, 6.2

parent tabs, 6.1

standard tabs, 6.1

tab, 6.1

trees, 6.4

navigation bar, 6.5

Reorder Navigation Bar Entries Icon, 6.5.5

navigation bar entry, 6.5

about, 6.5.1

creating, 6.5.2

editing, 6.5.3

editing multiple, 6.5.4

reports, 6.5.6

navigation bar entry history, 6.5.6.2 navigation bar entry reports

history, 6.5.6.2

subscription, 6.5.6.1

navigation bar entry subscription, 6.5.6.1 New Component Wizard, 5.2.4, 5.16.2.3 No Authentication (using DAD), 11.5.3, 11.5.3.5 Notifications list, 22.7.1

O

Object Browser

about, 16.1

accessing, 16.1.1

creating objects, 16.3

Detail pane, 16.1

Hide Objects control, 16.2.2

hiding Object Selection pane, 16.2.2

managing database links, 16.13

managing functions, 16.11

managing indexes, 16.6

managing materialized views, 16.14

managing packages, 16.9

managing procedures, 16.10

managing sequences, 16.7

managing tables, 16.4

managing triggers, 16.12

managing types, 16.8

managing views, 16.5

Object Selection pane, 16.1

searching for objects, 16.2

synonyms, 16.15

Object Reports

All Objects, 20.4.5

All Objects report, 20.4.5

Column Privileges report, 20.4.2

Data Dictionary, 20.4.5

Exception Reports, 20.4.4

Invalid Objects, 20.4.5

Object Calendar, 20.4.5

Object Counts by Type, 20.4.5

PL/SQL Source Code report, 20.4.3.3

Program Unit Arguments report, 20.4.3.1

Role Privileges report, 20.4.2

System Privileges report, 20.4.2

Unit Line Counts report, 20.4.3.2

objects

purging, 20.5

restoring, 20.5

online Help

field level, 1.7

online Help system, 1.7

page Help, 1.7

searching, 1.7

Open Cursors report, 20.8.1.6 Open Door Credentials, 11.5.3 Oracle Application Express

about, 1.1

application owner, 8.2.3

architecture, 1.2

browser requirements, 1.4.1

configuring your environment, 1.4.2

current time (on server), 8.2.3

current user, 8.2.3

DAD CHARACTERSET, 8.2.3

database version, 8.2.3

host schema, 8.2.3

JOB_QUEUE_PROCESSES, 8.2.3

language preference, 8.2.3

last DDL time, 8.2.3

list of features, 1.1

logging in, 1.4

logging in to as a developer, 1.4.3

NLS_CHARACTERSET, 8.2.3

schema compatibility, 8.2.3

user roles, 1.3

version, 8.2.3

workspace ID, 8.2.3

workspace name, 8.2.3

Oracle Application Express administrator, 1.3, 8.1, 22

approving a change request, 22.8.4

approving a workspace request, 22.7.3

changing a workspace request, 22.7.4

changing build status, 22.11.2

creating a workspace manually, 22.6.3

creating user accounts, 22.9.1

deleting a workspace, 22.10.5

deleting a workspace request, 22.7.5

deleting log entries, 22.3.2

deleting user accounts, 22.9.3

editing user accounts, 22.9.2

exporting and importing a workspace, 22.10.7

locking a workspace, 22.10.6

managing email, 22.3.4

managing environment settings, 22.4

managing schemas, 22.6.4

managing session state, 22.3.3

managing users, 22.9

Oracle default schemas, 22.5.2

provisioning a workspace, 22.6

purging inactive workspaces, 22.10.4

viewing Parse as Schemas report, 22.11.3

viewing pending change requests, 22.8.1

viewing pending workspace requests, 22.7.1, 22.7.1

viewing report attributes, 22.11.1

viewing workspaces, 22.10.1

Oracle Application Express Application Migration Workshop, 21 Oracle Application Express Engine, 1.2 Oracle Application Server Single Sign-On, 11.5.3

preconfigured authentication schemes

Oracle Application Server Single Sign-On, 11.5.3

Oracle default schemas

determining administrator privilege status, 22.5.2

removing default restrictions, 22.5.2

revoking administrator privileges, 22.5.2

Oracle Optimizer

Explain Plan, 19.10, 19.10.2

P

package

compiling, 16.9.4

creating, 16.9.1

downloading, 16.9.2.1, 16.9.5

dropping, 16.9.6

editing, 16.9.2.1, 16.9.3

finding, 16.9.2.1

grants for, 16.9.2.1

object dependencies, 16.9.2.1

package body, 16.9.2.1

related errors, 16.9.2.1

viewing, 16.9.2

packaged application

about, 12.4.1

about Supporting Objects page, 12.4.2.2

adding access control list, 12.4.4

adding CSS installation script, 12.4.3

adding image installation script, 12.4.3

adding static file installation script, 12.4.3

build options, 12.4.2.2.1

creating supporting objects, 12.4.2

defining an upgrade script, 12.4.7.1

deinstallation scripts, 12.4.2.2.4

deinstalling, 12.4.8

deleting installation options, 12.4.6

deleting messages, 12.4.6

deleting supporting object scripts, 12.4.6

how to create, 12.4

installing supporting objects, 12.4.5

installion scripts, 12.4.2.2.1

messages, 12.4.2.2.2

prerequisites, 12.4.2.2.1

substitutions strings, 12.4.2.2.1

testing installation scripts, 12.4.5

upgrade scripts, 12.4.2.2.3

upgrading a packaged application, 12.4.7.2

validations, 12.4.2.2.1

viewing an install summary, 12.4.9

packages

searching for, 5.15.6

page

creating, 5.2.1

creating from Application Home, 5.2.2

creating from Page Definition, 5.2.3

managing, 5.2

page attributes, 4.7.4.1

about, 4.8

accessing, 4.8.1

Authentication, 4.8.2.6

Authorization Scheme, 4.8.2.6

Cache, 4.8.2.8

Cache by User, 4.8.2.8

Cache Page, 4.8.2.8

Cache Page Condition, 4.8.2.8

Cache Timeout, 4.8.2.8

Comments, 4.8.2.12

Configuration, 4.8.2.9

Cursor Focus, 4.8.2.2

display attributes, 4.8.2.2

Duplicate Submission, 4.8.2.7

Expression 1, 4.8.2.8, 4.8.2.8

Footer, 4.8.2.3

Groups, 4.8.2.1

Header Text, 4.8.2.3

Help, 4.8.2.11

HTML Body Attributes, 4.8.2.5

HTML Header, 4.8.2.4

Name, 4.8.2.1

On Error Text, 4.8.2.10

Page Alias, 4.8.2.1

Page Template, 4.8.2.2

security, 4.8.2.6

Standard Tab Set, 4.8.2.2

Title, 4.8.2.2

page components

controlling access, 5.16.4

editing all, 4.7.1

page computation

computation point, 4.7.7.2

creating, 4.7.7.1

defining computation point, 4.7.7.3.1

defining computation source, 4.7.7.3.1

editing attributes, 4.7.7.3

making a computation conditional, 4.7.7.3.2

syntax, 4.7.7.2

page controls

editing all, 4.7.1

Page Definition

about, 3.1

Action Bar, 4.5.2.2

alternate views, 4.6.1

Copy button, 4.5.2.1

Copy icon, 4.7.2

Create button, 4.5.2.1

Create icon, 4.7.2

creating a page, 5.2.3

creating new controls and components, 4.7.2

Delete button, 4.5.2.1

editing, 4.7

editing all, 4.7.1

export, 4.6.5

Next button, 4.5.2.1

Page field, 4.5.2.1

Page Processing, 4.7.5

Page Rendering, 4.7.4

Previous button, 4.5.2.1

reordering components, 4.7.3

View list, 4.5.2.1, 4.6

viewing, 4.5

Page Events

Next button, 4.6.2

Page field, 4.6.2

Previous button, 4.6.2

Show All, 4.6.2, 4.6.2

Show Used, 4.6.2

View list, 4.6.2

Page Finder, 5.15, 5.15.3 page groups

assigning pages, 5.2.7.3

creating, 5.2.7.2

editing group definition, 5.2.7.2.1

managing, 4.3

Pages by Page Group report, 5.2.7.6

reassigning pages, 5.2.7.3.1

removing, 5.2.7.5

removing pages, 5.2.7.4

viewing, 4.6.6, 5.2.7.1

page help

creating, 5.18

page item

about, 5.10.1

creating, 5.10, 5.10.3

creating from Page Definition, 5.10.3.1

deleting multiple, 5.10.4.2.4

Drag and Drop Layout page, 5.10.5

editing attributes, 5.10.4.1

editing display on a page, 5.10.4.2.1

editing Help, 5.10.4.2.2

editing multiple, 5.10.4.2

naming conventions, 5.10.3.2

reassigning to a region, 5.10.4.2.3

static list of values, 5.10.3.6

types, 5.10.3.3

using Drag and drop icon, 5.10.2.1

using Reorder Region Items icon, 5.10.4.3

page items

about, 5.10.2

page layout

about, 7.1

page locks

managing, 4.3

page number, 4.7 page processes

changing processing points, 4.7.9.2.1

changing source, 4.7.9.2.1

creating, 4.7.4.6, 4.7.9.1

editing attributes, 4.7.9.2

making conditional, 4.7.9.2.2

When Button Pressed attribute, 3.6.2.20.3

Page Processing

about, 4.7.5

Branches, 4.7.5.4

Computations, 4.7.5.1

Processes, 4.7.5.3

Validations, 4.7.5.2

page processing, 3.2.1

understanding, 3.2

Page Rendering

about, 4.7.4

Buttons, 4.7.4.3, 5.9.1

Computations, 4.7.4.5

Items, 4.7.4.4, 5.10.2

Page, 4.7.4.1

Processes

about, 4.7.4.6

Regions, 4.7.4.2, 7.3.1 Tabs, 6.1.2 page rendering, 3.2.1

understanding, 3.2

page reports

viewing, 10.6

page template

Body, 7.8.11.2.3

Definition, 7.8.11.2.3

Display Points, 7.8.11.2.4

editing, 7.8.11

Error Page Template Control, 7.8.11.2.10

Footer, 7.8.11.2.3

Header, 7.8.11.2.3

Image Based Tab Attributes, 7.8.11.2.8

Multi Column Region Table Attribute, 7.8.11.2.9

Name, 7.8.11.2.1

Parent Tab Attributes, 7.8.11.2.7

specifying defaults, 7.8.2.1, 7.8.2.2

Standard Tab Attributes, 7.8.11.2.6

Subscription, 7.8.11.2.2

substitution strings, 7.8.11

Subtemplate, 7.8.11.2.5

page template substitution strings, 7.8.11

#APP_VERSION#, 7.8.11.1

#BOX_BODY#, 7.8.11.1

#CUSTOMIZE#, 7.8.11.1

#FORM_CLOSE#, 7.8.11.1

#FORM_OPEN#, 7.8.11.1

#GLOBAL_NOTIFICATION#, 7.8.11.1

#HEAD#, 7.8.11.1

#LOGO#, 7.8.11.1

#NAVIGATION_BAR#, 7.8.11.1

#NOTIFICATION_MESSAGE#, 7.8.11.1

#ONLOAD#, 7.8.11.1

#PARENT_TAB_CELLS#, 7.8.11.1

#REGION_POSITION_NN#, 7.8.11.1

#SUCCESS_MESSAGE#, 7.8.11.1

#TAB_CELLS#, 7.8.11.1

#TITLE#, 7.8.11.1

page view

Referenced Components, 4.6.7

Page View Activity logs

deleting, 22.3.2.2

page views

accessing alternate views, 4.6.1

Database Object Dependencies, 4.6.3

Groups, 4.6.6

History, 4.6.4

Page Events, 4.6.2

page zero, 7.1, 7.2 page-level item

History, 5.10.4.2.5

page-level template, 7.8.2.2 pages

about, 3.1

about page zero, 7.2

adding, 5.2

assigning to groups, 5.2.7.3

caching, 4.8.2.8

calling from a button, 3.5.4

calling with an alias, 3.5.3

controlling access to, 5.16.4

copying, 5.2.5

creating from Application home, 5.2.2

creating from Developer toolbar, 5.2.4

creating groups, 5.2.7.2

deleting, 5.2.9

determining lock status, 5.2.8.1

duplicate submission, 4.8.2.7

enabling user customization, 7.3.3.4

exporting, 12.5.4

grouping, 5.2.7

linking with f?p syntax, 3.5.2

locking, 5.2.8, 5.2.8.2

optimizing for printing, 7.9

preventing conflicts, 5.2.8

purging cached, 8.5.1

reassigning to groups, 5.2.7.3.1

removing from groups, 5.2.7.4

resource use, 10.5

running, 5.2.6

searching for, 5.15.3

specifying page template, 7.8.2.2

types, 5.2.3.1

unlocking, 5.2.8, 5.2.8.3

pagination

reports, 5.5.4, 7.8.14.2.3, 7.8.14.3.5

Pagination Subtemplate

Next Page Template, 7.8.14.3.6

Next Set Template, 7.8.14.3.6

Pagination Template, 7.8.14.3.6

Previous Page Template, 7.8.14.3.6

Previous Set Template, 7.8.14.3.6

parent tabs

creating, 6.1

Parsing Schema attribute, 4.4.1.2.1 password

changing, 1.4.3.4, 15.1.1

resetting, 1.4.3.4, 8.2.2

resetting and emailing, 15.1.61

password policies

about, 22.4.5.4

configuring, 22.4.5.5

patch

creating, 12.5.3

performance tuning, 10.1 PL/SQL

running in background, 13.6

PL/SQL code

searching for, 5.15.6

PL/SQL editing

disabling for workspace, 8.6.1

PL/SQL Finder, 5.15 PL/SQL program unit editing

controlling, 22.4.1

Popup List of Values, 5.10.3.3 Popup LOV template

Application, 7.8.12.1.1

Buttons, 7.8.12.1.5

editing, 7.8.12

Icon, 7.8.12.1.3

Page Attributes, 7.8.12.1.9

Pagination, 7.8.12.1.7

Result Set, 7.8.12.1.8

Search Field, 7.8.12.1.4

Subscription, 7.8.12.1.2

Window, 7.8.12.1.6

preconfigured authentication schemes, 11.5.3

Application Express Account Credentials, 11.5.3, 11.5.3.1

Database Account Credentials, 11.5.3, 11.5.3.2

LDAP Credentials Verification, 11.5.3, 11.5.3.3

No Authentication (using DAD), 11.5.3, 11.5.3.5

Open Door Credentials, 11.5.3

Oracle Application Server Single Sign-On, 11.5.3

preferences

login controls, 8.6.2

PL/SQL editing, 8.6.1

purging for a specific user, 8.4.2.6

viewing for a specific user, 8.4.2.2

workspace, 8.6

primary navigation, 1.6 Print Mode Page Template attribute, 4.4.1.2.8 Printer Friendly mode, 2.3.7 Printer Friendly template, 7.9 printing

report regions, 5.5.13.6

reports, 5.5.13

procedure

browsing, 16.10.2

compiling, 16.10.4

creating, 16.10.1

downloading, 16.10.5

dropping, 16.10.6

editing, 16.10.3

editing manually, 16.10.3.1

finding, 16.10.2.1

Procedure Finder, 5.15.6 procedures

searching for, 5.15.6

process

Cache Management, 4.7.9.1

Data Manipulation, 4.7.9.1

Form Pagination, 4.7.9.1

implementing background PL/SQL, 13.6.3

On Demand, 4.7.9.1

PL/SQL, 4.7.9.1

Report Pagination, 4.7.9.1

Web Services, 4.7.9.1

programming techniques

collections, 13.4

database links, 13.2

implementing Web services, 13.7

running background PL/SQL, 13.6

Project page, 21.7.1 provisioning mode

specifying, 22.6.2

proxy server

defining, 13.7.1.2

Proxy Server attribute, 4.4.1.2.1 Public User attribute, 4.4.2.2.1 pull-down menu, 1.6

Q

query

searching for, 5.15.4

Query Builder, 17

about, 17.1

accessing, 17.1.1

Conditions tab, 17.4

creating joins automatically, 17.5.3

creating joins manually, 17.5.2

creating relationships between objects, 17.5

filtering objects, 17.2.1

hiding objects in Design Pane, 17.3.3

Object Selection pane, 17.2, 17.2.2

removing objects in Design Pane, 17.3.3

resizing panes, 17.3.2.1

Results tab, 17.8

Saved SQL tab, 17.6.2

saving queries, 17.6

searching for objects, 17.2.1

specifying query conditions, 17.4

supported column types, 17.3, 17.3.1

Table Actions, 17.5.3

View Actions, 17.5.3

viewing generated SQL, 17.7

viewing query results, 17.8

Query Finder, 5.15, 5.15.4

R

radio group, 5.10.3.3

generate, 15.3.12

Recycle Bin

purging, 20.5

searching, 20.5

using, 20.5

viewing objects, 20.5

Referenced Components

Next button, 4.6.7

Page field, 4.6.7

Previous button, 4.6.7

View list, 4.6.7

region

about, 4.7.4.2, 7.3.1

about types, 7.3.5

based on a URL, 7.6

controlling positioning, 7.3.3.2.1

copying, 7.3.6

creating, 7.3.4

customizing, 7.3

displaying conditionally, 7.3.3.2

editing attributes, 7.3.3.1

enabling customization, 7.3.3.4

specifying header and footer, 7.3.3.3

using Reorder Regions icon, 7.3.2

region attributes

Cache, 7.3.3.5

Column, 7.3.3.2

Condition Type, 7.3.3.2

Customization, 7.3.3.2

Display Point, 7.3.3.2

Expression, 7.3.3.2

Region Footer, 7.3.3.2

Region Header, 7.3.3.2

Region HTML table cell attributes, 7.3.3.2

Sequence, 7.3.3.2

Static ID, 7.3.3.6

Template, 7.3.3.2

region template

Comments, 7.8.13.1.5

Definition, 7.8.13.1.3

editing, 7.8.13

Form Table Attributes, 7.8.13.1.4

Name, 7.8.13.1.1

Subscription, 7.8.13.1.2

Substitution Strings, 7.8.13.1.6

region type

Calendar, 7.3.5, 7.3.5

Chart, 7.3.5

form, 7.3.5

Help Text, 7.3.5

HTML, 7.3.5

List, 7.3.5, 7.3.5, 7.3.5

PL/SQL Dynamic Content, 7.3.5

Report, 7.3.5

Tree, 7.3.5

URL, 7.3.5

regions

purging cahed, 8.5.2

REMOVE_SCHEMA_EXCEPTIONS, 22.5.2.3.2 Reorder icon, 4.7.3 report attributes

changing, 5.5.2

report column templates

colorizing cell headings, 7.8.14.2.4

omitting headings, 7.8.14.2.4

report column templates (generic)

After Rows, 7.8.14.2.8

Before Each Row, 7.8.14.2.5, 7.8.14.2.7

Before Rows, 7.8.14.2.3

Column Headings, 7.8.14.2.4

Column Templates, 7.8.14.2.6

displaying HTML after all columns, 7.8.14.2.7

displaying HTML after last row, 7.8.14.2.8

Next Page Template, 7.8.14.2.10

Next Set Template, 7.8.14.2.10

Pagination Subtemplate, 7.8.14.2.10, 7.8.14.2.10

Previous Page Template, 7.8.14.2.10

Previous Set Template, 7.8.14.2.10

Report Template, 7.8.14.2.1

Row Highlighting, 7.8.14.2.9

Template Subscription, 7.8.14.2.2

report column templates (named)

Before Rows attribute, 7.8.14.3.5

colorizing column header cell, 7.8.14.3.4

Column Headings, 7.8.14.3.4

Pagination Subtemplate, 7.8.14.3.6

Report Template Identification, 7.8.14.3.1

Row Templates, 7.8.14.3.3

Subscription, 7.8.14.3.2

report layouts

about, 5.5.13.5

copying, 5.5.13.5.4

creating, 5.5.13.5.2

editing, 5.5.13.5.3

options, 5.5.13.5.1

report printing

configuring, 22.4.8

report queries

about, 5.5.13.4

copying, 5.5.13.4.3

creating, 5.5.13.4.1

editing, 5.5.13.4.2

report region

printing, 5.5.13

report regions

about configuration options, 5.5.13.2

configuring print attributes, 5.5.13.7

printing, 5.5.13.6

printing methods, 5.5.13.3

printing to PDF, 5.5.13.1

report templates, 7.8.14

editing, 7.8.14

generic column templates, 7.8.14.1.1

named column templates, 7.8.14.1.2

using JavaScript, 7.8.14.4

reports, 7.8.4

about, 5.5

about an application, 4.13

Active Sessions, 8.17.4

adding download link, 5.5.6

Application Attributes, 22.11.1

Application Builder, 4.13

Application Changes by Application, 8.17.3

Application Changes by Developer, 8.17.2

Bulk Edit Item Help, 5.18.2.3

changing alignment, 5.5.2

changing column attributes, 5.5.2

changing column text, 5.5.2

changing pagination, 5.5.4

class references, 7.7.9.4

comparing user interface defaults, 9.3

controlling column breaks, 5.5.12

controlling column display, 5.5.11

creating a column link, 5.5.8

creating a sum of a column, reports

sorting columns, 5.5.2

creating updatable columns, 5.5.9 creating with a wizard, 5.5.1 CSV export, 7.8.14.2.5 Data Dictionary, 20.4.5 database objects, 20.4.5 defining a column as a list of values, 5.5.10 exception reports, 20.4.4 exporting, 5.5.7 exporting to CSV format, 7.8.14.2.3, 7.8.14.3.5 hiding columns, 5.5.2 including pagination above, 7.8.14.2.3, 7.8.14.3.5 monitor activity, 8.17 Parse as Schemas, 22.11.3 PL/SQL Source Code, 20.4.3.3 printing, 5.5.13 Program Unit Arguments, 20.4.3.1 schema, 8.14 sorting columns, 5.5.5 SQL, 5.5.1 supported substitution strings, 7.7.9.5 template subscription, 7.8.4 template utilization, 7.8.4 templates in a theme, 7.7.9.1 theme file references, 7.7.9.3 theme template counts, 7.7.9.2 themes, 7.7.9 Unit Line Counts report, 20.4.3.2 User Groups Assignments, 8.16.5.3 Wizard Report, 5.5.1 REQUEST

button names, 5.9.5

referencing value of, 3.6.2.20

substitution string, 3.6.2.20

resource use

monitoring, 10.5

restrict access

of application, 4.4.1.2.2

results, 18.2.1 Run Application icon, 4.3 Run Page icon, 4.3.1.1, 4.5.2.2.1 runtime settings

RESTRICT_IP_RANGE, 22.4.5.8

S

Sample Application, 2.1, 5.1.4.1

about, 2.3, 2.3

schema

associating with a workspace, 22.6.4.3

creating new, 22.6.4.4

determining for Application Express, 22.5.1

editing workspace assignment, 22.6.4.2

existing, 22.6.4.1

reports, 8.14

script files

exporting, 12.5.8

scripts

creating in editor, 18.3.1

deleting from editor, 18.5.2

deleting from SQL Scripts page, 18.5.1

executing, 18.7

executing from SQL Scripts page, 18.7.2

executing in editor, 18.7.1

export, 18.2.1

exporting, 18.9

importing, 18.9

results, 18.2.1

SQL Script editor, 18.4

uploading to another account, 18.2.1

uploading to SQL Scripts, 18.3.2

viewing repository quotas, 18.10

SDLC, 12.1

rapid application development, 12.1.1

Spiral, 12.1.1

waterfall, 12.1

secondary navigation, 1.6 Secure Sockets Layer (SSL), 22.4.7 security

attributes, 4.4.2

for pages, 4.8.2.6

security attributes

authentication, 4.4.2.2.1

Authentication Scheme, 4.4.2.2.1

Authorization Scheme, 4.4.2.2.2

Database Schema, 4.4.2.2.3

Home Link, 4.4.2.2.1

Login URL, 4.4.2.2.1

Public User, 4.4.2.2.1

Session State Protection, 4.4.2.2.4

Security reports

Column Privileges report, 20.4.2

security risks

file upload table, 11.4

security settings

configuring password policies, 22.4.5.5

disabling access to Administration Services, 22.4.5.6

disabling access to Internal, 22.4.5.7

disabling cookies to populate login form, 22.4.5.1

enabling login controls, 22.4.5.3

excluding domains, 22.4.5.2

exluding URL regions, 22.4.5.2

restricting by IP address, 22.4.5.8

seeding, 14.3.2 select lists, 5.10.3.3

creating dependent list of values, 5.13

sequence

altering, 16.7.2.1

browsing, 16.7.2

creating, 16.7.1

dependent objects, 16.7.2.1

dropping, 16.7.3

grants associated with, 16.7.2.1

service

terminating, 8.11

services

viewing overview, 8.10

session

cookies, 15.5.4

ID, 3.3.2

killing, 20.8.1.1

purging by age, 8.4.1.4

session ID

facilitating bookmarking, 3.5.5

Session report, 20.8.1.1 session state

clearing, 3.4.3

clearing application cache, 3.4.3.3

clearing cache by item, 3.4.3.1

clearing cache by page, 3.4.3.2

clearing cache for current user session, 3.4.3.4

clearing cache for two pages, 3.4.3.2.1

enabling projection, 4.4.2.2.4

fetching for current application, 15.1.21

management, 3.3

managing, 8.4, 22.3.3

passing item value, 3.4.3.2.2

protection, 11.3

purging current session, 8.4.1.3

referencing, 3.4.1

removing, 8.4.1.1

removing for current page, 15.1.9

removing for current session, 15.1.8

setting, 3.4.2, 15.1.71

viewing, 3.3.3

viewing session details, 8.4.1.1

session state protection

configuring all attributes, 11.3.3.2

configuring security attributes, 11.3.3

disabling, 11.3.2

enabling, 11.3.2

enabling from Edit Security Attributes, 11.3.2.1

enabling from Session State Protection, 11.3.2.2

enabling using a wizard, 11.3.2.2

reports, 11.3.3.1

understanding, 11.3.1

viewing existing settings, 11.3.3.1

viewing summaries, 11.3.3.1

Session State Protection attribute, 4.4.2.2.4 session state values

managing, 3.4

shared components

about, 4.7.6, 4.10.2

accessing, 4.10.1

accessing reports, 4.10.4

backing up, 12.5.3

Breadcrumbs, 4.7.6.3

creating, 4.10.1

exporting, 4.10.3, 12.5.3

icon, 4.3

list of values, 4.7.6.2

Lists, 4.7.6.4

Lists of Values, 4.7.6.2

Navigation Bar, 4.7.6.8

Security, 4.7.6.7

Shared Components page, 4.10

Tabs, 4.7.6.1

Templates, 4.7.6.6

Theme, 4.7.6.5

Shared Components icon, 4.3.1.3, 4.5.2.2.2 Shared Components page

Application Computations, 4.10.2.2.3

Application Items, 4.10.2.2.1, 4.10.2.2.4

Application Processes, 4.10.2.2.2, 4.11

Authentication Schemes, 4.10.2.3.1

Authorization Schemes, 4.10.2.3.2

Breadcrumbs, 4.10.2.5.3

Build Options, 4.10.2.2.5

Cascading Style Sheets, 4.10.2.8.1

Comments, 4.10.2.1.2

Definition, 4.10.2.1.1

Edit Attributes, 4.10.2.4.3

Edit Security Attributes, 4.10.2.3.4

Images, 4.10.2.8.2

Lists, 4.10.2.5.2

Lists of Values, 4.10.2.6.4

Navigation Bar Entries, 4.10.2.5.5

Report Layouts, 4.10.2.7.2

Report Queries, 4.10.2.7.1

Session State Protection, 4.10.2.3.3

Shortcuts, 4.10.2.6.5

Static Files, 4.10.2.8.3

Tabs, 4.10.2.5.1

Templates, 4.10.2.6.2

Test Messages, 4.10.2.4.2

Themes, 4.10.2.6.1

Translate Application, 4.10.2.4.1

Trees, 4.10.2.5.4

User Interface Defaults, 4.10.2.6.3

Web Service References, 4.10.2.2.4

Shortcut page, 5.14.2.1 shortcuts, 5.14

defining, 5.14.2

editing attributes, 5.14.3

HTML Text, 5.14.1

HTML Text with Escaped Special Characters, 5.14.1

Image, 5.14.1

Message, 5.14.1

Message with JavaScript Escaped Special Quotes, 5.14.1

PL/SQL Function Body, 5.14.1

reports, 5.14.4

Shortcut History, 5.14.4.2

Shortcut page, 5.14.2.1

Subscribed Shortcuts, 5.14.4.1

supporting translatable messages, 14.1.4.1

Text with JavaScript Escaped Single Quotes, 5.14.1

types, 5.14.1

Show Page, 3.2.1 shuttle multiple select list, 5.10.3.3 site-specific tasks lists, 22.3.1

adding a task, 22.3.1.1

deleting a task, 22.3.1.3

editing a task, 22.3.1.2

SOAP, 13.7 special characters

encoding, 15.1.78

spreadsheets

importing, 20.2.2.2

SQL Commands

command termination, 19.4.4

Explain Plan, running, 19.10, 19.10.2

home page, 19.3

transaction support, 19.4.2

SQL report, 5.5.1, 20.8.1.5 SQL Scripts

accessing, 18.2

creating script in editor, 18.3.1

deleting script from editor, 18.5.2

deleting script from SQL Scripts home page, 18.5.1

executing script from SQL Scripts page, 18.7.2

executing script in editor, 18.7.1

exporting scripts, 18.9

importing scripts, 18.9

script editor, 18.4

SQL Scripts page, 18.2.1

uploading script, 18.3.2

viewing quotas, 18.10

viewing script results, 18.8.1

SQL Scripts page

accessing Manage Script Results, 18.2.1

Show Quotas, 18.2.1

Task list, 18.2.1

SQL Scripts page Task list

export scripts, 18.2.1

uploading scripts, 18.2.1

SQL tracing

enabling, 10.4

SQL Workshop

configuring, 22.4.3

deleting logs, 22.3.2.1

SQL*Plus command support, 19.4.3 SQL*Plus commands

unsupported, 19.4.3

SSL-enabled URLs, 22.4.7 standard tabs

creating, 6.1

Static File Repository, 7.12, 7.12.1 static files

deleting, 7.12.4

downloading, 7.12.3

editing, 7.12.2

exporting, 12.5.7, 12.5.7

importing, 12.6.3

importing into another instance, 12.5.7

managing, 7.12

uploading, 7.12.1

static substitution string, 4.4.1.2.4 Status attribute, 4.4.1.2.2 style sheet, 7.8.1 substitution strings

#COLCOUNT#, 7.8.14.2.5

#CSV_LINK#, 7.8.14.2.3, 7.8.14.3.5

#GLOBAL_NOTIFICATION#, 4.4.1.2.3

#HIGHLIGHT_ROW#, 7.8.14.2.5

#IMAGE_PREFIX#, 7.11.2

#ROWNUM#, 7.8.14.2.5

about built-in, 3.6.2

APP_ALIAS, 3.6.2.1

APP_ID, 3.6.2.2

APP_IMAGES, 3.6.2.3

APP_PAGE_ID, 3.6.2.4

APP_SESSION, 3.6.2.5

APP_UNIQUE_PAGE_ID, 3.6.2.6

APP_USER, 3.6.2.7

Application Express SCHEMA OWNER, 3.6.2.15

AUTHENTICATED_URL_PREFIX, 3.6.2.8

BROWSER_LANGUAGE, 3.6.2.9

calendar, 5.7.1.1

CURRENT_PARENT_TAB_TEXT, 3.6.2.10

DEBUG, 3.6.2.11

IMAGE_PREFIX, 3.6.2.14

in page templates, 7.8.11

LOGOUT_URL, 3.6.2.17

PRINTER_FRIENDLY, 3.6.2.16

PROXY SERVER, 3.6.2.18

PUBLIC_URL_PREFIX, 3.6.2.19

report of supported, 7.7.9.5

REQUEST, 3.6.2.20

SQLERRM, 3.6.2.21

static, 4.4.1.2.4

supported in region footer, 7.3.3.3

SYSDATE_YYYYMMDD, 3.6.2.22

understanding, 3.6

usage within templates, 3.6.1.1

using, 3.6.1

WORKSPACE_IMAGES, 3.6.2.23

sums

creating in reports, 5.5.2

supporting objects

creating, 12.4.2

deinstalling, 12.4.8

SVG chart

about types, 5.8.4.3

adding to existing page, 5.8.4.1

adding to new page, 5.8.4.2

CSS classes, 5.8.4.4

migrating all to Flash, 5.8.5.3.3

migrating to Flash, 5.8.5.3.2

migration restrictions, 5.8.5.3.1

referencing CSS styles inline, 5.8.4.6

referencing custom CSS, 5.8.4.5

SVG plug-in, 5.8.1.2 synonym

creating, 16.15.1

dropping, 16.15.3

viewing, 16.15.2

system message

creating, 22.4.10.2

disabling, 22.4.10.2

T

tab

adding, 6.1

creating, 6.1.4, 6.1.5

editing, 6.1.6

editing multiple, 6.1.6.1

managing, 6.1.4

Reorder Tabs icon, 6.1.3

reports, 6.1.7

template support, 6.1.1

tab reports

History, 6.1.7

Utilization, 6.1.7

tab-delimited file

loading, 20.2.2.1

Table Finder, 5.15, 5.15.5 tables

add column, 16.4.3

browsing, 16.4.2

constraints, 16.4.2.1

copy, 16.4.3

creating, 16.4.1

drop column, 16.4.3

dropping, 16.4.4

editing, 16.4.3

exporting user interface defaults, 9.4

exports data to spreadsheet, 16.4.2.1

forcing close of HTML table, 5.10.3.3

grants on, 16.4.2.1

indexes associated, 16.4.2.1

insert row, 16.4.2.1

modify column, 16.4.3

remove all rows, 16.4.3

rename, 16.4.3

rename column, 16.4.3

report of number of rows, 16.4.2.1

searching for, 5.15.5

sort by column, 16.4.2.1

statistics about, 16.4.2.1

user interface defaults, 16.4.2.1

viewing data, 16.4.2.1

tablespaces

Oracle-managed files, 22.6.1

tabs

about, 6.1.2

Tabs page, 6.1.4 tabular form

creating, 5.6.2

Template Defaults, 4.4.1.2.8 template edit history, 7.8.4 templates

application defaults, 4.4.1.2.8

breadcrumbs, 7.8.6

button, 7.8.7

carlendar, 7.8.8

changing defaults, 7.7.2

columns, 7.8.14.2.6, 7.8.14.4

creating, 7.8.3

customizing, 7.8

editing, 7.8.5

labels, 7.8.9

lists, 7.8.10

page, 7.8.11

popup LOV, 7.8.12

regions, 7.8.13

reports, 7.8.14

selecting for a page, 7.8.2.2

selecting theme default, 7.8.2.1

supported substitution strings, 7.7.9.5

viewing, 7.8.5.1

viewing reports, 7.8.4

wizard defaults, 4.4.1.2.9

text, 5.10.3.3 text area, 5.10.3.3 Text Data Load Repository, 20.2.4 text file

loading, 20.2.2.1

text strings

translating, 14.4, 14.4.1, 14.4.2

theme

Themes page, 7.7.3.1

Theme attribute, 4.4.1.2.7 theme reports

class references, 7.7.9.4

files references, 7.7.9.3

supported substitution strings, 7.7.9.5

template counts, 7.7.9.2

templates in a theme, 7.7.9.1

themes

changing identification number (ID), 7.7.8

copying, 7.7.5

creating, 7.7.3

default templates, 7.7.2

deleting, 7.7.6

exporting, 7.7.7, 12.5.9

exporting with different ID, 7.7.8

importing, 7.7.7, 12.6.5

managing, 7.7

reports, 7.7.9

selecting page-level template, 7.8.2.1

switching, 7.7.4

Themes page, 7.7.1

Themes page, 7.7.3.1

accessing from Page Definition, 7.7.1

accessing from Shared Components, 7.7.1

toolbar, 4.9 transaction support, 19.4.2 translatable messages

defining, 14.4.1

translation, 14.1

applications, 14.1

dynamic, 14.5

dynamic text strings, 14.1.4.1

dynamic translations, 14.1.4.3

editing manually, 14.3.5

export options, 14.3.2.2.4

exporting text, 14.3.2

globalization support, 14.1

language identification, 14.1.1

mapping primary application ID, 14.3.1

mapping target application ID, 14.3.1

messages, 14.1.4.1, 14.1.4.2

region titles, 14.1.4.4

rules, 14.1.2, 14.1.2

seeding, 14.3.2

shortcuts, 14.1.4.1, 14.1.4.1

steps, 14.3

templates, 14.1.4.5

translatable components, 14.1.4

translation file, 14.3.2.2

understanding, 14.3

understanding application rendering, 14.1.3

viewing installed, 22.3.5

XLIFF, 14.3.2.2

XLIFF Target Elements, 14.3.2.2.3

translation file, 14.3.2.2

uploading and publishing, 14.3.4

tree

creating, 6.4

editing, 6.4.2

reports, 6.4.3

Trees page, 6.4.2

tree reports

History, 6.4.3

Utilization, 6.4.3

Trees page, 6.4.2 trigger

browsing, 16.12.2

compiling, 16.12.4

creating, 16.12.1

downloading, 16.12.5

dropping, 16.12.6

editing, 16.12.3

type

browsing, 16.8.2

creating, 16.8.1

dropping, 16.8.3

grants associated with, 16.8.2.1

list of synonyms, 16.8.2.1

U

UDDI registry, 13.7.3

Unload to Text Wizard, 20.2.3.1

Unload to XML Wizard, 20.2.3.2

URL

publishing, 12.8

SSL-enabled, 7.6

syntax, 3.5

url

zero as session ID, 3.5.5

user

get e-mail address, 15.1.30

remove preference, 15.1.57

user access

restricting by IP address, 22.4.5.8

user account

altering, 15.1.16

creating, 22.9.1

creating new, 15.1.13

deleting, 22.9.3

editing, 22.9.2

fetching, 15.1.22

removing, 15.1.59

update email address, 15.1.67

updating FIRST_NAME, 15.1.68

updating LAST_NAME value, 15.1.69

updating USER_NAME value, 15.1.72

user accounts

controlling account availability, 22.9.1

requiring password change, 22.9.1

user identity

establishing, 11.5

verifying, 3.2.3

user interface

about, 1.1

controlling, 7

navigation options, 1.6

User Interface Defaults

importing, 12.6.6

user interface defaults, 5.1.2.2

column definition, 9.2

comparing, 9.3

exporting, 12.5.10

leveraging, 5.1.2.3

reports, 9.2.1.2

user preferences

managing, 8.4, 8.4.2.1

purging, 8.4.2.6

removing programatically, 8.4.2.4

report, 8.4.2.2

resetting using a page process, 8.4.2.5

setting, 8.4.2.3

viewing, 8.4.2.2

user roles

developer, 1.3, 8.1, 22.1

Oracle Application Express administrator, 8.1, 22.1

Workspace administrator, 8.1

Workspace administrators, 22.1

Utilities

Data Dictionary, 20.4.5

utilities

about, 20

comparing schemas, 20

generating DDL, 20

loading data, 20

monitoring the database, 20

restoring dropped objects, 20

unloading data, 20

viewing database details, 20

viewing object reports, 20

V

validations

about, 4.7.8

defining error messages, 4.7.8.2

making conditional, 4.7.8.3

When Button Pressed attribute, 3.6.2.20.3

variables

global, 15.4

Version attribute, 4.4.1.2.1 view

browsing, 16.5.2

compiling, 16.5.4

creating, 16.5.1

dropping, 16.5.5

editing, 16.5.3

grants associated with, 16.5.2.1

objects referenced by, 16.5.2.1

report of data, 16.5.2.1

user interface defaults, 16.5.2.1

View list

configuring defaults, 4.2.1

Virtual Private Database attribute, 4.4.2.2.5

W

Waits report, 20.8.1.3

wallet

configuring, 22.4.7

Web service process

editing a process, 13.7.10

mapping input parameters to static values, 13.7.10

Web service reference, 13.7.1

creating, 13.7.3

creating forms, 13.7.8

creating forms and reports, 13.7.7

creating manually, 13.7.3.3, 13.7.6

invoking as a process, 13.7.9

searching UDDI registry, 13.7.3.1

specifying WSDL, 13.7.3.2

viewing a history, 13.7.11

Web Service Reference Page, 13.7.1.1 Web services, 13.7

specifying proxy server address, 13.7.1.2

SSL enabled, 13.7.2

utilizing, 13.7.1

Web Services References page, 13.7.1.1

Wizard Report, 5.5.1 wizards

copying and pasting tab-delimited data, 20.2.2.1

Create Page, 5.2.1

creating a branch, 6.6

creating a breadcrumb, 6.3.2.2

creating a button, 5.9.2

creating a calendar, 5.7

creating a chart, 5.8

creating a list, 6.2.1

creating a LOV, 5.12.1

creating a new component, 5.2.4, 5.16.2.3

creating a page computation, 4.7.7.1, 13.7.9

creating a page process, 4.7.9.1

creating a region, 7.3.4

creating a workspace, 22.6.3

creating an application, 5.1, 5.1.1

creating navigation bar entry, 6.5.2

creating reports, 5.5.1

creating validations, 4.7.8.1, 5.6.5.1

exporting contents of table, 20.2.3.1

exporting text file, 20.2.3.1

exporting XML, 20.2.3.2

importing text, 20.2.2.1

importing XML, 20.2.2.3

workspace

administration, 22

creating manually, 22.6.3

creating new tablespaces, 22.6.1

deleting, 22.10.5

export file, 15.1.20

exporting and importing, 22.10.7

locking, 22.10.6

logging in, 1.4.3.2

logging out, 1.4.3.5

login controls, 8.6.2

managing, 8

numeric security group ID, 15.1.23

preferences, 8.6

provisioning, 22.6

requesting, 1.4.3.1

size options for requests, 22.4.9

specifying a provisioning mode, 22.6.2

utilization, 22.8.2

viewing, 22.10.1

Workspace administrator, 1.3, 8, 8.1

requesting a database schema, 8.12

requesting additional storage, 8.13

requesting service termination, 8.11

viewing schema reports, 8.14

viewing workspace overview, 8.10

Workspace home page

about, 1.5

Links list, 1.5

Migrations, 1.5

Workspace Schemas list, 1.5

workspace report

applications, 8.10

developers, 8.10

schemas utilizing space, 8.10

space used, 8.10

storage space, 8.10

workspace requests

approving, 22.7.3

changing, 22.7.4

configuring size options, 22.4.9

managing, 22.7

Workspace Requests page, 22.7.2 workspaces

deleting inactive, 22.10.4.3

identifying inactive, 22.10.4.1

purging, 22.10.4

removing resources, 22.10.4.2

WSDL document, 13.7.1

X

XLIFF, 14.3.2.2

applying, 14.3.4.2

deleting an uploaded document, 14.3.4.3

Target Elements, 14.3.2.2.3

uploading, 14.3.4.1

uploading and publishing, 14.3.4

XML document

exporting to, 20.2.3.2

loading, 20.2.2.3

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2014, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.