12.3.17 Report Templates

Report column templates provide you with control over the results of a row from a SQL query. This type of template defines a cell, not an entire row.

Each report template identifies column names using the syntax #1#, #2#, #3#, and so on. You can also name columns using column name substitution syntax such as #ENAME# or #EMPNO#. You can reference any item from your application within your template. For example, to reference an item called ABC. in your template, you could include the exact substitution string &ABC.. The actual value of ABC. would be provided by an end user editing an item in your application named ABC.

• Generic Column Templates and Named Column Templates
  
• Report Column Template Attributes for Generic Column Templates
  
• Report Column Template Attributes for Named Column Templates
  
• About Using JavaScript in Column Templates
  

12.3.17.1 Generic Column Templates and Named Column Templates

Oracle Application Express includes two types of report templates:

• Generic Column Templates
  
• Named Column Templates
  

12.3.17.1.1 Generic Column Templates

A generic column template determines the appearance of a report by defining the look of the column once. This look is then repeated as many times as is necessary, based on the number of columns specified in the report's definition. This type of template is limited to reports that have a standard row and column structure. Additional style can be applied to a report using this type of template through the use of conditions.

The following example demonstrates how to have each column use a specific style:

<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

12.3.17.1.2 Named Column Templates

Named column templates allow for more flexibility in report design. However, because they reference columns by name, they can only be used by reports that are based on those columns. For example:

<tr><td>#ENAME#</td><td>#SAL#</td></tr>

Although named column templates offer flexibility, you may need to create a new template for each query. You can also include a position notation. The following example demonstrates how to use following HTML and substitution strings:

<tr><td>#ENAME#</td><td>#SAL#</td></tr>

<tr><td>#1#</td><td>#2#</td></tr>

12.3.17.2 Report Column Template Attributes for Generic Column Templates

This section describes specific sections of the Edit Report Template page for Generic Column Templates. To learn more about a specific attribute, see field-level Help.

• Report Template
  
• Before Rows
  
• Column Headings
  
• Before Each Row
  
• Column Templates
  
• After Each Row
  
• After Rows
  
• Row Highlighting
  
• Pagination Subtemplate
  
• Comments
  

12.3.17.2.1 Report Template

Template Name identifies the name of the template. Template Type indicates the type of template. Named Column templates reference column names in the template. Generic Column Templates reference the #COLUMN_VALUE# substitution string in the template.

Theme indicates the theme to which the template is a member. Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. App Builder accomplishes this template mapping through the assignment of a template class. Use the Translatable check box to indicate the template contains text strings that require translation.

12.3.17.2.2 Before Rows

In Before Rows, enter HTML that displays once at the beginning of a report template.

Opening an HTML table is a common use of this attribute as shown in the following example:

<table>

You can include pagination above a report by including the substitution string #TOP_PAGINATION#. This substitution string generates HTML that starts with an opening <tr> tag and ends with a closing </tr> tag. For example, to include an open table tag and the #TOP_PAGINATION# substitution string, you would enter the following:

<table>#TOP_PAGINATION#

You can also include the substitution string #CSV_LINK# to include support for exporting your report to comma-separated value (CSV) format, a format compatible with most spreadsheet programs.

You can also use the substitution string #REPORT_ATTRIBUTES#. This substitution string is set per report region on the report attributes page.

12.3.17.2.3 Column Headings

Use Before Column Heading to display text before report heading.

Use Column Heading Template to colorize each column header cell. The text of this attribute must include Help to indicate where the cell heading text should be colorized. For example:

<th >Item Help Text</th>

If you do not want any column headings, enter the following:

OMIT

If you do use this attribute, Application Express engine applies the default column heading template.

Use After Column Heading to display text after report headings.

12.3.17.2.4 Before Each Row

In Before Each Row, enter text to display before all columns in the report. Use this attribute to open a new HTML row. Before Each Row supports the following substitution strings:

• #ROWNUM#

  Use this substitution string to specify the current row.

• #COLCOUNT#

  Use this substitution string to specify the number of columns.

• #HIGHLIGHT_ROW#

  Use this substitution string to specify the number of highlighted rows.

12.3.17.2.5 Column Templates

Column templates define the look of each column. You can define up to four column templates; each can be conditional. For example, you can have different background colors for even and odd rows, or highlight rows that meet a PL/SQL defined condition.

In each Column Template, you define the look of each column. Column Templates support the substitution strings described in Table 12-14.

Table 12-14 Column Template Substitution Strings

Substitution String	Description
#ALIGNMENT#	Determines the column alignment. Specified by the user.
#COLCOUNT#	Defines the count of the number of columns.
#COLNUM#	Defines the current column number.
#COLUMN_HEADER#	Defines the column header.
#COLUMN_VALUE#	Replaced with the value of the column.
#ROWNUM#	Specifies the current row number.

Consider the following example:

<td> #ALIGNMENT#>#COLUMN_VALUE#</td>

If you actually ran this report, these substitution strings would be replaced with values generated by the results of a SQL query.

By creating conditions, you can create a report that displays columns differently depending on whether the specified condition is met. To specify a column template be used conditionally, select a condition type from the Column Template Condition list. Valid values include:

• Use Based on PL/SQL Expression. Conditionally formats columns based on data in that row.

• Use for Even Numbered Rows. Conditionally formats even numbered rows.

• Use for Odd Numbered Rows. Conditionally formats odd numbered rows.

If you select Use Based on PL/SQL Expression, the next step is to enter a PL/SQL expression in the Column Template Expression field. For example, the following expression displays a value in bold if the value is greater than 2000:

#SAL# > 2000

You could also use the substitution string #ROWNUM#. For example:

#ROWNUM# > 2000

12.3.17.2.6 After Each Row

In After Each Row, enter HTML that displays after all columns in the report display. This attribute is often used to close an HTML table row. For example:

</tr>

12.3.17.2.7 After Rows

Use After Rows to specify text that should display after the last row. A common use of this attribute is to close the HTML table tag. For example:

</table>

The After Rows attribute supports the following substitution strings:

• #PAGINATION#

  Replaced with a pagination attribute.

• #COLCOUNT#

  Substituted at runtime with the number of columns defined in the report.

• #CSV_LINK#

  Substituted at runtime with CSV download link if CSV export is enabled. Otherwise the string is not shown.

• #EXTERNAL_LINK#

  Substituted at runtime with the download link for exports using external processing engine for (for example, PDF export). If this feature is not enabled, the string is not shown.

12.3.17.2.8 Row Highlighting

Background color for checked row controls the background color of a report row when the row selector is checked. Background color for current row controls the background color of a report row when the user moves the mouse over the row.

12.3.17.2.9 Pagination Subtemplate

The Pagination Subtemplate section contains attributes for editing the Pagination Template, Next Page Template, Previous Page Template, Next Set Template, and Previous Template. Pagination Subtemplates support the substitution strings #PAGINATION_NEXT#, #PAGINATION_NEXT_SET#, #PAGINATION_PREVIOUS# and #PAGINATION_PREVIOUS_SET#. Table 12-17 describes these templates.

Table 12-15 Pagination Subtemplate Attributes

Pagination Subtemplate Attribute	Description
Pagination Template	Applies to the entire pagination subtemplate. For example: <span class="instructiontext">#TEXT#</span> Use the substitution string #TEXT# to specify where you want the pagination subtemplate to display. Use the other Pagination Subtemplate attributes to modify individual items.
Next Page Template	Enter HTML to modify how the Next Page portion of the pagination subtemplate appears. For example: <a href="#LINK#">next</a>
Previous Page Template	Enter HTML to modify how the Previous Page portion of the pagination subtemplate appears. For example: <a href="#LINK#">previous</a>
Next Set Template	Enter HTML to modify how the Next Set portion of the pagination subtemplate appears. For example: <a href="#LINK#">next set</a>
Previous Set Template	Enter HTML to modify how the Previous Set portion of the pagination subtemplate appears. For example: <a href="#LINK#">previous set</a>

12.3.17.2.10 Comments

Use this attribute to record comments about this component.

12.3.17.3 Report Column Template Attributes for Named Column Templates

This section describes specific sections of the Edit Report Template page for Named Column Templates. You can access the sections of the page by either scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

• Name
  
• Subscription
  
• Row Templates
  
• Column Headings
  
• Before first and after last row text
  
• Pagination
  
• Comments
  

12.3.17.3.1 Name

Template Name identifies the name of the template. Template Type indicates the type of template. Named Column templates reference column names in the template. Generic Column Templates reference the #COLUMN_VALUE# substitution string in the template.

Theme indicates the theme to which the template is a member. Use the Translatable check box to indicate the template contains text strings that require translation. Template Class identifies a specific use for the template. When you switch to a new theme, all templates in one theme are mapped to corresponding templates in another theme. App Builder accomplishes this template mapping through the assignment of a template class.

12.3.17.3.2 Subscription

Use Subscription 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.

12.3.17.3.3 Row Templates

Row templates define the look of each column. You can define up to four row templates, each of which can be conditional.

In each Row Template, you define the look of each row. Row Templates support the substitution strings described in Table 12-16.

Table 12-16 Row Template Substitution Strings

Substitution String	Description
#ALIGNMENT#	Determines the row alignment. Specified by the user.
#COLCOUNT#	Defines the count of the number of columns.
#COLNUM#	Defines the current column number.
#COLUMN_HEADER#	Defines the column header.
#COLUMN_VALUE#	Replaced with the value of the column.
#ROWNUM#	Specifies the current row number.

By creating conditions, you can create a report that displays rows differently depending on whether the specified condition is met. To specify a row template be used conditionally, select a condition type from the Column Template Condition list. Valid values include:

• Use Based on PL/SQL Expression. Conditionally formats columns based on data in that row.

• Use for Even Numbered Rows. Conditionally formats even numbered rows.

• Use for Odd Numbered Rows. Conditionally formats odd numbered rows.

If you select Use Based on PL/SQL Expression, the next step is to enter a PL/SQL expression in the Column Template Expression field. For example, the following expression displays a value in bold if the value is greater than 2000:

#SAL# > 2000

You could also use the substitution string #ROWNUM#. For example:

#ROWNUM# > 2000

12.3.17.3.4 Column Headings

Use this template to add color to each column header cell. The text of this attribute must include help to indicate where the cell heading text should be colorized. If you do not enter a Column Heading Template, then a default column header template is applied. If you do not want any column headings, then enter OMIT. For example:

 <th #ALIGNMENT#>#COLUMN_HEADER#</th>

12.3.17.3.5 Before first and after last row text

In Before Rows, enter HTML that displays once at the beginning of a report template. Opening an HTML table is a common use of this attribute, as shown in the following example:

<table>

You can identify column headers using the syntax #1#, #2#, #3#. For example:

<th>#1#</th><th>#2#</th><th>#3#</th>

You can include pagination above a report by including the substitution string #TOP_PAGINATION#. This substitution string generates HTML that starts with an opening <tr> tag and ends with a closing </tr> tag. For example, to include an open table tag and #TOP_PAGINATION# substitution string, you would enter the following:

<table>#TOP_PAGINATION#

You can also include the substitution string #CSV_LINK# to include support for exporting your report to CSV format, a format compatible with most spreadsheet programs.

Use After Rows to specify text that should display after the last row. A common use of this attribute is to close the HTML table tag. For example:

</table>

The After Rows attribute supports the following substitution strings:

• #PAGINATION#

  Replaced with a pagination attribute.

• #COLCOUNT#

  Substituted at runtime with the number of columns defined in the report.

12.3.17.3.6 Pagination

The Pagination section contains attributes for editing the Pagination Template, Next Page Template, Previous Page Template, Next Set Template, and Previous Template. Pagination Subtemplates support the substitution strings #PAGINATION_NEXT#, #PAGINATION_NEXT_SET#, #PAGINATION_PREVIOUS# and #PAGINATION_PREVIOUS_SET#. Table 12-17 describes these templates.

Table 12-17 Pagination Subtemplate Attributes

Pagination Subtemplate Attribute	Description
Pagination Template	Applies to the entire pagination subtemplate. For example: <span class="instructiontext">#TEXT#</span> Use the substitution string #TEXT# to specify where you want the pagination subtemplate to display. Use the other Pagination Subtemplate attributes to modify individual items.
Next Page Template	Enter HTML to modify how the Next Page portion of the pagination subtemplate appears. For example: <a href="#LINK#">next</a>
Previous Page Template	Enter HTML to modify how the Previous Page portion of the pagination subtemplate appears. For example: <a href="#LINK#">previous</a>
Next Set Template	Enter HTML to modify how the Next Set portion of the pagination subtemplate appears. For example: <a href="#LINK#">next set</a>
Previous Set Template	Enter HTML to modify how the Previous Set portion of the pagination subtemplate appears. For example: <a href="#LINK#">previous set</a>

12.3.17.3.7 Comments

Use this attribute to record comments about this component.

12.3.17.4 About Using JavaScript in Column 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>;</TD>
</TR>
</TR>
<TD>#GROUP_DESC#</TD>
          	</TR>" );
	</TR>" );

See Also:

"About Regions"