1 Quick Start

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

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
Using Online Help

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 and standard SQL bind variable syntax.

To learn more about Oracle Application Express, click the Learn more... button on the Workspace home page. The Learn Application Express page appears.

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 Application Express Listener, 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 Application Express Listener or Oracle HTTP Server (Apache) with mod_plsql. The following graphic illustrates the three-tier architecture.

Description of the illustration arch.gif

With Oracle Database 11.1 or later or Oracle Database 10g Express Edition, you can use the embedded PL/SQL gateway. The following graphic illustrates the two-tier architecture using the embedded PL/SQL gateway.

Description of the illustration arch_epg.gif

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

Different Oracle Application Express Environments

When you install Oracle Application Express, you can install two different environments:

A runtime environment is the appropriate choice for production implementations in which users can run applications that cannot be modified.
A full development environment provides complete access to the Application Builder environment to develop applications as described in this document.

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.
Instance administrators are superusers that manage an entire hosted instance using the Application Express Administration Services application

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 must 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:

About Browser Requirements
Configuring Your Oracle Application Express Environment
Logging In to Oracle Application Express as a Developer

About Browser Requirements

To view or develop Oracle Application Express applications, Web browsers must support Java Script and the HTML 4.0 and CSS 1.0 standards. The following browsers are required to develop applications in Oracle Application Express:

Microsoft Internet Explorer 7.0 or later version
Mozilla Firefox 3.5 or later version
Google Chrome 4.0 or later version
Apple Safari 4.0 or later version

Application Express applications can be developed that support earlier Web browser versions, including Microsoft Explorer 6.0.

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:

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. You log in using the ADMIN account and password created or reset during the installation process.
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. See "Verifying the Oracle XML DB HTTP Server Port".
    
    apex is the database access descriptor (DAD) defined in the configuration file.
  - If your setup uses the Oracle Application Express Listener, go to:
```
http://hostname:port/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 8888. See the Oracle Application Express Listener documentation.
    
    apex is the database access descriptor (DAD) defined in the configuration file.
  - 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.
    
    pls is the indicator to use the mod_plsql cartridge.
    
    apex is the database access descriptor (DAD) defined in the mod_plsql configuration file.
2. On the Login page:
  - In Username, enter admin.
  - In Password, enter the Oracle Application Express administrator account password you specified when you installed Oracle Application Express.
  - Click Login.
See Also:
See "Logging in to Oracle Application Express Administration Services" in Oracle Application Express Administration Guide.
Specify a provisioning mode. In Oracle Application Express Administration Services you must determine how the process of creating (or provisioning) a workspace will work. See "About Workspace Provisioning" in Oracle Application Express Administration Guide.
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" in Oracle Application Express Administration Guide.
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".

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"in Oracle Application Express Administration Guide

Topics:

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.

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:

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.
Under Workspace, click Request a Workspace.

The Request Service Wizard appears.
Click Next and follow the on-screen instructions.

See Also:
"Creating Workspaces" in Oracle Application Express Administration Guide

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.

To log in to Oracle Application Express:

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. See "Verifying the Oracle XML DB HTTP Server Port".
  - 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 the Oracle Application Express Listener, go to:
```
http://hostname:port/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 8888. See the Oracle Application Express Listener documentation.
  - 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
```
    Be aware that if you change a port number, it is not updated in the portlist.ini file. You can only rely on this file immediately after installation.
  - 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.
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.
Click Login.

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

Verifying the Oracle XML DB HTTP Server Port

To verify the port number where the Oracle XML DB HTTP Server is running:

Start SQL*Plus and connect the database where Oracle Application Express is installed as SYS:
- On Windows:
```
SYSTEM_DRIVE:\ sqlplus /nolog
connect sys as sysdba
```
- On UNIX and Linux:
```
$ sqlplus /nolog
connect sys as sysdba
```
When prompted, enter the appropriate username and password.
Enter the following statement to verify the port number:
```
SELECT DBMS_XDB.GETHTTPPORT FROM DUAL;
```
If the port number returns 0, the Oracle XML DB HTTP Server is disabled.

See Also:

Oracle Database Installation Guide to learn how to enable the Oracle XML DB HTTP Server

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:

On the Login page, click Find My Workspace on the Tasks list.
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:

Log in to Oracle Application Express. See "Logging In to Oracle Application Express".
From the Administration list, click Change Password.

The Change Password page appears.
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.
Click Apply Changes.

Tip:

You can also reset your password on the Login page by clicking the Reset Password link.

See Also:

"Changing an End User Password" in Oracle Application Express Administration Guide

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. Note that your user name and workspace name display in the lower left corner of the page.

Description of the illustration wrkspc_home.gif

The following 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. See Oracle Application Express SQL Workshop Guide.
Team Development. Use Team Development to track new features, non-feature related tasks (or To Do tasks), bugs, and milestones. Users can also provide real-time feedback which then can be categorized into features, general tasks, or bugs. See "Managing the Development Process".
Admin istration links to the Workspace Administration page. See "Workspace and Application Administration" in Oracle Application Express Administration Guide.

About Learn More

Click the Learn More button to view an informative introduction to Oracle Application Express. Topics covered include architecture, self service, security, websheets, application development, SQL Workshop, Team Development, administration, and managing development.

About the System Message and News Regions

Description of wrkspc_home_news.gif follows

Description of the illustration wrkspc_home_news.gif

The system message displays at the top of the page. The News region displays in the center of the page. Use these regions to communicate with other users in the workspace. To learn more, see "Defining a System Message" in Oracle Application Express Administration Guide and "Managing News Entries".

About Top Applications, Top Users, and Team Development

The Top Applications, Top Users, and Team Development dashboards display at the bottom on the page. These regions offer real time information about development activities in the workspace.

Your user name and workspace name display in the lower left corner of the page.

About Search Workspace

Description of the illustration hlp_ico.gif

The Search Workspace field displays in the upper right corner of the page. Use this field to search for application names, application ID and page, workspace images, workspace theme names, and other workspace components. By default, this field is case sensitive and supports regular expressions.

For example, to navigate to a specific application and page use the following formats:

page
application_ID:page
application_ID-page

Where:

application_ID is the numeric identification number (or ID) that identifies an application.
page is the numeric identification number that identifies a specific page.

Consider the following examples:

10
570-10
570:10

About Available Updates

This region displays whether a newer version of Oracle Application Express or Oracle Application Express Listener is available.

To disable this feature, click the Edit icon. From Check for Available Updates, select No and click Apply Changes.

About Language

Displays the default language for this Oracle Application Express instance.

About Set Screen Reader Mode

Use the Set Screen Reader Mode flag to identify if a page optimized for screen readers. This flag toggles between Set Screen Reader Mode On and Set Screen Reader Mode Off. To learn more, see "Accessibility in Oracle Application Express" in Oracle Application Express Installation Guide and the accessible mode functions described in Oracle Application Express API Reference.

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.

Description of the illustration hlp_ico.gif

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.

Description of the illustration help_window.gif

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.