Formatting Report Output in Oracle HTML DB Using Report Templates
Author: Raj Mattamal
Date: August 2004

In HTML DB, the layout of data displayed in report regions is ultimately controlled by report templates. In addition to facilitating basic formatting, however, report templates in HTML DB give application developers the opportunity to reference the data in a current row while determining how it is to be displayed. This ability to easily reference report data makes report templates in HTML DB a very powerful feature.

This Technical Note will provide an overview of report templates while illustrating how they can be used to achieve specific implementation goals.

Overview of HTML DB Report Templates

HTML DB offers two kinds of report templates: Report Column Templates and Report Row Templates. Report Column templates are the simpler of the two types; they specify the HTML to be used when rendering columns in a report row. Because each column in a report column template is handled the same way, these template types are sometimes called "Generic Column" templates. In the case of Report Row Templates, each column to be displayed must be referenced. Because row templates allow the developer to reference individual columns, even more control over look and feel is possible.

What follows is a set of five examples in which report templates are used to achieve specific report layouts. To follow along with the examples, log into an HTML DB workspace with access to a copy of the SCOTT.EMP table. The examples covered will include:

1. Displaying Data Vertically as Opposed to Horizontally
2. Displaying Single Records Across Multiple Rows
3. Color-Coding Data
4. Using Session State Values when Conditionally Rendering Report Row Buttons
5. Controlling Text Wrapping in Lengthy Report Columns

Displaying data vertically as opposed to horizontally

Although report data is most often displayed using a single row for each record, developers will at times wish to display each column as its own row. This formatting gives the report a vertical look that's most often used when single records are being displayed at a time. The easiest way to achieve this look is to use the built-in "vertical" style report templates that are available for every report region in HTML DB. These templates include:

• default: vertical report, look 1 (exclude null columns)
• default: vertical report, look 1 (include null columns)
• default: vertical report, look 2 (exclude null columns)
• default: vertical report, look 2 (include null columns)

To call your report template from a report region, navigate to the Report Attributes screen for your report region and select "Simple Column" in the "Report Template" field as shown in Figure 1, below.

Figure 1: Changing the Report Template Selection for a Report Region

To make this new template render data vertically, one simple change is necessary. First go to the "Edit Report Template" screen for the new "Simple Column" template by clicking the edit icon next to its name in the "Report Templates: (Row and Column templates)" region. A quick glance over this screen show that only three fields are populated:

• Before Rows = <table>
• Column Template 1 = <td>#COLUMN_VALUE#</td>
• After Rows = </table>

These, of course, are the most basic attributes necessary for a report column template to render data. To change the template to render data vertically, you would need to change the "Column Template 1" code to display one row per column value as well as the name of the current column. To address these concerns, update "Simple Column" as shown in Figure 2 by entering the pattern:

<tr><td>#COLUMN_HEADER#</td><td>#COLUMN_VALUE#</td></tr>

into the "Column Template 1" field.

Figure 2: Modifying the HTML Pattern Used in a Report Column Template

As explained in the attribute-level help for that "Column Template 1" field, the substitution string, #COLUMN_HEADER#, returns the name of the current column. Being generic in nature, your "Simple Vertical" template can be used to display the data from any HTML DB report region in a vertical fashion.

Displaying Single Records Across Multiple Rows

To display a single record across two or more rows, it is necessary to define a Report Row Template in which you define your line breaks. Say, for instance, you were creating a report on the EMP table in the SCOTT schema that used a query like this:

select empno, ename, job, mgr, hiredate, sal, comm, deptno from emp

Creating a basic row template

1. From the HTML DB Application Builder home, click the "Templates" standard tab
2. In the "Report Templates: (Row and Column templates)" region, click Create/Copy
3. Choose "From Scratch" and click Next
4. Select "Named Column (row template)" from the "Report Type" list of values.
5. As shown in Figure 2, enter the HTML pattern to be used for each row into the "Template 1" field:

   <tr>
    <td>#EMPNO#</td>
    <td>#ENAME#</td>
    <td>#JOB#</td>
    <td>#MGR#</td>
    <td>#HIREDATE#</td>
    <td>#SAL#</td>
    <td>#COMM#</td>
    <td>#DEPTNO#</td>
   </tr>
   

6. Click Next
7. Name the new template "Simple Row" and click Create

Now that you have a Simple Row template, copy it and modify that copy to become the split row template that we're after:

Copy the "Simple Row" template and name it "Split Row"

Figure 3: Copying the "Simple Row" Template for Modification

Next, edit "Split Row" to render each returned record set as two rows:

Color-Coding Data

In some cases, developers need to color-code data based on selected values. Although it is possible to do so by selecting the required HTML out in the report query, it is most cleanly implemented using a report template.

Say, for example, you'd like to have your report on EMP render salaries over $2500 in red. You could do this by copying and modifying your Simple Row template as follows:

Copy the "Simple Row" template and call it "Color-Coded Salaries"

Next, edit "Color-Coded Salaries" to render salaries greater than $2500 in red:

Figure 4: Adding a Condition to "Row Template 1 Expression"

When you run this report now, you'll find your salary values greater than $2500 to be rendered in red. The mechanics behind this implementation are quite simple: If you review the template definition screen for "Color-Coded Salaries", you'll see that HTML DB tries to use your "Row Template 1" pattern if your "Row Template 1 Condition" resolves to TRUE. if not, it uses "Row Template 2". Notice, too, that HTML DB currently allows for four such conditionally displayed row patterns in a given report template.

Using Session State Values When Conditionally Rendering Report Row Buttons

Often, developers will want to display buttons in each row of a report to allow users to perform actions on the displayed data. In some cases developers will need to render different buttons for different rows depending on certain conditions. To explore this case, let's imagine that our management has decided that "Finance" users in our system will be allowed to adjust salaries higher than $2500. All other users will simply be give the ability to view the available emps. Management further decided this functionality should be available as button links shown in our EMP report. Assuming we have an item in our application called CURRENT_USER_TYPE, and we want only those users with CURRENT_USER_TYPE = 'Finance' to see our Edit buttons, this requirement could be implemented as follows:

Copy the "Color-Coded Salaries" template while naming it "Adjustable Color-Coded Salaries"

Next, edit "Adjustable Color-Coded Salaries" to render the appropriate buttons for each row:

Figure 5: Conditionally Displayed Column Links Based on Session State

Controlling Text Wrapping in Lengthy Report Columns

Sometimes developers want the text within report columns to not wrap even if that means the user has to scroll horizontally to see all the data. This simple example shows how to control such wrapping attributes from the report template level. First, let's update the JOB column to contain much more text than it already does:

If you run the report now, you'll find that the text in the JOB column wraps in such a way that all the columns of the report region fit cleanly within the screen's width. This rendering is default html behavior. To force your data to not wrap the text in that JOB column, specify nowrap for the white-space style attribute for the table data cell that renders that column. For simplicity's sake, make this change to a copy of your "Basic Row" template:

Copy the "Simple Row" template and call it "Unwrapped Job Rows"

Next, edit "Unwrapped Job Rows" to not wrap the JOB column:

When you run this report now, you will find your JOB column no longer wraps its data to fit to your screen's width.

Summary

In previous these five examples, you've hopefully gained a better appreciation for the power and flexibility provided by the Report Template features within HTMLDB. To recap, you've used HTML DB Report Templates to: