Skip Headers
Oracle® Application Express Application Builder User's Guide
Release 4.1

Part Number E21674-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

Understanding Regions

A region is an 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 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 in the page template body or can be placed explicitly into region positions. The page structure can be defined using HTML tables or more commonly today using DIV tags.

Topics:

Creating a Region

You create regions by running the Create Region Wizard.

To create a region:

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

  2. Access the Create Region Wizard:

    • Component view - Under Regions, click the Create icon.

    • Tree view - Right-click the Regions and select Create.

    The Create Region Wizard appears.

  3. Select a region type. See "About Region Types".

  4. Specify Display Attributes:

    • Component view - Under Regions, click the Create icon.

    • Tree view - Right-click the Regions and select Create.

    The Create Region Wizard appears.

  5. Follow the on-screen instructions.

About Creating Subregions

Subregions enable you to create a parent/child relationship between two regions. A subregion displays inside of a parent region. You can specify a Parent Region when you initially create the region, or when editing region attributes. See "Creating a Region" and "Editing Regions".

You can use this feature in a variety of ways. One use case would be to use subregions to group information. For example, suppose you have a region with a border. You can use this feature to display two classic reports (or subregions) within it. You can also use subregions to display regions as tabs or as an accordion. You control how parent and subregions display by editing the Sub Region attributes of the region template. To learn more, see "Region Templates".

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

Table 12-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 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"

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.

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:

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: "About Trees Created as Shared Components"

URL

URL based regions obtain their content by calling a Web server using a predefined URL.

See Also: "Incorporating Content from Other Web Sites"

Calendar

Calendar regions are used to contain a calendar.

See Also: "Creating Calendars"

Plug-ins

Plug-ins allow developers to declaratively extend the built-in types available with Application Express.

See Also: "Implementing Plug-ins"

Help Text

Help Text regions enable you to provide page-level help.

See Also: "Creating a Help Page"

Map

Map regions contain declaratively defined Flash maps.

See Also: "Creating Maps"

Region Display Selector

Region Display Selector region enables the display of show hide controls for each region on a page for which region display selection has been enabled.

See Also: "Creating a Region Display Selector"


See Also:

Editing Regions

A region is an area of a page that serves as a container for content. You can alter the appearance of a page by editing region attributes.

Topics:

Editing Region Attributes

To edit region attributes:

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

  2. Access the Edit Region page:

    • Component view - Under Regions, select the region name.

    • Tree view - Right-click the region name and select Edit.

    The Edit Region page appears.

    Note:

    For further information regarding regions that are plug-in type regions, see "Importing a Plug-in from the Plug-in Page".
  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.

About Navigation Alternatives

The Region Definition page is divided into the following 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.

How Region Attributes Affect Page Layout

Region attributes control the appearance of a page. Table 12-2 describes region attributes that affect the layout of a page.

Table 12-2 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, Parent Regions

Defines the parent region to which the current region belongs to.

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

Attributes, Region Display Selector

Identifies this region to be included in Region display selectors. Region display selector's will only display regions that have been identified using this attribute.

Attributes, Region Image

If populated, the identified image displays in the upper left of the region. There is no control over the table tag used to display this image.

See Also: "Adding a Region Image"

Attributes, Image Tag Attributes

Used in conjunction with the Region Image attributes. Enter attributes to be included in the image html. For example, use this attribute for height and width.

See Also: "Adding a Region Image"

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

Header and Footer

Specifies HTML text to be displayed at the top of the region (just before the #BODY# content).

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

For all report regions, the substitution string #TIMING# shows the elapsed time in seconds used when rendering a region. You can use this substitution string for debugging purposes.

For classic report regions, the region footer supports the following substitution strings:

  • #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 control whether display attributes in a region can be customized by users.

To enable end-user customization:

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

  2. Access the Edit Region page:

    • Component view - Under Regions, select the region name.

    • Tree view - Right-click the region name and select Edit.

    The Edit Region page 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.

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.

Tip:

Region caching is not available for interactive report regions.

When you enable region caching, the Application Express engine renders a region from a cached (or stored) repository 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.

Enabling Region Caching

To enable region caching:

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

  2. Access the Edit Region page:

    • Component view - Under Regions, select the region name.

    • Tree view - Right-click the region name and select Edit.

    The Edit Region page appears.

  3. Scroll down to Caching.

  4. For Caching, select one of the following:

    • Cached - Caches the region independent of the user.

    • Cached by User - Caches the region specific to a given user.

    • Not Cached - Disables this feature.

  5. If you select Cached or Cached by User, specify the following:

    1. Timeout Cache After - Identify how long the cached region remains valid.

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

    3. Expression 1 and Expression 2 - Enter values based on the specific condition type selected.

  6. Click Apply Changes.

Managing Cached Regions

One way to improve an application's performance is to take advantage region caching. Developers can configure region caching by setting the Cache attribute on the Edit Region pages. See "Utilizing Region Caching".

You can manage cached regions on the Cached Regions page.

To access the Cached Regions page:

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

  2. Select an application.

  3. Click the Utilities button and select Caching.

  4. Under Cached Regions, click Manage.

    The Cached Regions page appears.

  5. You can customize the appearance the page using the Search bar at the top of the page. See 4.

  6. Select the regions you want to purge and click one of the following:

    • Purge Expired

    • Purge Checked

  7. To purge all cached regions, click Purge All.

See Also:

"Managing Cached Regions" in Oracle Application Express Administration Guide

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.

A static region ID is included by assigning it as a HTML element ID to the region container object (that is, the table or DIV). The ID of an HTML element must be unique for the entire page. For example, to keep the page HTML valid you cannot have a button and region with the same ID.

To specify a static region ID:

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

  2. Access the Edit Region page:

    • Component view - Under Regions, select the region name.

    • Tree view - Right-click the region name and select Edit.

    The Edit Region page appears.

  3. Scroll down to Attributes.

  4. For Static ID, enter value to identify this region. You can reference this value using the substitution string #REGION_STATIC_ID#.

  5. Click Apply Changes.

Adding a Region Image

Use the Region Image and Image tag attributes to add an image to the upper left side of a region.

To add a region image:

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

  2. Access the Edit Region page:

    • Component view - Under Regions, select the region name.

    • Tree view - Right-click the region name and select Edit.

    The Edit Region page appears.

  3. Scroll down to Attributes.

  4. Under Attributes, specify the following:

    • Region Image - Specify an image to display in the upper left of the region. Note that you cannot the table tag used to display this image.

    • Image Tag Attributes - Enter attributes to be included in the image html. Use these attributes to specify height and width.

  5. Click Apply Changes.

Editing Multiple Regions at Once

Application Builder includes several ways to edit multiple regions at once.

Topics:

Editing Multiple Attributes Across All Regions

Using the Regions page you can update multiple region attributes across all regions on a page, including sequence (the order), column, region name, and display point.

See Also:

To learn more about region attributes, go to the Edit Region page. See"Editing Regions".

To edit multiple attributes across all regions:

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

  2. Access the Edit Regions page:

    • Component view - Click the Edit All icon. The Edit All icon resembles a small grid with a pencil on top of it.

    • Tree view - Right-click Regions and select Edit All.

    Regions page appears.

  3. Update the appropriate attributes and click

  4. Click Apply Changes.

Accessing Region Utilities

Use the Utilities page to access Grid Edit pages and reports across all pages within a selected application.

To access the Region Utilities page:

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

  2. Access the Regions page:

    • Component view - Click the Edit All icon. The Edit All icon resembles a small grid with a pencil on top of it.

    • Tree view - Right-click Regions and select Edit All.

    Regions page appears.

  3. Update the appropriate attributes and click

  4. Click Apply Changes.

Reordering Regions

You can quickly change the order that regions display, edit a region title, or change a region template on the Drag and Drop Layout page.

To access the Drag and Drop Layout page:

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

  2. Access the Edit Region page:

    • Component view - Under Regions, click the Reorder Regions icon. The Reorder Regions icon resembles a light green downward arrow and upward arrow.

    • Tree view - Right-click the region and select Drag and Drop Layout.

    The Reorder Regions page appears. Use this page to edit the region title or select a template.

  3. In Region, enter a title.

  4. From Template, select a 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.

Creating a Region Display Selector

Region Display Selector region enables you to include show and hide controls for each region on a page.

To create a Region Display Selector:

  1. Create the page and regions to be included in the Region Page Selector.

  2. For each region to be included in the selector, edit Region Display Selector attribute:

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

    2. Access the Edit Region page:

      • Component view - Under Regions, select the region name.

      • Tree view - Right-click the region name and select Edit.

      The Edit Region page appears.

    3. Under Attributes, change Region Display Selector to Yes.

    4. Click Apply Changes.

  3. Create a region of type Region Display Selector:

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

    2. Access the Create Region Wizard:

      • Component view - Under Regions, click the Create icon.

      • Tree view - Right-click the Regions and select Create.

      The Create Region Wizard appears.

    3. Select a region type Region Display Selector.

    4. Click Create.

Copying a 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 the Page Definition".

  2. Access the Edit Region page:

    • Component view - Under Regions, click the Copy icon. The Copy icon resembles two small overlapping pages.

    • Tree view - Right-click the region and select Drag and Drop Layout.

    The Reorder Regions page appears. Use this page to edit the region title or select a template.

  3. If you are using Component view, select the region you want to copy. Otherwise, proceed to the next step.

  4. For To Page:

    1. To Page - Select the page to which you want to copy the region.

    2. Copy Region Items - Select Yes or No to determine whether to copy items within this region.

    3. Copy Buttons - Select Yes or No to determine whether to copy buttons within this region.

    4. Click Next.

  5. Click Copy Region.

Deleting Regions

To delete a region:

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

  2. Access the Edit Region page:

    • Component view - Under Regions, select the region name.

    • Tree view - Right-click the region name and select Edit.

    The Edit Region page appears.

  3. Click Delete.

Deleting Multiple Regions at Once

To delete multiple regions at once:

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

  2. Access the Edit Regions page:

    • Component view - Click the Edit All icon. The Edit All icon resembles a small grid with a pencil on top of it.

    • Tree view - Right-click Regions and select Edit All.

    Regions page appears.

  3. Click the Delete Multiple Regions tab.

  4. Specify the following:

    1. Cascade to Delete Button - Select Yes to delete corresponding region buttons.

    2. Cascade to Delete Items - Select Yes to delete corresponding region items.

    3. Delete associated list and list Entries - Select Yes to delete corresponding lists. This option only displays when the region to be deleted is the only region which references the list.

    4. Cascade to Delete Dynamic Actions - Select Yes to delete corresponding region items.

  5. Select the lists to be deleted.

  6. Click Apply Changes.