12.5 Managing Regions in Page Designer

Regions function as containers for content. Each page in an Oracle Application Express application contains one or more regions.

Topics:

12.5.1 Creating a Region in Page Designer

Tip:

You can also create a form or breadcrumb region from the Page Designer toolbar. On the Page Designer toolbar, click the Create menu and then selecting Form Region or Breadcrumb Region.

To create a region in Page Designer:

  1. View the page in Page Designer:
    1. On the Workspace home page, click the App Builder icon.
    2. Select an application.
    3. Select a page.
    Page Designer appears.
  2. In the Gallery at the bottom of the central pane, locate the type of region you want to create. Pass the cursor over a control or component to view a tooltip that describes it.

    Tip:

    In addition to dragging and dropping components from the Gallery, you can also right-click a component in the Gallery to view a context menu. Select Add To and then the location where you want to add the component.

  3. Click and hold the mouse on the region to be created and drag it the desired location in the Layout tab.

    When the mouse is over the appropriate location, the Layout tab displays as a darkened yellow tile. Release the mouse to drop the component. You can only drop components into appropriate drop positions, as determined by the component type.

    Based on the type of component you add, Page Designer indicates what actions are required next. The Messages tab displays a red or yellow badge indicating the number of messages you need to address.

  4. Edit the appropriate attributes in the Property Editor.

    Tip:

    To view help for an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.

  5. Click Save or Save and Run Page.

See Also:

"Messages Tab"

12.5.2 Managing Regions in Page Designer

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:

12.5.2.1 Editing Region Attributes in Page Designer

To edit region attributes:

  1. View the page in Page Designer:
    1. On the Workspace home page, click the App Builder icon.
    2. Select an application.
    3. Select a page.
    Page Designer appears.
  2. In the Rendering tab, select the region.

    The Property Editor displays the region attributes in the right pane.

    Attributes are organized into functional groups. To expand or collapse these groups, click the Show Common, Show All, Collapse All, and Expand All icons.

  3. View all attributes in the Property Editor. Click the Show All icon at the top of the left pane.
  4. Edit the appropriate attributes in the Property Editor.

    To learn more about an attribute, see field-level Help.

  5. To save your changes click Save. To save and run the page, click Save and Run Page.

12.5.2.2 Controlling Region Positioning

When you create a region, you can specify its position in the Property Editor by editing the Layout, Position attribute. The template positions defined within the current theme for the page's user interface determine the available selections.

12.5.2.3 Specifying a Region Header and Footer

In addition to the body content of a region, you can specify additional HTML to be placed above and below a region by editing the Header and Footer attributes in the Property Editor.

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
    

12.5.2.4 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 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 Customize link appears wherever you include the #CUSTOMIZE# substitution string in the page template. When users click this link, a window appears, enabling them to display or hide regions on the page.

To enable end user customization:

  1. View the page in Page Designer:
    1. On the Workspace home page, click the App Builder icon.
    2. Select an application.
    3. Select a page.
    Page Designer appears.
  2. Select the region in the Rendering tab or the Layout tab.

    The Property Editor displays attributes for the region.

  3. Locate Customization. For Customizable, select one of the following:
    • Not Customizable By End Users

    • Customizable and Not Shown By Default

    • Customizable and Shown By Default

  4. Click Save.

12.5.2.5 Utilizing Region Caching in Page Designer

Enabling region caching is an effective way to 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.

Topics:

See Also:

"Managing Page and Region Caching" in Oracle Application Express Administration Guide

12.5.2.5.1 About Region Caching

Enabling region caching is an effective way to improve the performance of static regions such as regions containing lists that do not use conditions or regions containing static HTML.

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

See Also:

"Server Cache"

12.5.2.5.2 Enabling Region Caching in Page Designer

To enable region caching:

  1. View the page in Page Designer:
    1. On the Workspace home page, click the App Builder icon.
    2. Select an application.
    3. Select a page.
    Page Designer appears.
  2. Select the region in the Rendering tab or the Layout tab.

    The Property Editor displays Region attributes.

  3. To view all attributes in the Property Editor, click Show All .
  4. Expand Server Cache. For Caching, select one of the following:
    • Disabled - Content is not cached and computed for each request.

    • Enabled - Content is cached and utilized by all users.

    • Cached by User - Content is cached specifically for each user.

    • Cache by Session - Content is cached specifically for each session.

  5. Click Save.

12.5.2.6 Specifying a Static Region ID

Specifying a static region ID is useful when creating custom JavaScript or cascading style sheets. 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 an 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. View the page in Page Designer:
    1. On the Workspace home page, click the App Builder icon.
    2. Select an application.
    3. Select a page.
    Page Designer appears.
  2. Select the region in the Rendering tab or the Layout tab.

    The Property Editor displays the Region attributes.

  3. To view all attributes in the Property Editor, click Show All .
  4. Locate Advanced. Edit the Static ID attribute:
    1. Locate Advanced and then Static ID.

    2. In Static ID, enter the static ID for this region. If defined, this is used as the ID for the region, using the substitution string #REGION_STATIC_ID#, which can be useful if developing custom JavaScript behavior for the region. If this is not defined, the region generates an internal ID.

    Tip:

    The template must include the #REGION_STATIC_ID# substitution string, in order for the region to utilize the static ID entered.

  5. Click Save.

12.5.2.7 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. View the page in Page Designer:
    1. On the Workspace home page, click the App Builder icon.
    2. Select an application.
    3. Select a page.
    Page Designer appears.
  2. Select the region in the Rendering tab or the Layout tab.

    The Property Editor displays Region attributes.

  3. Locate Advanced. Edit the following attributes:
    • Region Image - Enter a reference to an image that displays in the upper left of the region. There is no control over the table tag used to display this image.

    • Image Tag Attributes - Enter image tag attributes included in the image HTML. This can be used for attributes such as height, width or image ALT text (if the image is non-decorative).

      If no ALT is defined in the image tag attributes, Application Express defaults to rendering the image as a decorative image, for example with an empty ALT tag.

  4. Click Save.

12.5.2.8 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, set the Region Display Selector attribute to Yes.
  3. In the Gallery, right-click Region Display Selector region, select Add To, and select the appropriate location.

    Tip:

    You can also drag and drop from the Gallery. From the Gallery select the Region Display Selector region and drag it to the appropriate location in the Layout tab.

  4. Edit the region attributes in the Property Editor:
    1. Identification, Title - Enter a region title. The region title only displays when it is defined in the region template.
    2. Advanced, Region Display Selector - Select Yes if you want this region included in the Region Display Selector. This attribute is only utilized if a region type of Region Display Selector is defined and viewable on the page.

      Tip:

      To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.

  5. Click Save.

12.5.3 Copying a Region in Page Designer

Note:

You cannot copy a Tree region since this type of region encompasses more than one region.

To copy a region:

  1. View the page in Page Designer:
    1. On the Workspace home page, click the App Builder icon.
    2. Select an application.
    3. Select a page.
    Page Designer appears.
  2. Right-click the region in Layout tab, select Copy To, and select a destination from the submenu.

Tip:

To copy a region to another page, select the region in the Rendering tab, right-click, and select Copy to Other Page. Follow the on-screen instructions.

12.5.4 Deleting Regions in Page Designer

To delete regions:

  1. View the page in Page Designer:
    1. On the Workspace home page, click the App Builder icon.
    2. Select an application.
    3. Select a page.
    Page Designer appears.
  2. Select one or more regions in the Rendering tab.
  3. Right-click and select Delete.
  4. Click Save.