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:
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.
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
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:
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.
Attribute | Description | Required |
---|---|---|
Sets the name of the variable where the report source will be cached. |
Attribute | Description | Required |
---|---|---|
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.
Sets the viewer height in pixels. Together, the height and width attributes control the viewer's viewable size.
Sets the viewer width in pixels. Together, the height and width attributes control the viewer's viewable size.
Sets the left position of the viewer. The units used are browser dependent.
Sets the top position of the viewer. The units used are browser dependent.
Sets whether to display the Group Tree on viewer start up.
Sets whether to display the report page.
Sets whether to display the toolbar.
Sets the width of the Group Tree in pixels.
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.
Sets the zoom factor used when displaying the report. Acceptable values for the zoom factor range from 10 to 400 percent.
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.
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.
Sets whether to allow users to be prompted for database logon information.
Sets whether to allow the user to drill down on the report.
Sets whether to allow the user to be prompted for parameter values.
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.
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
Sets whether to display the view list on the toolbar.
Note: The view
list includes the Main Report and any views you have drilled
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.
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.
Sets whether to display the page navigation buttons on the toolbar.
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.
Sets whether to display the refresh button on the toolbar.
Sets whether to display the search button on the toolbar.
Sets whether to display the Group Tree toggle button on the toolbar.
Sets whether to display a zoom factor drop down list on the toolbar.
Sets whether to display the Crystal Decisions logo on the toolbar.
Specifies the type of report source the viewer will use. For more information on report sources, see Report sources.
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.
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.
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.
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">
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.
Attribute | Description | Required |
---|---|---|
Sets the name of the report to be viewed when an unmanaged report source is used. |
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.
The following example shows how to view a report stored on the local file system:
<crviewer:report
reportName="c:\\Reports\\World Sales.rpt" />
The Viewer Tag Library is designed around simplicity and
ease
Click the appropriate link to jump to that section:
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:
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.
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
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.
In this tag, you must specify the viewer name and the type report source that is being used.
<crviewer:viewer
viewerName="CrystalViewer" reportSourceType="reportingComponent" >
This specifies the report that is displayed.
<crviewer:report reportName="/reports/sample.rpt"/>
This is sample shows you how to use the Viewer Tag Library to display a report using an unmanaged Report Application Server.
<%@ taglib uri="/crystal
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.
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.
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.
<crviewer:viewer
viewerName="CrystalViewer" reportSourceType="reportApplicationServer" >
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"/>
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:
This is sample shows you how to use the Viewer Tag Library to display a report using a Page Server report source.
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");
IInfoObjects
infoObjects = infoStore.query("SELECT * FROM CI_INFOOBJECTS WHERE
SI_NAME='World Sales Report'");
IInfoObject
report = (IInfoObject) infoObjects.get(0);
IReportSourceFactory2
rsFactory = (IReportSourceFactory2) es.getService("PSReportFactory");
IReportSource
rptSrc = rsFactory.createReportSource(report, request.getLocale());
This allows it to be retrieved by the viewer.
session.setAttribute("ReportSource",
rptSrc);
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.
<crviewer:viewer
viewerName="CrystalViewer" reportSourceType="pageServer"
reportSourceVar="ReportSource" />
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.
This is sample shows you how to use the Viewer Tag Library to display a report using a managed Report Application Server report source.
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");
IInfoObjects
infoObjects = infoStore.query("SELECT * FROM CI_INFOOBJECTS WHERE
SI_NAME='World Sales Report'");
IInfoObject
report = (IInfoObject) infoObjects.get(0);
IReportSourceFactory2
rsFactory = (IReportSourceFactory2) es.getService("RASReportFactory");
IReportSource
rptSrc = rsFactory.createReportSource(report, request.getLocale());
This allows it to be retrieved by the viewer.
session.setAttribute("ReportSource",
rptSrc);
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.
<crviewer:viewer
viewerName="CrystalViewer" reportSourceType="pageServer"
reportSourceVar="ReportSource" />
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/ |