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
Displaying Components on Every Page of an Application
Customizing Regions
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
Creating a Multiple Column Layout
Rendering HTML Using Custom PL/SQL

See Also:

"Adding Navigation" for information about creating navigation bars, tabs, breadcrumbs, lists, and trees

Understanding Page Layout

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 templates 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 will be substituted with the appropriate components at run time.

As a developer, you add content on 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:

Create a new page.
Specify the page ID as zero (0).

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

Creating a Region
How Region Attributes Affect Page Layout

Creating a Region

You create new regions by running the Create Region Wizard.

To create a new region:

Navigate to the appropriate Page Definition:
1. Navigate to the Database Home Page.
2. Click the Application Builder icon.
3. Select an application.
4. Select a page.
  
  The Page Definition appears.
Under Regions, click the Create icon.

The Create Region Wizard appears.
Select a region type and follow the on-screen instructions.

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-1 describes the available region types.

Table 7-1 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 contain 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 an 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 monthly 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 Application Developer's Guide - Fundamentals for information about developing Web applications with PL/SQL
Oracle Database PL/SQL Packages and Types Reference for information about htp packages

How Region Attributes Affect Page Layout

You can alter the appearance of a page by changing the region attributes.

To edit region attributes:

Navigate to the appropriate Page Definition:
1. Navigate to the Database Home Page.
2. Click the Application Builder icon.
3. Select an application.
4. Select a page.
  
  The Page Definition appears.
Under Regions, select the region name.

The Region Definition appears.

Table 7-2 describes region attributes that affect the layout of a page.

Table 7-2 Region Attributes Affecting Page Layout

Attribute	Description
Conditions	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"
Header and Footer	Specifies HTML text to be displayed at the top of the region (just before the `#BODY#` content).
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"
User Interface, Column	Determines the column in which 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.
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 within the page the region displays. 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.

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 cab 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# displays 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:

Navigate to the appropriate Page Definition:
1. Navigate to the Database Home Page.
2. Click the Application Builder icon.
3. Select an application.
4. Select a page.
  
  The Page Definition appears.
Under Regions, click the region name.

The Region Definition appears.
Scroll down to Customization and select one of the following:
- Customizable and Not Shown By Default
- Customizable and Shown By Default
In Customized Option Name, enter the label that represents this region on the page to the user.
Include the #CUSTOMIZE# substitution string in the Header, Body, or Footer section of the page template.

To utilize 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 displays enabling them to turn on and off regions on the page.

See Also:

"Customizing Templates"

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:

"Creating Items"

To edit item attributes:

Navigate to the Page Definition:
1. Navigate to the Database Home Page.
2. Click the Application Builder icon.
3. Select an application.
4. Select a page.
  
  The Page Definition appears.
Under Items, click the item name.

The Item Definition 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 in which items are rendered within a region.
Displayed	Region	Defines the region in which the item displays. All items must be in a region.
Displayed	Begin On New Line	Determines if this item displays on the same line as the previous item or if it displays on the next line.
Displayed	Begin On New 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 in which that the item displays.
Label	Label	Enter 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"`).
Label	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 will display 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 a 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 will 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 Also:

"Configuring Standard Application Attributes" for information about setting the Proxy Server application attribute

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 (button, calendar, label, list, breadcrumb, page, popup LOV, 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 Default Templates in a Theme
Creating a New Theme
Switching an 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.

To access the Themes page from Shared Components:

On the Database Home Page, click the Application Builder icon.
Select an application.
Click Shared Components.
Under User Interface, select Themes.

The Themes page appears.
To access the Details view, select Details from the View list.

The currently selected theme displays a check mark in the current column.

To access the Themes page from the Page Definition:

On the Database Home Page, click the Application Builder icon.
Select an application.
Select a page.

The Page Definition appears.
Select the theme name.

About the Themes Page

Once you create a theme, it appears on the Themes page. You control how the page displays by selecting the following options from the View list:

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 Display list:
- Summary View displays the theme ID, name, and current status.
- Detailed View displays the theme ID, name, current status, and the number of templates in each template type.

Changing Default Templates in a Theme

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 Define Theme page.

You can override these defaults, by either 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:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
Access the Details view. From the View list, select Details.
Select the appropriate theme name.

Create/Edit Theme page appears.

The top of the page displays the associated application ID and the Theme Identification Number.
To change the theme name, enter a new name in the Name field.
To change a default template, make a new selection from the appropriate list.

Table 7-4 describes the default templates available under the section Default Templates by Component.

Table 7-4 Default Templates by Component

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 Application Attributes 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	Optional. 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 Application Attributes 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. When calling Application Express to render a page, you have the option to identify a printer friendly attribute with values of YES or NO. If you select `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#` tags. The objective is to be able to display information with few tables and in a format suitable for printing. Once defined, this default template appears on the Edit Application Attributes page under the heading Application Template Defaults. See Also: "Optimizing a Page for Printing"
Breadcrumb	Identifies the default breadcrumb template used when you create new breadcrumb.
Button	Identifies the default button template used when creating a new button.
Calendar	Specifies the default calendar template used when you create new calendar.
Label	Identifies the default label template used when you create new label.
List	Specifies the default list template used when you create new list.
Region	Specifies the default region template used when you create new region.
Report	Identifies the default region template used when you create a report.

Table 7-5 describes the default templates available under the section Default Templates by Region Type.

Table 7-5 Region Templates by Region Type

Attribute	Description
Breadcrumbs	Default region template used when creating a breadcrumb.
Charts	Default chart template used when creating a chart.
Forms	Default form template used when creating a form.
Lists	Default region template used when creating a list.
Reports	Default region template used when creating a report.
Tabular Forms	Default region template used when creating a tabular form.
Wizards	Default region template used when creating a new 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:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
Click Create.
Specify whether to select a theme from the repository, or create a theme from scratch.
If you select From Repository:
1. Select a theme from the repository.
2. Click Create.
If you select From Scratch:
1. Specify a name.
2. Click Create.
  
  Themes page appears.
3. Define the default templates for the new theme:
  - Click the Edit icon adjacent to the new theme name.
  - To change the theme name, enter a new name in the Name field.
  - When the Define Theme page appears, select default templates for the new theme.

Switching an Active Theme

When you switch to a new theme, all components that are assigned a template 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 another theme already exists.

To apply a theme to an application:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
Click Switch Theme.

The Switch Theme page appears.
From the Switch to Theme list, select a new theme and click Next.
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.
Click Next to continue.
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:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
On the Tasks list, click Copy Theme.
On Copy Theme:
1. Copy From Theme - Select the theme you want to copy.
2. Copy to this Theme Identification Number - Enter a new ID for the theme.
3. Click Next.
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:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
On the Tasks list, click Delete Theme.
From Remove Theme, select the theme you want to delete and click Next.
Click Remove Theme.

About Exporting and Importing Themes

You export a theme in the same way you export any related application file. Exporting a theme from one development instance to another involves the following steps:

Export the theme using the Export Theme utility.
Import the exported file into the target Oracle Application Express instance.
Install the exported file from the Export Repository.

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

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
On the Tasks list, click Change Identification Number.
On the Change Theme ID page:
1. Select a theme.
2. Specify a new identification number.
3. Click Next.
4. 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:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
Click Reports.
On the Theme Reports page:
1. From Report, select Application Templates.
2. From Theme, select a theme.
3. Click Go.
A listing of templates displays listing the template type, template name, the associated theme, and template class.
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:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
Click Reports.
On the Theme Reports page:
1. From Report, select Theme Template Counts.
2. From Theme, select a theme.
3. Click Go.
If you are using custom classifications, select Show Custom and click Go.

Viewing File References

The File References report displays a listing of all files associated with templates, shared components, or page components in the current application.

To view the File References report:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
On the Themes page, click Reports.
On the Theme Reports page:
1. From Report, select File References.
2. From Theme, select a theme.
3. Click Go.
On the File References page:
1. From Show, select the type of component to include in the report. If you do not make a selection, no results are returned.
2. 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 ID. Select the page ID to link to a Page Definition.
  - Without context displays only the file name and the image (if applicable).
3. From File Extensions, select the type of extensions for which to search.
4. Click Go.
To download a comma-delimited file (.csv) version of this report, click Download CSV at the bottom of the page.

Viewing Class References

Accessing the Class References report displays a listing of classes associated with templates, shared components, or page components in the current application.

To view the Class References report:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
Click Reports.
On the Theme Reports page:
1. From Report, select Class References.
2. From Theme, select a theme.
3. Click Go.
On the Class References page:
1. From Show, select the components to check for a class reference. If you do not make a selection, no results are returned.
2. 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 ID.
  - Without context displays only the referenced class.
3. Click Go.
To download a comma-delimited file (.csv) version of this report, click Download CSV 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:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Themes.
Click Reports.
On the Theme Reports page:
1. From the Report list, select Template Substitution Strings.
2. From the Theme list, select which themes to include in the report.
3. Click Go.
To link to a template definition, select the component name.

See Also:

"Using 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 simplest 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
Viewing Templates
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 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.

Selecting a Page-level Template Within a Theme

To specify a default page template within a theme:

On the Database Home Page, click the Application Builder icon.
Select an application.
Click Shared Components.
Under User Interface, select Themes.

The Themes page appears.
Change the View. From View, select Details.
In the Themes list, select the theme name.
Under Default Templates by Component, make a selection from the Page list.

See Also:

"Changing Default Templates in a Theme"

Selecting a Page-level Template for a Specific Page

To specify an page-level template for a specific page:

On the Database Home Page, click the Application Builder icon.
Select an application.
Select a page.
Click Edit Attributes.
Locate the section Primary Display Attributes.
Make a selection from the Page Template list.

Viewing Templates

You can view all available templates on the Templates page. Alternatively, you can view the templates used on a specific page on the Page Definition.

See Also:

"Viewing All Templates in a Theme"

Viewing Templates on the Templates Page

To view existing templates:

On the Database Home Page, click the Application Builder icon.
Select an application.
Click Shared Components.
Under User Interface, select Templates.

The Templates page appears.
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.
To view a template definition, click the template name.
To see a preview of a template, click the Run icon in the Preview column.

Note:

Not all template types have the preview capability.

Viewing Templates from the Page Definition

To view existing templates from the Page Definition:

On the Database Home Page, click the Application Builder icon.
Select an application.
Select a page.

The Page Definition appears. Templates associated with the current page display under the Templates heading in the far right column.
To view attributes of an existing template, click the template name.

Creating a New Template

If you need to create a custom template, it is generally simplest 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:

Navigate to the Templates page.
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Templates.
Click Create.
Select the type of template you want to create.
Select a creation method:
- From Scratch
- As a Copy of an Existing Template
Follow the on-screen instructions. Be careful to 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:

Navigate to the Themes page:
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Templates.
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.
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 developer and last update date.

Editing Templates

Once you create a custom template, you can quickly edit it from either the Templates page or from the Page Definition.

To edit an existing template from the Templates page:

Navigate to the Templates page.
1. On the Database Home Page, click the Application Builder icon.
2. Select an application.
3. Click Shared Components.
4. Under User Interface, select Templates.
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.
Locate the template you want to edit and select the template name.
Follow the on-screen instructions.

As you edit templates, you can make changes in one window and run your application in another by selecting Return to Page. Selecting this check box, keeps the page you are editing current after you click Apply Changes.

Breadcrumb Templates

A breadcrumb template controls the display of breadcrumb entries. You select a breadcrumb template when you create a region.

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. The Database Home Page user interface includes breadcrumb paths beneath the standard tabs (or second level navigation tabs) at the top of each page.

Description of the illustration bc_menu.gif

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 Breadcrumb Template page.

Identification

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.

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

Breadcrumb Template Style)

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

Breadcrumb Entry Control

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

Template Attributes

Use Breadcrumb Link Attributes to specify hypertext link attributes for a breadcrumb entry.

Use Between Levels to specify text that displays between each level of a breadcrumb breadcrumb. For example, if your breadcrumb has three levels, this text would display at the "X" in the example that follows:

main X cars X porsche X 911

In Max Levels specify the number of levels when displaying breadcrumbs.

Comments

Use this attribute to record developer comments.

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.

Button Template Attributes

This section describes specific sections of the Button Template page.

Button Template

Template Name identifies the name of the template. Use the Translatable check box to indicate if the template contains text strings which require translation. Theme indicates the theme to which the template is a member.

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 Text

Defines 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 which submits the page (that is, setting the request value), or simply redirects it to the supplied URL.

Comments

Use this attribute to record developer comments.

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 Calendar Template Attributes page. Note that template substitution strings must be in uppercase letters and begin and end with a number sign (#).

See Also:

"Creating Calendars"

Calendar Template Attributes

This section describes specific sections of the Calendar Template page.

Calendar Template Identification

Name identifies the name of the template. Theme indicates the theme to which the template is a member.

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.

Month Attributes

In Month Title Format enter the format for the monthly title that appears at the top of each month. This is the first part of a calendar which prints on the page. For example:

<table>
 <tr>
   <td>#MONTH#</td>
 </tr>

In Day of Week Format enter the format for the week day names which displays as the column header for that day of the week. For example:

<th width="14%">#IDAY#</th>

In Month Open Format enter HTML to be used to open a month. This displays immediately after the Month Title Format. Typically this attribute contains an HTML tag that functions as a container (such as a table). For example:

<table  border="0" cellpadding="0" cellspacing="0" class="htmldbRowWithBorders" width="100%"><tr>

In Close Month Format enter HTML to be used to close a month. Since this is the last part printed, this attribute should contain HTML that closes the HTML tags used in the Month Open Format. For example:

</table>

Week Attributes

Enter HTML to open and close a week.

In Week Open Format enter HTML to be used to open a week. This is printed for each week. Typically this attribute contains an HTML tag which functions as a container. For example:

<tr>

In Week Close Format enter HTML to be used to close the week. Since this is the last part printed, this attribute should contain HTML that closes HTML tags used in Week Open Format.

</tr>

Weekday Attributes

Enter HTML to format the days that occur during the work week (that is, Monday through Friday).

In Day Title Format enter HTML to be used the title of each day. This title displays after the Day Open Format. For example:

#DD#

In Day Open Format enter HTML to used to open a day. This displays on each day in the calendar. Typically this attribute contains an HTML tag that functions as a container. For example:

<td>

In Day Close Format enter HTML used to close a day. Since this is the last part printed, this attribute should close any HTML tags used in Day Open Format. For example:

</td>

In Today Open Format enter HTML used to open today. Typically this attribute contains an HTML tag which functions as a container (such as <td>) and would be different from the Day Open Format. For example:

<td style="background:#c5d5c5">

Non-Day Attributes

A non-day is not part of the current month. For example, suppose the first of a month is a Monday, but the week starts on a Sunday. Because Sunday is not part of the current month, Sunday would be a non-day. Use these attributes to format non-days.

In Non-Day Title Format enter a non-day title. For example:

#DD#

In Non-Day Open Format enter HTML to open a non-day. Typically this attribute would contain an HTML tag that functions as a container. For example:

<td>

In Non-Day Close Format enter HTML to close a non-day. Typically this attribute would contain an HTML tag that closes the tag used in Non-Day Open Format. For example:

</td>

Weekend Attributes

Enter HTML used to format days that occur on the weekend. Include substitution strings to include dynamic content. To view a list of supported substitution strings, see the Substitution Strings list on the right side of the Calendar Template page.

In Weekend Title Format, enter HTML to be used for a day occurring on a weekend. For example:

#DD#

In Weekend Open Format, enter HTML to open a day which is on a weekend. Typically this attribute would contain an HTML tag that functions as a container. For example:

<td>

In Weekend Close Format, enter HTML to close a day which is in a weekend. Since this is the last part printed, this attribute should close any HTML tags used in Weekend Open Format.For example:

</td>

Comments

Use this attribute to record developer comments.

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.

Label Template Attributes

This section describes specific sections of the Label Template page.

Label Template Attributes

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 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 (normal display)

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#',
  '&SESSION.','&CLOSE.')" >

In After Label, enter HTML to display after the item label. Since the label will be 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>

Label Template Attributes (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#</font>

In On Error After Label enter HTML to be appended to the item label when a 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>

Template Comments

Use this attribute to record developer comments.

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.

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 List Template page.

Template Identification

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.

Before List Elements

Enter HTML that displays before any list elements. You can use this attribute to open an HTML table or HTML table row.

List Element Display

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 Elements

Enter HTML that displays before any sublist elements.

Sub List Elements

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 Elements. Enter HTML that displays between list elements. This attribute will be ignored if no HTML is specified.

After Sub List Elements

Enter HTML that displays after displaying sublist elements.

After List Elements

Enter HTML that displays after displaying all list elements. You can use this attribute to close a HTML table opened in the Before List Elements attribute.

Comments

Use this attribute to record developer comments.

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

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

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 Application Attributes 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: "How Region Attributes Affect Page Layout"
`#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 `HTMLDB_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 Application Attributes 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 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 of level 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:

Page Template Attributes

This section describes specific sections of the Page Template page.

Name

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.

Definitions

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 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 and defines where the breadcrumbs are placed on the page. Sidebar Display Point applies to generated components that use Sidebars and 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 that 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 in the Notification Message the body of the message will appear.

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