Adding the HTML Table of Contents Tree Control to Reports

In this section:

How to:

Reference:

You can use three different types of syntax to add an HTML TOC object to a report.

Syntax: How to Add a TOC Tree Control to a Report Using a SET Command.

Using a SET command, the syntax is

At the beginning of a request: 

SET COMPOUND = 'BYTOC [n]'

In a request, use the syntax:

ON TABLE SET COMPOUND 'BYTOC [n]'

where:

n
Represents the number of vertical sort (BY) fields to include in the TOC, beginning with the first (highest-level) sort field in the request. The hierarchy of sort fields is determined by the order in which they are specified in the request.

The default value is 1, meaning that only the highest-level sort field and its values are displayed in the TOC.

By default, a section break is placed after the first (highest-level) sort field, unless otherwise specified in the request.

Note: Single quotation marks (') should be used when BYTOC is specified with a number in a SET command.

Syntax: How to Add a TOC Tree Control to a Report by Using the PCHOLD Command

Using a PCHOLD command, the syntax is 

ON TABLE PCHOLD FORMAT HTML BYTOC [n]

where:

n
Represents the number of vertical sort (BY) fields to include in the TOC, beginning with the first (highest-level) sort field in the request. The hierarchy of sort fields is determined by the order in which they are specified in the request.

The default value is 1, meaning that only the highest-level sort field and its values are displayed in the TOC.

By default, a section break is placed after the first (highest-level) sort field, unless otherwise specified in the request.

Note: Single quotation marks (') should not be used when BYTOC is specified in a PCHOLD command with a number.

Syntax: How to Add a TOC Tree Control to a Report Using a StyleSheet Declaration

The following syntax enables the TOC tree control in the StyleSheet: 

TYPE=REPORT, TOC='n',$

or

TYPE=REPORT, TOC='sortfieldname',$

where:

n

Represents the number of vertical sort (BY) fields to include in the TOC, beginning with the first (highest-level) sort field in the request. The hierarchy of sort fields in the TOC Tree is determined by the order in which they are listed in the request.

sortfieldname

Specifies the vertical sort (BY) column by its field name.

Note: Single quotation marks (') should be used when TOC is specified in the StyleSheet.

Example: Adding an HTML TOC as an Object in the Report (Report Option)

You can add an HTML TOC as an icon to the upper-left corner of a report by preceding the request with a SET command, as illustrated in the following request. The TOC will list values of the first (highest level) vertical sort field, PLANT: 

SET COMPOUND='BYTOC 2'
TABLE FILE CENTORD
HEADING
"SALES REPORT"
SUM LINEPRICE BY PLANT BY PRODCAT
ON TABLE SET PAGE-NUM OFF
ON TABLE NOTOTAL 
ON TABLE PCHOLD FORMAT HTML
ON TABLE SET HTMLCSS ON 
ON TABLE SET STYLE *
TYPE=REPORT, GRID=OFF, $
ENDSTYLE
END

You can also add an HTML TOC as an icon to the upper-left corner of a report by using a SET command within the request. 

TABLE FILE CENTORD
HEADING
"SALES REPORT"
SUM LINEPRICE BY PLANT BY PRODCAT
ON TABLE SET PAGE-NUM OFF
ON TABLE NOTOTAL 
ON TABLE PCHOLD FORMAT HTML
ON TABLE SET COMPOUND 'BYTOC 2'
ON TABLE SET HTMLCSS ON 
ON TABLE SET STYLE *
TYPE=REPORT, GRID=OFF, $
ENDSTYLE
END

The following example shows how you can use a PCHOLD command to run the request: 

TABLE FILE CENTORD
HEADING
"SALES REPORT"
SUM LINEPRICE BY PLANT BY PRODCAT
ON TABLE SET PAGE-NUM OFF
ON TABLE NOTOTAL 
ON TABLE PCHOLD FORMAT HTML BYTOC 2
ON TABLE SET HTMLCSS ON 
ON TABLE SET STYLE *
TYPE=REPORT, GRID=OFF, $
ENDSTYLE
END

In the following request, the TOC Tree control is enabled in the Report StyleSheet: 

TABLE FILE CENTORD 
HEADING
"SALES REPORT"
SUM LINEPRICE
BY PLANT BY PRODCAT
ON TABLE SET PAGE-NUM OFF
ON TABLE NOTOTAL
ON TABLE PCHOLD FORMAT HTML
ON TABLE SET HTMLCSS ON
ON TABLE SET STYLE *
TYPE=REPORT, GRID=OFF, $ 
TYPE=REPORT, TOC='PRODCAT', $ 
ENDSTYLE
END

Note: Single quotation marks (') should be used when TOC is specified in the StyleSheet.

Run the report. The TOC object displays in the upper-left corner.

Double-click the TOC icon to open the Table of Contents Tree control. This displays the values of the sort fields in the report in the order in which they have been specified.

Note: You can move the TOC by clicking the blue area above Table of Contents and then dragging it to another area of the report, or double-click on a desired location in the report.

If you wish to display all available fields (the whole report), click the View Entire Report (On/Off) option.

Tip: You can also customize the look and feel of the TOC object by editing a .css file. It is recommended that you make a backup copy prior to editing.

  • If you are working in a self service or Managed Reporting environment from a browser, go to the \ibi\WebFOCUS##\ibi_apps\ibi_html\javaassist\intl\xx directory, where ## is the release of WebFOCUS and xx is the language abbreviation. For English (EN) the .css file name is toc.css. For all other languages the .css file name is xxtoc.css, where xx is the language abbreviation.

Note: If you click Remove Table of Contents and then want to view the TOC again, simply double-click on a desired location in the report.

Reference: Grouping Sort Fields for Display

Data in a TOC report is grouped into sections based on the sort fields. TOC reports only display one section at a time for easier viewing. Each section contains all of the values for its sort field. You can customize each section with a page break. By default, a page break is included in the first (highest level) sort field. You can add page breaks to create additional sections and group data that is based on lower level sort fields.

When adding a TOC to a heading, add additional page breaks for each lower level sort field. This ensures that the sorted data is correctly grouped and displayed.

Example: Customizing Sections of the Report With a Page Break 

TABLE FILE SHORT
PRINT PROJECTED_RETURN
BY CONTINENT
BY REGION
BY COUNTRY
BY HOLDER
BY TYPE
ON HOLDER PAGE-BREAK
ON TABLE SET PAGE-NUM OFF 
ON TABLE PCHOLD FORMAT HTML
ON TABLE SET COMPOUND 'BYTOC 5'
ON TABLE SET HTMLCSS ON
ON TABLE SET STYLE *
TYPE=REPORT,
GRID=OFF,
FONT='ARIAL',
SIZE=9,
COLOR='BLACK',
BACKCOLOR='NONE',
STYLE=NORMAL,
$
ENDSTYLE
END

One section of the report is displayed at a time.

The report is broken into sections based on the values for HOLDER. You will see the detail for each value of HOLDER in a single section.

Navigation Behavior in a Multi-Level TOC

How to:

Reference:

If you select a value in the TOC, that value flashes (that is, it is highlighted in gray) to draw your attention to it in the browser window. Where the flash appears, and whether and how the screen display changes, is controlled by the following factors:

Example: Navigating Sorted Data From a Multi-Level TOC

This request adds a dynamic HTML TOC as an icon in the upper-left corner of the report by including a SET command in the request. The TOC displays a hierarchy consisting of four levels of sort fields, beginning with the first (highest-level). The sort fields are: CONTINENT, REGION, COUNTRY, and TYPE. 

TABLE FILE SHORT
PRINT PROJECTED_RETURN
BY CONTINENT
BY REGION
BY COUNTRY
BY HOLDER
BY TYPE
ON TABLE SET PAGE-NUM OFF 
ON TABLE PCHOLD FORMAT HTML
ON TABLE SET COMPOUND 'BYTOC 5'
ON TABLE SET HTMLCSS ON
ON TABLE SET STYLE *
TYPE=REPORT,
GRID=OFF,
FONT='ARIAL',
SIZE=9,
STYLE=NORMAL,
$
ENDSTYLE
END

The output is displayed with the TOC object in the upper-left corner.

Double-click the object to expand the Table of Contents.

Select View Entire Report. Scroll down to see that the report contains data for all of the continents.

Scroll back to the top of the report window and reopen the TOC. This time select Americas. Your selection flashes to highlight it on the screen. Although the report display does not appear to change, if you scroll down now you will see that the report only contains values for the Americas.

Scroll up again and double-click anywhere in the report to open the TOC. This time click the + sign next to Americas, then click the + sign next to South America.

The field values (Argentina and Brazil) are listed in the TOC. These are values of the field COUNTRY. If you wish to see the field name of a value in the TOC, hover over that value with your cursor.

Select Brazil. Your selection flashes and moves to the top of the window, as shown next.

Scroll down to see the data for Brazil.

Continue to navigate to the detail you want to view by choosing values at any sort level in the TOC.

  • Clicking a + sign expands the field to display its values in the TOC.
  • Clicking an actual value (hyperlink) in the TOC momentarily highlights that value and, if necessary, adjusts the report display to move the value into view.

    The TOC collapses to its icon when you click Table of Contents, but you can continue to scroll back, expand it, and make additional selections.

Syntax: How to Add TOC Drop-down List Controls to a Heading

Include the following attribute in your StyleSheet declaration 

TYPE=heading, [subtype,] TOC=sort_column, $

where:

heading
Is the type of heading or footing that contains the TOC.
Valid values are: 
TABHEADING

Report heading.

 
TABFOOTING

Report footing.

 
HEADING

Page heading.

 
FOOTING

Page footing.
subtype
Are attributes that identify the location in the heading or footing where each requested drop-down list will be displayed. These options can be used separately or in combination, depending upon the degree of specificity required to identify a component. Valid values are:

LINE_# identifies a line by its position in a heading or footing.

If a heading or footing has multiple lines and you apply a StyleSheet declaration that does not specify LINE_#, the declaration is applied to all lines. Blank lines are counted when interpreting the value of LINE.

LINE=n is required for a heading or footing that has multiple lines. Otherwise, you can omit it.

OBJECT identifies the TOC object in a heading or footing as a text string or field value. Valid values are TEXT or FIELD.

You can use a field and/or text as a placeholder for a TOC drop-down list. However, field is preferred. (If the TOC feature is not in effect, the field name is displayed in the report.)

TEXT may represent free text or a Dialogue Manager amper (&) variable.

It is not necessary to specify OBJECT=TEXT unless you are styling both text strings and embedded fields in the same heading or footing.

For related information, see ITEM_#.

ITEM_# which identifies an item by its position in a line.

To determine an ITEM_# for an OBJECT, follow these guidelines:

  • When used with OBJECT=TEXT, count only the text strings from left to right.
  • When used with OBJECT=FIELD, count only the fields from left to right.

If you apply a StyleSheet declaration that specifies ITEM_#, the number is counted from the beginning of each line in the heading or footing, not just from the beginning of the first line.

sort_column
Identifies the vertical sort columns (BY fields) to include as TOCs. You can identify a column using the following notations:

TOC=fieldname specifies the sort column by its field name.

TOC=Bn specifies the sort column by its order in the request. For example, B2 denotes the second BY field (NOPRINT BY fields are included in the count).

TOC=n is the same as TOC=Bn.

Note: You must maintain the hierarchy of BY fields because the TOC objects in headings (the drop-down lists) are interdependent and corresponds with the hierarchy in the report.

Example: Adding HTML TOC Drop Down Lists in a Page Heading

This request uses the required StyleSheet attributes to add a TOC to an HTML report. The drop-down TOC lists the values of the field CONTINENT, identified in the StyleSheet code as OBJECT=FIELD, ITEM=1, TOC=CONTINENT. 

TABLE FILE SHORT
HEADING
"Projected Returns Report for Region:  <REGION in Continent:  <CONTINENT "
" "
SUM PROJECTED_RETURN
BY CONTINENT
BY REGION
BY COUNTRY
BY TYPE
ON TABLE SET PAGE-NUM OFF 
ON TABLE PCHOLD FORMAT HTML
ON TABLE SET HTMLCSS ON
ON TABLE SET STYLE *
TYPE=REPORT,
GRID=OFF,
FONT='ARIAL',
SIZE=9,
STYLE=NORMAL,
$
TYPE=HEADING, LINE=1, OBJECT=FIELD, ITEM=1, TOC=CONTINENT, $
ENDSTYLE
END

When you run the report. The TOC appears as a drop-down menu in the heading, in place of the field CONTINENT:

Click the TOC to see the list of sort values: AMERICAS, ASIA, EUROPE.

Click each continent to see the related information. The selected value flashes gray to highlight it in the window.

You can display all available fields (the whole report) by clicking the View Entire Report option. To remove the TOC, click the Remove Table of Contents option. To restore the TOC, double-click anywhere in the report or click the Refresh button in your browser.

Example: Navigating a Multi-Level HTML TOC in a Page Heading

This request uses a StyleSheet to add an HTML TOC that contains drop-down lists in the third line of the page heading for two sort (BY) fields specified in the request: CONTINENT and REGION. Each field becomes a place-holder for its TOC. (If the TOC features were not in effect, the field would display in the report.) 

TABLE FILE SHORT
"Projected Return"
" "
"For:<CONTINENT For:<REGION "
SUM PROJECTED_RETURN
BY CONTINENT BY REGION BY COUNTRY BY TYPE
ON TABLE PCHOLD FORMAT HTML
ON TABLE SET HTMLCSS ON
ON CONTINENT PAGE-BREAK
ON TABLE SET STYLE *
TYPE=REPORT,
GRID=OFF,
FONT='ARIAL',
SIZE=9,
STYLE=NORMAL,
$
TYPE=HEADING, LINE=1, STYLE=BOLD, $
TYPE=HEADING, LINE=3, OBJECT=FIELD, ITEM=1, TOC=B1,$
TYPE=HEADING, LINE=3, OBJECT=FIELD, ITEM=2, TOC=REGION,$
ENDSTYLE
END

The output is:

Click the arrow in the second TOC drop-down list and select North America. Keep in mind that the values in this drop-down list are related to those in the higher level drop-down list. They are all part of the same higher level sort group, and therefore, within the same section break. The selected value, North America, flashes and moves to the top of the browser window. From there, you can scroll to see the related data, as shown in the image below.

Note that if you select information already in your field of view, the value will be highlighted in gray and will flash, to draw your attention to it.

Next, scroll up and choose ASIA from the first TOC list. This selection changes your highest-level sort group, and affects all of the lists below it. ASIA flashes and moves to the top of the window, where you see information for the first country (Hong Kong) in the Far East region. The page number is now 2 since this is the second of the high-level sort groups in the TOC.

Continue to experiment with other selections.

Reference: Navigating Between Reports

Along with techniques and tools for navigating within a report, WebFOCUS provides several mechanisms for navigating between reports. With these features, a user initiates navigation from a report display. You can:

Reference: HTML Table of Contents Limits

The TOC feature:

  • Applies to HTML output.
  • Is supported with Internet Explorer. This feature may generate unexpected behavior when using other browsers. See the Web Browser Support Statement for WebFOCUS (https://techsupport.informationbuilders.com/tech/wbf/wbf_tmo_027.html) for information on supported browsers for this and other WebFOCUS features.
  • Does not support the Dialogue Manager command -HTMLFORM.
  • Is not supported with Accordion reports.
  • You cannot designate a TOC for a BY field without also specifying a TOC for its parent (BY) fields. The reason for this is that the TOC controls are interdependent and require the physical presence of each parent control to operate correctly. For example, if the request contains BY COUNTRY BY CAR BY MODEL, a report cannot include a TOC control for CAR without also including one for COUNTRY.
  • The size of a TOC-enabled report is limited to the memory available on the WebFOCUS Client.
  • If your request has both BYTOC Table of Contents and a Heading Table of Contents in the StyleSheet, the output will have the Heading TOC.

If you have installed ReportCaster, you can distribute a report with an HTML TOC by including the following commands in the report request:

  • The SET BASEURL command set to the URL to connect to the application server on which WebFOCUS Client is installed. For information, see Specifying a Base URL.