7 Using Application Builder

About Template Identification

Application ID identifies the application to which this template corresponds. Name identifies the template name used by application developers to identify the template.

About Template Subscription

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

About Header, Body, and Footer Definitions

Each template consists of a header, a body, a footer, and subtemplate definitions. Use substitution strings to indicate the existence of a component on a page template. All template substitution strings must be in upper case and begin and end with a pound sign (#). You can include the substitution strings listed.

Header is the first section of the page template. When displaying regions or executing processes or computations AFTER HEADER, they will display or execute immediately after this section in the template is rendered.

Body is the second section in the page template and is rendered after the header and before the footer section. At a minimum, you must include the #BOX_BODY# substitution string.

Footer is the third section.

About Subtemplate Definitions

Use Subtemplate Definitions to specify how a component should display. Available subtemplate definitions 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 icons. This subtemplate is only relevant if the #NAVIGATION_BAR# substitution string is identified in your page template. Use the #BAR_BODY# substitution string to identify where each navigation bar icon should display.

• Notification. Alerts the user that validation errors have occurred. This subtemplate expands the #NOTIFICATION _MESSAGE# substitution string. Notification messages will not be display unless the #NOTIFICATION_MESSAGE# substitution string is included in the page template.

About Standard Tab Attributes

You MUST populate this attribute if your application includes standard tabs. Standard tabs may 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. Defines the subtemplate to use for standard tabs that are selected (or current) Whether or not a tab is current is determined by standard tab attributes and the page displays. Use #TAB_TEXT# to position a tab's label and link within the template.

• Non Current Standard Tab. Defines the subtemplate to use for standard tabs that are not current. Use #TAB_TEXT# to position a tab's label and link within the template.

About Parent Tab Attributes

You MUST populate this attribute if your application includes two levels of tabs. Parent tabs may 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. Defines the subtemplate to use for parent tabs that are selected (or current). Whether or not a tab is current is determined by the page that displays and the standard tab set the page uses. Use #TAB_TEXT# to position a tab's label and link within the template.

• Non Current Parent Tab. Defines the subtemplate to use for parent tabs that are not current. Use #TAB_TEXT# to position a tab's label and link within the template.

About Image Based Tab Attributes

Use this subtemplate for tabs that are entirely based on images.

About Multi Column Region Table Attribute

Each region is assigned a column and a display sequence within that column. When regions are placed in more than one column, Oracle HTML DB renders the regions using an HTML table. This attribute will be used in the <table> tag used for the layout.

About Error Page Template Control

Use this attribute only when a page template will be designated as an error template. Use #MESSAGE# to place the error message and #BACK_LINK# to display a link back to the previous page. A template can be designated as an error template by editing the application attributes. For example:

#MESSAGE#

<br>

<a href="#BACK_LINK#">back</a>

About Configuration Management

You can use build options to enable or disable functionality. Most application attributes have a build option attribute.

Build Options have two possible values: INCLUDE and EXCLUDE. A component that is excluded is not considered part of the application definition at runtime.

About Comments

Use this attribute to record developer comments.

About Region Template Identification

Application ID Identifies the application to which this template corresponds. Name identifies the template name used by developers to identify the template.

About Template Subscription

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

About Region Template

#BODY# (the only required substitution string) identifies where the source of the region should be placed. All other substitution strings are optional.

When you create a button in a region position, the positions you have defined will appear in a select list. Use the following substitution strings to define positions for placement of buttons in a region:

• #EDIT#

• #CLOSE#

• #CREATE#

• #EXPAND#

• #HELP#

• #DELETE#

• #COPY#

• #NEXT#

• #PREVIOUS#

About Form Table Attributes

Page items display within regions. Items are rendered as HTML form elements in an HTML table. With this template property, you can define attributes that will be placed in the <table> tag. For example:

class="tanBox"

About Comments

Use this attribute to record developer comments.

About Generic Column Templates

You can use generic column templates for most queries. This template defines the look of each column. You can conditionally display one-column templates for rows that meet a specific condition and use another column template for other rows. You cannot use this type of template to display multiple columns on the same row differently. If you want each column to use a specific style, you could define the column template similar to the following:

<td class="tabledata" align="#ALIGN#">#COLUMN_VALUE#</td>

This example assumes your page template includes a CSS containing the class tabledata. This example also demonstrates the use the substitution strings #ALIGN# and #COLUMN_VALUE#. If you actually ran this report, these substitution strings would be replaced with values generated by the results of a SQL query.

If your query uses an expression in the select list, it is a good idea to create an alias for the columns to avoid runtime errors. For example, suppose your query was as follows:

SELECT ename, (sal + comm) * 12 FROM emp

You could rewrite the query to alias the columns as follows:

SELECT ename, (sal + comm) * 12 yearly_comp FROM emp

About Named Column Templates

Although named column templates offer a great deal of flexibility, you may need to create a new template for each query. When you use a named column template, you specify the column name in the template. For example:

<tr><td>#ENAME#</td><td><font color=red>#SAL#</td></tr>

You can also include a position notation. The following example demonstrates how to use following HTML and substitution strings:

<tr><td>#ENAME#</td><td><font color=red>#SAL#</td></tr>

<tr><td>#1#</td><td><font color=red>#2#</td></tr>

About Conditional Use of Report Templates

By creating conditions, you can create a report that displays rows differently depending upon who runs the report. You can conditionally use up to four report templates for each query and can refer to specific rows using the syntax #1#, #2#, #3#. For example, to display a row in bold if the salary was greater then 2000 you could include the following row template condition:

#5# > 2000

About Using JavaScript in Row Templates

You can conditionally display HTML depending upon values in the database using JavaScript. The following example displays an HTML row only if the GROUP_DESC query column is not null.

<script language="javascript">
IF ( "#GROUP_DESC#" != "" )
document.writeln( "<TR>;
<TD BGCOLOR=#336699>;<FONT SIZE=2 COLOR=#FFFFFF FACE=Arial, Helvetica>Group Description</FONT></TD>
</TR>
</TR>
<TD>#GROUP_DESC#</TD>
                </TR>" );
        </TR>" );

Breadcrumb Style Menu Navigation

Breadcrumb style menus 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. Oracle HTML DB includes breadcrumb paths beneath the standard tabs (or second level navigation tabs) at the top of each page as shown in the following example:

Figure 7-6 Breadcrumb Style Menu

Description of the illustration bc_menu.gif

Understanding Region Source Types

Each region has a region source type. The HTML DB engine interprets a region differently based the type you select. Table 7-7 describes available region types.

Controlling Region Positioning

When you create a region, you must specify its position or Display Point on the page. Regions are rendered in order of sequence number within a Display Point. 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 which column the region will be placed in. When you place regions in multiple columns, Oracle HTML DB automatically renders the necessary HTML to produce a multi column layout.

Displaying a Region Conditionally

Whether a region is displayed can be based on conditions defined at the region level. Conditions may reference session state, the currently logged in user, or HTML DB engine settings (such as whether or not a page is in Print View mode).

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 may use this for debugging purposes.

• #ROWS_FETCHED# shows the number of rows fetched by the Oracle HTML DB reporting engine. You may 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_NUMBER# and #LAST_ROW_NUMBER# displays the range of rows displayed. For example:

  Row(s) #FIRST_ROW_NUMBER# through #LAST_ROW_NUMBER# of #ROWS_FETCHED# displayed
  
  

About Branching with Buttons

Each page can include any number of branches. A branch links to another page in your application or to an URL. The HTML DB engine considers branching at different times during page processing. You can choose to branch before processing, before computation, before validation, and after processing. Like any other component in Application Builder, branching can be conditional. For example, you can branch when a user clicks a button. When you create a branch, you associate it with a specific button. The branch will only be considered if a user clicks the button.

Understanding the Relationship Between Button Names and REQUEST

The name you give a button determines the value of the built-in attribute REQUEST. You can reference the value of REQUEST from within PL/SQL using the bind variable :REQUEST. By using this bind variable, you can conditionally process, validate, or branch based on which button the user clicks. You can also create processes that execute when the user clicks a button. You can also use a more complex condition as demonstrated in the following examples:

If :REQUEST in ('EDIT','DELETE') then ...
If :REQUEST != 'DELETE' then ...

These examples assume the existence of buttons named EDIT and DELETE. You can also use this syntax in PL/SQL Expression conditions. Be aware, however, that the button name case is preserved. In other words, if you name a button "LOGIN" then a request looking for the name "Login" will fail. For example:

<input type="BUTTON" value="Finish" onClick="javascript:doSubmit('Finish');">

Note that Finish is the name of the REQUEST and in this example is case sensitive.

Displaying Buttons Conditionally

You can choose to have a button display conditionally by making a selection from the Conditional Display Type list and entering an expression.

Understanding Item Display As Options

For each item, you specify a type by making a selection from the Display As list. Table 7-8 describes many available Display As options.

SELECT NULL display_text, 'YES' return_value FROM DUAL;

SELECT 'Click to select' display_text, 'YES' return_value FROM DUAL;

SELECT ename, empno FROM emp

SELECT ename||' '||job display_value, empno FROM emp

SELECT ename, empno FROM emp

SELECT ename display_text, empno return_value FROM emp

Referencing Item Values

You can reference item values stored in session state in regions, computations, processes, validation, and branches. Table 7-9 describes the supported syntax for referencing item values.

You can set the value of an item in your application using any of the following methods:

• For page items, use the Source Attribute to set the item value.

  From the Page Definition, select the item name to view the item attributes (called Edit Page Item). Scroll down to the Source attribute and edit the appropriate fields.

  You can also set the value of an item in any region based on PL/SQL or a process using the following syntax:

  BEGIN
   :MY_ITEM :=  'new value';
  END;
  
  

• Pass the value on an URL reference using f?p syntax. For example:

  f?p=100:101:10636547268728380919::NO::MY_ITEM:ABC
  
  

• Set the value using a computation. Computations are designed to set item values. For example:

  TO_CHAR(SYSDATE,'Day DD Month, YYYY');
  
  

• Use the PL/SQL API to set an item value within a PL/SQL context. For example:

  HTMLDB_UTIL.SET_SESSION_STATE('MY_ITEM',SYSDATE);
  
  

Displaying Conditional or Read-only Items

You can choose to have an item display conditionally by making a selection from the Conditional Display, Conditional Display Type list and entering an expression.

You can define an item a read-only by making selections under Items Is Read-only When.

Specifying an Item and Computation Type

For each computation, specify the item for which you are creating the computation as well as a computation type.

Defining a Computation Point and Computation Source

You control when a computation executes under Computation Points attributes by specifying a sequence number and a computation point. The computation point On New Instance executes the computation when a new session (or instance) is generated.

Under Computation Source, enter an expression or query to compute an item's value. In the event a computation fails, you can optionally define an error message in Computation Error Message field.

Creating Conditional Computations

You can make a computation conditional by making a selection from the Conditional Type list and entering text in the expression fields.

Creating a Page Process

You create a process by running the Create Page Process Wizard. During the page creation process, you define a process name, specify a sequence, the point at which process will execute, and a process type. You can change nearly all of these attributes on the Edit Page Process page.

Defining Processing Points and Source

You control when a process executes under Process Firing Point attributes by specifying a sequence number and a process point. You can prevent a process from running during subsequent visits to a page by selecting one of the following options under Run Process:

• Once for each page visit

• Once for each session or when reset

Under Source, enter the appropriate code for SQL or PL/SQL process types. In the event a process fails, you can optionally define an error message in the Process Error Message field.

Creating Conditional Processes

You can make a process conditional by selecting a conditional type and entering an expression under Conditional Processing attributes.

Defining How Validation Error Messages Display

You can choose to have validation error messages display inline (that is, on the page where the validation is performed) or on a separate error page.

To define how a validation error message displays:

1. In the Error Message field, enter your error message text.

2. From the Error message display location list, select a display location.

3. If you selected either Inline with Field or Inline with Field and in Notification in step 2, select the item associated with the error message from the Associated Item list.

Processing Validations Conditionally

You can control when and if a validation is performed under Conditional Validation Processing. To have a validation performed when a user clicks a button, make a selection from the When Button Pressed list.

You can add other conditions by making a selection from the Conditional Type list and entering text in the expression fields.

About Branch Types

You create a new branch by running the Create Page Branch Wizard and specifying Branch Point and Branch Type. The Branch Type defines the type of branch you are creating. For more information on Branch Types, see online help.

Defining a Branch Point and Branch Action

You specify when to create a branch by making a selection from the Branch Point list. Valid options include:

• On Submit: Before Computation - Occurs before computations, validations, or processing. Use this option for buttons that do not need to invoke any processing, for example, a "Cancel" button.

• On Submit: Before Validation - Occurs after computations, but before validations or processing. If a validation fails, page processing stops, a rollback is issued, and the page displays the error. Because of this default behavior, you do not need to create branches to accommodate validations. However, you might want to branch based on the result of a computation (for example, to the previous branch point).

• On Submit: Before Processing - Occurs after computations and validations, but before processing. Use this option to branch based on a validated session state, but before performing any page processing.

• On Submit: After Processing - Occurs after computations, validations, and processing. This option branches to an URL or page after performing computations, validations, and processing. When using this option, remember to sequence your branches if you have multiple branches for a given branch point.

• On Load: Before Header - Occurs before a page is rendered. This option displays another page instead of the current page or redirects the user to another URL or procedure.

Depending upon the Branch Type you select, you can specify the following additional information in Branch Action attributes:

• The page ID of the page you wish to branch to

• PL/SQL code

• An URL address

Branching Conditionally

Like other Application Builder components, branches can be made conditional. To create a conditional branch, make a selection from the Conditional Type list and enter text in the expression fields to implement the condition type you choose.