PUBLIC

SAP BusinessObjects Business Intelligence platform

Document Version: 4.2 SP4 – 2020-06-12

SAP Crystal Reports JavaScript API Developer

Guide
© 2020 SAP SE or an SAP affiliate company. All rights reserved.

THE BEST RUN

Content

1 Document History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 About the SAP Crystal Reports JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Using the SAP Crystal Reports JavaScript API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.1 Create a report viewer and open a report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2 Show and hide viewer controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.3 Change the look and feel the JavaScript viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4 Event listeners. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 API reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

4.1 SAP.CR.Viewer.ActionListener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
onEvent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
removeEvent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2 SAP.CR.Viewer.CanvasListener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
onEvent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
removeEvent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.3 SAP.CR.Parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
addValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
setReportName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.4 SAP.CR.Parameter.RangeValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
setBeginValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
setEndValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
setLowerBound. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
setUpperBound. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.5 SAP.CR.Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
addActionListener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
addCanvasListener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
batchExecute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
create. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
drilldown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
getInstance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
refresh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
removeActionListener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
removeCanvasListener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
setDisplayBreadcrumb. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
setDisplayLeftPanel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
setDisplayStatusBar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

SAP Crystal Reports JavaScript API Developer Guide

2 PUBLIC Content
 setDisplayToolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
setHasLogo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
setHasRefreshButton. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
setLogo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
setPageNumber. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
setParameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
setPrintMode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
setPromptOnRefresh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
setReportMode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
setReportSource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
setEnableDrillDown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
setToolPanelViewMode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
setHasToggleGroupTreeButton. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
setHasToggleParameterPanelButton. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
setHasSearchButton. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.6 SAP.CR.Viewer.ThemeManager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
setThemeColor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
setThemeFont. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

SAP Crystal Reports JavaScript API Developer Guide

Content PUBLIC 3
1 Document History

Version Date Description

SAP BusinessObjects Business November 2015 Updated the guide with branding
Intelligence platform 4.2 changes.

SAP BusinessObjects Business March, 2017 The following 5 new APIs were added
Intelligence platform 4.2, Support within API reference → SAP.CR.Viewer
Package 4
● setEnableDrillDown
● setToolPanelViewMode
● setHasToggleGroupTreeButton
● setHasToggleParameterPanelButt
on
● setHasSearchButton

SAP Crystal Reports JavaScript API Developer Guide

4 PUBLIC Document History
2 About the SAP Crystal Reports
JavaScript API

With the SAP Crystal Reports JavaScript API, you can display Crystal reports content in an embedded web
application without any client-side component installation. The JavaScript API lets you customize the report
viewer, and add interactivity to your Crystal reports content. You can develop your web application in any
language that uses JavaScript, because reports are generated in DHTML.

API features include:

● Event listeners for mouse clicks and mouse over events.

● Action listeners for printing and exporting events.
● Methods to customize color and font.
● Methods to show and hide viewer components.

The JavaScript API supports most OpenDocument parameters. If you previously used OpenDocument URLs to
link to reports stored in the BI Platform repository, you can transition to the JavaScript API without losing
functionality.

SAP Crystal Reports JavaScript API Developer Guide

About the SAP Crystal Reports JavaScript API PUBLIC 5
3 Using the SAP Crystal Reports JavaScript
API

The SAP Crystal Reports JavaScript API is included as part of the SAP BusinessObjects Business Intelligence
Platform installation. The API can be accessed by referencing the ViewerSeed.js file located on the BIP
server.

General workflow, shown in detail in this guide:

1. Find the location of the ViewerSeed.js file. In a typical BIP installation, the file is available at the following
location: http://localhost:8080/clientapi/CR/ViewerSeed.js
2. Retrieve a logon token to use for BI platform authentication.
3. Add a reference to the ViewerSeed.js file to your web application.
4. Add the CR Embedded viewer to your web application.
5. Set the report source.

 Note

If you are developing your application on your local computer instead of on deployed to a web server, the
Adobe Flash Player may prevent the Flex prompting dialog from appearing. You can resolve this issue by
deploying your application to a web server or designating your application content as trusted in the Flash
Player Global Security Settings.

3.1 Create a report viewer and open a report

1. Set up head, style and body opening and closing tags.

2. Add a script tag within the head tags and use it to reference ViewerSeed.js.

<script src="http://localhost:8080/clientapi/CR/ViewerSeed.js">

3. Create a token variable, which will hold the logon token and set it to null.

var token = null;

4. Create a function called init that sets the value of token to the logon token and creates a new JavaScript
viewer instance.
Refer to the Business Intelligence Platform RESTful Web Services Developer Guide for information on
generating a logon token.

init(){
token = "logonToken";
SAP.CR.Viewer.create("viewerName","container",onViewerInit);
}

SAP Crystal Reports JavaScript API Developer Guide

6 PUBLIC Using the SAP Crystal Reports JavaScript API
 5. Add a function called onViewerInitthat sets the report source.

function onViewerInit(viewerInstance){
viewerInstance.setReportSource('reportID', token);
}

The reportID is the numerical code assigned to a report.

You can discover the report ID programmatically or through the Central Management Console (CMC).
When you right-click a report in the CMC, the report ID is be listed with the report properties. For more
information see the SAP Crystal Reports RESTful web services API.
6. Within the body tag set onload event handler equal to the init function.

<body onload="init()">

This calls the initialization function once the page is fully loaded, which causes any text or buttons coded
into the body to load before the report viewer.
7. Within the style tag create a new class that defines the position and size of the JavaScript viewer. In the
code below the viewer is given absolute positioning. Its width and height will be 75% of the size of the width
and height of the page the viewer will be opened in. The position of the viewer in the page is specified by
the left and top properties.

.viewerStyle
{
position : absolute;
left : 12.5%;
top : 20.5%;
width : 75%;
height : 75%;
}

8. Within the body tags add code to set the style of the viewer.

<div id="container" class="viewerStyle"></div>

Example: Create a report viewer and open a report

The following example opens a report with report ID 1234 in a report viewer given the name crystalViewer. The
value set to the token variable in the init function is an example.The value you use must be generated by you.
The viewer is given absolute positioning. Its width and height will be 75% of the size of the width and height of
the page the viewer will be opened in. The position of the viewer in the page is specified by the left and top
properties. The onViewerFailure function is optional.

<head>

<script src="http://computername/clientapi/CR/ViewerSeed.js">
<script>
var token = null;
function init(){
token = "COMMANDCOM-LCM:6400@{3&2=5328,U3&p=40676
.8926203819,Y7&4F=12,U3&63=secEnterprise
,0P&66=60,03&68=secEnterprise:Administrator
,0P&qe=100,U3&vz=IVD21LbMCB0eRiI4at
z9sNL18Ux5anRBdYB9fFv5NrY,UP}";
SAP.CR.Viewer.create("crystalViewer", 'viewerContainer1', onViewerInit,
onViewerFailure);

SAP Crystal Reports JavaScript API Developer Guide

Using the SAP Crystal Reports JavaScript API PUBLIC 7
 }
function onViewerInit(){
viewerInstance.setReportSource('1234', token);
}
function onViewerFailure(instance, error){
alert(error);
}

</script>
</head>
<style>

.viewerStyle
{
position : absolute;
left : 12.5%;
top : 20.5%;
width : 75%;
height : 75%;
}
</style>
<body>

<div id="viewerContainer1" class = "viewerStyle"></div>

</body>

3.2 Show and hide viewer controls

The JavaScript API allows you to show or hide the following browser controls in the JavaScript viewer:

● The left panel (used to find, set parameters and view the Group Tree.)
● The toolbar.
● The status bar.
● The page navigation bar.

This is done by setting the control to true or false. By default all browser controls are set to true.

Example

The following code causes all control bars and panels to be displayed, except for the status bar.

var viewerInstance = SAP.CR.Viewer.getInstance("crystalViewer");

viewerInstance.setDisplayToolbar(true);
viewerInstance.setDisplayLeftPanel(true);
viewerInstance.setDisplayStatusbar(false);
viewerInstance.setDisplayBreadcrumb(true);

SAP Crystal Reports JavaScript API Developer Guide

8 PUBLIC Using the SAP Crystal Reports JavaScript API
3.3 Change the look and feel the JavaScript viewer

The JavaScript API allows you to customize the color and font used in the JavaScript viewer.

Example

The following example changes the color of the viewer to a light purple gradient and the font to Times. The first
parameter in the setThemeColor method is the hexidecimal representation of a color. Use of true instead of
false as the boolean value of the second parameter gives the viewer a solid color instead of a gradient.

SAP.CR.Viewer.ThemeManager.setThemeColor("#CDB7F9", false);
SAP.CR.Viewer.ThemeManager.setThemeFont("times");

3.4 Event listeners

The JavaScript API supports canvas and action event listeners. Event listeners detect when a certain event has
occured, and then trigger a response. Canvas events are mouse events (clicks and mouse-overs) that occur on
the report canvas. Action listeners deal with action events, such as clicking a button or selecting an item from a
list.

Example

The following code causes report objects to get highlighted in green on a mouseover event. When the curser
leaves the report object the background color property is cleared. This means that the default background
color of the object is not restored.

var canvasListener = new SAP.CR.Viewer.CanvasListener();

var viewerInstance = SAP.CR.Viewer.getInstance("crystalViewer");

canvasListener.onEvent(SAP.CR.Viewer.CanvasEvents.REPORT_ELEMENT_MOUSE_ENTER,func
tion(args){
args.target.style.backgroundColor="green";
});
canvasListener.onEvent(SAP.CR.Viewer.CanvasEvents.REPORT_ELEMENT_MOUSE_LEAVE,func
tion(args){
args.target.style.backgroundColor=" ";
});
viewerInstance.addCanvasListener(canvasListener);

SAP Crystal Reports JavaScript API Developer Guide

Using the SAP Crystal Reports JavaScript API PUBLIC 9
Related Information

SAP.CR.Viewer.CanvasListener [page 13]

SAP.CR.Viewer.ActionListener [page 11]

SAP Crystal Reports JavaScript API Developer Guide

10 PUBLIC Using the SAP Crystal Reports JavaScript API
4 API reference

This section provides a reference of the classes and methods in the JavaScript API.

4.1 SAP.CR.Viewer.ActionListener

The ActionListener class allows you to add custom functionality for viewer action events, for most items in
the toolbar.

Syntax

var actionListener = new SAP.CR.Viewer.ActionListener();

4.1.1 onEvent

The onEvent method registers an action listener for an event. Multiple listeners can be registered for the same
event.

Syntax

var actionListener = new SAP.CR.Viewer.ActionListener();

actionListener.onEvent(eventName,listener);

Parameters

● eventName - The name of the event.

Possible values:

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 11
 Value Description

SAP.CR.Viewer.ActionEvents User clicks the export button.

.EXPORT

SAP.CR.Viewer.ActionEvents User clicks the print button.

.PRINT

SAP.CR.Viewer.ActionEvents User drills down to the report from the group tree,
.DRILL breadcrumb, content or a chart.

SAP.CR.Viewer.ActionEvents User clicks on a group tree node that changes the page
.GROUP_TREE_NAVIGATE being viewed.

SAP.CR.Viewer.ActionEvents Report prompts for database or parameters.

.PROMPT

SAP.CR.Viewer.ActionEvents An error occurs in the viewer.

.ERROR

● listener - [function(arg)] Custom function that you define, that determines what happens when the
event occurs. The parameter arg can be given any name except for JavaScript keyword names, and is
created by the handler of the report viewer and passed to the function.

4.1.2 removeEvent

The removeEvent method removes listeners from an ActionListener object. The method can be used to
remove a specific listener, with an associated event name or to remove all listeners with an associated event
name.

Syntax

var actionListener = new SAP.CR.Viewer.ActionListener();

actionListener.removeEvent(eventName,listener);

Parameters

● eventName - The name of the event to be removed.

Possible values:

SAP Crystal Reports JavaScript API Developer Guide

12 PUBLIC API reference
 Value Description

SAP.CR.Viewer.ActionEvents User clicks the export button.

.EXPORT

SAP.CR.Viewer.ActionEvents User clicks the print button.

.PRINT

SAP.CR.Viewer.ActionEvents User drills down to the report from the group tree,
.DRILL breadcrumb, content or a chart.

SAP.CR.Viewer.ActionEvents User clicks on a group tree node that changes the page
.GROUP_TREE_NAVIGATE being viewed.

SAP.CR.Viewer.ActionEvents Report prompts for database or parameters.

.PROMPT

SAP.CR.Viewer.ActionEvents An error occurs in the viewer.

.ERROR

● listener - [function(arg)] The specific listener to be removed. A custom function defined by the user
when the event listener was created.

4.2 SAP.CR.Viewer.CanvasListener

The CanvasListener class allows you to add custom functionality for mouse events that occur on the report
page.

Syntax

var canvasListener = new SAP.CR.Viewer.CanvasListener();

4.2.1 onEvent

The onEvent method registers a canvas listener for an event. Multiple listeners can be registered for the same
event.

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 13
Syntax

var canvasListener = new SAP.CR.Viewer.CanvasListener();

canvasListener.onEvent(eventName,listener);

Parameters

● eventName - The name of the event.

Possible values:

Value Description

SAP.CR.Viewer.CanvasEvents Curser enters a report element.

.REPORT_ELEMENT_MOUSE_ENTER

SAP.CR.Viewer.CanvasEvents Curser leaves a report element.

.REPORT_ELEMENT_MOUSE_LEAVE

SAP.CR.Viewer.CanvasEvents User clicks a report element.

.REPORT_ELEMENT_CLICK

SAP.CR.Viewer.CanvasEvents User right-clicks a report element.

.REPORT_ELEMENT_RIGHT_CLICK

SAP.CR.Viewer.CanvasEvents Curser enters the report canvas.

.REPORT_CANVAS_MOUSE_ENTER

SAP.CR.Viewer.CanvasEvents Curser leaves the report canvas.

.REPORT_CANVAS_MOUSE_LEAVE

SAP.CR.Viewer.CanvasEvents User clicks the report canvas.

.REPORT_CANVAS_CLICK

SAP.CR.Viewer.CanvasEvents User right-clicks the report canvas.

.REPORT_CANVAS_RIGHT_CLICK

● listener - [function(arg)] Custom function that you define, that determines what happens when the
event occurs. The parameter arg can be given any name except for JavaScript keyword names, and is
created by the handler of the report viewer and passed to the function.

SAP Crystal Reports JavaScript API Developer Guide

14 PUBLIC API reference
4.2.2 removeEvent

The removeEvent method removes listeners from a CanvasListener object. The method can be used to
remove a specific listener, with an associated event name or to remove all listeners with an associated event
name.

Syntax

var canvasListener = new SAP.CR.Viewer.CanvasListener();

canvasListener.removeEvent(eventName,listener);

Parameters

● eventName - The name of the event to be removed.

Possible values:

Value Description

SAP.CR.Viewer.CanvasEvents Curser enters a report element.

.REPORT_ELEMENT_MOUSE_ENTER

SAP.CR.Viewer.CanvasEvents Curser leaves a report element.

.REPORT_ELEMENT_MOUSE_LEAVE

SAP.CR.Viewer.CanvasEvents User clicks a report element.

.REPORT_ELEMENT_CLICK

SAP.CR.Viewer.CanvasEvents User right-clicks a report element.

.REPORT_ELEMENT_RIGHT_CLICK

SAP.CR.Viewer.CanvasEvents Curser enters the report canvas.

.REPORT_CANVAS_MOUSE_ENTER

SAP.CR.Viewer.CanvasEvents Curser leaves the report canvas.

.REPORT_CANVAS_MOUSE_LEAVE

SAP.CR.Viewer.CanvasEvents User clicks the report canvas.

.REPORT_CANVAS_CLICK

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 15
 Value Description

SAP.CR.Viewer.CanvasEvents User right-clicks the report canvas.

.REPORT_CANVAS_RIGHT_CLICK

● listener - [function(arg)] The specific listener to be removed. A custom function defined by the user
when the event listener was created.

4.3 SAP.CR.Parameter

The SAP.CR.Parameter class allows you to create parameters and add them to a viewer instance. The class
can also be used to set parameter values in a sub-report.

Syntax

var param = new SAP.CR.Parameter(parameterName,parameterType);

Parameters

● parameterName - [String] The name of the parameter in the report. This value is often pre-defined by the
report.
● parameterType - The type of the parameter.
Possible values:

Value Description

SAP.CR.Parameter Boolean value (true or false.)

.DataTypes.BOOLEAN

SAP.CR.Parameter Numerical value.

.DataTypes.CURRENCY

SAP.CR.Parameter Date and time specified using the JavaScript Date

.DataTypes.DATE_TIME function.

SAP.CR.Parameter Date specified using the JavaScript Date function.

.DataTypes.DATE

SAP Crystal Reports JavaScript API Developer Guide

16 PUBLIC API reference
 Value Description

SAP.CR.Parameter Time specified using the JavaScript Date function.

.DataTypes.TIME

SAP.CR.Parameter Numerical value.

.DataTypes.NUMBER

SAP.CR.Parameter String value.

.DataTypes.STRING

4.3.1 addValue

Sets the value of a parameter.

Syntax

var param = new SAP.CR.Viewer.Parameter(parameterName,parameterType);

param.addValue(val);

Parameters

● val - Parameter value. The type depends on parameterType. Can be a discreet or range value.

4.3.2 setReportName

Sets the parameters of a sub report. If you do not use the setReportName method the parameters are
automatically set to the main report.

Syntax

var param = new SAP.CR.Viewer.Parameter(parameterName,parameterType);

param.setReportName(subReportName);

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 17
Parameters

● subReportName - [String] Name of the sub report you are setting the parameters to.

Example

The following example creates a new parameter of type SAP.CR.DataTypes.NUMBER, and adds it to the sub
report with name subReport1.

var instance = SAP.CR.Viewer.getInstance("crystalViewer");

var param = new
SAP.CR.Parameter("subNumberParameter",SAP.CR.Parameter.DataTypes.NUMBER);
param.setReportName("subReport1");
param.addValue(10);
instance.setParameters([param]);

4.4 SAP.CR.Parameter.RangeValue

The SAP.CR.Parameter.Range class is used to specify a range of values for a parameter. The
SAP.CR.Parameter.Range object is added to an SAP.CR.Parameter object using the addValue method.

Syntax

var range = new SAP.CR.Parameter.RangeValue();

4.4.1 setBeginValue

Sets the first of the range of values.

Syntax

var range = new SAP.CR.Parameter.RangeValue();

range.setBeginValue(val);

SAP Crystal Reports JavaScript API Developer Guide

18 PUBLIC API reference
Parameters

● val - The lower bound of the range of values.

Possible types for val:

Value Description

SAP.CR.Parameter Boolean value (true or false.)

.DataTypes.BOOLEAN

SAP.CR.Parameter Numerical value.

.DataTypes.CURRENCY

SAP.CR.Parameter Date and time specified using the JavaScript Date

.DataTypes.DATE_TIME function.

SAP.CR.Parameter Date specified using the JavaScript Date function.

.DataTypes.DATE

SAP.CR.Parameter Time specified using the JavaScript Date function.

.DataTypes.TIME

SAP.CR.Parameter Numerical value.

.DataTypes.NUMBER

SAP.CR.Parameter String value.

.DataTypes.STRING

The type must be the same as that of the parameter the range value will be added to.

4.4.2 setEndValue

Sets the last of the range of values.

Syntax

var range = new SAP.CR.Parameter.RangeValue();

range.setEndValue(val);

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 19
Parameters

● val - The upper bound of the range of values.

Possible types for val:

Value Description

SAP.CR.Parameter Boolean value (true or false.)

.DataTypes.BOOLEAN

SAP.CR.Parameter Numerical value.

.DataTypes.CURRENCY

SAP.CR.Parameter Date and time specified using the JavaScript Date

.DataTypes.DATE_TIME function.

SAP.CR.Parameter Date specified using the JavaScript Date function.

.DataTypes.DATE

SAP.CR.Parameter Time specified using the JavaScript Date function.

.DataTypes.TIME

SAP.CR.Parameter Numerical value.

.DataTypes.NUMBER

SAP.CR.Parameter String value.

.DataTypes.STRING

The type must be the same as that of the parameter the range value will be added to.

4.4.3 setLowerBound

Sets the type of the lower bound of the range parameter.

Syntax

var range = new SAP.CR.Parameter.RangeValue();

range.setLowerBound(boundType);

SAP Crystal Reports JavaScript API Developer Guide

20 PUBLIC API reference
Parameters

● boundType - Determines the type of the lower bound.

Possible values:

Value Description

SAP.CR.Parameter.Parameter Range of values includes the begin value.

.RangeBoundTypes.INCLUSIVE

SAP.CR.Parameter.Parameter Range of values does not include the begin value.

.RangeBoundTypes.EXCLUSIVE

SAP.CR.Parameter.Parameter No lower bound.

.RangeBoundTypes.UNBOUNDED

4.4.4 setUpperBound

Sets the type of the upper bound of the range parameter.

Syntax

var range = new SAP.CR.Parameter.RangeValue();

range.setUpperBound(boundType);

Parameters

● boundType - Determines the type of the upper bound.

Possible values:

Value Description

SAP.CR.Parameter.Parameter Range of values includes the end value.

.RangeBoundTypes.INCLUSIVE

SAP.CR.Parameter.Parameter Range of values does not include the end value.

.RangeBoundTypes.EXCLUSIVE

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 21
 Value Description

SAP.CR.Parameter.Parameter No upper bound.

.RangeBoundTypes.UNBOUNDED

4.5 SAP.CR.Viewer

The SAP.CR.Viewer class contains methods that allows you to create an instance of the report viewer, and to
customize and add functionality to it.

4.5.1 addActionListener

Adds an action event listener to a viewer instance.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.addActionListener(aListener);

Parameters

● aListener - Name of the action listener you are adding. Must be an instance of SAP.CR.ActionListener.

4.5.2 addCanvasListener

Adds a canvas event listener to a viewer instance.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.addCanvasListener(cListener);

SAP Crystal Reports JavaScript API Developer Guide

22 PUBLIC API reference
Parameters

● cListener - Name of the canvas listener you are adding. Must be an instance of SAP.CR.CanvasListener.

4.5.3 batchExecute

The batchExecute method ensures that API calls are executed synchronously.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.batchExecute(function());

Parameters

● function - [function()] Function defined by you that contains the API calls to be executed in the order
they are to be executed.

Example

The following example drills down on a group path and then sets the page number to 2. If the batchExecute
method was not used, two asynchronous calls would be sent to the server at the same time. This would cause
only one of the two API calls to occur.

var viewerInstance = SAP.CR.Viewer.getInstance("crystalViewer");

viewerInstance.batchExecute(function(){
viewerInstance.drillDown(["0"]);
viewerInstance.setPageNumber(2);
});

4.5.4 create

Creates a CR Embedded viewer instance.

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 23
Syntax

SAP.CR.Viewer.create(viewerName,containerID,initCB,failCB)

Parameters

● containerID - [String] ID of the element that will hold the viewer.

● viewerName - [String] Name of the viewer.
● initCB - [function(instance)] Function that initializes the viewer instance. It is not defined within the
method call. The parameter instance is the viewer instance.
● failCB - [function(instance,error)] Function that is executed if something fails. It is not defined within the
method call. This is an optional parameter. The parameter instance is the viewer instance.

4.5.5 drilldown

Drills down to a group.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.drilldown([groupPath]);

Parameters

● groupPath - An array of integers, which displays the path you have drilled down on.

4.5.6 getInstance

Gets a viewer instance based on the viewer name.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

SAP Crystal Reports JavaScript API Developer Guide

24 PUBLIC API reference
Parameters

● viewerName - [String] Name of the viewer you are getting.

4.5.7 refresh

Refreshes the report displayed in the JavaScript viewer. The method refreshes the data in the report being
displayed and if necessary prompts for parameters or logon information.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.refresh();

4.5.8 removeActionListener

Removes an action event listener from a viewer instance.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.removeActionListener(aListener);

Parameters

● aListener - Name of the action listener you are removing.

4.5.9 removeCanvasListener

Removes a canvas event listener from a viewer instance.

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 25
Syntax

var instance = SAP.CR.Viewer.getInstance(viewerName);

instance.removeCanvasListener(cListener);

Parameters

● cListener - Name of the canvas listener you are removing.

4.5.10 setDisplayBreadcrumb

Show or hide the breadcrumb.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setDisplayBreadcrumb(isBreadcrumb);

Parameters

● isBreadcrumb - [Boolean] True to show breadcrumb or false to hide breadcrumb.

4.5.11 setDisplayLeftPanel

Show or hide the left panel, which can be used as the find panel, to view the Group Tree, or to view and edit
parameters.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setDisplayLeftPanel(isLeftPanel);

SAP Crystal Reports JavaScript API Developer Guide

26 PUBLIC API reference
Parameters

● isLeftPanel - [Boolean] Set to true to show panel or false to hide panel.

4.5.12 setDisplayStatusBar

Show or hide the status bar along the bottom of the report viewer.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setDisplayStatusBar(isStatusBar);

Parameters

● isStatusBar - [Boolean] Set to true to show status bar or false to hide status bar.

4.5.13 setDisplayToolbar

Show or hide the toolbar.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setDisplayToolbar(isToolbar);

Parameters

● isToolbar - [Boolean] True to show toolbar or false to hide toolbar.

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 27
4.5.14 setHasLogo

Shows or hides the logo in the top, right corner of the report viewer. By default the logo is shown.

 Note

Must be called before the viewer has initialized, or an exception is thrown.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerInstance);

viewerInstance.setHasLogo(isLogo);

Parameters

● isLogo - [Boolean] Set to true to show the logo or to false to hide it.

4.5.15 setHasRefreshButton

Shows or hides the refresh button in the report viewer's toolbar. By default the refresh button is hidden.

 Note

Must be called before the viewer has initialized, or an exception is thrown.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setHasRefreshButton(isRefreshButton);

Parameters

● isRefreshButton - [Boolean] Set to true to show the refresh button or to false to hide it.

SAP Crystal Reports JavaScript API Developer Guide

28 PUBLIC API reference
4.5.16 setLogo

Sets the image to be used as a logo in the top, right corner. Allows you to link a url to the logo and set a tooltip
for when you mouseover the logo.

 Note

Must be called before the viewer has initialized, or an exception is thrown.

 Note

The image should be at most 100x125 pixels in size.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setLogo(url, link, tooltip);

Parameters

● url - [String] Relative or absolute path to the image to be used as the logo.
● link - [String] The url that will be opened when the user clicks the logo.
● tooltip - [String] The tooltip that appears when you mouseover the logo. If it contains non-English
characters it must be encoded.

4.5.17 setPageNumber

Sets the page number of the report page being viewed.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setPageNumber(pageNumber);

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 29
Parameters

● pageNumber - [number] A positive number. If larger than the number of pages in the report the page
number is set to the last page in the report.

4.5.18 setParameters

Sets report parameters. Multiple parameters can be set in one call of the method.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setParameters([param]);

Parameters

● param - An array of the parameter(s) being set to the viewer.

4.5.19 setPrintMode

Sets the print mode of the report viewer to either ACTIVEX or PDF.

 Note

Must be called before the viewer has initialized, or an exception is thrown.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setReportMode(mode);

SAP Crystal Reports JavaScript API Developer Guide

30 PUBLIC API reference
Paramters

● mode - The print mode.

Possible values:

Value Description

SAP.CR.PrintMode.ACTIVEX Print using the ActiveX printer. Only works in Internet

Explorer.

SAP.CR.PrintMode.PDF Print to PDF.

4.5.20 setPromptOnRefresh

Sets whether or not the viewer prompts for new parameter values after being refreshed. By default the viewer
prompts for new parameter values.

 Note

Must be called before the viewer has initialized, or an exception is thrown.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerIntance.setPromptOnRefresh(isPrompt);

Parameters

● isPrompt - [Boolean] Set to true to prompt for new parameters or to false to use existing parameter
values.

4.5.21 setReportMode

Sets the color of the background behind the report page and the alignment of the report pages in the report
viewer.

 Note

Must be called before the viewer has initialized, or an exception is thrown.

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 31
Syntax

var viewerInstance = SAP.CR.Viewer.getInsatnce(viewerName);

viewerInstance.setReportMode(mode);

Parameters

● mode - Sets the color and alignment of the report page in the report viewer.
Possible values:

Value Description

SAP.CR.Viewer Sets the background of the report viewer to grey.

.ReportMode.PRINT

SAP.CR.Viewer Sets the background of the report viewer to white. Report pages are
.ReportMode.WEB not center aligned in the viewer.

4.5.22 setReportSource

Sets the report source based on a numerical object ID and an enterprise session. If needed you can also set the
document locale.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setReportSource(infoObjectID,token,locale);

Parameters

● infoObjectID - [String] ID or report in info view/CMC.

● token - [String] Logon token. The token expires after a few minutes of inactivity and needs to be
regenerated. Refer to the Business Intelligence Platform RESTful Web Services Developer Guide for how to
generate a logon token.
● locale - [String] The document locale.

SAP Crystal Reports JavaScript API Developer Guide

32 PUBLIC API reference
4.5.23 setEnableDrillDown

Sets whether to enable drilldown.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setEnableDrillDown (enableDrillDown);

Parameters

● <enableDrillDown> - [Boolean] Set to 'true' to enable drill down, and 'false' to disable drill down.

 Caution

The method must be called before the viewer has initialized, or an exception is thrown.

4.5.24 setToolPanelViewMode

Sets the view to display in the tool panel.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setToolPanelViewMode(mode);

Parameters

● <mode>- The tool panel view mode.

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 33
 Possible Values of 'mode'

Value Description

SAP.CR.Viewer.ToolPanelViewMode.NONE Hides the tool panel.

SAP.CR.Viewer.ToolPanelViewMode.GROUPTREE Show Displays group tree view in the tool panel.

group tree view on tool panel

SAP.CR.Viewer.ToolPanelViewMode.PARAMETER Displays parameter view in the tool panel.

SAP.CR.Viewer.ToolPanelViewMode.SEARCH Displays search view in the tool panel.

 Caution

The method must be called before the viewer has initialized, or an exception is thrown.

4.5.25 setHasToggleGroupTreeButton

Sets whether to display the toggle group tree button.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setHasToggleGroupTreeButton(hasToggleGroupTreeButton);

Parameters

● <hasToggleGroupTreeButton> - [Boolean] Set to 'true' to display the group tree button, and 'false' to
hide it.

 Caution

The method must be called before the viewer has initialized, or an exception is thrown.

4.5.26 setHasToggleParameterPanelButton

Sets whether to display the toggle parameter panel button.

SAP Crystal Reports JavaScript API Developer Guide

34 PUBLIC API reference
Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setHasToggleParameterPanelButton (hasToggleParameterPanelButton);

Parameters

● <hasToggleParameterPanelButton> - [Boolean] Set to 'true' to display the parameter panel button,

and 'false' to hide it.

 Caution

The method must be called before the viewer has initialized, or an exception is thrown.

4.5.27 setHasSearchButton

Sets whether to display the search button.

Syntax

var viewerInstance = SAP.CR.Viewer.getInstance(viewerName);

viewerInstance.setHasSearchButton(hasSearchButton);

Parameters

● <hasSearchButton> - [Boolean] Set to 'true' to display the group tree button, and 'false' to hide it.

 Caution

The method must be called before the viewer has initialized, or an exception is thrown.

4.6 SAP.CR.Viewer.ThemeManager

The ThemeManager class allows you to set the color and font style used in the viewer.

SAP Crystal Reports JavaScript API Developer Guide

API reference PUBLIC 35
4.6.1 setThemeColor

Sets the color of the viewer.

Syntax

SAP.CR.Viewer.ThemeManager.setThemeColor(hexColor,isSolid);

Parameters

● hexColor - [String] The hexadecimal representation of the color being used. Value always starts with the
# symbol.
● isSolid - [Boolean] Set to true for a solid color or set to false for a gradient color.

4.6.2 setThemeFont

Sets the family font name used in the JavaScript viewer UI. This does not effect the font used in the report
being viewed.

Syntax

SAP.CR.Viewer.ThemeManager.setThemeFont(font);

Parameters

● font - [String] The font to be used in the viewer. Any browser supported fonts can be used.

SAP Crystal Reports JavaScript API Developer Guide

36 PUBLIC API reference
Important Disclaimers and Legal Information

Hyperlinks
Some links are classified by an icon and/or a mouseover text. These links provide additional information.
About the icons:

● Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your
agreements with SAP) to this:

● The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.
● SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

● Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering a SAP-hosted Web site. By using such
links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this
information.

Beta and Other Experimental Features

Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by
SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use
the experimental features in a live operating environment or with data that has not been sufficiently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your
feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax
and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of
example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Gender-Related Language
We try not to use gender-specific word forms and formulations. As appropriate for context and readability, SAP may use masculine word forms to refer to all genders.

Videos Hosted on External Platforms

Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any
advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within
the control or responsibility of SAP.

SAP Crystal Reports JavaScript API Developer Guide

Important Disclaimers and Legal Information PUBLIC 37
www.sap.com/contactsap

© 2020 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form

or for any purpose without the express permission of SAP SE or an SAP
affiliate company. The information contained herein may be changed
without prior notice.

Some software products marketed by SAP SE and its distributors

contain proprietary software components of other software vendors.
National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for

informational purposes only, without representation or warranty of any
kind, and SAP or its affiliated companies shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP or
SAP affiliate company products and services are those that are set forth
in the express warranty statements accompanying such products and
services, if any. Nothing herein should be construed as constituting an
additional warranty.

SAP and other SAP products and services mentioned herein as well as
their respective logos are trademarks or registered trademarks of SAP
SE (or an SAP affiliate company) in Germany and other countries. All
other product and service names mentioned are the trademarks of their
respective companies.

Please see https://www.sap.com/about/legal/trademark.html for

additional trademark information and notices.

THE BEST RUN