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

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

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:

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

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

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

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/