# Viewer Tag Library

The Viewer Tag Library allows you to access the report viewing capabilities of the Crystal report viewers without needing to embed large amounts of Java code in your JSP pages.

This section first provides a brief overview of the Viewer Tag Library, including how to set up your JSP pages to use the tag library. The section then provides a list of all the tags available, their specific uses, and relevant examples.

Click the appropriate link to jump to that section:

- Overview
- Tag reference
- Samples

## Overview

The Viewer Tag Library allows you to access the Crystal report viewers through modular and reusable tags. Using tags allows you to reduce the amount of embedded Java code in a JSP page by moving the functional implementation into the tag and its implementing class. Doing so effectively abstracts the details of the code from the presentation of the actual page, allowing the web page author to concentrate on developing JSP pages. This allows all the functionality of the Crystal report viewers to be accessed without knowing how to write Java code.

The Viewer Tag Library is made up of a primary tag, the viewer tag, and a collection of nested tags. The viewer tag supports attributes that relate to the way the Crystal report viewers appear and behave.

Using the Viewer Tag Library is equivalent to using the Viewer Java SDK to programmatically customize the viewer. It provides the same basic functionality that the Viewer Java SDK provides, supporting the same features and allowing the same level of customization over how the viewer is displayed. The advantage of using the Viewer Tag Library, however, is that it consistently generates efficient code, as the tag implementation has been carefully tested and optimized.

### Using the Viewer Tag Library

To use the tags provided by the Viewer Tag Library in a JSP page, a reference to the tag library's descriptor file is required. The following code needs to be added to the top of each JSP page using the tag library:

`<%@ taglib uri="/crystal-tags-reportviewer.tld" prefix="crviewer" %>`

## Tag reference

The Viewer Tag Library is comprised of several tags. The tag reference is designed to provide a concise description of the tags available, their supported attributes, and how the tags and attributes should be used. Each tag description follows the same format. First, a brief summary of the tag and its function are given. This is followed by a list of nested tags and a table containing a summary of all the attributes. The attributes are then described in detail.

Each attribute description provides a quick summary that states whether the tag is optional or required, its default value, and the type of value it expects. This summary is followed by a more comprehensive description of the attribute, and, if required, what specific values the attribute accepts.

The following list provides a hierarchical view of the tags available:

Viewer tag

- Report tag

## Viewer tag

The viewer tag is the main tag that instantiates the CrystalReportViewer. It handles the creation of the viewer and allows you to set viewer properties through supported attributes.

Each instance of the viewer tag requires a report tag to specify the report to be displayed. If multiple instances of the viewer will be used on a single HTML page, each instance must be given a unique name, specified through the viewerName attribute.

### Nested tags

Report tag

### Attributes

Appearance

Attribute | Description | Required
--- | --- | ---
enablePageToGrow | Sets whether the viewer takes up as much space as it needs to properly display the report. | No
height | Sets the viewer height in pixels. | No
width | Sets the viewer width in pixels. | No
left | Sets the left position of the viewer. | No
top | Sets the top position of the viewer. | No
displayGroupTree | Sets whether to display the Group Tree on viewer start up. | No
displayPage | Sets whether to display the report page. | No
displayToolbar | Sets whether to display the toolbar. | No
groupTreeWidth | Sets the width of the Group Tree in pixels. | No
groupTreeWidthUnit | Sets whether to use pixels or percentage to determine the group tree width. | No
zoomPercentage | Sets the zoom factor used when displaying the report. | No
styleSheet | Sets the stylesheet that used to display the report content. | No

Behavior

Attribute | Description | Required
--- | --- | ---
printMode | Sets whether to print using PDF or ActiveX print mode when the user clicks the print button. | No
allowDatabaseLogonPrompting | Sets whether to allow users to be prompted for database logon information. | No
allowDrillDown | Sets whether to allow the user to drill down on the report. | No
allowParameterPrompting | Sets whether to allow the user to be prompted for parameter values. | No
hyperlinkTarget | Sets the window or frame where hyperlinked documents are displayed. | No
isOwnPage | Sets whether the viewer control owns the page. | No

Toolbar

Attribute | Description | Required
--- | --- | ---
displayToolbarViewList | Sets whether to display the view list on the toolbar. | No
displayToolbarExportButton | Sets whether to display the export button on the toolbar. | No
displayToolbarFindPageButton | Sets whether to display the Go To Page button on the toolbar. | No
displayToolbarPageNavigationButtons | Sets whether to display the page navigation buttons on the toolbar. | No
displayToolbarPrintButton | Sets whether to display the print button on the toolbar. | No
displayToolbarRefreshButton | Sets whether to display the refresh button on the toolbar. | No
displayToolbarFindButton | Sets whether to display the search button on the toolbar. | No
displayToolbarToggleTreeButton | Sets whether to display the Group Tree toggle button on the toolbar. | No
displayToolbarZoomList | Sets whether to display a zoom factor drop down list on the toolbar. | No
displayToolbarCrystalLogo | Sets whether to display the Crystal Decisions logo on the toolbar. | No

Report Source

Attribute | Description | Required
--- | --- | ---
reportSourceType | Specifies the type of report source the viewer will use. | Yes
reportSourceVar | Sets the name of the variable where the report source will be cached. | No

Identification

Attribute | Description | Required
--- | --- | ---
viewerName | Sets the name of the viewer. | Yes

#### enablePageToGrow

`Optional`

`Defaults to true`

`boolean`

Sets whether the viewer ignores the height and width values it is given and try to find the best fit for the report by taking up as much space as it needs to properly display the report.

#### height

`Optional`

`Defaults to 600`

`int`

Sets the viewer height in pixels. Together, the height and width attributes control the viewer's viewable size.

#### width

`Optional`

`Defaults to 800`

`int`

Sets the viewer width in pixels. Together, the height and width attributes control the viewer's viewable size.

#### left

`Optional`

`Defaults to 0`

`int`

Sets the left position of the viewer. The units used are browser dependent.

#### top

`Optional`

`Defaults to 0`

`int`

Sets the top position of the viewer. The units used are browser dependent.

#### displayGroupTree

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the Group Tree on viewer start up.

#### displayPage

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the report page.

#### displayToolbar

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the toolbar.

#### groupTreeWidth

`Optional`

`Defaults to 200`

`int`

Sets the width of the Group Tree in pixels.

#### groupTreeWidthUnit

`Optional`

`pixel`

`String`

Sets whether to use pixels or percentage to determine the group tree width.

Use `pixel` to specify to use pixels and `percent` to specify to use percentage to determine the group tree width.

#### zoomPercentage

`Optional`

`Defaults to 100`

`int`

Sets the zoom factor used when displaying the report. Acceptable values for the zoom factor range from 10 to 400 percent.

#### styleSheet

`Optional`

`Defaults to default.css`

`String`

Sets the style sheet that used to display the report content. The cascading style sheet that you use needs to contain the same classes as the default style sheet. The default style sheet is located in the `/crystalreportviewers10/css` directory. When specifying a custom style sheet, the paths are always relative to this directory.

#### printMode

`Optional`

`Defaults to PDF`

`String`

Sets whether to print using PDF or ActiveX print mode when the user clicks the print button. In PDF print mode, a PDF is displayed, allowing the user to then print it. In ActiveX print mode, an ActiveX control is downloaded to the client machine and is sent directly to the printer. If ActiveX print mode is selected on a system that does not support ActiveX controls, the print mode defaults to PDF printing.

Use `PDF` to specify PDF print mode and `ActiveX` to specify ActiveX print mode.

#### allowDatabaseLogonPrompting

`Optional`

`Defaults to true`

`boolean`

Sets whether to allow users to be prompted for database logon information.

#### allowDrillDown

`Optional`

`Defaults to true`

`boolean`

Sets whether to allow the user to drill down on the report.

#### allowParameterPrompting

`Optional`

`Defaults to true`

`boolean`

Sets whether to allow the user to be prompted for parameter values.

#### hyperlinkTarget

`Optional`

`Defaults to _self`

`String`

Sets the window or frame where hyperlinked documents are displayed.

Use the target `_self` to display the HTML document in the same frame, `_parent` to display HTML document in the same frame or window that contains the current frameset, `_top` to display HTML document in the entire browser window, and `_blank` to display HTML document in a new browser window.

#### isOwnPage

`Optional`

`Defaults to false`

`boolean`

Sets whether the viewer control owns the page. Set this attribute to false if the page is within a portal. If the server control owns the page, it provides the opening and closing HTML tags and it is able to get and set values for the entire page.

Note: If you set isOwnPage to false then you must set the charset and the content-type of the HTML page where the viewer is displayed.

#### displayToolbarViewList

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the view list on the toolbar.

Note: The view list includes the Main Report and any views you have drilled-down into. This can include groups, charts and subreports.

#### displayToolbarExportButton

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the export button on the toolbar.

Note: isOwnPage must be set to true or the button is not rendered, regardless of the value set in the setHasExportButton method.

#### displayToolbarFindPageButton

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the Go To Page button on the toolbar.

Note: If true, the HTML returned includes a text box, into which the user can type a page number to navigate to a specific page in the report. If false, the HTML returned displays the current page, but does not allow the user to navigate by page number.

#### displayToolbarPageNavigationButtons

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the page navigation buttons on the toolbar.

#### displayToolbarPrintButton

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the print button on the toolbar. This is only available if isOwnPage is set to true.

Note: By default, printing is accomplished by automatically exporting the report to PDF and then printing the report from the PDF viewer. For systems with ActiveX support, ActiveX print mode, which uses ActiveX controls to print the report, can be used. To specify the print mode, use the printMode attribute.

#### displayToolbarRefreshButton

`Optional`

`Defaults to false`

`boolean`

Sets whether to display the refresh button on the toolbar.

#### displayToolbarFindButton

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the search button on the toolbar.

#### displayToolbarToggleTreeButton

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the Group Tree toggle button on the toolbar.

#### displayToolbarZoomList

`Optional`

`Defaults to true`

`boolean`

Sets whether to display a zoom factor drop down list on the toolbar.

#### displayToolbarCrystalLogo

`Optional`

`Defaults to true`

`boolean`

Sets whether to display the Crystal Decisions logo on the toolbar.

#### reportSourceType

`Required`

`No default value.`

`String`

Specifies the type of report source the viewer will use. For more information on report sources, see Report sources.

Possible values are:

- `reportingComponent`

  Specifies that the Java Reporting Component will be used to render the report.

- `reportApplicationServer`

  Specifies that a Report Application Server will be used as a report source.

- `pageServer`

  Specifies that a Page Server from part of a Crystal Enterprise deployment will be used as a report source.

#### reportSourceVar

`Optional`

`No default value.`

`String`

Sets the name of the session variable where the report source will be cached. Caching the report source in the browser's session allows it to be reused, improving performance when the same report source will be used multiple times.

#### viewerName

`Required`

`Defaults to CrystalViewer`

`String`

Sets the name of the viewer. The name represents the HTML form name used to post back requests to the server. When there is more than one viewer on a page, each viewer must be given a unique name, otherwise, a post back in one viewer my be sent to the wrong viewer.

### Example

The following example shows how to create a viewer with the Group Tree hidden and 80% zoom:

`<crviewer:viewer displayGroupTree="false" zoomPercentage="80" reportSourceType="reportingComponent">`

`...`

`</crviewer:viewer>`

## Report tag

The report tag is used to specify the report that is displayed by the viewer. It is required by the viewer tag, unless you are using a manually cached report source.

### Nested tags

None

### Attributes

Attribute | Description | Required
--- | --- | ---
reportName | Sets the name of the report to be viewed when an unmanaged report source is used. | Yes

#### reportName

`Required`

`No default value`

`String`

Sets the name of the report to be viewed when an unmanaged report source is used. This applies to unmanaged RAS and Java Reporting Component report sources.

For Java Reporting Component report sources, the reportName attribute can be specified using absolute or relative file paths and URLs. For more information, see Java Reporting Component.

For unmanaged RAS report sources, the reportName attribute must specify a path that is accessible by Report Application Server. That is, the path is interpreted by the Report Application Server and so local paths refer to the machine on which the RAS server is running. If you would like to access reports running on a separate machine, you must make sure that the report is accessible through a network share.

### Example

The following example shows how to view a report stored on the local file system:

`<crviewer:viewer ...>`

`<crviewer:report reportName="c:\\Reports\\World Sales.rpt" />`

`</crviewer:viewer>`

## Samples

The Viewer Tag Library is designed around simplicity and ease-of-use. The following examples demonstrate how to use the functionality provided by the tag library to view reports.

Click the appropriate link to jump to that section:

- Viewing unmanaged reports
- Viewing managed reports

### Viewing unmanaged reports

Unmanaged reports do not require authentication or other logon procedures in order to access them. Components that support unmanaged reports include the Java Reporting Component and unmanaged Report Application Servers. Viewing an unmanaged report using the Viewer Tag Library primarily relies on specifying the appropriate report source type and location of the report file.

Click the appropriate link to jump to that section:

- Viewing a report using the Java Reporting Component
- Viewing a report using an unmanaged RAS server

#### Viewing a report using the Java Reporting Component

This is a basic sample designed to show you how to use the Viewer Tag Library to display a report using the Java Reporting Component.

###### To view a report

1. Ensure that the appropriate reference to the Viewer Tag Library's descriptor file is added at the top of your JSP page.

   You must also ensure that the appropriate JAR files and additional support files are present. If you are using a wizard, this is automatically done for you.

   `<%@ taglib uri="/crystal-tags-reportviewer.tld" prefix="crviewer" %>`

   Note: You can specify any name for the prefix attribute. This just determines what tag prefix you use to access the tag library's tags.

2. Create an opening viewer tag.

   In this tag, you must specify the viewer name and the type report source that is being used.

   `<html>`

   `<body>`

   `<crviewer:viewer viewerName="CrystalViewer" reportSourceType="reportingComponent" >`

3. Create the required report tag.

   This specifies the report that is displayed.

   `<crviewer:report reportName="/reports/sample.rpt"/>`

4. Close the viewer tag.

   The JSP page is now ready to view the sample.rpt report.

   `</crviewer:viewer>`

   `</body>`

   `</html>`

#### Viewing a report using an unmanaged RAS server

This is sample shows you how to use the Viewer Tag Library to display a report using an unmanaged Report Application Server.

###### To view a report

1. Ensure that the appropriate reference to the Viewer Tag Library's descriptor file is added at the top of your JSP page.

   `<%@ taglib uri="/crystal-tags-reportviewer.tld" prefix="crviewer" %>`

   Note: You can specify any name for the prefix attribute. This just determines what tag prefix you use to access the tag library's tags.

2. Set system property to specify the location of the clientSDKOptions.xml file.

   This file is used to set the location of the RAS server.

   `<%`

   `System.setProperty("ras.config","C:\\temp");`

   `%>`

   Note: You can also set the location of the clientSDKOptions.xml file in the classpath.

3. Create an opening viewer tag.

   In this tag, you must specify the viewer name and the type report source that is being used. In this case, the reportApplicationServer report source is being used.

   `<html>`

   `<body>`

   `<crviewer:viewer viewerName="CrystalViewer" reportSourceType="reportApplicationServer" >`

4. Create the required report tag, specifying the report to be displayed.

   The reportName value is prefixed with `rassdk://` so that the RAS server can correctly locate the file.

   `<crviewer:report reportName="rassdk://c:/reports/sample.rpt"/>`

5. Close the viewer tag.

   The JSP page is now ready to view the sample.rpt report.

   `</crviewer:viewer>`

   `</body>`

   `</html>`

### Viewing managed reports

Although there are no tags that provide direct support for viewing managed reports, a combination of tags and JSP code can provide the equivalent functionality. Viewing managed reports requires you to have either a Crystal Enterprise deployment or Report Application Server running.

Click the appropriate link to jump to that section:

- Viewing a report using a Page Server
- Viewing a report using a managed RAS server

#### Viewing a report using a Page Server

This is sample shows you how to use the Viewer Tag Library to display a report using a Page Server report source.

###### To view a report using a Page Server

1. Log on to Crystal Enterprise and get an InfoStore object.

   In this case, the default administrator account is used to log on to a Crystal Enterprise installation running on the same machine as the application server.

   `<%`

   `IEnterpriseSession es = CrystalEnterprise.getSessionMgr().logon("administrator", "", "localhost", "secEnterprise");`

   `IInfoStore infoStore = (IInfoStore) es.getService("","InfoStore");`

2. Query for the report you wish to view.

   `IInfoObjects infoObjects = infoStore.query("SELECT * FROM CI_INFOOBJECTS WHERE SI_NAME='World Sales Report'");`

   `IInfoObject report = (IInfoObject) infoObjects.get(0);`

3. Create Page Server report source for the report you retrieved.

   `IReportSourceFactory2 rsFactory = (IReportSourceFactory2) es.getService("PSReportFactory");`

   `IReportSource rptSrc = rsFactory.createReportSource(report, request.getLocale());`

4. Cache the ReportSource object in a session variable.

   This allows it to be retrieved by the viewer.

   `session.setAttribute("ReportSource", rptSrc);`

   `%>`

5. Create a viewer tag, specifying the viewer name, report source type, and report source variable.

   In this case, the pageServer report source is being used and the report source variable refers to the session variable where you stored the ReportSource object.

   `<html>`

   `<body>`

   `<crviewer:viewer viewerName="CrystalViewer" reportSourceType="pageServer" reportSourceVar="ReportSource" />`

   `</body>`

   `</html>`

   Note: In this case, a report tag is not needed because the report source has already been cached in a session variable and does not to be retrieved by the viewer.

#### Viewing a report using a managed RAS server

This is sample shows you how to use the Viewer Tag Library to display a report using a managed Report Application Server report source.

###### To view a report using a managed RAS server

1. Log on to Crystal Enterprise and get an InfoStore object.

   In this case, the default administrator account is used to log on to a Crystal Enterprise installation running on the same machine as the application server.

   `<%`

   `IEnterpriseSession es = CrystalEnterprise.getSessionMgr().logon("administrator", "", "localhost", "secEnterprise");`

   `IInfoStore infoStore = (IInfoStore) es.getService("","InfoStore");`

2. Query for the report you wish to view.

   `IInfoObjects infoObjects = infoStore.query("SELECT * FROM CI_INFOOBJECTS WHERE SI_NAME='World Sales Report'");`

   `IInfoObject report = (IInfoObject) infoObjects.get(0);`

3. Create a RAS report source for the report you retrieved.

   `IReportSourceFactory2 rsFactory = (IReportSourceFactory2) es.getService("RASReportFactory");`

   `IReportSource rptSrc = rsFactory.createReportSource(report, request.getLocale());`

4. Cache the ReportSource object in a session variable.

   This allows it to be retrieved by the viewer.

   `session.setAttribute("ReportSource", rptSrc);`

   `%>`

5. Create a viewer tag, specifying the viewer name, report source type, and report source variable.

   In this case, the reportApplicationServer report source is being used and the report source variable refers to the session variable where you stored the ReportSource object.

   `<html>`

   `<body>`

   `<crviewer:viewer viewerName="CrystalViewer" reportSourceType="pageServer" reportSourceVar="ReportSource" />`

   `</body>`

   `</html>`

   Note: In this case, a report tag is not needed because the report source has already been cached in a session variable and does not to be retrieved by the viewer.

Crystal Decisions http://www.crystaldecisions.com/ Support services http://support.crystaldecisions.com/