How-To Document

Add Navigation within a Page

Date: 28-DEC-2004
Based on Oracle Application Express (formerly HTML DB) version 1.6

After reviewing this How-To, you should be able to add navigation within a page to your application.

The sections include:



Introduction

Oracle HTML DB provides navigation within pages that contain vertical content that scrolls off the screen. This is implemented as a list of sections at the top of the page with links to the appropriate region within the page. Each region then contains a link back to the top of the page. This type of navigation is very useful for users.

The discussion below walks you through creating the necessary templates and then using those in a page to provide vertical page navigation. This navigation employs simple html anchors.

Necessary Template Changes

To implement navigation within a page, you need specific code within your page template, region template and list template. This code can be added to any application theme, whether custom or standard. The Theme being used for this example is Theme 5, Opal Look.

Page Template

Each theme has several page templates. If you are only using the default Page Template in your application, only that template needs to be modified. To find out which Page Template is the default:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select the desired application. This takes you to the Application Builder home page.

  3. Above the Pages list, select Shared Components.

  4. Under the User Interface section, select Themes and Templates. If there is more than one theme displayed, the current one for your selected application will have a check to the left of the name (under the Current heading).

  5. Select the name of the current theme, or the theme that you will be making current for your application.

  6. Scroll down to the Page templates. The one with that is defined as default will have a check on the right under the Default column.

To include page navigation, you need to include an anchor at the top of the page. Make the following change to any page template referenced by a page where you want to include navigation.

  1. Select the template that was identified as the default page template, or the template that you will be using on pages with navigation.

  2. Under the Header/Body/Footer Definitions section, in a new line under #FORM_OPEN#, add:

    <a name="PAGETOP"></a>
    
    The change will look like the image below:

    Image 1 - Page Template Change
    Page Template Change


  3. Click Apply Changes.

Region Template

Next, you need to modify the region templates you will use on the pages to include a reference in the title bar to the anchor. You can use the word "Top" or an image for the link. The example below uses an image.

  1. From the Templates page (where the previous step left you), scroll down to the Region templates and select the region template that you will be using on pages with navigation.

  2. Under the Region Template section, for Template, insert the following code to the far right of the title bar:

    <a href="#PAGETOP" class="smWhtLk">
    <img src="#IMAGE_PREFIX#up_arrow.gif" width="23" height="16" alt="&TOP. /></a>
    
    Depending on your template, you may need to include an additional 'td' tag. The change will look like the image below:

    Image 2 - Region Template Change
    Region Template Change


  3. Click Apply Changes.

List Template

Lastly, you need a list template that will display the list entries as references, side-by-side. Each theme from the HTML DB Repository includes a list template named 'Horizontal Links List'. The template displays list entries horizontally but does not include a separator. To include a separator, you need to modify the template. You can either modify the 'Horizontal Links List' List template or copy it, and then modify the copy. To modify the existing template:

  1. From the Templates page (where the previous step left you), scroll down to the List templates and select Horizontal Links List.

  2. Under the List Element Display section, for List Template Current, insert the following code to the left of the reference:

     -
    
    This is simply a space, dash, and another space.

  3. Under the List Element Display section, for List Template Noncurrent, insert the same code to the left of the reference. The change will look like the image below:

    Image 3 - List Template Change
    List Template Change

  4. Click Apply Changes.

This is just one example where the separator is just a dash. You can use any separator you want.


Creating the List

The navigation will be created as a list. First, you create a list and reference your new modified list template. Then you create list entries within the list, one for each region on your page that will include a link. These list entries will be of type URL and the target will be the anchor name that will be defined in each region.

  1. Select Shared Components from the breadcrumb menu.

  2. Under the Navigation section, select Lists.

  3. Click Create List >.

  4. For Name, enter P100 Navigation. Because this list will be specific to a page, including the page number will act as a reminder.

  5. For List Template, select the template you modified. The page should look like the image below.

    Image 4 - Create List
    Create List

  6. Click Create.

Now that you have the list created, you will create a list entry for each region on the page.

  1. Click Create List Entry >.

  2. Under the Label and Sequence section, for List Entry Label, enter First Region.

  3. Under the Target section, for Target type, select URL.

  4. Under the Target section, for URL Target, enter #1ST. The page should look like the image below.

    Image 5 - Create List Entry
    Create List Entry

  5. Click Create and Create Another.

  6. Under the Label and Sequence section, for Sequence, enter 20.

  7. Under the Label and Sequence section, for List Entry Label, enter Second Region.

  8. Under the Target section, for Target type, select URL.

  9. Under the Target section, for URL Target, enter #2ND.

  10. Click Create and Create Another.

  11. Continue creating list entries until you have enough for each region, incrementing the sequence for each entry. For the final List Entry, click Create.


Adding to a Page

For navigation to be displayed on a page, you need to have the following things:

  • The page references the modified page template.
  • The page includes a region referencing the new List.
  • Each region on the page, except the one for the new List, has anchors included in their region titles to provide a target for the List Entries.


To add the anchors to the region titles:

  1. Navigate to the Application Builder home page. You can do this by selecting the Builder - Application xxx breadcrumb or by selecting the Application Builder tab.

  2. Under Pages, select the page you wish to add navigation to.

  3. Under the Regions section, select the Regions heading.

  4. You will now be on the Regions page. From here, you can edit each of the regions to include an anchor. Preface each Region title with:

    <a name="xxx"></a>
    
    with 'xxx' replaced with the value from the appropriate List Entry, such as '1ST'. The page should look like the image below.

    Image 6 - Edit Region Titles
    Edit Region Titles


  5. Click Apply Changes.

Next, you will create the List region. The example below has the region without a region template. Although page navigation typically does not have a region template, it is your design preference whether or not to include one.

  1. Navigate back to the Page Definition. You can do this by selecting the Page Definition breadcrumb or by clicking the edit page icon ( Edit Page) in the upper right.

  2. Under the Regions section, click the create icon ( Create).

  3. For Select a common region type, select List and click Next >.

  4. For Title, enter Page Navigation.

  5. For Region Template, select No Template.

  6. For Sequence, enter 5 and click Next >.

  7. For List, select P100 NAVIGATION and click Create List Region.

Lastly, if your page does not already reference the page template that you modified to include the PAGETOP anchor, you will need to change the page template reference.

  1. Within the Page button bar, click Edit Attributes.

  2. Under the Primary Display Attributes section, for Page Template, select the page template that you modified above.

  3. Click Apply Changes.


Running the Page

The page displayed below has a region containing the page navigation and three regions of content. The first image shows the page, as it would initially display. To run a specific page, you can click the run icon ( Run) in the upper right of the Page Definition.

Image 7 - Top of New Page
Top of New Page

Below is the page after the Third Region link is selected. It scrolls the screen so that the Third Region is displayed. To navigate back to the top, the user just needs to click on the up arrow image ( Up Arrow) in the right of the title bar.

Image 8 - Scrolling Down
Scrolling Down

Now you should be able to include page navigation within your applications.

Discuss this how-to in the OTN HTML DB Discussion Forum.