Focusing on Templates in Oracle HTML DB

In this second part of a three-part article covering Oracle HTML DB, you’ll learn about common template sections and more. This article is excerpted from the Oracle HTML DB Handbook, written by Lawrence Linnemeyer and Bradley Brown (McGraw-Hill, 2006; ISBN: 0072257687).

Using Substitution Variables

HTML DB utilizes four different syntaxes for accessing different types of variables throughout the HTML DB application. The following table shows the different syntaxes.

 

 

 

 

Syntax Usage
#VARIABLENAME# For system-defined substitution variables such as those used in templates.
&VARIABLENAME.

For global application variables, session variables, and page items (note the trailing period)

v
(‘VARIABLENAME’)

For use in PL/SQL for character-type variables, including session variables and page items

nv
(‘VARIABLENAME’)

For use in PL/SQL for number-type variables, including session variables and page items.

:VariableName

Bind variable syntax also used in PL/SQL to refer to global application variables, session variables, and page items.

Substitution variables are used in template definitions as placeholders for values that will be filled when the page is generated. HTML DB has a large number of predefined substitution variables that are used in template definitions. Those used in template definitions always start and end with the pound symbol (#). For example, #TITLE# is the substitution variable that will be replaced with the page title that is defined when a page is created. Each type of template has a number of substitution variables predefined for use with the template. The best way to know what variables are available for a particular section of a template and which ones are required for that section is to click on the section title to access the help text for that section.

TIP

Utilize HTML DB’s extensive built-in context-sensitive help, available by clicking on most item’s labels.

A complete list and description of each of the substitution variables available for each type of template can be found in HTML DB’s online help, accessible from the Help icon located in the upper-right corner of each page. Once you open Help to the contents page, select the Customizing Templates link under the Controlling Page Layout and User Interface section. Near the top of the page is a list of links that will take you to a section for each of the different types of templates. Each section lists the substitution variables and a brief description of the template’s major sections.

Page Template

In this section, we will look at the details in a Page template to see how the template works with substitution variables and where those substitution variables tie back to what was specified when the pages were created.

The Edit Page Template screen contains 12 sections. Several of these sections are common to all or most of the other template-editing pages. We will address those sections before moving on to the page-specific ones. Navigate to an edit template screen by clicking on the name of the template from the list on the Templates page, as shown earlier in Figure 6-4.

{mospagebreak title=Common Template Sections}

All templates have a corresponding edit page. Many of the items on these pages are specific to only one type of template; however, there are a number of sections in the edit pages that are common to most types of templates.

Page Template Identification

The first common section is the Template Identification section. Here, you provide a unique descriptive name for the template as well as select the theme to which the template belongs. Additionally, in this section you specify the template class for the template and select whether the template is translatable (which has to do with deploying a template in multiple languages). See Chapter 7 for more details on deploying applications in multiple languages.

Template Subscription

The next section is the Template Subscription section. This section lists details about subscriptions. Was this template copied from another template? Is this template subscribed to another template? Does this template have any subscribers? 

The first line contains a pick list for a master template. If the template was copied from another template, it will have a meaningless reference number listed in the pick list field, as previously shown. Otherwise, it will be empty, as shown next. In either case, you can select another template from the pick list and then refresh this template from the selected template. In instances where there already is a master (as in the previous example), you would click on the Refresh Template button. If this template never had a master template, like in the following example, a Refresh check box will appear next to the pick list. If this is checked and you apply changes to the page, it will refresh from the master.

The section then displays where the template was copied from and a list of templates that are subscribed to it. If the template is subscribed to another template, you’ll see a Refresh Template button. Clicking that button recopies from the subscribing template, overwriting everything. If this template has other templates that subscribe to it, you’ll see a Publish Template button. Clicking the Publish Template button will copy the current template out to all templates that are subscribed to it, overwriting any changes that may have been made to them.

Configuration Management

This section contains a single field to select the build option for this template. Build options are used to include or exclude certain components of an application. There can be any number of build options. You will have a pick list that includes a selection for each build option and a {Not} selection for each build option. Refer to Chapter 4 for more details on build options.

Comments

The last common section is the Comments section. This section allows the developer to enter any pertinent comments about a template. Comments should be used to document anything that is done out of the ordinary.

{mospagebreak title=Header/Body/Footer Definitions}

The next section contains the definitions for the header, the body, and the footer of the page. Remember, the HTML DB engine generates each page at run time by combining the static HTML defined in your template with the dynamic pieces derived from the metadata you used when building the pages. This connection is made through the use of substitution variables. There is an area for entering the HTML for the Header section, the Body section, and the Footer section. Let’s take a closer look at an example of each of these definitions.

Header

The Header section contains the HTML for the HEAD section of an HTML document. Everything you would normally include before the BODY tag in an HTML document belongs here. Someone familiar with web page layout and HTML should make the modifications to templates. However, if you must do it and are not familiar with HTML, then try HTML & XHTML: The Complete Reference by Thomas Powell (McGraw-Hill/Osborne, 2003).

The following is a listing of code from the header definition:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
   
<title>#TITLE#</title>
   
#HEAD#
   
<link rel="stylesheet" href="#IMAGE_PREFIX#css/einstein.css"
     
type="text/css" />
    <script src="#IMAGE_PREFIX#javascript/functions.js"
           type="text/javascript"> </script>
</head>

Notice the example contains normal HTML items such as the title tag and includes statements for a Cascading Style Sheet and a file containing JavaScript. It also contains several substitution variables.

The substitution variable #TITLE# will be replaced at run time with the value from the Title field in the Primary Page Attributes section of the Edit page, or “Form on CONTACTS,” as shown in Figure 6-7. The substitution variable #HEAD# will be replaced with the value entered in the HTML Header section of the Edit page, as shown in Figure 6-7. You might have HTML to reference additional JavaScript libraries or Cascading Style Sheets.

The other substitution variable seen in this code block is #IMAGE_PREFIX#. This is a predefined variable that contains the directory on the server for the images that come with HTML DB. If you look at the source of a generated page, you will see that it resolves to /i/, which is mapped to ORACLE_HOMEmarvelimages. The Cascading Style Sheet (CSS) file is located in ORACLE_HOME marvelimagescss, and the JavaScript file is located in ORACLE_HOMEmarvelimages javascript. At a minimum, the Header section should contain the #TITLE# and the


Figure 6-7.  Edit page–source for substitution variables

#HEAD# substitution variables. Here’s a list of the other substitution variables allowed in the Header section:

#ONLOAD#

#NAVIGATION_BAR#

#FORM_OPEN#

#NOTIFICATION_MESSAGE#

#SUCCESS_MESSAGE#

#GLOBAL_NOTIFICATION#

{mospagebreak title=Body Section}

The Body section contains the HTML tags and substitution variables for the BODY section of the HTML document. This is the section through which the majority of your page will be created. You can define the location of your main body content and position up to eight different regions for your page. If you are using tabs and sub-tabs, their location will also be defined here. The following is a listing of code from a BODY section definition:

<body #ONLOAD#>
#FORM_OPEN#
<table width="100%" cellpadding="0" cellspacing="0" border="0" summary="">
  <tr>
    <td valign="top" class="t1Logo">#LOGO#</td>
    <td valign="top" class="t1Logo">
      <img src=#WORKSPACE_IMAGES#change_user2.gif />
    </td>
    <td align="right" valign="top">#NAVIGATION_BAR#</td>
  </tr>
  <tr>
    <td>&APP_USER.</td>
  </tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0" border="0" summary="">
 
<tr>
    <td colspan="5" class="t1ParentTabHolder">
      <table border="0" cellpadding="0" cellspacing="0" summary="" align="right"> 
        <tr><td><br/></td>
          #TAB_CELLS#
        </tr>
      </table>
    </td>
  </tr>
<tr>
  <td class="t1topbarLeft" valign="top">
   
<img src="#IMAGE_PREFIX#themes/theme_1/ top_bar_far_left.png" alt="" />
  </td>
  <td align="right" class="t1topbarLeft" colspan="2" valign="top">
   
<img src="#IMAGE_PREFIX#themes/theme_1/ top_barleft2_1.png" alt="" /></td>
  <td align="right" class="t1topbarLeft" valign="top">
    <img src="#IMAGE_PREFIX#themes/theme_1/ top_barleft2_2.png" alt="" /></td>
  <td class="t1topbarMiddle" valign="top">
    <table height="100%" cellpadding="0" cellspacing="0" border="0" summary="">
      <tr>
       
<td height="20"><br/></td>
      </tr>
      <tr>
        <td valign="bottom" height="20">#REGION_POSITION_01#</td>
      </tr>
    </table></td>
  <td valign="top">
    <img src="#IMAGE_PREFIX#themes/theme_1/ top_bar_right.png" alt="" /></td>
</tr>
<tr>
 
<td class="t1PageLeft" colspan="3" align="left" valign="top">
   
#REGION_POSITION_02#
  </td>
  <td><br/></td>
  <td class="t1PageRight" colspan="2">
   
<table summary="" cellpadding="0" width="100%" cellspacing="0" border="0">
      <tr>
        <td width="100%" valign="top" class="t1PageBody">
          <div class="t1messages">
            #GLOBAL_NOTIFICATION#
#SUCCESS_MESSAGE##NOTIFICATION_MESSAGE# 
          </div>
          #BOX_BODY# #REGION_POSITION_04##REGION_POSITION_05# #REGION_POSITION_06# 
          #REGION_POSITION_07# #REGION_POSITION_08#
       
</td>
        <td valign="top">#REGION_POSITION_03#<br /></td>
      </tr>
      
</table>
    </td>
  </tr>
</table>

This example contains a lot of HTML tags that you would expect to see in the body of a regular HTML page, but it also has a large number of substitution variables. This particular example defines a page that has a logo image, a navigation menu, one set of tabs, a side navigation bar, a breadcrumb-type menu, and a region for a report. Figure 6-8 shows a page based on this template.

The #ONLOAD# substitution variable in the <body> tag is used for JavaScript that will be executed when the page is first loaded. The value that will be substituted at run time is entered in the On Load JavaScript section of the Edit Page section, as shown here.

The #FORM_OPEN# substitution variable is placed where you would normally place the HTML <form> tag. If a page using this template is to be submitted, you must include this substitution variable in your template. There is no source for this substitution variable; HTML DB will generate the necessary code.

The next section of HTML code defines a table that contains the two logo images and the navigation bar. The first logo image is placed using the #LOGO# substitution variable, which


Figure 6-8.  Template base page

derives its source from the Image and Logo Image Attributes fields in the Logo section of Application Attributes. We have already seen the use of the #IMAGE_PREFIX# for an image that came with HTML DB, but here we see another substitution variable, #WORKSPACE_IMAGES#, which allows you to use an image that is imported into your workspace. Simply include this substitution variable before the name of the image. For further details on managing image files, see Chapter 7. The #NAVIGATION_BAR# substitution variable specifies the location of the navigation bar. For more information about navigation bars, see Chapter 11. The source for the substitution variable comes from the navigation bar sub template definition (see the “Sub-template Definitions” section, later in this chapter).

Notice the use of both regular HTML style elements, such as <td height=”20”>, and Cascading Style Sheet classes, such as <table class=”t1Logo”>. Remember, the CSS was specified in the Header section of the template. Also note the use of the substitution variable &APP_USER. in <td> &APP_ USER.</td>, which retrieves the current username.

The next section of HTML code defines a table and a table row that displays the standard tabs. The substitution variable #TAB_CELLS# is used to position the display of the tabs. The value for this variable comes from the Standard Tab Attribute section of the page template (for further explanation, see the “Standard Tab and Parent Tab Attributes” section, later in this chapter). It is possible to position your tabs anywhere on the page you would like. The #TAB_CELLS# substitution variable can be placed in the Header, Body, or Footer section. If your page also contains parent tabs, you would place the #PARENT_TAB_CELLS# substitution variable in its own table row. This could be in the same table or a different table definition.

The next group of HTML, which includes three image definitions that use the #IMAGE_PREFIX# substitution variable and the #REGION_POSITION_01# substitution variable, make up the bar below the tab and the region used for the breadcrumb menu. The following group uses one image, and the #REGION_POSITION-02# substitution variable is used to define the region where the side navigation bar is located.

The next three substitution variables used are #GLOBAL_NOTIFICATION#, #NOTIFICATION_ MESSAGE#, and #SUCCESS_MESSAGE#. The #GLOBAL_NOTIFICATOIN# substitution variable gets its source from the Global Notification field in the Application Attributes. The substitution variable #NOTIFICATION_MESSAGES# will be replaced with a summary of inline error messages from item validation. When creating a validation, you may choose to display the error messages next to the associated items, all together in the #NOTIFICATION_MESSAGE# location, or in both places. The #SUCCESS_MESSAGE# substitution variable defines the location for the display of the page-level success and error messages.

In the remainder of the HTML code, a number of substitution variables are used, #BOX_BODY# and #REGION_POSITION_O3# through #REGION_POSITION_08#. The region position variables specify the locations for different regions within the page. You may create a template with up to eight different regions, #REGION_POSITION_01# through #REGION_POSITION_08#. When designing your template, you might use one region on the side of your page for a navigation section, another for a breadcrumb menu across the top, one in the center for the main content, and another at the bottom of the page. It does not matter in what order you place the region positions within your HTML code. Notice that #REGION_POSITION_03# is actually placed after all the other region positions.

The region positions are used in your page definition. As you define a page and create its regions, you specify, through a pick list, the template region position in which you would like your regions displayed. It is not necessary to use every template region position when creating a page that uses that template.

Please check back next week for the conclusion to this article.

[gp-comments width="770" linklove="off" ]

chat