Using BIRT Viewer Toolkit

Information in this document is subject to change without notice. Examples provided are fictitious. No part of
this document may be reproduced or transmitted in any form, or by any means, electronic or mechanical, for any
purpose, in whole or in part, without the express written permission of Actuate Corporation.

© 1995 - 2013 by Actuate Corporation. All rights reserved. Printed in the United States of America.

Contains information proprietary to:

Actuate Corporation, 951 Mariners Island Boulevard, San Mateo, CA 94404

www.actuate.com

The software described in this manual is provided by Actuate Corporation under an Actuate License agreement.
The software may be used only in accordance with the terms of the agreement. Actuate software products are
protected by U.S. and International patents and patents pending. For a current list of patents, please see
http://www.actuate.com/patents.

Actuate Corporation trademarks and registered trademarks include:

Actuate, ActuateOne, the Actuate logo, Archived Data Analytics, BIRT, BIRT 360, BIRT Analytics, The BIRT
Company, BIRT Data Analyzer, BIRT iHub, BIRT Performance Analytics, Collaborative Reporting Architecture,
e.Analysis, e.Report, e.Reporting, e.Spreadsheet, Encyclopedia, Interactive Viewing, OnPerformance, The people
behind BIRT, Performancesoft, Performancesoft Track, Performancesoft Views, Report Encyclopedia, Reportlet,
X2BIRT, and XML reports.

Actuate products may contain third-party products or technologies. Third-party trademarks or registered
trademarks of their respective owners, companies, or organizations include:
Mark Adler and Jean-loup Gailly (www.zlib.net): zLib. Adobe Systems Incorporated: Flash Player. Amazon Web
Services, Incorporated: Amazon Web Services SDK, licensed under the Apache Public License (APL). Apache
Software Foundation (www.apache.org): Ant, Axis, Axis2, Batik, Batik SVG library, Commons Command Line
Interface (CLI), Commons Codec, Crimson, Derby, Hive driver for Hadoop, Pluto, Portals, Shindig, Struts,
Tomcat, Xalan, Xerces, Xerces2 Java Parser, and Xerces-C++ XML Parser. Castor (www.castor.org), ExoLab
Project (www.exolab.org), and Intalio, Inc. (www.intalio.org): Castor. Day Management AG: Content Repository
for Java. Eclipse Foundation, Inc. (www.eclipse.org): Babel, Data Tools Platform (DTP) ODA, Eclipse SDK,
Graphics Editor Framework (GEF), Eclipse Modeling Framework (EMF), and Eclipse Web Tools Platform (WTP),
licensed under the Eclipse Public License (EPL). Gargoyle Software Inc.: HtmlUnit, licensed under Apache
License Version 2.0. GNU Project: GNU Regular Expression, licensed under the GNU Lesser General Public
License (LGPLv3). HighSlide: HighCharts. Jason Hsueth and Kenton Varda (code.google.com): Protocole Buffer.
IDAutomation.com, Inc.: IDAutomation. IDRsolutions Ltd.: JBIG2, licensed under the BSD license. InfoSoft
Global (P) Ltd.: FusionCharts, FusionMaps, FusionWidgets, PowerCharts. Matt Inger (sourceforge.net):
Ant-Contrib, licensed under Apache License Version 2.0. Matt Ingenthron, Eric D. Lambert, and Dustin Sallings
(code.google.com): Spymemcached, licensed under the MIT OSI License. International Components for Unicode
(ICU): ICU library. jQuery: jQuery, licensed under the MIT License. Yuri Kanivets (code.google.com): Android
Wheel gadget, licensed under the Apache Public License (APL). LEAD Technologies, Inc.: LEADTOOLS. The
Legion of the Bouncy Castle: Bouncy Castle Crypto APIs. Bruno Lowagie and Paulo Soares: iText, licensed under
the Mozilla Public License (MPL). Microsoft Corporation (Microsoft Developer Network): CompoundDocument
Library. Mozilla: Mozilla XML Parser, licensed under the Mozilla Public License (MPL). MySQL Americas, Inc.:
MySQL Connector. Netscape Communications Corporation, Inc.: Rhino, licensed under the Netscape Public
License (NPL). OOPS Consultancy: XMLTask, licensed under the Apache License, Version 2.0. Oracle
Corporation: Berkeley DB, Java Advanced Imaging, JAXB, JDK, Jstl. PostgreSQL Global Development Group:
pgAdmin, PostgreSQL, PostgreSQL JDBC driver. Progress Software Corporation: DataDirect Connect XE for
JDBC Salesforce, DataDirect JDBC, DataDirect ODBC. Rogue Wave Software, Inc.: Rogue Wave Library
SourcePro Core, tools.h++. Sam Stephenson (prototype.conio.net): prototype.js, licensed under the MIT license.
Sencha Inc.: Ext JS, Sencha Touch. ThimbleWare, Inc.: JMemcached, licensed under the Apache Public License
(APL). World Wide Web Consortium (W3C)(MIT, ERCIM, Keio): Flute, JTidy, Simple API for CSS. XFree86
Project, Inc.: (www.xfree86.org): xvfb. ZXing authors (code.google.com): ZXing, licensed under the Apache
Public License (APL).

All other brand or product names are trademarks or registered trademarks of their respective owners,
companies, or organizations.
Document No. 130131-2-749311 July 10, 2013
 Contents
About Using BIRT Viewer Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Part 1
Installing BIRT Viewer Toolkit
Chapter 1
Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
About BIRT Viewer Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
About deployment formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Checking installation prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2
Deploying BIRT Viewer Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Setting web application parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Configuring locale parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Configuring path parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Configuring performance parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Compressing files and renaming the WAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Deploying BIRT Viewer Toolkit as a WAR or EAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Deploying the BIRT Viewer Toolkit WAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Deploying the BIRT Viewer Toolkit EAR file to JBoss 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Chapter 3
Testing BIRT Viewer Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Testing the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Setting JVM properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Part 2
Using BIRT Viewer Toolkit
Chapter 4
Introducing Actuate BIRT Viewers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
About BIRT Viewer Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
About Actuate BIRT commercial viewers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 5
Navigating a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
About navigation options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

i
Paging through a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Displaying parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Linking to a report page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

Chapter 6
Exporting report data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
About exporting options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Exporting report data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Exporting content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Exporting content to Microsoft Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Exporting content to PDF format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Exporting content to PostScript format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Exporting content to Microsoft Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Exporting content to Microsoft PowerPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Chapter 7
Filtering report data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Providing parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Chapter 8
Working with charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
About charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Types of charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
About bar charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
About tube, cone, and pyramid charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
About area charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
About line charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
About pie charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
About meter charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
About stock charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
About scatter charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
About bubble charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Exporting data from a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Exporting a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Chapter 9
Working with cross tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
About cross tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Introducing a cross tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Parts of a cross tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Exporting cross tab content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

ii
Part 3
Using Actuate JavaScript API
Chapter 10
Creating a custom web page using the Actuate JavaScript API . . . . . . . 55
About the Actuate JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Accessing the Actuate JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
About the DOCTYPE tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
About UTF-8 character encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Establishing an HTTP session with an Actuate BIRT Viewer Toolkit application . . . . . . . . . . . 57
About Actuate JavaScript API security integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Establishing a connection to more than one web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Unloading authentication information from the session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Viewing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Using and submitting report parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Using a parameter component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Accessing parameter values from the viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 11
Actuate JavaScript API classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Actuate JavaScript API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
About the actuate namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Using the Actuate library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Actuate JavaScript API classes quick reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Actuate JavaScript API reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Class actuate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Class actuate.Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Class actuate.Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Class actuate.parameter.Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Class actuate.parameter.ConvertUtility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Class actuate.parameter.EventConstants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Class actuate.parameter.NameValuePair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Class actuate.parameter.ParameterValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Class actuate.RequestOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Class actuate.Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Class actuate.viewer.EventConstants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Class actuate.viewer.ParameterValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
Class actuate.viewer.ViewerException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

iii
iv
 Ab ou t U s in g B I RT
Vi e w e r To o l k i t

Using BIRT Viewer Toolkit provides users with information about using and
integrating Actuate BIRT Viewer Toolkit. This document explains how to
generate, view, and customize reports and report content.
■ About Using BIRT Viewer Toolkit. This chapter provides an overview of this
document.
■ Part 1. Installing BIRT Viewer Toolkit. This part contains information about
installing, deploying, and testing Actuate BIRT Viewer Toolkit.
■ Chapter 1. Before you begin. This chapter explains BIRT Viewer Toolkit
capabilities, installation prerequisites, and licensing.
■ Chapter 2. Deploying BIRT Viewer Toolkit. This chapter covers editing
parameters for using BIRT Viewer Toolkit and deploying the BIRT Viewer
Toolkit WAR file.
■ Chapter 3. Testing BIRT Viewer Toolkit. This chapter describes testing BIRT
Viewer Toolkit and configuring Java Virtual Machine (JVM) options.
■ Part 2. Using BIRT Viewer Toolkit. This part contains information about using
BIRT Viewer Toolkit.
■ Chapter 4. Introducing Actuate BIRT Viewers. This chapter introduces the
viewing environments for BIRT reports, and lists the modification capabilities
each environment provides.
■ Chapter 5. Navigating a report. This chapter describes how you can begin
working with reports by navigating a report page, displaying parameter
values, and linking to the current report page.
■ Chapter 6. Exporting report data. This chapter describes exporting report data to
various flat file formats, and exporting report content to supported output
formats.

A b o u t U s i n g B I R T V i e w e r To o l k i t v
 ■ Chapter 7. Filtering report data. This chapter discusses how you can use BIRT
Viewer Toolkit to specify viewing parameter values for data in a report.
■ Chapter 8. Working with charts. This chapter describes the types of charts you
can view in a report.
■ Chapter 9. Working with cross tabs. This chapter describes cross tabs.
■ Part 3. Using Actuate JavaScript API. This part contains a guide to designing
custom reporting web applications with the Actuate JavaScript API.
■ Chapter 10. Creating a custom web page using the Actuate JavaScript API. This
chapter describes the Actuate JavaScript API requirements and common
implementations.
■ Chapter 11. Actuate JavaScript API classes. This chapter lists all of the standard
Actuate JavaScript API classes and their methods.

vi U s i n g B I R T V i e w e r To o l k i t
 Part One 1

Part 1 Installing BIRT Viewer Toolkit

 1
Chapter

Before you begin

Chapter 1

This chapter discusses the following topics:

■ About BIRT Viewer Toolkit
■ About deployment formats
■ Checking installation prerequisites

Chapter 1, Before you begin 3

About BIRT Viewer Toolkit
BIRT Viewer Toolkit provides a licensed and easily integrated Actuate BIRT
Viewer as a web application. The Actuate BIRT Viewer extends the capabilities of
BIRT to deliver rich dynamic content and display aggregate data in cross tabs.
BIRT Viewer Toolkit is a licensed, free web application you can download from
the BIRT Exchange web site.
http://www.birt-exchange.com/be/downloads/
The site asks you to agree to the license before downloading BIRT Viewer Toolkit.

About deployment formats

You can install BIRT Viewer Toolkit on Windows, Linux, and UNIX. Actuate
provides BIRT Viewer Toolkit in WAR and EAR formats. These formats are
suitable for deployment on application servers shown in Table 1-1.
Table 1-1 BIRT Viewer Toolkit deployment formats
File Application server
WL_TOMCAT_ActuateBIRTViewer.war Apache Tomcat 6
BEA WebLogic 9.2 or 10.3
JBOSS_ActuateBIRTViewer.ear JBoss 6
WAS_ActuateBIRTViewer.ear IBM WebSphere 6.1 or 1.1.01

Apache Tomcat 6 application server does not support EAR deployment. Only the
JBoss and WebSphere application servers support EAR deployment.

Checking installation prerequisites

Before you deploy BIRT Viewer Toolkit, ensure that your system meets the
following requirements:
■ Java Development Kit 5 or 6 (JDK)
Use the JAR utility included in the JDK to decompress and compress the BIRT
Viewer Toolkit archive. BIRT Viewer Toolkit also requires the Java Runtime
Environment (JRE) included in the JDK.
■ An application server
BIRT Viewer Toolkit runs as a web application in the application server, such
as Apache Tomcat 6 or JBoss 6.

4 I n s t a l l i n g B I R T V i e w e r To o l k i t
■ Administrators group privileges on Windows, or root privileges on Linux or
UNIX
■ Permission to start and stop the application server
■ A Java Virtual Machine (JVM) and Web Server configured for the same
application platform, either 32-bit or 64-bit

Chapter 1, Before you begin 5

6 I n s t a l l i n g B I R T V i e w e r To o l k i t
 2
Chapter

Deploying BIRT Viewer

Chapter 2

Toolkit
This chapter discusses the following topics:
■ Setting web application parameters
■ Compressing files and renaming the WAR file
■ Deploying BIRT Viewer Toolkit as a WAR or EAR file

C h a p t e r 2 , D e p l o y i n g B I R T V i e w e r To o l k i t 7
Setting web application parameters
The first step in deploying the BIRT Viewer Toolkit WAR file is editing the
web.xml file. Extract web.xml from the WAR file, then edit web.xml to set
configuration parameters. The tables in this section describe these parameters
and actions you take. Perform these actions as you edit web.xml.
How to edit web.xml
To access web.xml for editing, first decompress the WAR file that contains
web.xml. Next, configure parameters for the BIRT Viewer Toolkit.
1 Create a directory named /temp. BIRT Viewer Toolkit writes temporary files
to this directory after deployment.
2 Decompress the ActuateJavaComponent.war file in a subdirectory of /temp.
Type the following command:
jar -xf ActuateJavaComponent.war
Use this command on Windows, Linux, and UNIX. The BIRT Viewer Toolkit
files appear in the subdirectory of /temp.
Figure 2-1 shows these files on Linux.

Figure 2-1 Files extracted from ActuateJavaComponent.war

Keep all downloaded files together in their original relative locations.
3 Using a text editor that accepts UTF-8 encoding, edit web.xml in /WEB-INF to
configure the parameters for BIRT Viewer Toolkit.
4 Save and close web.xml.

Configuring locale parameters

BIRT Viewer Toolkit uses the locale parameters in web.xml, described in
Table 2-1.

8 I n s t a l l i n g B I R T V i e w e r To o l k i t
Table 2-1 Locale parameters
Parameter name Description Value
DEFAULT_LOCALE The value of this parameter Use the default locale
determines the default or a value from
locale. The default locale is Localemap.xml in the
en_US. WEB-INF directory.
DEFAULT_TIMEZONE The value of this parameter Use the default time
determines the default time zone or a value from
zone. The default time Timezonemap.xml in
zone is Pacific Standard the WEB-INF directory.
Time (PST).

Configuring path parameters

BIRT Viewer Toolkit contains path configuration parameters in web.xml.
Table 2-2 describes these parameters. Update these parameters and create the
physical locations on the file system before deployment.
Table 2-2 Path parameters
Parameter name Description
LOG_FILE_ The location of the files that log BIRT Viewer Toolkit
LOCATION activities. The default value is /logs.
TEMP_FOLDER_ The location where BIRT Viewer Toolkit creates
LOCATION temporary files. There is no default value.
TRANSIENT_STORE_ Another location where BIRT Viewer Toolkit creates
PATH temporary files. The default value is /temp.

Configuring performance parameters

BIRT Viewer Toolkit has performance configuration parameters in web.xml.
Table 2-3 describes these configuration parameters. Consider changing these
parameters to optimize performance.
Table 2-3 Performance parameters
Parameter name Description
BIRT_ARCHIVE_ Total memory available for BIRT report document
MEMORY_TOTALSIZE files in kilobytes. The default value is 50 MB.
REPOSITORY_CACHE Specifies, in seconds, how long to retain temporary
_TIMEOUT_SEC files that BIRT Viewer creates. The default value is
900, which is 15 minutes.

C h a p t e r 2 , D e p l o y i n g B I R T V i e w e r To o l k i t 9
Compressing files and renaming the WAR file
After editing the web.xml file, compress and rename the archive. For example,
rename the archive newBIRTViewerToolkit.war. Compress the files into a WAR
file of a different name to preserve your original WAR file.
How to compress files and rename the WAR file
1 After editing web.xml in the WEB-INF directory, move up one directory.
2 Check that files shown in Figure 2-1 are present in your current directory.
3 Compress the files and specify a new name for the WAR file. Type the
following command:
jar -cf newBIRTViewerToolkit.war *
Use this command on Windows, Linux, and UNIX. The WAR file containing
the modified configuration values in web.xml appears.

Deploying BIRT Viewer Toolkit as a WAR or EAR file

BIRT Viewer Toolkit is available in WAR and EAR file formats.

Deploying the BIRT Viewer Toolkit WAR file

This section discusses deploying a BIRT Viewer Toolkit WAR file. For example
purposes, deployment on Tomcat 6 is shown.
To deploy the WAR file on an application server other than Tomcat 6, use your
application server’s deployment tools. If your application server does not have
deployment tools, add the BIRT Viewer Toolkit context root to your application
server. Typically, you modify the application server's configuration file.
Deploying the WAR file on Apache Tomcat
Perform the steps in the following procedure to deploy the WAR file by putting it
in the /webapps directory.
1 Stop the Apache Tomcat service.
2 Copy the renamed BIRT Viewer Toolkit WAR file from the working directory
to the /webapps directory of your Tomcat installation files, as shown in
Figure 2-2.

10 I n s t a l l i n g B I R T V i e w e r To o l k i t
 Figure 2-2 Copying the WAR file to /webapps on Linux
3 Start Tomcat.
The Tomcat log confirms the deployment of the WAR file and the location of
the /temp directory that you created earlier.
Figure 2-3 shows an example of a Tomcat log file on Linux.

Default Linux
path to logs

Deployment
confirmation
Specified
temp directory
Figure 2-3 Tomcat log file confirms deployment

Deploying the BIRT Viewer Toolkit EAR file to JBoss 6

In order to deploy BIRT Viewer Toolkit EARs to JBoss 6, you must remove the
commons-logging.jar library from the EAR file before deploying it. Leaving this
file in the EAR causes JBoss 6 to throw an exception during deployment.
The commons-logging.jar file is still necessary for deployments to JBoss 5 and
JBoss 7.
To deploy BIRT Viewer Toolkit to JBoss 6, perform the following steps:
1 In a separate directory, extract the contents of JBOSS_ActuateBIRTViewer.ear
by typing the following command into a command prompt:
jar -xf JBOSS_ActuateBIRTViewer.ear
Keep all extracted files together in their original relative locations.
2 Copy JBOSS_ActuateBIRTViewer.war into a separate directory and extract the
contents of JBOSS_ActuateBIRTViewer.war by typing the following command
into a command prompt:
jar -xf JBOSS_ActuateBIRTViewer.war

C h a p t e r 2 , D e p l o y i n g B I R T V i e w e r To o l k i t 11
 3 Delete <warFile>/WEB-INF/lib/commons-logging.jar.
4 Compress the all files in the directory into a war file by typing the following
command:
jar -cf JBOSS_ActuateBIRTViewer.war *
5 Copy JBOSS_ActuateBIRTViewer.war into the separate directory containing
the extracted files from JBOSS_ActuateBIRTViewer.ear. Compress these files
into a ear file by typing the following command:
jar -cf JBOSS_ActuateBIRTViewer.ear *
6 Deploy JBOSS_ActuateBIRTViewer.ear to the JBoss 6 server.

12 I n s t a l l i n g B I R T V i e w e r To o l k i t
 3
Chapter

Chapter 3 Testing BIRT Viewer

Toolkit
This chapter discusses the following topics:
■ Testing the installation
■ Setting JVM properties

C h a p t e r 3 , Te s t i n g B I R T V i e w e r T o o l k i t 13
Testing the installation
To test the BIRT Viewer Toolkit installation, open the BIRT Viewer Toolkit landing
page. Go to the following URL to access the landing page shown in Figure 3-1:
http://host:8080/newBIRTViewerToolkit/

Figure 3-1 Actuate BIRT Viewer Toolkit landing page

The landing page displays a sample report and reportlet, accessed using Actuate
JavaScript API. After these items generate, they appear below the landing page
text. The report appears as shown in Figure 3-2.
Main menu Navigation bar

Figure 3-2 Landing page sample report

14 I n s t a l l i n g B I R T V i e w e r To o l k i t
A reportlet is a portion of a report displayed as a separate item. The sample
reportlet, which displays the doughnut chart from the sample report, appears as
shown in Figure 3-3.

Figure 3-3 Landing page sample reportlet

To test the BIRT Viewer Toolkit report viewer, copy a BIRT report design or BIRT
report document to the repository, restart the application server, and use a web
browser to access the report using a URL similar to the following one:
http://host:8080/newBIRTViewerToolkit/
frameset?__report=test.rptdesign
■ host:8080 is the host name and port for your application server web service
■ newBIRTViewerToolkit is the context root for BIRT Viewer Toolkit
■ frameset is the BIRT Viewer Toolkit JSP that loads the viewer
■ ?__report=test.rptdesign is the URL parameter used to identify the report
design or document
This URL displays the report as paginated HTML with a navigation bar and
menu of options such as exporting the report to multiple output formats.
How to view a report in the BIRT Viewer Toolkit repository
1 Stop the application server.
2 Copy a BIRT report into the following directory:
<Context Root>\WEB-INF\repository
3 Start the application server.
4 Open a web browser and type a frameset URL into the address bar. Include a
__report parameter with the name of your BIRT Report. For example, the
following URL loads the test.rptdesign report from the repository:
http://host:8080/newBIRTViewerToolkit/
frameset?__report=BIRTtest.rptdesign
5 View the report, providing parameters as required, shown in Figure 3-4.

C h a p t e r 3 , Te s t i n g B I R T V i e w e r T o o l k i t 15
 Figure 3-4 Displaying a report using Actuate BIRT Viewer Toolkit

Setting JVM properties

Deploying BIRT Viewer Toolkit within some application server environments
requires Java configuration to avoid Java Virtual Machine (JVM) errors. Set the
following JVM properties:
■ Initial heap size
Include -Xms64m as a Java option.
■ Maximum heap size
Include -Xmx512m as a Java option.
■ Maximum size for the permanent generation heap
Include -XX:MaxPermSize=128m as an option.
How to configure JVM properties for Tomcat 6.x on Windows
1 From the Windows Start menu, choose All Programs➛Apache Tomcat
6.x➛Configure Tomcat.
2 On Apache Tomcat 6.x Properties, choose Java.
3 Change the value of the Initial memory pool to 64.
4 Change the value of the Maximum memory pool to 512.
5 Add -XX:MaxPermSize=128m to Java Options, as shown in Figure 3-5.

16 I n s t a l l i n g B I R T V i e w e r To o l k i t
 Figure 3-5 Apache Tomcat 6 Java configuration
6 Choose OK.
7 Restart Tomcat.
How to configure JVM properties for JBoss on Windows
1 Navigate to the following directory:
<JBoss install directory>\bin
2 Open run.bat.
3 Add -Xms64m -Xmx512m and -XX:MaxPermSize=128m to the JAVA_OPTS
variable specification.
4 Save and close run.bat.
5 Restart Tomcat.
How to configure JVM properties for Tomcat 6 on Linux
1 Navigate to the following directory:
/etc/tomcat6
2 Open tomcat6.conf.
3 Add -XMs64m -XMx512m and -XX:MaxPermSize=128m to the JAVA_OPTS
variable specification.
4 Save and close tomcat6.conf.
5 Restart Tomcat.

C h a p t e r 3 , Te s t i n g B I R T V i e w e r T o o l k i t 17
18 I n s t a l l i n g B I R T V i e w e r To o l k i t
 Part Two 2

Part 2 Using BIRT Viewer Toolkit

 4
Chapter

Introducing Chapter 4

Actuate BIRT Viewers

This chapter contains the following topics:
■ About BIRT Viewer Toolkit
■ About Actuate BIRT commercial viewers

Chapter 4, Introducing Actuate BIRT Viewers 21

About BIRT Viewer Toolkit
Actuate BIRT Viewer Toolkit enables users to view BIRT reports quickly and
easily, and at no charge. BIRT Viewer Toolkit is a free offering that can easily be
integrated into existing software using Actuate JavaScript API or a URL.
Using BIRT Viewer Toolkit, you can view a report, navigate a multipage report,
use parameters formatted as lists or radio buttons to view specific information in
reports requiring parameter values, and share the report with other users using a
link to the report page. You can also use BIRT Viewer Toolkit to export report data
and content to supported formats, and view static charts and cross tab reports.
After registering on birt-exchange.com, you can download BIRT Viewer Toolkit
and benefit from community-support for the product. To begin using BIRT
Viewer Toolkit, navigate to the following location:
http://www.birt-exchange.com/be/downloads/

About Actuate BIRT commercial viewers

Actuate provides commercial web-based viewing environments for multiple
purposes. Actuate BIRT Viewer and Actuate BIRT Interactive Viewer are licensed
options you can use to navigate a report, print report data, and export the report
and report data to several other formats. In addition, Interactive Viewer provides
a high degree of interactivity. Users can easily modify the layout and formatting
of reports, organize report data by sorting, filtering and grouping, perform
calculations, compute and aggregate report data, and edit graphical
representations of report data by modifying charts in a report. In addition, you
can modify cross tabs and summary tables in a report. You can then save the
modified reports using Interactive Viewer. Actuate also provides BIRT Viewer for
mobile, which supports viewing BIRT content on mobile devices such as smart
phones and tablets.
If you find that you need to perform more modification tasks on your report
designs than BIRT Viewer Toolkit allows, you can purchase any of the separately
licensed commercial viewers from Actuate. For more information about Actuate
BIRT Interactive Viewer, visit:
http://www.birt-exchange.com/be/products/birt-user-experience
/interactive-viewer/features/

22 U s i n g B I R T V i e w e r To o l k i t
 5
Chapter

Navigating a report
Chapter 5

This chapter contains the following topics:

■ About navigation options
■ Paging through a report
■ Displaying parameter values
■ Linking to a report page

Chapter 5, Navigating a report 23

About navigation options
The following section describes how to navigate a generated report in BIRT
Viewer Toolkit.

Paging through a report

The viewer toolbar consists of a main menu with additional options and a page
navigation tool. You can view pages in a multipage report using the paging tool.
The tool consists of arrows that enable users to move forward or backward, page
by page, through the report.
To navigate directly to a specific page, type the page number in the Page number
field, then press Enter.

Displaying parameter values

Using parameter values is a way of limiting the report data retrieved when you
run a report. For example, in a report that displays customer information, you can
use parameter values to display sales history for a specific customer, or view the
details of specific orders. If a report requires you to enter parameter values, you
are prompted to type the value when you generate the report. Specifying
parameter values enables you to navigate a report more effectively, and display
only the information you need.
If the report requires you to enter parameter values to determine what data to
display, you can modify these values to view other data, by choosing Parameters
from the main menu. If you choose this option, and parameter values are not
needed, a message appears informing you that the report contains no parameters.
You learn more about using parameters later in this document.

Linking to a report page

You can also use the Link To This Page option to share the currently viewed
report with other users. When you share the report, the viewer generates a link to
the report and makes this available to other designated users.

24 U s i n g B I R T V i e w e r To o l k i t
How to link to the current report page
Choose Link To This Page from the main menu. On Link To This Page, you can
either copy the absolute link and paste it in an e-mail or Instant Messenger
window, or you can copy the HTML code, shown in Figure 5-1, and paste it in the
required location. Choose OK to close the window.

Figure 5-1 Linking to the current report page

Chapter 5, Navigating a report 25

26 U s i n g B I R T V i e w e r To o l k i t
 6
Chapter

Exporting report data

Chapter 6

This chapter contains the following topics:

■ About exporting options
■ Exporting report data
■ Exporting content

Chapter 6, Exporting report data 27

About exporting options
BIRT Viewer Toolkit enables you to export report data, report content, and
elements, such as charts, cross tabs, or summary tables, to various formats. You
can export data to several flat file formats that can be read by Excel. In addition,
BIRT Viewer Toolkit uses various emitters to enable you to export content, as well
as elements to formats such as Microsoft Excel, PowerPoint, and Word, and
Adobe PostScript and PDF.
When you export content or elements to other formats, each emitter such as the
PDF emitter or the Excel emitter provides several options that you can select to
maintain the existing properties of the exported content, enabling users to easily
perform additional analysis on the exported output. For example, when you
export an element such as a cross tab to Excel, the Excel emitter supports
exporting the content as a pivot table. This feature is specifically useful for
sharing content with users without access to the BIRT Viewers, who can still
analyze the output in Excel. BIRT Viewer Toolkit does not support exporting a
report or report elements using Actuate’s commercial emitters. To use the
commercial emitters you must purchase the license for Actuate BIRT Viewer or
Actuate BIRT Interactive Viewer.

Exporting report data

You export report data to extract some or all of the data from a report, to use the
data in another document, or format. For example, you can export customer sales
data from a previous quarter, then use the values in a spreadsheet to create a
forecast for an upcoming quarter.
The viewer supports the ability to export report data as a comma-separated
values (.csv) file, a pipe-separated values (.psv) file, a tab-separated values (.tsv)
file, or a semicolon-separated values (.ssv) file. These files store data in a flat file
format, which Excel can read. You choose a format to export report data based on
the requirements of the application to which you export the data, and the purpose
for which you plan to use the exported data.
Once you choose a format to export the data, Excel displays the exported data in a
spreadsheet. You can now resize columns and format the data as for any other
spreadsheet.
When you export data, you cannot export a table or chart element, but you can
export the data displayed in both these elements.
How to export data in comma-separated values file (.csv) format
1 From the main menu, as shown in Figure 6-1, choose Export Data.

28 U s i n g B I R T V i e w e r To o l k i t
 Figure 6-1 Exporting report data
2 On Export Data, Available ResultSets lists the report elements, such as tables,
charts, cross tabs, Flash charts and gadgets, and so on, that contain data. Select
an element from which to export data. The names on the list are internal
names. For example, a report table element begins with the prefix ELEMENT,
and is listed as ELEMENT_50, ELEMENT_65, and so on.
3 Available Columns lists the columns you can export from the specified table.
You can export any of the data the report uses, including the data in aggregate
rows and calculated columns. In Available Columns, select the columns to
export one by one and choose the single right arrow after each selection, as
shown in Figure 6-2. To select all columns, choose the double right arrow.
To deselect a column, choose a column from Selected Columns, then choose
the single left arrow. To deselect all the selected columns, choose the double
left arrow.
4 In Encoding Style, select UTF-8, or specify a style in Other. If you do not
specify a style, Actuate BIRT Viewer uses the local encoding style.
5 In Miscellaneous, specify the following information:
■ In Maximum Rows, type the maximum number of data rows to export. To
export all the data rows in the report, accept the default value of No Limit.
■ In Values Separator, choose the Comma (CSV) delimiter.
■ In Localize Column Name, select an option from the following:
❏ Select Export Column Name to export the column name specified in the
data source.
❏ Select Export Column Display Name to export the column name
specified in the report design.

Chapter 6, Exporting report data 29

 ❏ Select Export Column Name and Display Name to export the column
names specified in the data source as well as the one specified in the
report design.

Figure 6-2 Exporting report data

6 You can select the following additional options:
■ When you export report data to a flat file format, select Export Column
Data Type to include the data type information in the flat file. In the
following example, the second line identifies the type of data in the file:
FirstName, LastName, AccountID
STRING, STRING, INT
"Doe", Jane", 1234 …
■ When you export report data that contains date-and-time values, BIRT
Viewer Toolkit formats these values according to the syntax in the current
locale, by default. If no locale is configured, then the viewers use the US
locale as the default. For example, if you export the date 01/10/2009 in the
original format, it can be interpreted as January 10, 2009 or October 1, 2009,
depending on whether the locale is US or France. On Export Data, select
Export Locale Neutral Format to export report data without considering
locale information, so that the date is interpreted correctly in every locale.

30 U s i n g B I R T V i e w e r To o l k i t
 ■ When you select Export Column Header, BIRT Viewer Toolkit exports the
column header in addition to the data in the column. The spreadsheet
displays each exported column below the corresponding column header.
■ When you select Export Data With Carriage Return, BIRT Viewer Toolkit
exports the data using a Carriage Return (CR) character for each line break.
Choose OK.
7 On File Download, the default name and the file extension of the spreadsheet
file appear.
Choose Save.
8 On Save As, complete the following tasks:
1 In Save in, navigate to the folder in which you want to save the file.
2 In File name, change the name of the file. Choose Save. The
comma-separated values (.csv) file appears in the new location.
When you open the file, the output data appears as an editable Microsoft Excel
worksheet. You can expand the columns to view all the data.
Use the same process to export data to pipe-separated values (.psv) files,
tab-separated values (.tsv) files, and semicolon-separated values (.ssv) files.

Exporting content
You can export an entire report, as well as each individual report element, such as
a chart, summary table, or cross tab, to several different formats. Exporting
content to one of these formats creates a file that can be used by applications other
than the viewer. You can export report content to the following file formats:
■ Microsoft Excel (.xls)
■ PDF (.pdf)
■ PostScript (.ps)
■ Microsoft Word (.doc)
■ Microsoft Word (.docx)
■ Microsoft PowerPoint (.ppt)
■ Microsoft PowerPoint (.pptx)
The following sections describe the available formats, as well as the options
available when exporting content to each format. To use Actuate’s commercial
emitters to export content to Excel and PDF formats, you must upgrade to
Actuate BIRT Viewer or Actuate BIRT Interactive Viewer.

Chapter 6, Exporting report data 31

 Exporting content to Microsoft Excel
You can use BIRT Viewer Toolkit to export a BIRT report, selected pages of a BIRT
report, or a specific report element such as a chart, or cross tab, to Microsoft Excel,
Excel 2007, and Excel 2010. The exported content in any version of Excel has
exactly the same layout as the HTML page. In addition, all versions of Excel
support the following properties:
■ Formulas used in computed columns and aggregations in the existing report
or report element are maintained in Excel format.
■ BIRT charts with a single series are exported to Excel as editable Excel charts.
■ Exported images are displayed in Excel.
Each output Excel document contains one content sheet, and one or more data
sheets. If you are exporting a report containing a table view and a chart view of
data, exporting the chart view of the report to Excel results in the exported output
displaying the chart. Similarly, if you export the table view to Excel, Excel
displays tabular data.
You can set the following additional options:
■ Export BIRT charts in the report as an image.
■ Specify the output DPI for charts, to view the exported image in higher
resolution.
How to export a report or report element to Excel
1 To export a report or report element, such as a cross tab or a chart, choose
Export Content from the main menu, as shown in Figure 6-3. Export Content
appears.

Figure 6-3 Exporting a report

2 On Export Content, in Export Format, select Excel, as shown in Figure 6-4.

32 U s i n g B I R T V i e w e r To o l k i t
 Figure 6-4 Exporting content to Excel
3 Expand Page Settings. In Page Settings, provide the following information:
1 Select the page range or specify the page numbers that you want to export.
2 Select Text wrapping to eliminate the need for horizontal scrolling in the
exported report.
3 If exporting a BIRT chart, specify the DPI at which the chart is exported. If
you do not specify a value, BIRT Viewer Toolkit exports the chart at
192 DPI.
Choose OK.
4 File Download appears. The default name assigned to the file and file
extension are visible. Choose Open or Save.
When you open the file, Excel displays the report, and you can edit it as
needed.

Exporting content to PDF format

You can export report content or report elements, such as charts or cross tabs, to
PDF format. The PDF emitter in BIRT Viewer Toolkit provides consistent layout
and pagination properties between PDF and HTML output formats. The PDF
emitter also produces a high-quality PDF file with a small file size. In addition, it
provides high-quality images for charts, and Scalable Vector Graphics (SVG)
format in PDF output. The available customization options are described in the
following section.
How to export a report or report element to PDF format
1 Choose Export Content from the main menu. Export Content appears.
2 On Export Content, in Export Format, select PDF. Select Page Settings.
Export content appears, as shown in Figure 6-5.

Chapter 6, Exporting report data 33

 Figure 6-5 Selecting options to export a report
3 In Page Settings, complete the following steps:
1 Select the page range, or specify the page numbers that you want to export.
2 Select a layout for the exported file from the Page style menu.
3 When a report contains text in languages read from left to right, such as
English or French, and those read from right to left, such as Hebrew or
Arabic, the text from both languages can be presented in the appropriate
direction in the same report. This text is called bidirectional (BIDI) text.
Select BIDI processing if you have a report in two or more such languages
and need the data to be correctly presented in the PDF or PostScript output.
4 Select Text wrapping to eliminate the need for horizontal scrolling in the
exported report.
5 Select Text hyphenation, if necessary.
6 Select Font substitution to substitute any fonts that the application cannot
interpret.
7 Select Embedded font to embed a font being used in the exported output.
8 Enter a value in Chart DPI, specifying the resolution at which to display
the chart, if the report you are exporting contains one or more charts. A
higher DPI results in a larger file size. If you do not specify a DPI, the chart
engine exports the image with a DPI value of 192.
9 Select Render chart in vector graphics for existing charts in SVG format.
This option for SVG images improves the resolution of the exported image,
while maintaining a smaller file size.

34 U s i n g B I R T V i e w e r To o l k i t
 Choose OK.
Depending on the browser you use, File Download appears, as shown in
Figure 6-6. The default name assigned to the file and the file extension are
visible. Choose Open or Save.

Figure 6-6 Exporting data

When you open the file, the report displays as a PDF document.

Exporting content to PostScript format

When you export content to PostScript format, the PostScript emitter displays the
content in the output file, almost exactly the same way as it appears when
printed. The PostScript emitter provides the same options as the PDF emitter,
with two exceptions:
■ The option to export SVG images as vector graphics is not supported.
■ The option to embed fonts from the report being exported is not supported.
How to export a report or report element to PostScript format
1 Choose Export Content from the main menu. Export Content appears.
2 On Export Content, in Export Format, select PostScript.
3 Select Page Settings. In Page Settings, specify the following information:
1 Page range.
2 Page style.
3 Enable BIDI processing.
4 Enable text wrapping.
5 Enable font substitution.
6 If exporting a chart, specify the export DPI. If you do not specify a value,
BIRT Viewer Toolkit exports the chart at 192 DPI.
7 Select Fit to Paper to enable the PostScript emitter to format the report
according to the size of the paper in use.
Choose OK.
4 File Download appears. The default name assigned to the file and file
extension are visible. Choose Open or Save.
When you open the file, the report displays in the format you specified.

Chapter 6, Exporting report data 35

 Exporting content to Microsoft Word
BIRT Viewer Toolkit supports exporting content to Microsoft Word, Word 2007,
and Word 2010. When exporting content to Word 2010, we recommend that you
use the DOCX format in order to avail several features supported only in DOCX
format, and to avoid compatibility issues that occur when using Microsoft
Office 2010. To export content to either version of Word, on Export Content,
specify the following information:
■ Page range for the content you want to export
■ If exporting a chart element, the DPI or resolution
How to export a report or report element to Word format
1 Choose Export Content from the main menu. Export Content appears.
2 On Export Content, in Export Format, select Word (DOC) or Word (DOCX).
3 Select Page Settings. In Page Settings, specify the following options:
1 A page range.
2 If exporting a chart, specify the export DPI. If you do not specify a value,
BIRT Viewer Toolkit exports the chart at 192 DPI.
3 For DOCX format, select Embed HTML to include HTML content directly
in the output document.
Choose OK.
4 File Download appears. The default name assigned to the file and file
extension are visible. Choose Open or Save.
When you open the file, the report displays in the Word format you specified.

Exporting content to Microsoft PowerPoint

BIRT Viewer Toolkit supports exporting content to PowerPoint, PowerPoint 2007,
and PowerPoint 2010 formats. When exporting content to PowerPoint 2010, we
recommend that you use the PPTX format in order to avail several features
supported only in PPTX format, and to avoid compatibility issues that occur
when using Microsoft Office 2010. To export content, or a report element to either
PowerPoint version, specify the following information on Export Content:
■ Page range
■ Page style
■ BIDI processing
■ Text wrapping
■ Font substitution

36 U s i n g B I R T V i e w e r To o l k i t
■ Page overflow processing
■ Chart DPI
How to export a report or report element to PowerPoint format
1 Choose Export Content from the main menu. Export Content appears.
2 On Export Content, in Export Format, select PowerPoint or PowerPoint 2007.
3 Select Page Settings. In Page Settings, specify the following information:
1 Page range.
2 Page style.
3 Enable BIDI processing.
4 Enable text wrapping.
5 Enable font substitution.
6 Page overflow processing.
7 If exporting a chart, specify the export DPI. If you do not specify a value,
BIRT Viewer Toolkit exports the chart at 192 DPI.
Choose OK.
4 File Download appears. The default name assigned to the file and file
extension are visible. Choose Open or Save.
When you open the file, the report displays in the PowerPoint format you
specified.

Chapter 6, Exporting report data 37

38 U s i n g B I R T V i e w e r To o l k i t
 7
Chapter

Filtering report data

Chapter 7

This chapter contains information about providing parameter values.

Chapter 7, Filtering report data 39

Providing parameter values
If a report design already uses filters and requires you to enter values to display
data, you are prompted to enter these values before a report is run. The prompt
value is called a parameter. Parameters enable users to control displayed content
without editing the report. You can modify the parameter values at any time by
choosing the Parameters option from the main menu. For example, in a report
that displays sales data by sales office, you can use parameter values to select
which sales office data to view in the report. Even if you are the only person
reading the report, a parameter value enables you to view specific content in the
report.
If you save a report design file containing parameters as a report document file,
the user can no longer specify parameter values to view specific data. The
viewers display data based on parameter values specified when the report design
was saved as a report document file.
Reports using dynamic filters require you to first select an operator, and then
supply one or more parameter values for which the viewers display data.
Supplying specific parameter values in such reports is often optional, and you
can select the No Condition operator to view all the data in the report. You cannot
create dynamic filters using the viewers.
How to enter parameter values at run time
1 Run the report from the list of available reports. If the report contains filters
and requires parameter values, the Parameters dialog box appears, requiring
you to enter or choose specific values based on which data is retrieved and
displayed.
2 Choose the field for which you want to view data, or enter a value. For
example, in a report containing customer order history data, to view a specific
customer’s order history, choose the customer’s name from the list, as shown
in Figure 7-1.
Choose Finish to view the report. The report in the example displays the order
history for Boards & Toys Co.

Figure 7-1 Entering parameter values

How to modify parameter values in the viewers
1 From the main menu, choose Parameters.

40 U s i n g B I R T V i e w e r To o l k i t
2 A Parameters section appears in the lower pane of the viewer. The example in
Figure 7-2 shows the details for Boards & Toys Co. Choose another customer
from the list. Then choose Run Report from the Parameters toolbar.

Report

Parameters
section
Run Report

Close

Figure 7-2 Viewer displaying report and the Parameters section

The report displaying data for the selected customer appears in the upper part
of the viewer. To view all the data on the current page, use the scroll bar in the
report section, or collapse the Parameters section.
You can only modify parameter values for reports that already contain filters and
require the use of parameter values to view data. If the report you generate does
not use parameters, when you choose the Parameters option from the main
menu, a message appears informing you that the report contains no parameters.
How to select an operator and specify one or more parameter values
1 Run the report from the list of available reports. If the report contains filters
and requires parameter values to display data, Parameters appears, as shown
in Figure 7-3.

Figure 7-3 Specifying operators and parameter values

2 Select an operator in the first field, Customer. To view data for all customers,
select No Condition, as shown in Figure 7-3.
3 Select an operator from the drop-down list in the next field, City, and specify
one or more values from the list of values that appears. To select more than

Chapter 7, Filtering report data 41

 one value, press Ctrl while selecting each additional value. To select a range of
values select the first value, press Ctrl+Shift and select the last value in the
range.
4 Select an operator from the drop-down list in the next field, Credit Limit, and
type a value in the associated field that appears. To view all credit limits, select
No Condition.
Choose Finish. The report displays data for the parameter values you
specified.

42 U s i n g B I R T V i e w e r To o l k i t
 8
Chapter

Chapter 8 Working with charts

This chapter contains the following topics:
■ About charts
■ Types of charts
■ Exporting data from a chart
■ Exporting a chart

Chapter 8, Working with char ts 43

About charts
A chart is a graphical representation of data in a report. You use charts to display
complex data in a format that is easily understood. A report can contain a chart
that functions as a report itself, or it can combine a chart with other report
elements to highlight relevant information. This section provides an overview of
the different types of charts you can view in BIRT Viewer Toolkit, and explains
how you can export charts and chart data to other formats.
A chart displays data as one or more sets of points. Charts are particularly useful
for summarizing numeric data and showing the relationship between sets of
values called series. The two types of series are category series and value series,
typically denoted by the x- and y-axis. For example, a chart can show sales by
region, average temperatures by month, or the price of a stock over three months.

Types of charts
Specific types of data are best depicted with a specific type of chart. This section
describes the common types of charts you can view using BIRT Viewer Toolkit.

About bar charts

A bar chart typically displays data values as a set of vertical bars, but you can
transpose the axis to display horizontal bars. When you view report data in a
chart with vertical bars, you can easily compare the values. A bar chart is useful
to show data changes from one time period to another, for example from one year
or quarter to another, or to illustrate comparisons among items.
Standard bar charts are side by side, but you can have stacked and percent
stacked bar charts that also show the relationship of individual items to a whole.
Side-by-side bar charts show bars from each series, one beside the other. Each of
these bars have the same width. The width depends on the number of series
being plotted. Stacked bar charts show bars stacked one above the other. The
stacked bar chart shows totals for each series as well as the proportion that each
series contributes to the grand total. In a percent stacked bar chart, multiple series
are stacked vertically and the values appear as a percentage of the whole.

About tube, cone, and pyramid charts

Tube, cone, and pyramid charts are variations of the bar chart that use tubular,
conical, and pyramid-shaped risers in place of bars. You use a bar, tube, cone, or
pyramid chart when you want to display data values as a set of vertical or
horizontal columns.

44 U s i n g B I R T V i e w e r To o l k i t
About area charts
An area chart displays data values as a set of points connected by a line, with the
area shaded below the line. You use an area chart to present data that occurs over
a continuous period of time. For example, you can use an area chart to view the
percentage of orders and the corresponding unit volume for trains, ships, and
planes over three months.
A stacked area chart consists of multiple series stacked vertically. Overlay area
charts show areas from each series independent of each other. The areas appear
by joining the values for the series. In an overlay area chart, the areas of multiple
series overlap. In a percent stacked area chart, multiple series are stacked
vertically and the values appear as a percentage of the total.

About line charts

A line chart displays data values as a set of points connected by a line. You
typically use line charts to present large amounts of data that occur over a
continuous period of time. A line chart is similar to an area chart, except that it
does not fill in the area below the line, and it uses a square to mark each data
value. There are three subtypes of line charts.
In an overlay line chart, multiple series appear as overlapping lines. In a stacked
line chart, multiple series are stacked vertically. A percent stacked line chart
consists of multiple series stacked vertically and the values shown as a percentage
of the whole.

About pie charts

Pie charts show values as slices of a pie. The size of each slice is proportional to
the value it represents. You plot pie charts for multiple series as multiple pies, one
for each series. You use a pie chart to show the relationship of parts to the whole.

About meter charts

A meter chart is very effective when showing a small number of values in a
prominent manner. A meter chart displays a value as a needle pointer on a
circular or semicircular dial. You can use a meter chart to create a gauge or
dashboard display.
A standard meter chart displays multiple values in multiple dials, where each
dial displays a single value. A superimposed meter chart displays multiple values
in a single dial.

About stock charts

A stock chart shows data as points on a time continuum, such as days of the
week. Stock values appear as a candlestick, a box with lines extending up and

Chapter 8, Working with char ts 45

 down from the ends. Open and close values mark the upper and lower edges of
the box. High and low values mark the upper and lower points of the line.
Although a stock chart typically displays stock price data, you can also use a
stock chart to show scientific data, such as temperature changes over time.
Candlestick stock charts contain boxes with lines extending up and down from
the ends. The upper and lower edges are the open and close values of the stock.
The upper and lower points of the line are the high and low values of the stock.
Bar stick stock charts consist of a vertical line with two horizontal lines called
ticks attached to it. The upper and lower points of the vertical line are the stock
open and close values. The ticks are the high and low values.

About scatter charts

A scatter chart presents data as x-y coordinates by combining two sets of numeric
values into single data points. A scatter chart typically displays scientific and
statistical data, because it shows if there is a relationship between two sets of
measurements. Use a scatter chart to compare, for example, salaries and years of
experience, weight and body fat, rainfall amounts and pollen levels, or test scores
and hours of study. The greater the number of data values you include in a scatter
chart, the clearer are the trends the data reveals. A scatter chart shows data as
points. Scatter charts display values on both axes.

About bubble charts

A bubble chart resembles a scatter chart, but uses bubbles instead of data points.
You choose a bubble chart instead of a scatter chart if you have three values per
data point.

Exporting data from a chart

You can export data from a chart to a flat file format that uses a comma, tab, pipe,
or semicolon delimiter. These file formats can be read by Microsoft Excel.
How to export data from a chart
Select the chart, and choose Export Data from the chart menu. On Export Data,
specify the data to export, and other options, in the same way you did when
exporting report data.

Exporting a chart
You can export a chart to Excel, Excel 2007 and 2010, Microsoft Word, Microsoft
Word 2007 and 2010, Microsoft PowerPoint, Microsoft PowerPoint 2007 and 2010,

46 U s i n g B I R T V i e w e r To o l k i t
PDF, and PostScript formats. BIRT Viewer Toolkit does not support exporting a
report or report elements using Actuate’s commercial emitters.
How to export a chart to other formats
Select the chart, and choose Export Content from the chart menu. On Export
Content, specify the options in the same way you did when exporting report
content. Additionally, you can specify:
■ Resolution in DPI at which to export the chart
■ Exporting the chart as an image

Chapter 8, Working with char ts 47

48 U s i n g B I R T V i e w e r To o l k i t
 9
Chapter

Chapter 9 Working with cross tabs

This chapter contains the following topics:
■ About cross tabs
■ Exporting cross tab content

Chapter 9, Working with cross tabs 49

About cross tabs
A cross tab displays summary or aggregate values, such as sums, counts, or
averages, in a row-and-column matrix similar to a spreadsheet. For example, you
can use a cross tab to view sales data for each product line, by year, or total sales
for each product line, by geography, and so on.
You can export cross tab content to other formats such as Excel, Word,
PowerPoint, PostScript, or PDF. You can also print cross tab content, modify
charts, Flash charts and Flash gadgets in a cross tab, and save a cross tab as a BIRT
design (.rptdesign) or BIRT document (.rptdocument) file.

Introducing a cross tab

A cross tab is ideal for summarizing data in a compact and concise format. The
aggregate values in a cross tab are arranged in dimensions and measures, and
each cross tab can display multiple dimensions and multiple measures. The data
for a cross tab is derived from a cube, which also arranges data in dimensions and
measures. Dimensions are categories, such as products, customers, or sales
periods, by which measures are aggregated. Measures represent values that are
counted or aggregated, such as costs or units of products.
A cross tab has the following characteristics:
■ It requires at least three fields. In the example cross tab shown in Figure 9-1,
the three fields are year, product line, and revenue.
■ One field populates the column headings in the cross tab. There is one column
for each unique value in the field.
■ One field populates the row headings in the cross tab. There is one row for
each unique value in the field.
■ One field’s values are aggregated, and these values populate the cells of the
cross tab. In the example, each cell displays a sales total by product line, for
each month and quarter, in the year 2004. The sales total is calculated by
applying the SUM aggregate function across the values in the extended price
field.

Parts of a cross tab

A cross tab consists of the following three areas, as shown in Figure 9-1:
■ The row area
■ The column area
■ The detail area

50 U s i n g B I R T V i e w e r To o l k i t
 The row and column areas contain the dimensions. The dimension values form
the row and column headings of the cross tab. The detail area contains one or
more measures to display aggregate data.
Figure 9-1 shows an example report, which groups data by month, quarter, and
year. Each number in the cross tab represents the sales total of a particular
product for a particular month. Grand Total displays the total sales of all products
for each month, the total sales for each quarter, and the total sales across months
and quarters in 2004. Grand Total also displays the total sales for each product
line by month, quarter, and for the whole year.
Rows Columns

Detail
area

Figure 9-1 Parts of a cross tab

Exporting cross tab content

You can export cross tab content to other formats, such as Excel, PDF, PostScript,
PowerPoint, and Word, just as you can export content from a BIRT report. When
you export a cross tab to Microsoft Excel, Excel displays the cross tab as a pivot
table, in which you can further analyze existing data.

Chapter 9, Working with cross tabs 51

52 U s i n g B I R T V i e w e r To o l k i t
 Part Three 3

Part 3 Using Actuate JavaScript API

 10
Chapter

Creating a custom web

Chapter 10

page using the Actuate

JavaScript API
This chapter contains the following topics:
■ About the Actuate JavaScript API
■ Accessing the Actuate JavaScript API
■ Establishing an HTTP session with an Actuate BIRT Viewer Toolkit
application
■ About Actuate JavaScript API security integration
■ Viewing reports
■ Using and submitting report parameters

C ha p t e r 10 , C r e at in g a c us t om web p a ge u s i ng t h e A c t u a t e Java S c r ip t A P I 55
About the Actuate JavaScript API
The Actuate JavaScript API enables the creation of custom web pages that
incorporate Actuate BIRT reports. The Actuate JavaScript API classes functionally
embed BIRT reports into web pages using div elements. To use the Actuate
JavaScript API, deploy the BIRT Viewer Toolkit web application and reference the
JSAPI libraries in the HTML script markup that uses JSAPI functions.
The Actuate JavaScript API uses the Prototype JavaScript Framework. The
following directory contains the Actuate JavaScript API source files:
<Context Root>\jsapi
The base class in the Actuate JavaScript API is actuate. The actuate class is the
entry point for all of the Actuate JavaScript API classes. The actuate class
establishes connections to the Actuate BIRT Viewer Toolkit application services.
The Actuate JavaScript API uses HTTP requests to retrieve reports and report
data from an Actuate web service. The subclasses provide functionality that
determines the usage of the reports and report data.
Many functions in the Actuate JavaScript API use a callback function. A callback
function is a custom function written into the web page that is called immediately
after the function that calls it is finished. A callback function does not execute
before the required data or connection has been retrieved from the server.
Many of the callback functions in the Actuate JavaScript API use a passback
variable. A passback variable contains data that is passed back to the page by the
calling function. A callback function that uses an input parameter as a passback
variable must declare that input parameter.

Accessing the Actuate JavaScript API

To use the Actuate JavaScript API from a web page, add a script tag that loads the
Actuate JavaScript API class libraries from an Actuate application.
Start with a web page that contains standard HTML elements, as shown in the
following code:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html;
charset=utf-8" />
</head>
<body>

56 Using Actuate JavaScript API

 <div id="viewer1">
<script type="text/javascript" language="JavaScript"
src="http://localhost:8080/webapp/jsapi"></script>
<script type="text/javascript" language="JavaScript">
… <!--functionality goes here-->
</script>
</div>
</body>
</html>
The <script> element nested in the <div> element imports the Actuate JavaScript
API libraries into the web page’s context. For example:
<script type="text/javascript" src="http://localhost:8080/
webapp/jsapi">
</script>
■ localhost:8080 is the host name and TCP port for an available BIRT Viewer
Toolkit web application host.
■ /webapp is the context root for the BIRT Viewer Toolkit web service.
■ /jsapi is the default location of the Actuate JavaScript API libraries.
Use additional script tags to call JavaScript functions for the page. Use the
actuate.load( ) function to enable the components of the Actuate JavaScript API.
The scripts in this section are encapsulated in <div> tags for portability.
Encapsulated Actuate JavaScript API functions can be used in any web page.

About the DOCTYPE tag

To render the page in standards compliance mode, specify strict.dtd in the
DOCTYPE tag at the top of the page. Standards compliance mode makes the page
layout and behaviors significantly more consistent. Pages without this definition
render inconsistently.

About UTF-8 character encoding

Use a <meta> tag to direct the browser to use UTF-8 encoding for rendering and
sending data. UTF-8 encoding prevents the loss of data when using
internationalized strings.

Establishing an HTTP session with an Actuate BIRT

Viewer Toolkit application
The actuate class is the general controller for the HTTP session. Call
actuate.initialize( ) to establish a connection to the Actuate BIRT Viewer Toolkit.

C ha p t e r 10 , C r e at in g a c us t om web p a ge u s i ng t h e A c t u a t e Java S c r ip t A P I 57
 Load the elements that are selected by actuate.load( ) before accessing reports or
applications. Initialization establishes a session with an Actuate service. To
initialize the actuate object, call the actuate.initialize( ) initialization function. To
use actuate.initialize( ), provide connection parameters as shown in the following
code:
actuate.initialize("http://localhost:8080/webapp", null, null,
null, runReport, null);
■ http://localhost:8080/webapp is a URL for the Actuate report application
service. This URL must correspond to a BIRT Viewer toolkit web application.
■ null specifies the default settings for RequestOptions that are provided by the
Actuate BIRT Viewer Toolkit application. RequestOptions sets custom or
additional URL parameters for the request. To use custom or additional URL
parameters, construct an actuate.RequestOptions object, assign the specific
values to the object, and put the object into the URL parameter.
■ The third and fourth parameters are reserved. Leave these parameters as null.
■ runReport is the callback function called after the initialization finishes.
Specify the callback function on the same page as the initialize function. The
callback function cannot take a passback variable.
■ null specifies the optional errorCallback parameter. The errorCallback
parameter specifies a function to call when an error occurs.
The initialization procedure in this section is the first step in using Actuate
JavaScript API objects. Nest the initialization code in the second <script> element
in the <div> element of the page.
The runReport( ) function is used as a callback function that executes
immediately after actuate.initialize( ) completes. The page must contain
runReport( ).

About Actuate JavaScript API security integration

The web service that provides reports also establishes security for a reporting
web application. The actuate.initialize( ) function prompts users for
authentication information if the web service requires authentication. The
Actuate JavaScript API uses a secure session when a secure session already exists.
Remove authentication information from the session by using actuate.logout( ).

Establishing a connection to more than one web

service
The actuate.initialize( ) function establishes a session with one Actuate BIRT
Viewer Toolkit application service. Use the actuate.authenticate( ) function for

58 Using Actuate JavaScript API

additional sessions with other Actuate BIRT Viewer Toolkit application services.
Call actuate.initialize( ) before calling actuate.authenticate( ).
Use authenticate( ) as shown in the following code:
actuate.authenticate(serviceurl,
null, null, null, null,
callback,
errorcallback);
■ serviceurl is a URL for the Actuate web application service in use. This URL
must correspond to an Actuate BIRT Viewer Toolkit application.
■ null specifies the default settings for the RequestOptions object that is
provided by the connected Actuate BIRT Viewer Toolkit application.
RequestOptions sets custom or additional URL parameters for the request. To
use custom or additional URL parameters, construct an
actuate.RequestOptions object, assign the specific values to the object, and put
the object into the custom or additional URL parameter.
■ The third and fourth parameters are reserved. Leave these parameters as null.
■ null specifies no additional user credentials. This parameter holds information
that supports external user credential verification mechanisms, such as LDAP.
Add any required credential information with this parameter where
additional security mechanisms exist for the application server upon which
the web service is deployed.
■ callback is a function to call after the authentication completes.
■ errorcallback is a function to call when an exception occurs.
After authenticate( ) finishes, access resources from the Actuate BIRT Viewer
Toolkit application service at the URL in serviceurl.
Application servers share session authentication information to enable a user to
log in to one application context root and have authentication for another. For
example, for Apache Tomcat, setting the crossContext parameter to "true" in the
server.xml Context entries allows domains to share session information. The
entries to share the authentication information from the web application with
Actuate BIRT Viewer Toolkit look like the following example:
<Context path="/MyApplication" crossContext="true" />
<Context path="/ActuateJavaComponent" crossContext="true" />

Unloading authentication information from the

session
The Actuate JavaScript API keeps authentication information encrypted in the
session. To remove this information from the session, use actuate.logout( ). Use
logout( ) as shown in the following code:

C ha p t e r 10 , C r e at in g a c us t om web p a ge u s i ng t h e A c t u a t e Java S c r ip t A P I 59
 actuate.logout(serviceurl,
null,
callback,
errorcallback);
■ serviceurl is a URL for the Actuate web application service to log out from.
This URL must correspond to an Actuate BIRT Viewer Toolkit application.
■ null specifies the default settings for RequestOptions that are provided by the
connected Actuate web application. RequestOptions sets custom or additional
URL parameters for the request. To use custom or additional URL parameters,
construct an actuate.RequestOptions object, assign the specific values to the
object, and put the object into the custom or additional URL parameter.
■ callback is a function to call after logout( ) completes.
■ errorcallback is a function to call when an exception occurs.
After logout( ) finishes, the authentication for the serviceurl is removed.
Authenticate again to establish a secure connection.

Viewing reports
The actuate.Viewer class loads and displays reports and report content. Load
actuate.Viewer with actuate.load( ) before calling actuate.initialize( ), as shown in
the following code:
actuate.load("viewer");
Load the viewer component to use the viewer on the page. Call actuate.Viewer
functions to prepare a report, then call the viewer’s submit function to display the
report in the assigned <div> element.
The actuate.Viewer class is a container for Actuate reports. Create an instance of
actuate.Viewer using JavaScript, as shown in the following code:
var myViewer = new actuate.Viewer( "viewer1" );
The "viewer1" parameter is the name value for the <div> element which holds the
report content. The page body must contain a <div> element with the id viewer1
as shown in the following code:
<div id="viewer1"></div>
Use setReportName( ) to set the report to display in the viewer, as shown in the
following code:
myViewer.setReportName("/public/customerlist.rptdocument");
SetReportName accepts a single parameter, which is the path and name of a
report file in the repository. In this example, "/public/customerlist.rptdesign"
indicates the Customer List report design in the /public directory.

60 Using Actuate JavaScript API

Call viewer.submit( ) to make the viewer display the report, as shown in the
following code:
myViewer.submit( );
The submit( ) function submits all the asynchronous operations that previous
viewer functions prepare and triggers an AJAX request for the report. The
Actuate BIRT Viewer Toolkit application returns the report and the page displays
the report in the assigned <div> element.
This is an example of calling viewer( ) in a callback function to display a report:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text
/html;charset=utf-8" />
<title>Viewer Page</title>
</head>
<body onload="init( )">
<div id="viewerpane">
<script type="text/javascript" language="JavaScript"
src="http://localhost:8080/webapp/jsapi"></script>
<script type="text/javascript" language="JavaScript">
function init( ){
actuate.load("viewer");
actuate.initialize( "http://localhost:8080/webapp", null,
null, null, runReport);
} function runReport( ) {
var viewer = new actuate.Viewer("viewerpane");
viewer.setReportName("/Public
/Top 5 Sales Performers.rptdesign");
viewer.submit(callback);
}
</script>
</div>
</body>
</html>
The viewer component displays an entire report. If the report is larger than the
size of the viewer, the viewer provides scroll bars to navigate the report. To
display a specific element of a report instead of the whole report, use
viewer.setReportletBookmark( ) prior to calling submit( ), as shown in the
following code:

C ha p t e r 10 , C r e at in g a c us t om web p a ge u s i ng t h e A c t u a t e Java S c r ip t A P I 61
 function init( ) {
actuate.load("viewer");
actuate.initialize( "http://localhost:8080/webapp", null,
null, null, runReport);
function runReport( ) {
var viewer = new actuate.Viewer("viewerpane");
viewer.setReportName("/Public
/Top 5 Sales Performers.rptdesign");
viewer.setReportletBookmark("FirstTable");
viewer.submit(callback);
When the FirstTable bookmark is assigned to any table, this code displays that
table.
Any changes to the report display must take place after viewer.submit( )
completes. Embed presentation code in a callback class to ensure proper
execution.

Using and submitting report parameters

Use the actuate.Viewer class to run report design and executable files. When a
report design or executable runs, actuate.Viewer accepts parameters that modify
the report output.
The actuate.Parameter class handles parameters and parameter values. The
actuate.Parameter class enables a web page to display and gather parameters
from users before processing and downloading a report to the client. Load the
actuate.Parameter class with actuate.load( ), as shown in the following code:
actuate.load("parameter");
Load the parameter component to use it later in the page. Call actuate.Parameters
functions to prepare a parameters page, display the parameters in the assigned
<div> element, and assign the parameters to the viewer object for processing.

Using a parameter component

The actuate.Parameter class is a container for Actuate report parameters. Create
an instance of the actuate.Parameter class using JavaScript, as shown in the
following code:
var myParameters = new actuate.Parameter( "param1" );
The value of the "param1" parameter is the name value for the <div> element that
holds the report parameters display. The page body must contain a <div>
element with the param1 id, as shown in the following code:
<div id="param1"></div>

62 Using Actuate JavaScript API

Use setReportName( ) to set the report from which to retrieve parameters, as
shown in the following code:
myParameters.setReportName("/public/customerlist.rptdesign");
The setReportName( ) function takes the path and name of a report file
in the repository as the only parameter. In this example, "/public
/customerlist.rptdesign" indicates the Customer List report design in the /public
directory.
To download the parameters and display them in a form on the page, call
parameter.submit( ), as shown in the following code:
myParameters.submit(processParameters);
The submit( ) function submits all of the asynchronous operations prepared by
the calls to parameter functions. The submit function also triggers an AJAX
request to download the report parameters to the client. The Actuate BIRT Viewer
Toolkit application sends the requested report parameters and the page displays
them as a form in the assigned <div> element. The submit( ) function takes a
callback function as a parameter, shown above as processParameters.
The following code example calls parameter in the callback function for
actuate.initialize( ) to display a parameter:
<div id="param1">
<script type="text/javascript" language="JavaScript"
src="http://localhost:8080/webapp/jsapi"></script>
<script type="text/javascript" language="JavaScript">
function init( ){
actuate.load("viewer");
actuate.load("parameter");
actuate.initialize( "http://localhost:8900/webapp", null,
null, null, displayParams);
}
function displayParams( ) {
param = new actuate.Parameter("param1");
param.setReportName("/Public
/Customer Order History.rptdesign");
param.submit(function ( ) { this.run.style.visibility=
'visible';});
}function processParameters( ) {
…
}
</script></div>
The parameter component displays all of the parameters of the report in a form.
When the parameters page is larger than the size of the viewer, the viewer
provides scroll bars to navigate the parameters page.

C ha p t e r 10 , C r e at in g a c us t om web p a ge u s i ng t h e A c t u a t e Java S c r ip t A P I 63
 To retrieve the parameters, use actuate.Parameter.downloadParameterValues( ).
This function takes a callback function as an input parameter. The callback
function processes the parameter values, as shown in the following code:
function processParameters( ) {
myParameters.downloadParameterValues(runReport);
}
The downloadParameterValues( ) function requires the callback function to
accept an array of parameter name and value pairs. The API formats this array
properly for the actuate.Viewer class.

Accessing parameter values from the viewer

The actuate.Viewer.setParameterValues( ) function adds the parameters set by the
user to the viewer component. The setParameterValues( ) function takes as an
input parameter an object composed of variables whose names correspond to
parameter names. The downloadParameterValues( ) function returns a properly
formatted object for use with actuate.Viewer.setParameterValues( ). The
following code example shows how to call downloadParameterValues( ) and
move the parameter name and value array into the viewer with
actuate.Viewer.setParameterValues( ):
function runReport(ParameterValues){
var viewer = new actuate.Viewer("viewerpane");
viewer.setReportName("/Public
/Customer Order History.rptdesign");
viewer.setParameterValues(ParameterValues);
viewer.submit( );
}
When the viewer calls submit( ), the client transfers the parameters to the server
with the other asynchronous operations for the viewer.
The following code example shows a custom web page that displays parameters
and then shows the report in a viewer using those parameters:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/
html;charset=utf-8" />
<title>Viewer With Parameters Page</title>
</head>
<body onload="init( )">
<div id="parampane">
<script type="text/javascript" language="JavaScript"
src="http://localhost:8080/webapp/jsapi"></script>
<script type="text/javascript" language="JavaScript">

64 Using Actuate JavaScript API

 function init( ){
actuate.load("viewer");
actuate.load("parameter");
actuate.initialize( "http://localhost:8080/webapp", null,
null, null, displayParams);
}
function displayParams( ) {
param = new actuate.Parameter("parampane");
param.setReportName("/Public
/Customer Order History.rptdesign");
param.submit(
function ( ) {this.run.style.visibility = 'visible';});
}
function processParameters( ) {
param.downloadParameterValues(runReport);
}
</script>
</div>
<hr><br />
<input type="button" class="btn" name="run"
value="Run Report" onclick="processParameters( )"
style="visibility: hidden">
<div id="viewerpane">
<script type="text/javascript" language="JavaScript"
src="http://localhost:8080/webapp/jsapi"></script>
<script type="text/javascript" language="JavaScript">
function runReport(paramvalues) {
var viewer = new actuate.Viewer("viewerpane");
viewer.setReportName("/Public
/Customer Order History.rptdesign");
viewer.setParameterValues(paramvalues);
viewer.submit( );
}
</script>
</div>
</body>
</html>
The code in the example uses the administrator user credentials and a report at
the following path:
/Public/Customer Order History.rptdesign

C ha p t e r 10 , C r e at in g a c us t om web p a ge u s i ng t h e A c t u a t e Java S c r ip t A P I 65
66 Using Actuate JavaScript API
 11
Chapter

Actuate JavaScript API

Chapter 11

classes
This chapter contains the following topics:
■ Actuate JavaScript API overview
■ Actuate JavaScript API classes quick reference
■ Actuate JavaScript API reference

Chapter 11, Actuate JavaScript API classes 67

Actuate JavaScript API overview
The Actuate JavaScript API is a set of JavaScript classes used to create custom web
content that contains Actuate BIRT reports and report elements.
An HTML-based JSDoc JavaScript API class reference is provided for Actuate
BIRT Viewer Toolkit in the following file:
<Context Root>\help\jsapi\index.html

About the actuate namespace

All of the Actuate JavaScript API classes are in the actuate namespace. To use the
viewer element, call the actuate.Viewer class.
In addition, the Actuate JavaScript API has a static class:
actuate
This class handles connections to Actuate web applications and is the only static
class in the Actuate JavaScript API.

Using the Actuate library

The Actuate JavaScript library is available from any Actuate BIRT Viewer Toolkit
installation. The URL for the library is:
http://localhost:8080/webapp/jsapi
■ localhost:8080 is the host name and TCP port for an available Actuate web
application host.
■ /webapp is the context root for the web application.
■ /jsapi is the default location of the Actuate JavaScript API libraries.
A script tag loads the Actuate JavaScript API library, as shown in the following
code:
<script type="text/javascript" src="http://localhost:8080
/webapp/jsapi">
</script>
To call JavaScript functions, use additional script tags after the script tag that adds
these libraries for the page.

Actuate JavaScript API classes quick reference

Table 11-1 lists the Actuate JavaScript API classes.

68 Using Actuate JavaScript API

 Table 11-1 Actuate JavaScript API classes
JavaScript class Description
actuate Entry point to the Actuate JavaScript
API library
actuate.Exception Exception object passed to a callback
function or exception handler
actuate.Parameter Parameters from a report
actuate.parameter.Constants Global navigation and layout constants
used for the Parameter class
actuate.parameter.ConvertUtility Converts parameters into specific and
generic formats
actuate.parameter.EventConstants Defines the events for parameters this
API library supports
actuate.parameter.NameValuePair Display name and the associated value
actuate.parameter.ParameterValue The parameter’s value as processed by a
report
actuate.RequestOptions URL parameters for connection requests
actuate.Viewer A report viewer component that can be
embedded in an HTML page
actuate.viewer.EventConstants Defines the events for the viewer this
API library supports
actuate.viewer.ParameterValue Parameter values in the viewer
actuate.viewer.ViewerException Exception constants supported for the
viewer

Actuate JavaScript API reference

This section provides an alphabetical listing of the JavaScript API classes.

Chapter 11, Actuate JavaScript API classes 69

Class actuate
Description The entry point to the Actuate JavaScript API library. The actuate class uses
load( ) to generate viewer and parameter components. The actuate class uses
initialize( ) and authenticate( ) to connect to an Actuate web application service.
Use actuate.load( ) before calling actuate.initialize( ). The actuate.initialize( )
function loads all of the components added with load( ).
The initialize( ) function connects to an initial Actuate web application service. To
connect to additional services simultaneously, use authenticate( ). Call initialize( )
before calling authenticate( ).

Constructor
The static actuate class loads when a <script> element loads the Actuate
JavaScript API.

Function summary
Table 11-2 lists actuate functions.
Table 11-2 actuate functions
Function Description
authenticate( ) Connects to an Actuate web application service
getDefaultIportalUrl( ) Returns the default service URL
getDefaultRequestOptions( ) Returns the default request options
getViewer( ) Returns a viewer instance containing the given
bookmark element
initialize( ) Connects to an initial Actuate web application
service, imports library components, and
invokes a callback function
isConnected( ) Reports whether a given Actuate web
application is connected
isInitialized( ) Returns whether a library is initialized
load( ) Loads the library for an additional component
logout( ) Logs a user out of an Actuate web application
service

70 Using Actuate JavaScript API

 actuate.authenticate
Syntax void authenticate(string iPortalURL, actuate.RequestOptions requestOptions,
reserved, reserved, function callback, string credentials, function
errorCallback)
Connects to the Actuate web application service that is addressed by iPortalURL
and authenticates the connection.
Parameters iPortalURL
The iPortalURL parameter is a required string parameter that specifies the target
Actuate web application URL.
requestOptions
The requestOptions parameter is an optional actuate.RequestOptions object. The
requestOptions parameter defines the URL parameters to send with the
connection request. Functions in the RequestOptions class enable the addition of
custom parameters to the URL. When requestOptions is null, authenticate( ) uses
the default parameter values for the target Actuate web application URL. These
default parameter values are defined in the Actuate web application’s web.xml
file.
reserved
Set to null.
reserved
Set to null.
credentials
The credentials parameter is an optional string parameter. This parameter holds
information that supports checking user credentials with an externalized system
such as LDAP. The credentials parameter supports additional credential
information for any additional security systems in place on the application server
where the web service is deployed.
callback
The callback parameter is an optional function to call after authentication. The
actuate.authenticate( ) function passes the following variables to the callback
function, if applicable:
■ iportalURL: The iportal URL passed in from the iPortalURL parameter
■ userid: The authenticated user ID
errorCallback
The errorCallback parameter is an optional function that specifies a function to
call when an error occurs. The possible errors are actuate.ConnectionException,
actuate.AuthenticationException, and actuate.Exception. The callback function
must take an exception as an argument.

Chapter 11, Actuate JavaScript API classes 71

 Example To connect to an additional Actuate web service called digits, use code similar to
the following:
actuate.authenticate("http://digits:8080/webapp", null, null,
null, null, null, null);

actuate.getDefaultIportalUrl
Syntax String getDefaultIportalUrl( )
Returns the default service URL.
Returns String. The default service URL.
Example This example calls actuate.getDefaultIportalUrl( ) to return the default service
URL:
alert ("The default service URL is " + getDefaultIportalUrl( ));

actuate.getDefaultRequestOptions
Syntax actuate.RequestOptions getDefaultRequestOptions( )
Returns the default request options.
Returns actuate.RequestOptions object that contains the default request options.
Example This example calls actuate.getDefaultRequestOptions( ) to return the default
locale:
alert ("The default locale is " +
actuate.getDefaultRequestOptions( ).getLocale( ));

actuate.getViewer
Syntax actuate.Viewer getViewer(string bookmark)
actuate.Viewer getViewer(htmlelement viewer)
Returns a viewer instance containing the given bookmark element. Load the
viewer module before calling actuate.getViewer( ).
Parameters bookmark
This string parameter contains the name of the bookmark to retrieve or the name
of an HTML <div> element.
viewer
This parameter is the DOM htmlelement object for the HTML <div> element that
contains a viewer.
Returns An actuate.Viewer object that contains a viewer. When actuate.getViewer( ) does
not find a viewer, the function returns null.

72 Using Actuate JavaScript API

 Example To retrieve the viewer assigned to the first_viewer <div> element on the page, use
code similar to the following:
currentViewer = actuate.getViewer("first_viewer");

actuate.initialize
Syntax void initialize(string iPortalURL, actuate.RequestOptions requestOptions,
reserved, reserved, function callback, function errorCallback)
Connects to an initial Actuate web application service, loads all of the
components added with load( ), and invokes a callback function. Authentication
is optional in initialize( ).
When using more than one service in one mashup page, use
actuate.authenticate( ) to connect to additional services.
Parameters iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL
parameters to send in the connection request. It can also add custom parameters
to the URL. If requestOptions is null, initialize( ) uses the default parameter
values for the target Actuate web application URL. These default parameter
values are defined in Actuate web application’s web.xml file.
reserved
Set to null.
reserved
Set to null.
callback
Function. The callback function called after the initialization is done. The
following variables are passed to the callback function:
■ iportalUrl: The iportal URL passed in from the iPortalURL parameter
errorCallback
Function. The function to call when an error occurs. The possible errors are
actuate.ConnectionException, actuate.AuthenticationException, and
actuate.Exception. errorCallback must take an exception as an argument.
Example To initialize the client connection to a web service on myhost and then run the
init( ) function, use the following code:
actuate.initialize("http://myhost:8700/iportal", null, null, null,
init, null);

Chapter 11, Actuate JavaScript API classes 73

 actuate.isConnected
Syntax boolean isConnected(string iportalUrl, actuate.RequestOptions requestOptions)
Returns whether a given Actuate web application URL is connected.
Parameters iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL
parameters to send in the connection test. It can also add custom parameters to
the URL. If requestOptions is null, isConnected( ) uses the default parameter
values for the target Actuate web application URL. These default parameter
values are defined in Actuate web application’s web.xml file.
Returns Boolean. True if there is a connection to the given Actuate web application, False
if there is no connection or if it is pending.
Example The following sample code connects to the digits service using authenticate if not
currently connected:
if (!actuate.isConnected("http://digits:8700/iportal", null)){
actuate.authenticate("http://digits:8700/iportal", null, null,
null, null, null, null);
}

actuate.isInitialized
Syntax boolean isInitialized( )
Returns whether the library is already initialized.
Returns Boolean. True if the library is already initialized.
Example The following sample code initializes a connection with the Actuate web service
if one is not already initialized:
if (!actuate.isInitialized( )){
actuate.initialize("http://myhost:8700/iportal", null, null,
null, init, null);
}

actuate.load
Syntax void load(string componentName)
Specifies a component to be loaded by actuate.initialize( ). The available
components are:
■ parameter: The parameter page component including the actuate.Parameter
class and subclasses

74 Using Actuate JavaScript API

 ■ viewer: The viewer component including the actuate.Viewer class and
subclasses
Parameter componentName
String. componentName is a case-sensitive parameter. Valid component names
are listed above.
Example To enable a page to use both a viewer and parameters, call actuate.load( ) twice,
as shown in the following code:
actuate.load("viewer");
actuate.load("parameter");

actuate.logout
Syntax void logout(string iPortalURL, actuate.RequestOptions requestOptions, function
callback, function errorCallback)
Logs out from the given Actuate web application URL and removes
authentication information from the session. If the application was previously not
logged in to this Actuate web application, it generates no errors but still calls the
callback function.
Parameters iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL
parameters to send with the logout request. It can also add custom parameters to
the URL. If requestOptions is null, logout( ) uses the default parameter values for
the target Actuate web application URL. These default parameter values are
defined in the Actuate web application’s web.xml file.
callback
Function. Optional. The callback function called after the logout is done.
errorCallback
Function. The function called when an error occurs. The possible errors are
actuate.ConnectionException, actuate.AuthenticationException, and
actuate.Exception. errorCallback must take an exception as an argument.
Example The following sample code disconnects from the digits service if currently
connected:
if (actuate.isConnected("http://digits:8700/iportal", null)){
actuate.logout("http://digits:8700/iportal", null, null, null);
}

Chapter 11, Actuate JavaScript API classes 75

Class actuate.Exception
Description A container for an uncategorized exception that also supports specific exceptions.
Exception provides an object to pass to a callback function or event handler when
an exception occurs. The Exception object contains references to the exception’s
origin, description, and messages.

Constructor
The Exception object is constructed when unspecified exceptions occur. The
exceptions are divided into three types, which determine the contents of the
Exception object. These types are:
■ ERR_CLIENT: Exception type for a client-side error
■ ERR_SERVER: Exception type for a server error
■ ERR_USAGE: Exception type for a JSAPI usage error

Function summary
Table 11-3 lists actuate.Exception functions.
Table 11-3 actuate.Exception functions
Function Description
getDescription( ) Returns details of the exception
getErrCode( ) Returns error code for server-side exceptions
getMessage( ) Returns a short message about the exception
getType( ) Returns the type of exception error
isExceptionType( ) Confirms exception type

actuate.Exception.getDescription
Syntax string Exception.getDescription( )
Returns exception details as provided by the Server, Client, and User objects.
Returns String. A detailed description of the error. Information is provided according to
the type of exception generated, as shown below:
■ Server error: The SOAP string
■ Client error: For the Firefox browser, a list comprised of
fileName+number+stack
■ Usage error: Any values set in the object generating the exception

76 Using Actuate JavaScript API

Example This example displays the server error description in an alert box:
alert("Server error: " + Exception.getDescription( ));

actuate.Exception.getErrCode
Syntax string Exception.getErrCode( )
Returns the error code for server exceptions.
Returns String. A server error code.
Example This example displays the server error code in an alert box:
alert("Server error: " + Exception.getErrCode( ));

actuate.Exception.getMessage
Syntax string Exception.getMessage( )
Returns a short message about the exception. This message is set for an
actuate.Exception object with the actuate.Exception.initJSException( ) function.
Returns String. A server error code.
Example This example displays the error’s short message code in an alert box:
alert("Error Message: " + Exception.getMessage( ));

actuate.Exception.getType
Syntax string Exception.getType( )
Returns the type of the exception:
■ ERR_CLIENT: Exception type for a client-side error
■ ERR_SERVER: Exception type for a server error
■ ERR_USAGE: Exception type for a Actuate JavaScript API usage error
Returns String. A server error code.
Example This example displays the error type in an alert box:
alert("Error type: " + Exception.getType( ));

actuate.Exception.isExceptionType
Syntax boolean Exception.isExceptionType(object exceptionType)
Compares the input object to the exception contained in this actuate.Exception
object to the exceptionType object argument.

Chapter 11, Actuate JavaScript API classes 77

Parameters exceptionType
Object. Either an Exception object, such as an instance of
actuate.Viewer.ViewerException, or the name of an Exception class as a string.
Returns Boolean. Returns true if the exception contained in this actuate.Exception object
matches the exceptionType object argument.
Example To alert the user when the exception e is a usage error, use code similar to the
following:
if (e.isExceptionType(actuate.exception.ERR_USAGE)){
alert('Usage error occurred!');
}

78 Using Actuate JavaScript API

Class actuate.Parameter
Description The actuate.Parameter class retrieves and displays BIRT report parameters in an
HTML container. Users can interact with the parameters on the page and pass
parameter values to an actuate.Viewer object, but not to the web service directly.
The actuate.Parameter class displays the parameters by page. The
actuate.Parameter.navigate( ) function changes the page display or changes the
current position on the page.

Constructor
Syntax actuate.Parameter(string container)
Constructs a parameter object for a page, initializing the parameter component.
Parameter container
String. The name of the HTML element that displays the rendered parameter
component or a container object. The constructor initializes the parameter
component but does not render it.

Function summary
Table 11-4 lists actuate.Parameter functions.
Table 11-4 actuate.Parameter functions
Function Description
downloadParameterValues( ) Returns an array list of ParameterValue
objects
getReportName( ) Returns the name of the report file
getTransientDocumentName( ) Returns the name of the transient document
navigate( ) Navigates the parameter page
onUnload( ) Unloads unused JavaScript variables
renderContent( ) Renders the parameter content to the
container
setAutoSuggestDelay( ) Sets the autosuggest delay time
setAutoSuggestFetchSize( ) Sets the fetch size of the autosuggestion list
setAutoSuggestListSize( ) Sets the size of the autosuggestion list
setContainer( ) Sets the HTML container for the parameter
content
(continues)

Chapter 11, Actuate JavaScript API classes 79

 Table 11-4 actuate.Parameter functions
Function Description
setFont( ) Sets the font of the parameter page
setReportName( ) Sets the remote report path and name
setService( ) Sets the Actuate web application service
setShowDisplayType( ) Sets the parameter page to display localized
content
submit( ) Submits all the asynchronous operations that
the user has requested on this Parameter
object and renders the parameter component
on the page

actuate.Parameter.downloadParameterValues
Syntax void Parameter.downloadParameterValues(function callback)
Returns an array of the actuate.parameter.ParameterValue objects for the
parameter object. If no values have been set, the parameter object downloads the
default values from the server.
Parameter callback
Function. The function to execute after the report parameters finish downloading.
Parameter.downloadParameterValues( ) sends an array of
actuate.parameter.ParameterValue objects to the callback function as an input
argument.
Example To download the parameter values and add them to the viewer, the callback
function must use the values as an input parameter, as shown in the following
code:
paramObj.downloadParameterValues(runNext);
function runNext(values){
viewer.setParameterValues(values);
}

actuate.Parameter.getReportName
Syntax string Parameter.getReportName( )
Returns the name of the report file currently referenced by this Parameter object.
Returns String. The report file name.
Example This example displays an alert box with the name of the report file:
alert("Report file: " + paramObj.getReportName( ));

80 Using Actuate JavaScript API

 actuate.Parameter.getTransientDocumentName
Syntax string Parameter.getTransientDocumentName( )
Returns the name of the transient document generated by running the report
currently referenced by this Parameter object.
Returns String.
Example This example displays an alert box with the name of the transient document:
alert("Transient document: " +
paramObj.getTransientDocumentName( ));

actuate.Parameter.navigate
Syntax void Parameter.navigate(string containerId, string navTarget)
Changes the current page of the parameter component. The navTarget determines
the new location to display the parameter container.
Parameters containerId
String. The value of the id parameter for the HTML <div> element that holds the
parameter component.
navTarget
String constant. Which navigation button to trigger. Possible values from
actuate.parameter.Constants are NAV_FIRST, NAV_PREV, NAV_NEXT,
NAV_LAST.
Example This example displays the last page of the parameter component in the HTML
<div> element with the myParams ID:
function myParamsLast(myParameter){
myParameter.navigate("myParams", NAV_LAST);
}

actuate.Parameter.onUnload
Syntax void Parameter.onUnload( )
Performs garbage collection for the parameter object and unloads JavaScript
variables that are no longer needed by Parameter.
Example This example unloads JavaScript variables and displays an alert box:
myParameter.onUnload();
alert("JS variables unloaded.");

Chapter 11, Actuate JavaScript API classes 81

 actuate.Parameter.renderContent
Syntax void Parameter.renderContent(actuate.parameter.ParameterDefinition[ ]
paramDefs, function callback)
Renders the parameter component to the container.
Parameters paramDefs
Array of actuate.parameter.ParameterDefinition objects.
callback
Function. The function to execute after the rendering is done.
Example This example calls renderContent( ) after hiding parameter groups:
function showNoGroups(myParameter){
myParameter.hideParameterGroup(zipcodes);
myParameter.renderContent(myParameterArray,
cleanupParameter(myParameter));
}

actuate.Parameter.setAutoSuggestDelay
Syntax void Parameter.setAutoSuggestDelay(long delay)
Sets the autosuggest delay time.
Parameter delay
Long. Interpreted as milliseconds.
Example This example implements a custom autosuggest list. The list is 10 suggestions
long and displays 3 suggestions at a time after a delay of 250 milliseconds.
function myCustomAutoSuggest(myParameter){
myParameter.setAutoSuggestFetchSize(10);
myParameter.setAutoSuggestListSize(3);
myParameter.setAutoSuggestDelay(250);
}

actuate.Parameter.setAutoSuggestFetchSize
Syntax void Parameter.setAutoSuggestFetchSize(integer size)
Sets the fetch size of the autosuggestion list. Autosuggest fetches all suggestions
from the server when the fetch size is not set.
Parameter size
Integer. The number of suggestions to fetch at a time.
Example This example implements a custom autosuggest list. The list is 10 suggestions
long and displays 3 suggestions at a time after a delay of 250 milliseconds.

82 Using Actuate JavaScript API

 function myCustomAutoSuggest(myParameter){
myParameter.setAutoSuggestFetchSize(10);
myParameter.setAutoSuggestListSize(3);
myParameter.setAutoSuggestDelay(250);
}

actuate.Parameter.setAutoSuggestListSize
Syntax void Parameter.setAutoSuggestListSize(integer size)
Sets the length of the autosuggestion list. Autosuggest shows all of the
suggestions from the server when the list length is not set.
Parameter size
Integer. The number of suggestions to display.
Example This example implements a custom autosuggest list. The list is 10 suggestions
long and displays 3 suggestions at a time after a delay of 250 milliseconds.
function myCustomAutoSuggest(myParameter){
myParameter.setAutoSuggestFetchSize(10);
myParameter.setAutoSuggestListSize(3);
myParameter.setAutoSuggestDelay(250);
}

actuate.Parameter.setContainer
Syntax void Parameter.setContainer(string containerId)
Sets the HTML element container for the parameter content.
Parameter containerID
String. The name of the HTML element that displays the group of rendered
parameter components.
Example This example sets the container where the parameter components render:
paramObj.setContainer("leftpane");

actuate.Parameter.setFont
Syntax void Parameter.setFont(string fontStyleString)
Sets the font of the parameter page content after the page is rendered.
Parameter fontStyleString
String. The name of a font.
Example This example sets the font to Arial for the parameters page:
paramObj.setFont("arial");

Chapter 11, Actuate JavaScript API classes 83

 actuate.Parameter.setReportName
Syntax void Parameter.setReportName(string reportFile)
Sets the report file from which to get report parameters.
Parameter reportFile
String. The report file path and name. The report file can be a report design file or
a report document file.
Example To set the name using an HTML input tag with an ID of Selector, use the
following code:
myViewer.setReportName(document.getElementById("Selector").value);

actuate.Parameter.setService
Syntax void Parameter.setService(string iPortalURL, actuate.RequestOptions
requestOptions)
Sets the target service URL to which the Parameter object links. If the service URL
is not set, this Parameter object links to the default service URL set on the actuate
object.
Parameters iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL
parameters to send with the authentication request. The URL can also include
custom parameters.
Example This example sets the URL for the Actuate web application service:
paramObj.setService("http://localhost:8700/
iportal",myRequestOptions);

actuate.Parameter.setShowDisplayType
Syntax void Parameter.setShowDisplayType(boolean showDisplayType)
Sets whether localized data is shown or not.
Parameter showDisplayType
Boolean. True indicates that localized data is shown.
Example This example hides localized data:
paramObj.setShowDisplayType(false);
paramObj.submit(alert("Localized data hidden.");

84 Using Actuate JavaScript API

 actuate.Parameter.submit
Syntax void Parameter.submit(function callback)
Submits requests to the server for the report parameters. When this function is
called, an AJAX request is triggered to submit all the operations. When the server
finishes the processing, it returns a response and the results are rendered on the
page in the parameter container.
Parameter callback
Function. The function to execute after the asynchronous call processing is done.
Example This example calls submit( ) after hiding localized data:
paramObj.setShowDisplayType(false);
paramObj.submit(alert("Localized data hidden."));

Chapter 11, Actuate JavaScript API classes 85

Class actuate.parameter.Constants
Description Global constants used for Parameter class. Table 11-5 lists the constants used for
the parameter class.
Table 11-5 Actuate JavaScript API parameter constants
Event Description
ERR_CLIENT Constants used to tell JSAPI user that there was
a client-side error
ERR_SERVER Constants used to tell JSAPI user that there was
a server-side error
ERR_USAGE Constants used to tell JSAPI user that there was
a usage API error
NAV_FIRST Constants to programmatically control the first
page navigation link
NAV_LAST Constants to programmatically control the last
page navigation link
NAV_NEXT Constants to programmatically control the next
page navigation link
NAV_PREV Constants to programmatically control the
previous page navigation link

86 Using Actuate JavaScript API

Class actuate.parameter.ConvertUtility
Description actuate.parameter.ConvertUtility encodes multiple
actuate.parameter.ParameterValue objects into an array of generic objects. For
multi-value parameters, use the array of generic objects as the input parameter
for actuate.Viewer.setParameterValues.

Constructor
Syntax actuate.parameter.ConvertUtility(actuate.parameter.ParameterValue[ ]
aParamVals)
Constructs a new ConvertUtility object.
Parameter aParamVals
Array of actuate.parameter.ParameterValue objects to convert.

Function summary
Table 11-6 lists actuate.parameter.ConvertUtility functions.
Table 11-6 actuate.parameter.ConvertUtility functions
Function Description
convert( ) Converts the ParameterValues to an array of generic
objects
convertData( ) Converts locale-neutral parameter values to the user’s
login locale
getParameterMap( ) Returns the ParameterValues as an associative array
getParameterValues( ) Returns an array of ParameterValues

actuate.parameter.ConvertUtility.convert
Syntax void ConvertUtility.convert(function callback)
Converts ParameterValues into an array of generic objects. The callback function
takes the array as an argument.
Parameter callback
Function. The callback function to call after converting the results. The callback
function must take the generic array of objects as an argument.
Example This example stores the name-value pair array for myParamValues in a variable
called nameValueArray:

Chapter 11, Actuate JavaScript API classes 87

 var nameValueArray = new Array( );
var converter = new actuate.ConvertUtility(myParamValues)
converter.convert(callback);
function callback (values){
nameValueArray = values;
}

actuate.parameter.ConvertUtility.convertDate
Syntax void ConvertUtility.convertDate(function callback)
Converts locale-neutral parameter values to the user’s login locale.
Parameter callback
Function. An optional function to call when this function completes. The callback
function receives an array of actuate.parameter.ParameterValue objects as a
parameter.
Example This example converts the name-value pair array for myParamValues and stores
the results in a variable called nameValueArray:
var nameValueArray = new Array( );
var converter = new actuate.ConvertUtility(myParamValues)
converter.convertDate(callback);
function callback (values){
nameValueArray = values;
}

actuate.parameter.ConvertUtility.getParameterMap
Syntax object ConvertUtility.getParameterMap( )
Returns the parameters as an associative array. This function makes the name of
each parameter an object property and sets the value of that property to the
associated parameter value.
Returns Object.
Example This example stores the associative array for myParamValues in a variable called
nameValueArray:
var paramMap = new Object( );
var converter = new actuate.ConvertUtility(myParamValues)
paramMap = converter.getParameterMap( );

actuate.parameter.ConvertUtility.getParameterValues
Syntax actuate.parameter.ParameterValue[ ] ConvertUtility.getParameterValues( )
Returns the array of ParameterValue objects.

88 Using Actuate JavaScript API

Returns Array of actuate.parameter.ParameterValue objects.
Example This example stores the array of ParameterValue objects for myParamValues in a
variable called paramValues:
var paramValues = new Array( );
var converter = new actuate.ConvertUtility(myParamValues)
paramValues = converter.getParameterMap( );

Chapter 11, Actuate JavaScript API classes 89

Class actuate.parameter.EventConstants
Description Defines the supported event constants for parameters. Table 11-7 lists the
parameter event constants.
Table 11-7 Actuate JavaScript API parameter event constants
Event Description
ON_EXCEPTION Event triggered when an exception occurs. The event
handler must take an actuate.Exception object as an input
argument. The Exception object contains the exception
information.
ON_SESSION_TIMEOUT Session time-out event. Whenever a session time-out event
occurs and the user tries to perform any operation on
parameter component, a prompt dialog will be shown to
ask whether the user wants to log in again or not. If the
user clicks yes, the ON_SESSION_TIMEOUT event will be
fired. If no handler has been registered for this event, a
default built-in login dialog will be displayed.
The event handler takes the following argument:
actuate.Parameter: component for which the event
occurred

90 Using Actuate JavaScript API

Class actuate.parameter.NameValuePair
Description The NameValuePair object contains a display name associated with a value. The
actuate.parameter.parameterDefinition.setSelectNameValueList( ) function takes
an array of actuate.parameter.NameValuePair objects to use in a selection list. In
this way, a ParameterDefinition can display a list of names and map them to
values used internally. For example, set the name "My Default Country" for a
NameValuePair to display "My Default Country" in the drop-down list in the
interface, and set the value to "United States" internally for a US user.

Constructor
Syntax actuate.parameter.NameValuePair(string name, string value)
Constructs a new NameValuePair object.
Parameters name
String. The name to display in the selection list.
value
String. The value that selecting the name sets internally.

Function summary
Table 11-8 lists actuate.parameter.NameValuePair functions.
Table 11-8 actuate.parameter.NameValuePair functions
Function Description
getName( ) Gets the name for this NameValuePair
getValue( ) Gets the value for this NameValuePair
setName( ) Sets the name for this NameValuePair
setValue( ) Sets the value for this NameValuePair

actuate.parameter.NameValuePair.getName
Syntax string NameValuePair.getName( )
Returns the name for this NameValuePair.
Returns String.
Example This sample code returns the name component of the myNVPair NameValuePair
object:
alert("Name component is " + myNVPair.getName( ));

Chapter 11, Actuate JavaScript API classes 91

 actuate.parameter.NameValuePair.getValue
Syntax string NameValuePair.getValue( )
Returns the value for this NameValuePair.
Returns String.
Example This sample code returns the value component of the myNVPair NameValuePair
object:
alert("Value component is " + myNVPair.getValue( ));

actuate.parameter.NameValuePair.setName
Syntax void NameValuePair.setName(string name)
Sets the name for the NameValuePair.
Parameter name
String.
Example This sample code sets the name component of the myNVPair NameValuePair
object to "My hometown":
myNVPair.setName("My hometown");

actuate.parameter.NameValuePair.setValue
Syntax void NameValuePair.setValue(string value)
Sets the value for the NameValuePair.
Parameter value
String.
Example This sample code sets the value component of the myNVPair NameValuePair
object to "Cleveland":
myNVPair.setValue("Cleveland");

92 Using Actuate JavaScript API

Class actuate.parameter.ParameterValue
Description ParameterValue is a container for the value of Parameter to pass to a report for
processing. When a user sets a value in the interface, the corresponding
ParameterValue must change.

Constructor
Syntax actuate.parameter.ParameterValue( )
Constructs a new ParameterValue object.

Function summary
Table 11-9 lists actuate.parameter.ParameterValue functions.
Table 11-9 actuate.parameter.ParameterValue functions
Function Description
getColumnName( ) Gets the name of the column in this
ParameterValue
getColumnType( ) Gets the data type value of the column for this
ParameterValue
getDataType( ) Gets the dataType value for this ParameterValue
getName( ) Gets the name value for this ParameterValue
getValue( ) Gets the value or values for this ParameterValue
getValueIsNull( ) Gets the valueIsNull value for this
ParameterValue
setValue( ) Sets the value for this ParameterValue
setValueIsNull( ) Sets the valueIsNull value for this
ParameterValue

actuate.parameter.ParameterValue.getColumnName
Syntax string ParameterValue.getColumnName( )
Gets the column name value for this ParameterValue. Columns are supported as
part of ad hoc parameters.
Returns String. The name of the column.
Example To store the column name for the parameter value pvalue in a variable called
columnname, use code similar to the following:
var columnname = pvalue.getColumnName( );

Chapter 11, Actuate JavaScript API classes 93

 actuate.parameter.ParameterValue.getColumnType
Syntax string ParameterValue.getColumnType( )
Gets the data type value of the column for this ParameterValue. Columns are
supported as part of ad hoc parameters.
Returns String. Possible values are null, "", "Currency", "Date", "DateOnly", "Time",
"Double", "Integer", "String", "Boolean", "Structure", "Table", and "Unknown".
Example To store the column type for the parameter value pvalue in a variable called
columntype, use code similar to the following:
var columntype = pvalue.getColumnType( );

actuate.parameter.ParameterValue.getDataType
Syntax string ParameterValue.getDataType( )
Gets the dataType value for this ParameterValue.
Returns String. Possible values are null, "", "Currency", "Date", "DateOnly", "Time",
"Double", "Integer", "String", "Boolean", "Structure", "Table", and "Unknown".
Example To store the data type for the parameter value pvalue in a variable called type, use
code similar to the following:
var type = pvalue.getDataType( );

actuate.parameter.ParameterValue.getName
Syntax string ParameterValue.getName( )
Gets the name value for this ParameterValue.
Returns String.
Example To store the name of the parameter value pvalue in a variable called name, use
code similar to the following:
var name = pvalue.getName( );

actuate.parameter.ParameterValue.getValue
Syntax string[ ] ParameterValue.getValue( )
Gets the value values for this ParameterValue.
Returns String or array of strings. The value or values of this ParameterValue object.
Example To store the value of the parameter value pvalue in a variable called value, use
code similar to the following:
var value = pvalue.getValue( );

94 Using Actuate JavaScript API

 actuate.parameter.ParameterValue.getValueIsNull
Syntax boolean ParameterValue.getValueIsNull( )
Gets the valueIsNull value for this ParameterValue.
Returns Boolean. True indicates that this ParameterValue is null.
Example To alert the user that the value of the parameter value pvalue is null, use code
similar to the following:
if (pavalue.getValueIsNull( )){
alert('Default value is null!');
}

actuate.parameter.ParameterValue.setValue
Syntax void ParameterValue.setValue(string[ ] value)
Sets the value or values for this ParameterValue.
Parameter value
String or array of strings. The value or values of this ParameterValue object.
Example To set the value of the parameter value pvalue to 2010, use code similar to the
following:
pvalue.setValue("2010");
To set the values of the ParameterValue object pvalues to 2008, 2009, and 2010, use
code similar to the following:
pvalue.setValue({"2008", "2009", "2010"});

actuate.parameter.ParameterValue.setValueIsNull
Syntax void ParameterValue.setValueIsNull(boolean valueIsNull)
Sets the valueIsNull value for this ParameterValue.
Parameter valueIsNull
Boolean. True indicates that this ParameterValue is null.
Example To set the value of parameter value pvalue to null, use code similar to the
following:
pvalue.setValueIsNull(true);

Chapter 11, Actuate JavaScript API classes 95

Class actuate.RequestOptions
Description The request options that Actuate BIRT Viewer Toolkit requires for connection
requests. RequestOptions is used by other classes to provide authentication
information. It also adds any customized options to the request URL.

Constructor
Syntax actuate.RequestOptions( actuate.RequestOptions requestOptions)
Constructs a new RequestOptions object.
Parameter requestOptions
actuate.RequestOptions object. Optional. Provides request option settings to copy
into this RequestOptions object.

Function summary
Table 11-10 lists actuate.RequestOptions functions.
Table 11-10 actuate.RequestOptions functions
Function Description
getLocale( ) Returns the current locale
setCustomParameters( ) Appends a custom parameter to the request URL
setLocale( ) Sets the locale

actuate.RequestOptions.getLocale
Syntax string RequestOptions.getLocale( )
Returns the current locale or null if no locale is set.
Returns String. The locale value; null for default.
Example This example pops up an alert box if the locale value is set to the default:
var locale = reqOpts.getLocale( );
if (locale == null){
alert("Locale value is default");
}

actuate.RequestOptions.setCustomParameters
Syntax void RequestOptions.setCustomParameters(object parameters)
Returns a custom parameter in the request URL.

96 Using Actuate JavaScript API

Parameter parameters
Object. An associative array of name:value pairs for URL parameters.
Example To add "&myParam=myValue" in a request URL derived from RequestOptions
object, use code similar to the following:
MyRequestOptions.setCustomParameters({myParam: "myValue"});

actuate.RequestOptions.setLocale
Syntax void RequestOptions.setLocale(string Locale)
Sets the locale.
Parameter Locale
String. Optional. The locale value. Null indicates the default locale.
Example This example resets the locale for the reqOpts RequestOptions object to the
default:
reqOpts.setLocale( );

Chapter 11, Actuate JavaScript API classes 97

Class actuate.Viewer
Description The actuate.Viewer class retrieves and displays Actuate BIRT report contents in
an HTML container. The actuate.Viewer class displays the report by page. The
goto functions of this class change the current position and page displayed in the
viewer.

Constructor
Syntax actuate.Viewer(object viewContainer)
actuate.Viewer(string viewContainerId)
Constructs a new viewer object. The container is an HTML object defined on the
HTML page.
Parameters viewContainer
Object. A document object that references the <div> element that holds the
viewer.
viewContainerId
String. The value of the id parameter for the <div> element that holds the viewer.
Example To assign the viewer to display in a <div id='containerName' /> tag on the page,
use the following constructor call:
var myViewer = new actuate.Viewer("containerName");

Function summary
Table 11-11 lists actuate.Viewer functions.
Table 11-11 actuate.Viewer functions
Function Description
downloadReport( ) Exports a report using the specified format
getClientHeight( ) Gets the viewer’s height
getClientWidth( ) Gets the viewer’s width
getContentMargin( ) Gets the margin dimensions of the content in
pixels
getCurrentPageNum( ) Returns the current page number
getHeight( ) Returns the viewer height setting
getHelpBase( ) Gets the help URL
getId( ) Returns the ID of this object

98 Using Actuate JavaScript API

Table 11-11 actuate.Viewer functions (continued)
Function Description
getIportalUrl( ) Returns the Actuate web application URL that
this Viewer accesses
getReportletBookmark( ) Returns the bookmark of a Reportlet displayed
in the viewer
getReportName( ) Returns the report file displayed in the viewer
getRequestOptions( ) Returns the viewer’s request options
getTotalPageCount( ) Returns the total number of pages
getViewer( ) Returns a viewer object containing the given
bookmarked element
getWidth( ) Returns the viewer width setting
gotoBookmark( ) Goes to the position in the report specified by the
bookmark
gotoPage( ) Goes to the specified page
setContentMargin( ) Sets the viewer content margin
setHeight( ) Sets the viewer height
setHelpBase( ) Sets the base help URL
setParameters( ) Sets the parameters to run a report using a list of
literal string pairs
setParameterValues( ) Sets the parameters to run a report using a
generated object
setReportName( ) Sets the report file to render within this Viewer
setService( ) Sets the target service URL
setSize( ) Sets the size of the viewer
setWidth( ) Sets the width of the viewer
showDownloadReport Enables the export report dialog window
Dialog( )
showFacebookComment Shows the Facebook comments panel.
Panel( )
showParameterPanel( ) Shows the parameter panel
showPrintDialog( ) Enables the print dialog window
submit( ) Submits all the asynchronous operations that the
user has requested on this Viewer and renders
the viewer component on the page

Chapter 11, Actuate JavaScript API classes 99

 actuate.Viewer.downloadReport
Syntax void Viewer.downloadReport(string format, string pages,
actuate.viewer.RenderOptions renderoption)
Exports the report with a specified format. The downloadReport function does
not return any object. The report is exported to the client side. Then the browser
opens a download window for the user to specify a location for the report.
Parameters format
String. The format in which to export the report. Valid values and their
corresponding formats are:
■ doc: Word
■ docx: Word 2007
■ html: HTML-encoded web page
■ ppt: PowerPoint
■ pptx: PowerPoint 2007
■ pdf: Adobe PDF
■ ps: PostScript
■ xls: Excel
pages
String. The pages to retrieve. Indicate page ranges by using the first page number
of the range and the last page number separated by a dash. To use more than one
value, separate individual page numbers or page ranges with commas.
renderoption
actuate.viewer.RenderOptions object. Optional. Sets the rendering options for the
download, which currently only applies to multisheet xls format reports.
Example To download the first five pages of the report in the viewer, use the following
code:
viewer.downloadReport("pdf", "1-5", null);

actuate.Viewer.getClientHeight
Syntax integer Viewer.getClientHeight( )
Gets the browser window’s height.
Returns Integer. Height in pixels.
Example To reset the viewer height to 20 pixels less than the browser window if it is larger
than the browser window, use code similar to the following:

100 Using Actuate JavaScript API

 if(myViewer.getClientHeight( ) < myViewer.getHeight( )){
myViewer.setHeight(myViewer.getClientHeight( ) - 20);
}

actuate.Viewer.getClientWidth
Syntax integer Viewer.getClientWidth( )
Gets the browser window’s width.
Returns Integer. Width in pixels.
Example To reset the viewer width to 20 pixels less than the browser window if it is larger
than the browser window, use code similar to the following:
if(myViewer.getClientWidth( ) < myViewer.getWidth( )){
myViewer.setWidth(myViewer.getClientWidth( ) - 20);
}

actuate.Viewer.getContentMargin
Syntax integer | object Viewer.getContentMargin( )
Gets the viewer content margin.
Returns Integer or Object. An integer indicates the same margin on all sides, in pixels. The
object contains the pixel values for the top, bottom, left, and right margins of the
viewer in an array. For example, a 25-pixel top content margin and no margin in
the other directions would be the object array {top:25, left:0, right:0, bottom:0}.
Example To set the margin of the viewer newViewer to match the margin of myViewer, use
code similar to the following:
newViewer.setContentMargin(myViewer.getContentMargin( ));

actuate.Viewer.getCurrentPageNum
Syntax integer Viewer.getCurrentPageNum( )
Returns the page number for the page currently being displayed.
Returns Integer. The current page number.
Example This function is useful to move to another page relative to the current page. To go
to the next page in a document, use the following code:
viewer.gotoPage(viewer.getCurrentPageNum( ) + 1);

actuate.Viewer.getHeight
Syntax string Viewer.getHeight( )

Chapter 11, Actuate JavaScript API classes 101

 Returns the height value of the viewer.
Returns String.
Example This example decreases the viewer’s height by 10:
var height = myViewer.getHeight( );
myViewer.setHeight(height - 10);

actuate.Viewer.getHelpBase
Syntax string Viewer.getHelpBase( )
Returns the URL of the help base. The help base is the base URL for the product
help documentation.
Returns String. The base URL of the help documentation.
Example This example displays the help base URL in an alert box:
alert("The help base URL is " + myViewer.getHelpBase( ))

actuate.Viewer.getReportletBookmark
Syntax string Viewer.getReportletBookmark( )
Returns the bookmark of the current report page or element.
Returns String. Bookmark.
Example This example displays the bookmark of the current report page in an alert box:
alert ("Report bookmark is " + myViewer.getReportletBookmark( ));

actuate.Viewer.getReportName
Syntax string Viewer.getReportName( )
Returns the name of the report file, either a report design file or report document
file, that is currently displayed in this Viewer.
Returns String.
Example This example displays the currently displayed report file name in an alert box:
alert ("Currently displaying " + myViewer.getReportName( ));

actuate.Viewer.getTotalPageCount
Syntax integer Viewer.getTotalPageCount( )
Returns the total number of pages in the report being viewed.
Returns Integer.

102 Using Actuate JavaScript API

 Example This function is useful to move to the last page of a document. To go to the last
page in a document, use the following code:
viewer.gotoPage(viewer.getTotalPageCount( ));

actuate.Viewer.getViewer
Syntax actuate.Viewer Viewer.getViewer(string bookmark)
actuate.Viewer Viewer.getViewer(object elementID)
Returns a viewer object containing the report element that is associated with a
bookmark or contained in an HTML element.
Parameters bookmark
String. The bookmark of the report element to view.
elementID
Object. An HTML element that contains the viewer.
Returns actuate.Viewer object or null if the viewer is not found.
Example This example uses getViewer( ) to retrieve a report element and return the
bookmark of the chart in that report:
function chartBookmark(myReport){
var bviewer = myReport.getViewer("Chart");
var bpagecontents = bviewer.getCurrentPageContent( );
return bpagecontents.getChartByBookmark("ChartBookmark");
}

actuate.Viewer.getWidth
Syntax string Viewer.getWidth( )
Returns the width value of the viewer.
Returns String.
Example This example decreases the viewer’s width by 10:
var width = myViewer.getWidth( );
myViewer.setWidth(width - 10);

actuate.Viewer.gotoBookmark
Syntax void Viewer.gotoBookmark(string bookmark)
Goes to the page position by the specified bookmark. The viewer displays to the
first page when the bookmark is not found.
Parameter bookmark
String. The bookmark of a report element.

Chapter 11, Actuate JavaScript API classes 103

 Example To move the viewer to the page position specified by the value of the 'bookmark'
parameter, use this code:
viewer.gotoBookmark(document.getElementById('bookmark').value);

actuate.Viewer.gotoPage
Syntax void Viewer.gotoPage(integer pageNumber)
Goes to the specified page. The viewer throws an exception when the page is not
found.
Parameter pageNumber
Integer. A page number in the report.
Example To go to the first page of a report, use the following code:
viewer.gotoPage(1);

actuate.Viewer.setContentMarg
Syntax void Viewer.setContentMargin(string[ ] margin)
void Viewer.setContentMargin(int margin)
Sets the viewer content margin.
Parameter margin
Array of strings or integer. Each member of the array is the margin for the top,
left, right, and bottom internal margins for the viewer. A single integer sets all
margins to that value.
Example To set the internal margin of the viewer to a 10-pixel buffer, use the following
code:
myViewer.setContentMargin(10);

actuate.Viewer.setHeight
Syntax void Viewer.setHeight(integer height)
Sets the viewer height.
Parameter height
Integer. The height in pixels.
Example To set the height of the viewer to 600 pixels, use the following code:
viewer.setHeight(600);

actuate.Viewer.setHelpBase
Syntax void Viewer.setHelpBase(string helpBase)

104 Using Actuate JavaScript API

 Sets the URL of the help base. The help base is the base URL for the product help
documentation.
Parameter helpBase
String. The URL where the help documentation is located.
Example This example sets the help base URL to http://www.actuate.com
/documentation/R11:
myViewer.setHelpBase("http://www.actuate.com/documentation/R11");
myViewer.submit( );

actuate.Viewer.setParameters
Syntax void Viewer.setParameters(string[ ] params)
Sets parameters for executing report using literal string pairs.
Parameter params
Array of strings. Each string in the array is constructed of name:"value" pairs. Use
a literal list, such as {param1:"value1", param2:"value2", … }.
Example To set the value of a parameter, city, to the value, New York, use the following
object literal:
viewer.setParameters({ city:"New York"});

actuate.Viewer.setParameterValues
Syntax void Viewer.setParameterValues(actuate.parameter.ParameterValue[ ]
parameters)
Sets parameter values for executing a report using ParameterValue objects.
Parameter parameters
Array of actuate.parameter.ParameterValue objects. An array of this kind is
returned by actuate.Parameter.downloadParameterValues( ) and is the
recommended function for creating the parameters input.
Example To set the parameter values for a report to the parameters in the pvs array, use this
code:
viewer.setParameterValues(pvs);

actuate.Viewer.setReportletBookmark
Syntax void Viewer.setReportletBookmark(string bookmark)
Sets the bookmark for the Reportlet rendered.

Chapter 11, Actuate JavaScript API classes 105

 Parameter bookmark
String. The bookmark ID used to render the Reportlet. Viewer requires a
bookmark to render a Reportlet. Viewer does not support automatically
generated generic bookmarks from a BIRT report.
Example To open the Top 5 Customers Reportlet of the Customer Dashboard, set the
Reportlet bookmark by name and then call viewer.submit, as shown in the
following example:
viewer.setReportName("/Public/Customer Dashboard.rptdocument");
viewer.setReportletBookmark("Top 5 Customers");
viewer.submit( );

actuate.Viewer.setReportName
Syntax void Viewer.setReportName(string reportFile)
Sets the report file, either a report design or report document, to render in this
Viewer.
Parameter reportFile
String. The report file path for a report design file or report document file.
Example To open the Top 5 Sales Performers report, set the report by name and then call
submit( ), as shown in the following example:
viewer.setReportName("/Public/Top 5 Sales Performers.rptdesign");
viewer.submit( );

actuate.Viewer.setService
Syntax void Viewer.setService(string iPortalURL, actuate.RequestOptions
requestOptions)
Sets the target service URL to which this Viewer links. When the service URL is
not set, this Viewer links to the default service URL, which is set on the actuate
object.
Parameter iPortalURL
String. The target Actuate web application URL.
requestOptions
actuate.RequestOptions object. Optional. requestOptions defines URL
parameters to send with the authentication request. The URL can also include
custom parameters.
Example This example sets the URL for the Actuate web application service:
myViewer.setService("http://localhost:8700/iportal",
myRequestOptions);

106 Using Actuate JavaScript API

 actuate.Viewer.setSize
Syntax void Viewer.setSize(integer width, integer height)
Resizes the viewer’s width and height.
Parameter width
Integer. The new width is specified in pixels.
height
Integer. The new height is specified in pixels.
Example To set the viewer’s size to 300 pixels by 300 pixels, use code similar to the
following:
myViewer.setSize(300, 300);

actuate.Viewer.setSupportSVG
Syntax void Viewer.setSupportSVG(boolean usvgFlag)
Controls Scalable Vector Graphics support for the viewer.
Parameter svgFlag
Boolean. True enables Scalable Vector Graphic support.
Example To disable Scalable Vector Graphic support for the myViewer viewer, use code
similar to the following:
myViewer.setSupportSVG(false);

actuate.Viewer.setWidth
Syntax void Viewer.setWidth(string width)
Sets the viewer width.
Parameter width
String.
Example To set the width of the viewer to 800 pixels, use the following code:
viewer.setWidth(800);

actuate.Viewer.showDownloadReportDialog
Syntax void Viewer.showDownloadReportDialog( )
Displays the export report dialog window.
Example Use this code to display the report dialog window:
myViewer.showDownloadReportDialog( );

Chapter 11, Actuate JavaScript API classes 107

 actuate.Viewer.showFacebookCommentPanel
Syntax void Viewer.showFacebookCommentPanel( )
Displays the Facebook comments panel.
Example Use this code to display the Facebook comments panel:
viewer.showFacebookCommentPanel( );

actuate.Viewer.showParameterPanel
Syntax void Viewer.showParameterPanel( )
Displays the parameter panel.
Example Use this code to display the parameter panel:
viewer.showParameterPanel( );

actuate.Viewer.showPrintDialog
Syntax void Viewer.showPrintDialog( )
Displays the print dialog window.
Example Use this code to display the print dialog window:
viewer.showPrintDialog( );

actuate.Viewer.submit
Syntax void Viewer.submit(function callback, boolean rerun)
Updates and reloads the viewer after submitting requests for the viewer. The
submit( ) function triggers an AJAX request for all asynchronous operations.
When the server finishes the processing, it returns a response and the results are
rendered on the page in the viewer container. Calling submit( ) when a previous
submit( ) is pending throws an exception.
Parameters callback
Function. Optional. The function to execute after the asynchronous call
processing is done.
rerun
Boolean. Optional. Indicates whether to re-run the report design when refreshing.
Default to true.
Example To open the Top 5 Sales Performers report, set the report by name and then call
submit( ), as shown in the following example:
viewer.setReportName("/Public/Top 5 Sales Performers.rptdesign");
viewer.submit( );

108 Using Actuate JavaScript API

Class actuate.viewer.EventConstants
Description Defines the event constants supported by this API. Table 11-12 lists the viewer
event constants.
Table 11-12 Actuate JavaScript API viewer event constants
Event Description
ON_EXCEPTION An exception event is broadcast when an error occurs.
The event handler must take the viewer instance that fired
the event and an instance of actuate.viewer.Exception as
input arguments.
ON_SESSION_TIMEOUT Calls a registered event handler when the session expires.
The event handler must take the viewer instance that fired
the event as an input argument.

Chapter 11, Actuate JavaScript API classes 109

Class actuate.viewer.ParameterValue
Description The ParameterValue class is a JavaScript version of the
com.actuate.schemas.ParameterValue class.

Constructor
Syntax actuate.parameter.ParameterValue( )
Constructs a new ParameterValue object.

Function summary
Table 11-13 lists the actuate.viewer.ParameterValue functions.
Table 11-13 actuate.viewer.ParameterValue functions
Function Description
getName( ) Returns the name value
getValue( ) Returns the value value
getValueIsNull( ) Returns the valueIsNull value
setName( ) Sets the name value
setValue( ) Sets the value value
setValueIsNull( ) Sets the valueIsNull value

actuate.viewer.ParameterValue.getName
Syntax string ParameterValue.getName( )
Returns the name value.
Returns String. The name value.
Example To store the name of a viewer.ParameterValue object in a variable called
vPVname, use code similar to the following:
var vPVname = myParamValue.getName( );

actuate.viewer.ParameterValue.getValue
Syntax object ParameterValue.getValue( )
Returns the value value.
Returns Object. The value value, a string or array of strings.

110 Using Actuate JavaScript API

 Example To store a ParameterValue’s value in vPVvalue, use the following code:
var vPVvalue = myParamValue.getValue( );

actuate.viewer.ParameterValue.getValueIsNull
Syntax boolean ParameterValue.getValueIsNull( )
Returns the valueIsNull value.
Returns Boolean. The valueIsNull value.
Example This example displays an alert with the valueIsNull of the ParameterValue object:
alert("Value is null: " + myParamValue.getValueIsNull( ));

actuate.viewer.ParameterValue.setColumnName
Syntax void ParameterValue.setColumnName(string columnName)
Sets the columnName value.
Parameter columnName
String. The column name.
Example To set the column name to "Motorcycles", use code similar to the following:
myParamValue.setColumnName("Motorcycles");

actuate.viewer.ParameterValue.setValue
Syntax void ParameterValue.setValue(object value)
Sets the value. A value can be a string or an array of strings.
Parameter value
Object. The value for this ParameterValue object, a string or an array of strings.
Example To set the value for a ParameterValue to myValues, use the following code:
var myValues = myParamValue.setValue(myValues);

actuate.viewer.ParameterValue.setValueIsNull
Syntax void ParameterValue.setValueIsNull(boolean valueIsNull)
Sets the valueIsNull value.
Parameter valueIsNull
Boolean. The valueIsNull value.
Example To set a ParameterValue’s setValueIsNull to true, use the following code:
myParamValue.setValueIsNull(true);

Chapter 11, Actuate JavaScript API classes 111

Class actuate.viewer.ViewerException
Description A container for an exception. ViewerException provides an object to pass to a
handler when the user-defined ON_EXCEPTION event occurs. It contains a
reference to the element that generated the exception.

Constructor
The ViewerException object is constructed when an ON_EXCEPTION event
occurs. The exceptions are divided into three types, which determine the contents
of the Exception object. These types are:
■ ERR_CLIENT: Exception type for a client-side error
■ ERR_SERVER: Exception type for a server error
■ ERR_USAGE: Exception type for a JSAPI usage error

Function summary
Table 11-14 describes the actuate.viewer.ViewerException function.
Table 11-14 actuate.viewer.ViewerException function
Function Description
getErrorMessage( ) Returns the exception message

actuate.viewer.ViewerException.getErrorMessage
Syntax string ViewerException.getErrorMessage( )
Returns the error message for the exception.
Returns String. A server error message.
Example This example displays the server error code in an alert box:
alert("Server error message: " + vException.getErrorMessage( ));

112 Using Actuate JavaScript API

 Index
A base class 56
bidirectional (BIDI) text 34
accessing BIRT Interactive Viewer 22
BIRT Viewer Toolkit landing page 14 BIRT Viewer 22, 24
JavaScript API 56, 68 BIRT Viewer Toolkit 22, 28, 31
report viewers 60 configuring 8–9
resources 59 deploying 4, 8, 10, 16
source code 56 displaying data and 4
web service applications 59 optimizing performance 9
activity logs 9 setting location of 9
actuate class 56, 57, 68, 70 testing installation 14
actuate namespace 68 BIRT Viewer Toolkit landing page 14
ad hoc parameters 87, 93, 94 BIRT_ARCHIVE_ MEMORY_TOTALSIZE
adding parameter 9
parameter components 62, 79 bookmarks
URL parameters 58 displaying report elements and 61, 103
viewer components 60, 98 displaying Reportlets and 102, 105
web pages 56, 57 getting report content for 102
aggregate data 29, 32, 50 navigating through reports and 103
alerts 78 returning viewer objects for 72, 103
Apache Tomcat servers 59 bubble charts 46
configuring 16, 17 button constants (navigation) 81
deploying to 4, 10
application servers 4, 5, 10, 16, 59 C
applications 22, 28, 31
accessing 59 cache 9
developing 56, 68 calculated data 29, 32
displaying reports and 61, 62 callback functions
establishing connections to 56, 57, 73 closing HTTP sessions and 60
loading class libraries from 56 connecting to web services and 59, 71, 73
logging out of 75 defined 56
providing security for 58–60 displaying reports and 61
See also Microsoft Office applications handling exceptions and 71, 76
testing connections for 74 initializing HTTP sessions and 58
area charts 45 retrieving parameters and 63, 80, 87
authenticate function 58, 71 category series (charts) 44
authentication 58, 71 See also data series
authentication information 58, 59, 75, 96 changing
autosuggest delays 82 parameters 40, 41, 79
autosuggestion lists 82, 83 report designs 22
report output 62
B character encoding 57
character encryption 59
bar charts 44 chart images 32, 33

Index 113
chart types 44 cubes 50
chart views 32 customizing
charts autosuggestion lists 83
See also specific chart type URL parameters 58
displaying data and 44 web pages 56
displaying small sets of values in 45
exporting 28, 32, 46 D
showing scientific data and 46 data 56, 57
class libraries 56, 68, 74 comparing 44
classes 56, 68 displaying 44
client-side errors 76, 86 exporting 28–37
code 56 retrieving 24, 40
column headers 31 selecting 41
column names 93, 111 showing changes over time 44, 45
columns 29, 50, 94 showing percentage to whole 44, 45
comma-separated values files 28 showing relationship between 44
comparisons 44 showing relationship to whole 45
component names 75 showing trends in 46
cone charts 44 data cubes 50
configuration files 8 data filters 40
configuration parameters 8 data points (charts) 44
configuring data ranges 42
application servers 16–17 data rows 29, 50
BIRT Viewer Toolkit 8–9 data series
connection parameters 58, 73 See also charts
connections displaying in columns 44
authenticating users and 58, 71 displaying multiple 45
closing 75 displaying side by side 44
opening 56, 57, 73 overlapping multiple 45
testing 74 plotting data and 44
Constants class 86 stacking multiple 44, 45
content components 60 data service components 75
convert function 87 data types 30, 94
convertDate function 88 date values 30, 44, 88
ConvertUtility class 87 default parameters 71
creating default settings 58, 59
autosuggestion lists 83 default values 80
display names 91 default web service URL 72
parameter components 62, 79 DEFAULT_LOCALE parameter 9
URL parameters 58 DEFAULT_TIMEZONE parameter 9
viewer components 60, 98 delays 82
web pages 56, 57 deploying BIRT Viewer Toolkit 4, 8, 10, 16
credentials 59, 71 deployment errors 11, 16
cross tabs 50–51 design files 62, 84, 106
See also tables developing web applications 56, 68
crossContext parameter 59 dialog boxes 107, 108
CSV files 28

114 U s i n g B I R T V i e w e r To o l k i t
dimensions (cross tabs) 50, 51 event handlers 76
display names 91 EventConstants class 90, 109
displaying Excel formats 28, 32, 51
cross tabs 50 Excel output formats 100
data 44 Exception class 76
report elements 29 exception classes 112
report parameters 63, 64, 79, 82 exception types 76, 77
Reportlets 102, 105 exceptions
reports 22, 24, 40, 60, 62, 98 authentication and 59
tables 62 closing HTTP sessions and 60
div tag 57, 60 report parameters and 90
DOCTYPE tag 57 viewer and 109, 112
.doc files. See Word document formats executable files 62
.docx files. See Word document formats Export Content dialog box
document files 9, 81, 84, 106 Excel output formats and 32
document files. See report document files PDF output formats and 33
document output formats 100 PostScript output formats and 35
documentation v PowerPoint output formats and 37
documentation URLs 102, 105 Word output formats and 36
documents. See reports Export Data command 46
domains 59 Export Data dialog box 29, 46
downloading export report dialog 107
BIRT Viewer Toolkit 4 exporting data 28–37
report parameters 63, 64, 80 exporting reports 100, 107
reports 100 external user credentials 59
downloadParameterValues function 64, 80
downloadReport function 100 F
Facebook comments panel 108
E fields. See columns
EAR files 11 file cache 9
emitters 28 file formats 31
encoding 57 See also flat file formats
encoding styles 29 file names
encryption 59 getting 80, 102
ERR_CLIENT constant 86 rendering reports and 106
ERR_CLIENT exception type 76, 112 filters 40
ERR_SERVER constant 86 Firefox browsers 76
ERR_SERVER exception type 76, 112 FirstTable parameter 62
ERR_USAGE constant 86 Flash charts 50
ERR_USAGE exception type 76, 112 Flash gadgets 50
error codes 77 flat file formats 28, 30
error constants 86 fonts 34, 83
error messages 77, 112 formats. See output formats
errorcallback function 59, 60, 73 formulas 32
errorCallback parameter 58, 71 functions 57
errors 11, 16, 58, 71, 73

Index 115
G HTTP sessions
closing 59
garbage collection 81 initializing 57, 58
getClientHeight function 100 providing security for 58
getClientWidth function 101 sharing information for 59
getColumnName function 93
getColumnType function 94 I
getContentMargin function 101
getCurrentPageNum function 101 image resolution 34
getDataType function 94 images 32, 33
getDefaultIportalUrl function 72 initialize function 57, 58, 73
getDefaultRequestOptions function 72 input 24, 40
getDescription function 76 input parameters 56, 87
getErrCode function 77 installation prerequisites 4
getErrorMessage function 112 installations, testing 14
getHeight function 101 interactive features 22
getHelpBase function 102 Interactive Viewer. See BIRT Interactive
getLocale function 96 Viewer
getMessage function 77 iportalURL variable 71, 73
getName function 91, 94, 110 isConnected function 74
getParameterMap function 88 isExceptionType function 77
getParameterValues function 88 isInitialized function 74
getReportletBookmark function 102
getReportName function 80, 102 J
getTotalPageCount function 102 JAR files 11
getTransientDocumentName function 81 Java Development Kit (JDK) 4
getType function 77 Java Virtual Machine (JVM) 5, 16
getValue function 92, 94, 110 JavaScript API
getValueIsNull function 95, 111 accessing 56
getViewer function 72, 103 closing sessions for 59
getWidth function 103 developing with 56, 68
global constants 86 initializing sessions for 57, 58
gotoBookmark function 103 providing security with 58–60
gotoPage function 104 JavaScript API class libraries 56, 68, 74
grand totals 44, 51 JavaScript API class reference 69
graphics 32, 33 JavaScript API classes 56, 68
graphs. See charts JavaScript API functions 57
JavaScript framework 56
H JBoss servers 4, 11, 17
headings. See column headers
heap size properties (JVM) 16 L
help 102, 105 landing page (BIRT Viewer Toolkit) 14
HTML elements 79, 98 large reports 61
HTML formats 33, 100 LDAP environments 59
HTML forms 79, 83 libraries 11, 56, 68, 74
HTTP requests 56 licensing options 22
line charts 45

116 U s i n g B I R T V i e w e r To o l k i t
Link To This Page dialog box 25 ON_EXCEPTION event 112
linking to reports 25 ON_SESSION_TIMEOUT constant 90, 109
literal strings 105 online documentation v, 102, 105
load function online help. See online documentation
actuate 57, 58, 74 onUnload function 81
Parameter 62 opening
loading connections 56, 57, 73
class libraries 56 Excel output 33
JavaScript API library 68 PDF output 35
report components 58, 74 PostScript output 35
reports 60 PowerPoint output 37
locale parameters 8 reports 60
locale-specific reports 30, 34 Word document files 36
localization opening BIRT Viewer Toolkit 14
converting parameters for 88 operating systems 4
getting current locale for 96 operators 40, 41
setting locale for 97 optimizing performance 9
viewing data and 57, 84 output 62
LOG_FILE_LOCATION parameter 9 output formats 100
logout function 59, 75 bidirectional text and 34
exporting charts and 46, 47
M exporting cross tabs and 51
margins 101, 104 exporting data and 28, 30, 31
measures (cross tabs) 50, 51 pagination properties and 33
memory 9
meta tag 57 P
meter charts 45 page components 86, 101, 104
Microsoft Office applications 36 page counts 102
mobile applications 22 page layouts 57
multi-clue parameters 87 page navigation constants 86
page navigation tool 24
N page numbers 101
NameValuePair class 91 page position (viewer) 103
navigate function 81 page ranges 100
navigation buttons 81, 86 Parameter class 62, 79
navigation options 24 parameter components 62, 70, 74, 79
No Condition operator 40 parameter convert utility class 87
null values parameter definitions 91
authentication and 71 parameter global constants 86
getting 95, 111 parameter lists
reserved parameters and 58, 59 defining name-value pairs for 91
setting 95, 111 setting autosuggest delays for 82
numeric values 44 setting column names for 111
setting fetch size of 82
O setting length of 83
parameter maps 88
ON_EXCEPTION constant 90, 109

Index 117
parameter names 94, 110 PostScript formats 34, 35, 100
parameter objects 79, 81, 84 PowerPoint formats 36, 100
parameter pages .ppt files. See PowerPoint formats
changing 81 .pptx files. See PowerPoint formats
displaying parameters and 64, 79, 82 printing 108
loading 74 privileges 5
navigating through 63, 81, 86 processParameters function 63
setting fonts for 83 prompting for input 24, 40
setting HTML container for 83 .ps files. See PostScript formats
parameter panels 108 PSV files 28, 31
parameters pyramid charts 44
authenticating web services and 59, 71
changing 40, 41, 79 R
converting values for 87 renaming deployment archives 10
displaying reports and 60 renderContent function 82
downloading 63, 64, 80 rendering
getting custom URL 96 parameter components 79, 82
getting data types for 94 reports 57, 106
getting file names for 80 report components 58, 74
getting values for 88, 94, 95, 110, 111 report design files 62, 84, 106
initializing HTTP sessions and 58, 73 report designs 22, 40
linking to web services 84 report document files 9, 40, 81, 84, 106
localizing 84 report elements 29
removing authentication information getting bookmarks for 102, 103
and 60 loading 58
retrieving data and 24, 40, 56 report emitters 28
retrieving from reports 63, 64, 84 report executables 62
running reports and 62, 81, 105 report files 80, 102
selecting 83 report parameters 62, 79
setting properties for 88 Reportlets 102, 105
setting values for 40, 41, 87, 93, 95, 111 reports
specifying null values for 95, 111 counting pages in 102
submitting requests for 85, 93 displaying 22, 40, 60, 62, 98
unloading 81 downloading 100
viewing 63, 64, 79, 82 embedding in web pages 56, 57
Parameters command 24, 40 exporting 100, 107
Parameters dialog box 40, 41 generating 81
ParameterValue class 93, 110 getting parameters for 79
passback variable 56 limiting data retrieved for 24
path parameters 9 linking to 25
PDF emitter 33 navigating through 24, 103, 104
PDF formats 28, 33, 100 opening 60
performance parameters 9 printing 108
pie charts 45 rendering 57, 106
pipe-separated values files 28, 31 retrieving content for 56
pixel values (viewer) 101 retrieving parameters from 63, 64, 80, 84
PostScript emitter 35

118 U s i n g B I R T V i e w e r To o l k i t
 retrieving specific pages 100 setContentMarg function 104
running 41, 105 setCustomParameter function 96
setting locale for 97 setFont function 83
viewing specific pages 24 setHeight function 104
viewing specific parts of 61 setHelpBase function 104
REPOSITORY_CACHE_TIMEOUT_SEC setLocale function 97
parameter 9 setName function 92
RequestOptions class 58, 71, 96 setParameters function 105
requestOptions parameter 96 setParameterValues function 64, 105
requests setReportletBookmark function 61, 105
authenticating 96 setReportName function
closing HTTP sessions and 60 Parameter 63, 84
displaying reports and 61, 108 Viewer 60, 106
getting options for 72 setService function 84, 106
retrieving data and 56 setShowDisplayType function 84
retrieving parameters and 63, 64, 85, 93 setSize function 107
specifying default settings for 58, 59 setSupportSVG function 107
reserved parameters 58, 59 setValue function 92, 95, 111
resizing viewers 100, 102, 107 setValueIsNull function 95, 111
resources 59 setWidth function 107
rows 29, 50 sharing reports 24, 28
running reports 62, 105 showDownloadReportDialog function 107
showFacebookCommentPanel function 108
S showParameterPanel function 108
saving showPrintDialog function 108
Excel output 33 SOAP message error descriptions 76
PDF output 35 source code 56
PostScript output 35 spreadsheet output formats 100
PowerPoint output 37 spreadsheets 32
Word document files 36 See also Excel formats
Scalable Vector Graphics 107 SSV files 28, 31
Scalable Vector Graphics formats 34 standards compliance mode 57
scatter charts 46 statistical data 46
scientific data 46 stock charts 45
script tag 57, 68 strings 57, 105
scrolling 61 subclasses 56
security 58–60 submit function
semicolon-separated values files 28, 31 Parameter 63, 85
series. See data series Viewer 60, 108
server errors 76, 86 summary data 50
servers 4, 5, 10, 16, 59 SVG flag 107
setAutoSuggestDelay function 82 SVG formats 34
setAutoSuggestFetchSize function 82 system requirements 4
setAutoSuggestListSize function 83
setColumnName function 111 T
setContainer function 83 table views 32

Index 119
tables 28, 29, 62 setting display names for 91
See also cross tabs setting parameter 87, 93, 95, 111
tab-separated values files 28, 31 specifying null 95, 111
target service URL 106 variables 56, 81
TEMP_FOLDER_LOCATION parameter 9 viewContainer parameter 98
temporary files 9, 81 viewContainerId parameter 98
testing connections 74 Viewer class 60, 62, 98
testing installations 14 viewer components 60, 70, 75, 98
text 34 viewer event constants 109
time values 30 viewer objects 98
time zones 9 Viewer Toolkit. See BIRT Viewer Toolkit
Tomcat servers 59 ViewerException class 112
toolbars 24 viewers
totals 44, 51 displaying parameters in 63, 64
transient files 9, 81 displaying reports in 60, 62, 98
TRANSIENT_STORE_PATH parameter 9 getting browser size for 100, 101
TSV files 28, 31 getting file names for 102
tube charts 44 getting margins for 101
types. See data types getting size 102, 103
getting specific instance 72, 103
U handling events for 109
uncategorized exceptions 76 handling exceptions for 112
URL parameters 58, 71, 84, 96 instantiating 60
URLs loading 60
accessing JavaScript library and 68 reloading 108
accessing resources and 59 resizing 100, 102, 107
BIRT Viewer Toolkit landing page 14 setting margins for 104
connecting to web services and 106 setting size 104, 107
displaying help documentation and 102, submitting requests for 108
105 viewing
retrieving parameters and 84 cross tabs 50
returning default web service 72 data 44
testing connections for 74 report elements 29
usage errors 76, 86 report parameters 63, 64, 79, 82
user credentials 59, 71 Reportlets 102, 105
userid variable 71 reports 22, 24, 40, 60, 62, 98
UTF8 character encoding 57 tables 62

V W
value series (charts) 44 WAR files 8, 10
See also data series web browser exceptions 76
valueIsNull value 95, 111 web browser windows 101
values web browsers 76, 100
converting 87 web pages
downloading parameters and 80 accessing class libraries for 56, 68
getting parameter 88, 94, 95, 110, 111 adding JavaScript functions to 57

120 U s i n g B I R T V i e w e r To o l k i t
 displaying reports in 60, 62, 98 WebLogic servers 4
embedding report parameters in 62, 63, 64 WebSphere servers 4
embedding reports in 56, 57 Word document formats 36
enabling SVG support for 107 Word document output formats 100
initializing HTTP sessions for 57, 58 worksheets 32
loading report components for 58, 74 See also Excel formats
retrieving data for 56
web services X
authenticating users for 58 x-axis values (charts) 44
closing connections to 75
getting default URL for 72 Y
linking parameters to 84
opening connections for 56, 57, 73 y-axis values (charts) 44
setting URLs for 106

Index 121
122 U s i n g B I R T V i e w e r To o l k i t