Using BIRT Viewer Toolkitotadocs.opentext.com/documentation/ManualsBVT/... · 8 Installing BIRT...

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

i

ContentsAbout Using BIRT Viewer Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Part 1Installing BIRT Viewer Toolkit

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

Chapter 2Deploying BIRT Viewer Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Setting web application parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Configuring locale parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Configuring path parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Configuring performance parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Compressing files and renaming the WAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Deploying BIRT Viewer Toolkit as a WAR or EAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Deploying the BIRT Viewer Toolkit WAR file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Deploying the BIRT Viewer Toolkit EAR file to JBoss 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

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

Part 2Using BIRT Viewer Toolkit

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

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

ii

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

Chapter 6Exporting report data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27About exporting options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28Exporting report data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28Exporting content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Exporting content to Microsoft Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32Exporting content to PDF format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33Exporting content to PostScript format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35Exporting content to Microsoft Word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36Exporting content to Microsoft PowerPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

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

Chapter 8Working with charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43About charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Types of charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44

About bar charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44About tube, cone, and pyramid charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44About area charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45About line charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45About pie charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45About meter charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45About stock charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45About scatter charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46About bubble charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Exporting data from a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46Exporting a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Chapter 9Working with cross tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49About cross tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50

Introducing a cross tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50Parts of a cross tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50

Exporting cross tab content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

iii

Part 3Using Actuate JavaScript API

Chapter 10Creating a custom web page using the Actuate JavaScript API . . . . . . . 55About the Actuate JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Accessing the Actuate JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

About the DOCTYPE tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57About UTF-8 character encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Establishing an HTTP session with an Actuate BIRT Viewer Toolkit application . . . . . . . . . . . 57About Actuate JavaScript API security integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Establishing a connection to more than one web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Unloading authentication information from the session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Viewing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Using and submitting report parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Using a parameter component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Accessing parameter values from the viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 11Actuate JavaScript API classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Actuate JavaScript API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

About the actuate namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Using the Actuate library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

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

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

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

A b o u t U s i n g B I R TV i e w e r T o 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.

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

■ 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.

Part 1Installing BIRT Viewer Toolkit

PartOne1

C h a p t e r 1 , B e f o r e y o u b e g i n 3

C h a p t e r

1Chapter 1Before you begin

This chapter discusses the following topics:

■ About BIRT Viewer Toolkit

■ About deployment formats

■ Checking installation prerequisites

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

About BIRT Viewer ToolkitBIRT 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 formatsYou 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.

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

Checking installation prerequisitesBefore 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 serverBIRT Viewer Toolkit runs as a web application in the application server, such as Apache Tomcat 6 or JBoss 6.

Table 1-1 BIRT Viewer Toolkit deployment formats

File Application server

WL_TOMCAT_ActuateBIRTViewer.war Apache Tomcat 6BEA WebLogic 9.2 or 10.3

JBOSS_ActuateBIRTViewer.ear JBoss 6

WAS_ActuateBIRTViewer.ear IBM WebSphere 6.1 or 1.1.01

C h a p t e r 1 , B e f o r e y o u b e g i n 5

■ 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

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

C h a p t e r

2Chapter 2Deploying BIRT Viewer

ToolkitThis 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


Setting web application parametersThe 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 parametersBIRT Viewer Toolkit uses the locale parameters in web.xml, described in Table 2-1.


Configuring path parametersBIRT 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.

Configuring performance parametersBIRT 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-1 Locale parameters

Parameter name Description Value

DEFAULT_LOCALE The value of this parameter determines the default locale. The default locale is en_US.

Use the default locale or a value from Localemap.xml in the WEB-INF directory.

DEFAULT_TIMEZONE The value of this parameter determines the default time zone. The default time zone is Pacific Standard Time (PST).

Use the default time zone or a value from Timezonemap.xml in the WEB-INF directory.

Table 2-2 Path parameters

Parameter name Description

LOG_FILE_LOCATION

The location of the files that log BIRT Viewer Toolkit activities. The default value is /logs.

TEMP_FOLDER_LOCATION

The location where BIRT Viewer Toolkit creates temporary files. There is no default value.

TRANSIENT_STORE_PATH

Another location where BIRT Viewer Toolkit creates temporary files. The default value is /temp.

Table 2-3 Performance parameters

Parameter name Description

BIRT_ARCHIVE_MEMORY_TOTALSIZE

Total memory available for BIRT report document files in kilobytes. The default value is 50 MB.

REPOSITORY_CACHE_TIMEOUT_SEC

Specifies, in seconds, how long to retain temporary files that BIRT Viewer creates. The default value is 900, which is 15 minutes.


Compressing files and renaming the WAR fileAfter 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 fileBIRT Viewer Toolkit is available in WAR and EAR file formats.

Deploying the BIRT Viewer Toolkit WAR fileThis 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.


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.

Figure 2-3 Tomcat log file confirms deployment

Deploying the BIRT Viewer Toolkit EAR file to JBoss 6In 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

Deployment confirmation

Specified temp directory

Default Linux path to logs


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.

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

C h a p t e r

3Chapter 3Testing BIRT Viewer

ToolkitThis chapter discusses the following topics:

■ Testing the installation

■ Setting JVM properties


Testing the installationTo 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.

Figure 3-2 Landing page sample report

Main menu Navigation bar


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.


Figure 3-4 Displaying a report using Actuate BIRT Viewer Toolkit

Setting JVM propertiesDeploying 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 sizeInclude -Xms64m as a Java option.

■ Maximum heap sizeInclude -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.


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.

Part 2Using BIRT Viewer Toolkit

Part Two2

C h a p t e r 4 , I n t r o d u c i n g A c t u a t e B I R T V i e w e r s 21

C h a p t e r

4Chapter 4Introducing

Actuate BIRT ViewersThis chapter contains the following topics:

■ About BIRT Viewer Toolkit

■ About Actuate BIRT commercial viewers

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

About BIRT Viewer ToolkitActuate 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 viewersActuate 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/

C h a p t e r 5 , N a v i g a t i n g a r e p o r t 23

C h a p t e r

5Chapter 5Navigating a report

This chapter contains the following topics:

■ About navigation options

■ Paging through a report

■ Displaying parameter values

■ Linking to a report page


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

Paging through a reportThe 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 valuesUsing 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 pageYou 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.

C h a p t e r 5 , N a v i g a t i n g a r e p o r t 25

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

C h a p t e r 6 , E x p o r t i n g r e p o r t d a t a 27

C h a p t e r

6Chapter 6Exporting report data


■ About exporting options

■ Exporting report data

■ Exporting content


About exporting optionsBIRT 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 dataYou 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.


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.


❏ 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.


■ 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 contentYou 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.


Exporting content to Microsoft ExcelYou 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.


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 formatYou 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.


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.


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 formatWhen 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


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.


When you open the file, the report displays in the format you specified.


Exporting content to Microsoft WordBIRT 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


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.


3 For DOCX format, select Embed HTML to include HTML content directly in the output document.

Choose OK.


When you open the file, the report displays in the Word format you specified.

Exporting content to Microsoft PowerPointBIRT 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


■ Page overflow processing

■ Chart DPI

How to export a report or report element to PowerPoint format


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.


Choose OK.


When you open the file, the report displays in the PowerPoint format you specified.

C h a p t e r 7 , F i l t e r i n g r e p o r t d a t a 39

C h a p t e r

7Chapter 7Filtering report data

This chapter contains information about providing parameter values.


Providing parameter valuesIf 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.

C h a p t e r 7 , F i l t e r i n g r e p o r t d a t a 41

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.

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

Close

Parameters section

Report

Run Report


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.

C h a p t e r 8 , W o r k i n g w i t h c h a r t s 43

C h a p t e r

8Chapter 8Working with charts


■ About charts

■ Types of charts

■ Exporting data from a chart

■ Exporting a chart


About chartsA 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 chartsSpecific 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 chartsA 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 chartsTube, 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.


About area chartsAn 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 chartsA 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 chartsPie 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 chartsA 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 chartsA 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


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 chartsA 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 chartsA 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 chartYou 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 chartYou can export a chart to Excel, Excel 2007 and 2010, Microsoft Word, Microsoft Word 2007 and 2010, Microsoft PowerPoint, Microsoft PowerPoint 2007 and 2010,


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

C h a p t e r 9 , W o r k i n g w i t h c r o s s t a b s 49

C h a p t e r

9Chapter 9Working with cross tabs


■ About cross tabs

■ Exporting cross tab content


About cross tabsA 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 tabA 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 tabA cross tab consists of the following three areas, as shown in Figure 9-1:

■ The row area

■ The column area

■ The detail area

C h a p t e r 9 , W o r k i n g w i t h c r o s s t a b s 51

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.

Exporting cross tab contentYou 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.

Detail area

Rows Columns

Figure 9-1 Parts of a cross tab

Part 3Using Actuate JavaScript API

Part Three3

Chapter 10, Creat ing a custom web page us ing the Actuate JavaScr ip t API 55

C h a p t e r

10Chapter 10Creating a custom web

page using the ActuateJavaScript API


■ 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

56 U s i n g A c t u a t e J a v a S c r i p t A P I

About the Actuate JavaScript APIThe 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 APITo 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>

<div id="viewer1"><script type="text/javascript" language="JavaScript"

src="http://localhost:8080/webapp/jsapi"></script><script type="text/javascript" language="JavaScript">… </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 tagTo 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 encodingUse 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.


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 integrationThe 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 serviceThe actuate.initialize( ) function establishes a session with one Actuate BIRT Viewer Toolkit application service. Use the actuate.authenticate( ) function for


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 sessionThe 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:


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 reportsThe 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.


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:


<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:


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 parametersUse 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 componentThe 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>


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.


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 viewerThe 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:


<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">

C h a p t e r 1 1 , A c t u a t e J a v a S c r i p t A P I c l a s s e s 67

C h a p t e r

11Chapter 11Actuate JavaScript API

classesThis chapter contains the following topics:

■ Actuate JavaScript API overview

■ Actuate JavaScript API classes quick reference

■ Actuate JavaScript API reference


Actuate JavaScript API overviewThe 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 namespaceAll 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 libraryThe 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 referenceTable 11-1 lists the Actuate JavaScript API classes.


Actuate JavaScript API referenceThis section provides an alphabetical listing of the JavaScript API classes.

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


Class actuateDescription 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( ).

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

Function summaryTable 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


actuate.authenticateSyntax 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 iPortalURLThe iPortalURL parameter is a required string parameter that specifies the target Actuate web application URL.

requestOptionsThe 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.

reservedSet to null.


credentialsThe 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.

callbackThe 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

errorCallbackThe 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.


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.getDefaultIportalUrlSyntax 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.getDefaultRequestOptionsSyntax 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.getViewerSyntax 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.


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.initializeSyntax 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 iPortalURLString. The target Actuate web application URL.

requestOptionsactuate.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.



callbackFunction. 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

errorCallbackFunction. 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);


actuate.isConnectedSyntax boolean isConnected(string iportalUrl, actuate.RequestOptions requestOptions)

Returns whether a given Actuate web application URL is connected.


requestOptionsactuate.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.isInitializedSyntax 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.loadSyntax 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


■ viewer: The viewer component including the actuate.Viewer class and subclasses

Parameter componentNameString. 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.logoutSyntax 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.


requestOptionsactuate.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.

callbackFunction. Optional. The callback function called after the logout is done.

errorCallbackFunction. 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);

}


Class actuate.ExceptionDescription 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.

ConstructorThe 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 summaryTable 11-3 lists actuate.Exception functions.

actuate.Exception.getDescriptionSyntax 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

Table 11-3 actuate.Exception functions


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


Example This example displays the server error description in an alert box:

alert("Server error: " + Exception.getDescription( ));

actuate.Exception.getErrCodeSyntax 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.getMessageSyntax 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.


Example This example displays the error’s short message code in an alert box:

alert("Error Message: " + Exception.getMessage( ));

actuate.Exception.getTypeSyntax string Exception.getType( )

Returns the type of the exception:



■ ERR_USAGE: Exception type for a Actuate JavaScript API usage error


Example This example displays the error type in an alert box:

alert("Error type: " + Exception.getType( ));

actuate.Exception.isExceptionTypeSyntax boolean Exception.isExceptionType(object exceptionType)

Compares the input object to the exception contained in this actuate.Exception object to the exceptionType object argument.


Parameters exceptionTypeObject. 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!');

}


Class actuate.ParameterDescription 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.

ConstructorSyntax actuate.Parameter(string container)

Constructs a parameter object for a page, initializing the parameter component.

Parameter containerString. 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 summaryTable 11-4 lists actuate.Parameter functions.

Table 11-4 actuate.Parameter functions


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)


actuate.Parameter.downloadParameterValuesSyntax 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 callbackFunction. 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.getReportNameSyntax 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( ));

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

Table 11-4 actuate.Parameter functions



actuate.Parameter.getTransientDocumentNameSyntax 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.navigateSyntax 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 containerIdString. The value of the id parameter for the HTML <div> element that holds the parameter component.

navTargetString 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.onUnloadSyntax 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.");


actuate.Parameter.renderContentSyntax void Parameter.renderContent(actuate.parameter.ParameterDefinition[ ]

paramDefs, function callback)

Renders the parameter component to the container.

Parameters paramDefsArray of actuate.parameter.ParameterDefinition objects.

callbackFunction. 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.setAutoSuggestDelaySyntax void Parameter.setAutoSuggestDelay(long delay)

Sets the autosuggest delay time.

Parameter delayLong. 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.setAutoSuggestFetchSizeSyntax 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 sizeInteger. The number of suggestions to fetch at a time.




}

actuate.Parameter.setAutoSuggestListSizeSyntax 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 sizeInteger. The number of suggestions to display.



}

actuate.Parameter.setContainerSyntax void Parameter.setContainer(string containerId)

Sets the HTML element container for the parameter content.

Parameter containerIDString. 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.setFontSyntax void Parameter.setFont(string fontStyleString)

Sets the font of the parameter page content after the page is rendered.

Parameter fontStyleStringString. The name of a font.

Example This example sets the font to Arial for the parameters page:

paramObj.setFont("arial");


actuate.Parameter.setReportNameSyntax void Parameter.setReportName(string reportFile)

Sets the report file from which to get report parameters.

Parameter reportFileString. 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.setServiceSyntax 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.


requestOptionsactuate.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.setShowDisplayTypeSyntax void Parameter.setShowDisplayType(boolean showDisplayType)

Sets whether localized data is shown or not.

Parameter showDisplayTypeBoolean. True indicates that localized data is shown.

Example This example hides localized data:

paramObj.setShowDisplayType(false);paramObj.submit(alert("Localized data hidden.");


actuate.Parameter.submitSyntax 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 callbackFunction. 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."));


Class actuate.parameter.ConstantsDescription 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


Class actuate.parameter.ConvertUtilityDescription 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.

ConstructorSyntax actuate.parameter.ConvertUtility(actuate.parameter.ParameterValue[ ]

aParamVals)

Constructs a new ConvertUtility object.

Parameter aParamValsArray of actuate.parameter.ParameterValue objects to convert.

Function summaryTable 11-6 lists actuate.parameter.ConvertUtility functions.

actuate.parameter.ConvertUtility.convertSyntax void ConvertUtility.convert(function callback)

Converts ParameterValues into an array of generic objects. The callback function takes the array as an argument.

Parameter callbackFunction. 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:

Table 11-6 actuate.parameter.ConvertUtility functions


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


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

nameValueArray = values;}

actuate.parameter.ConvertUtility.convertDateSyntax void ConvertUtility.convertDate(function callback)

Converts locale-neutral parameter values to the user’s login locale.

Parameter callbackFunction. 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.getParameterMapSyntax 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.getParameterValuesSyntax actuate.parameter.ParameterValue[ ] ConvertUtility.getParameterValues( )

Returns the array of ParameterValue objects.


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( );


Class actuate.parameter.EventConstantsDescription 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


Class actuate.parameter.NameValuePairDescription 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.

ConstructorSyntax actuate.parameter.NameValuePair(string name, string value)

Constructs a new NameValuePair object.

Parameters nameString. The name to display in the selection list.

value

String. The value that selecting the name sets internally.

Function summaryTable 11-8 lists actuate.parameter.NameValuePair functions.

actuate.parameter.NameValuePair.getNameSyntax 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( ));

Table 11-8 actuate.parameter.NameValuePair functions


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.getValueSyntax 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.setNameSyntax void NameValuePair.setName(string name)

Sets the name for the NameValuePair.

Parameter nameString.

Example This sample code sets the name component of the myNVPair NameValuePair object to "My hometown":

myNVPair.setName("My hometown");

actuate.parameter.NameValuePair.setValueSyntax void NameValuePair.setValue(string value)

Sets the value for the NameValuePair.

Parameter valueString.

Example This sample code sets the value component of the myNVPair NameValuePair object to "Cleveland":

myNVPair.setValue("Cleveland");


Class actuate.parameter.ParameterValueDescription 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.

ConstructorSyntax actuate.parameter.ParameterValue( )

Constructs a new ParameterValue object.

Function summaryTable 11-9 lists actuate.parameter.ParameterValue functions.

actuate.parameter.ParameterValue.getColumnNameSyntax 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( );

Table 11-9 actuate.parameter.ParameterValue functions


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.getColumnTypeSyntax 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.getDataTypeSyntax 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.getNameSyntax 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.getValueSyntax 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( );


actuate.parameter.ParameterValue.getValueIsNullSyntax 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.setValueSyntax void ParameterValue.setValue(string[ ] value)

Sets the value or values for this ParameterValue.

Parameter valueString 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.setValueIsNullSyntax void ParameterValue.setValueIsNull(boolean valueIsNull)

Sets the valueIsNull value for this ParameterValue.

Parameter valueIsNullBoolean. 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);


Class actuate.RequestOptionsDescription 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.

ConstructorSyntax actuate.RequestOptions( actuate.RequestOptions requestOptions)

Constructs a new RequestOptions object.

Parameter requestOptionsactuate.RequestOptions object. Optional. Provides request option settings to copy into this RequestOptions object.

Function summaryTable 11-10 lists actuate.RequestOptions functions.

actuate.RequestOptions.getLocaleSyntax 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.setCustomParametersSyntax void RequestOptions.setCustomParameters(object parameters)

Returns a custom parameter in the request URL.

Table 11-10 actuate.RequestOptions functions


getLocale( ) Returns the current locale

setCustomParameters( ) Appends a custom parameter to the request URL

setLocale( ) Sets the locale


Parameter parametersObject. 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.setLocaleSyntax void RequestOptions.setLocale(string Locale)

Sets the locale.

Parameter LocaleString. 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( );


Class actuate.ViewerDescription 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.

ConstructorSyntax 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 viewContainerObject. A document object that references the <div> element that holds the viewer.

viewContainerIdString. 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 summaryTable 11-11 lists actuate.Viewer functions.

Table 11-11 actuate.Viewer functions


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


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

showDownloadReportDialog( )

Enables the export report dialog window

showFacebookCommentPanel( )

Shows the Facebook comments 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

Table 11-11 actuate.Viewer functions (continued)



actuate.Viewer.downloadReportSyntax 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 formatString. 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

pagesString. 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.

renderoptionactuate.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.getClientHeightSyntax 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:


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

}

actuate.Viewer.getClientWidthSyntax 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.getContentMarginSyntax 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.getCurrentPageNumSyntax 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.getHeightSyntax string Viewer.getHeight( )


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.getHelpBaseSyntax 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.getReportletBookmarkSyntax 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.getReportNameSyntax 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.getTotalPageCountSyntax integer Viewer.getTotalPageCount( )

Returns the total number of pages in the report being viewed.

Returns Integer.


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.getViewerSyntax 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 bookmarkString. The bookmark of the report element to view.

elementIDObject. 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.getWidthSyntax 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.gotoBookmarkSyntax 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 bookmarkString. The bookmark of a report element.


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.gotoPageSyntax void Viewer.gotoPage(integer pageNumber)

Goes to the specified page. The viewer throws an exception when the page is not found.

Parameter pageNumberInteger. 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.setContentMargSyntax void Viewer.setContentMargin(string[ ] margin)

void Viewer.setContentMargin(int margin)

Sets the viewer content margin.

Parameter marginArray 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.setHeightSyntax void Viewer.setHeight(integer height)

Sets the viewer height.

Parameter heightInteger. The height in pixels.

Example To set the height of the viewer to 600 pixels, use the following code:

viewer.setHeight(600);

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


Sets the URL of the help base. The help base is the base URL for the product help documentation.

Parameter helpBaseString. 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.setParametersSyntax void Viewer.setParameters(string[ ] params)

Sets parameters for executing report using literal string pairs.

Parameter paramsArray 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.setParameterValuesSyntax void Viewer.setParameterValues(actuate.parameter.ParameterValue[ ]

parameters)

Sets parameter values for executing a report using ParameterValue objects.

Parameter parametersArray 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.setReportletBookmarkSyntax void Viewer.setReportletBookmark(string bookmark)

Sets the bookmark for the Reportlet rendered.


Parameter bookmarkString. 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.setReportNameSyntax void Viewer.setReportName(string reportFile)

Sets the report file, either a report design or report document, to render in this Viewer.

Parameter reportFileString. 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.setServiceSyntax 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 iPortalURLString. The target Actuate web application URL.

requestOptionsactuate.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);


actuate.Viewer.setSizeSyntax void Viewer.setSize(integer width, integer height)

Resizes the viewer’s width and height.

Parameter widthInteger. The new width is specified in pixels.

heightInteger. 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.setSupportSVGSyntax void Viewer.setSupportSVG(boolean usvgFlag)

Controls Scalable Vector Graphics support for the viewer.

Parameter svgFlagBoolean. 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.setWidthSyntax void Viewer.setWidth(string width)

Sets the viewer width.

Parameter widthString.

Example To set the width of the viewer to 800 pixels, use the following code:

viewer.setWidth(800);

actuate.Viewer.showDownloadReportDialogSyntax void Viewer.showDownloadReportDialog( )

Displays the export report dialog window.

Example Use this code to display the report dialog window:

myViewer.showDownloadReportDialog( );


actuate.Viewer.showFacebookCommentPanelSyntax void Viewer.showFacebookCommentPanel( )

Displays the Facebook comments panel.

Example Use this code to display the Facebook comments panel:

viewer.showFacebookCommentPanel( );

actuate.Viewer.showParameterPanelSyntax void Viewer.showParameterPanel( )

Displays the parameter panel.

Example Use this code to display the parameter panel:

viewer.showParameterPanel( );

actuate.Viewer.showPrintDialogSyntax void Viewer.showPrintDialog( )

Displays the print dialog window.

Example Use this code to display the print dialog window:

viewer.showPrintDialog( );

actuate.Viewer.submitSyntax 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 callbackFunction. Optional. The function to execute after the asynchronous call processing is done.

rerunBoolean. 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( );


Class actuate.viewer.EventConstantsDescription 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.


Class actuate.viewer.ParameterValueDescription The ParameterValue class is a JavaScript version of the

com.actuate.schemas.ParameterValue class.

ConstructorSyntax actuate.parameter.ParameterValue( )

Constructs a new ParameterValue object.

Function summaryTable 11-13 lists the actuate.viewer.ParameterValue functions.

actuate.viewer.ParameterValue.getNameSyntax 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.getValueSyntax object ParameterValue.getValue( )

Returns the value value.

Returns Object. The value value, a string or array of strings.

Table 11-13 actuate.viewer.ParameterValue functions


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


Example To store a ParameterValue’s value in vPVvalue, use the following code:

var vPVvalue = myParamValue.getValue( );

actuate.viewer.ParameterValue.getValueIsNullSyntax 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.setColumnNameSyntax void ParameterValue.setColumnName(string columnName)

Sets the columnName value.

Parameter columnNameString. The column name.

Example To set the column name to "Motorcycles", use code similar to the following:

myParamValue.setColumnName("Motorcycles");

actuate.viewer.ParameterValue.setValueSyntax void ParameterValue.setValue(object value)

Sets the value. A value can be a string or an array of strings.

Parameter valueObject. 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.setValueIsNullSyntax void ParameterValue.setValueIsNull(boolean valueIsNull)

Sets the valueIsNull value.

Parameter valueIsNullBoolean. The valueIsNull value.

Example To set a ParameterValue’s setValueIsNull to true, use the following code:

myParamValue.setValueIsNull(true);


Class actuate.viewer.ViewerExceptionDescription 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.

ConstructorThe 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_USAGE: Exception type for a JSAPI usage error

Function summaryTable 11-14 describes the actuate.viewer.ViewerException function.

actuate.viewer.ViewerException.getErrorMessageSyntax 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( ));

Table 11-14 actuate.viewer.ViewerException function


getErrorMessage( ) Returns the exception message

I n d e x 113

IndexAaccessing

BIRT Viewer Toolkit landing page 14JavaScript API 56, 68report viewers 60resources 59source code 56web service applications 59

activity logs 9actuate class 56, 57, 68, 70actuate namespace 68ad hoc parameters 87, 93, 94adding

parameter components 62, 79URL parameters 58viewer components 60, 98web pages 56, 57

aggregate data 29, 32, 50alerts 78Apache Tomcat servers 59

configuring 16, 17deploying to 4, 10

application servers 4, 5, 10, 16, 59applications 22, 28, 31

accessing 59developing 56, 68displaying reports and 61, 62establishing connections to 56, 57, 73loading class libraries from 56logging out of 75providing security for 58–60See also Microsoft Office applicationstesting connections for 74

area charts 45authenticate function 58, 71authentication 58, 71authentication information 58, 59, 75, 96autosuggest delays 82autosuggestion lists 82, 83

Bbar charts 44

base class 56bidirectional (BIDI) text 34BIRT Interactive Viewer 22BIRT Viewer 22, 24BIRT Viewer Toolkit 22, 28, 31

configuring 8–9deploying 4, 8, 10, 16displaying data and 4optimizing performance 9setting location of 9testing installation 14

BIRT Viewer Toolkit landing page 14BIRT_ARCHIVE_ MEMORY_TOTALSIZE

parameter 9bookmarks

displaying report elements and 61, 103displaying Reportlets and 102, 105getting report content for 102navigating through reports and 103returning viewer objects for 72, 103

bubble charts 46button constants (navigation) 81

Ccache 9calculated data 29, 32callback functions

closing HTTP sessions and 60connecting to web services and 59, 71, 73defined 56displaying reports and 61handling exceptions and 71, 76initializing HTTP sessions and 58retrieving parameters and 63, 80, 87

category series (charts) 44See also data series

changingparameters 40, 41, 79report designs 22report output 62

character encoding 57character encryption 59chart images 32, 33


chart types 44chart views 32charts

See also specific chart typedisplaying data and 44displaying small sets of values in 45exporting 28, 32, 46showing scientific data and 46

class libraries 56, 68, 74classes 56, 68client-side errors 76, 86code 56column headers 31column names 93, 111columns 29, 50, 94comma-separated values files 28comparisons 44component names 75cone charts 44configuration files 8configuration parameters 8configuring

application servers 16–17BIRT Viewer Toolkit 8–9

connection parameters 58, 73connections

authenticating users and 58, 71closing 75opening 56, 57, 73testing 74

Constants class 86content components 60convert function 87convertDate function 88ConvertUtility class 87creating

autosuggestion lists 83display names 91parameter components 62, 79URL parameters 58viewer components 60, 98web pages 56, 57

credentials 59, 71cross tabs 50–51

See also tablescrossContext parameter 59CSV files 28

cubes 50customizing

autosuggestion lists 83URL parameters 58web pages 56

Ddata 56, 57

comparing 44displaying 44exporting 28–37retrieving 24, 40selecting 41showing changes over time 44, 45showing percentage to whole 44, 45showing relationship between 44showing relationship to whole 45showing trends in 46

data cubes 50data filters 40data points (charts) 44data ranges 42data rows 29, 50data series

See also chartsdisplaying in columns 44displaying multiple 45displaying side by side 44overlapping multiple 45plotting data and 44stacking multiple 44, 45

data service components 75data types 30, 94date values 30, 44, 88default parameters 71default settings 58, 59default values 80default web service URL 72DEFAULT_LOCALE parameter 9DEFAULT_TIMEZONE parameter 9delays 82deploying BIRT Viewer Toolkit 4, 8, 10, 16deployment errors 11, 16design files 62, 84, 106developing web applications 56, 68dialog boxes 107, 108

I n d e x 115

dimensions (cross tabs) 50, 51display names 91displaying

cross tabs 50data 44report elements 29report parameters 63, 64, 79, 82Reportlets 102, 105reports 22, 24, 40, 60, 62, 98tables 62

div tag 57, 60DOCTYPE tag 57.doc files. See Word document formats.docx files. See Word document formatsdocument files 9, 81, 84, 106document files. See report document filesdocument output formats 100documentation vdocumentation URLs 102, 105documents. See reportsdomains 59downloading

BIRT Viewer Toolkit 4report parameters 63, 64, 80reports 100

downloadParameterValues function 64, 80downloadReport function 100

EEAR files 11emitters 28encoding 57encoding styles 29encryption 59ERR_CLIENT constant 86ERR_CLIENT exception type 76, 112ERR_SERVER constant 86ERR_SERVER exception type 76, 112ERR_USAGE constant 86ERR_USAGE exception type 76, 112error codes 77error constants 86error messages 77, 112errorcallback function 59, 60, 73errorCallback parameter 58, 71errors 11, 16, 58, 71, 73

event handlers 76EventConstants class 90, 109Excel formats 28, 32, 51Excel output formats 100Exception class 76exception classes 112exception types 76, 77exceptions

authentication and 59closing HTTP sessions and 60report parameters and 90viewer and 109, 112

executable files 62Export Content dialog box

Excel output formats and 32PDF output formats and 33PostScript output formats and 35PowerPoint output formats and 37Word output formats and 36

Export Data command 46Export Data dialog box 29, 46export report dialog 107exporting data 28–37exporting reports 100, 107external user credentials 59

FFacebook comments panel 108fields. See columnsfile cache 9file formats 31

See also flat file formatsfile names

getting 80, 102rendering reports and 106

filters 40Firefox browsers 76FirstTable parameter 62Flash charts 50Flash gadgets 50flat file formats 28, 30fonts 34, 83formats. See output formatsformulas 32functions 57


Ggarbage collection 81getClientHeight function 100getClientWidth function 101getColumnName function 93getColumnType function 94getContentMargin function 101getCurrentPageNum function 101getDataType function 94getDefaultIportalUrl function 72getDefaultRequestOptions function 72getDescription function 76getErrCode function 77getErrorMessage function 112getHeight function 101getHelpBase function 102getLocale function 96getMessage function 77getName function 91, 94, 110getParameterMap function 88getParameterValues function 88getReportletBookmark function 102getReportName function 80, 102getTotalPageCount function 102getTransientDocumentName function 81getType function 77getValue function 92, 94, 110getValueIsNull function 95, 111getViewer function 72, 103getWidth function 103global constants 86gotoBookmark function 103gotoPage function 104grand totals 44, 51graphics 32, 33graphs. See charts

Hheadings. See column headersheap size properties (JVM) 16help 102, 105HTML elements 79, 98HTML formats 33, 100HTML forms 79, 83HTTP requests 56

HTTP sessionsclosing 59initializing 57, 58providing security for 58sharing information for 59

Iimage resolution 34images 32, 33initialize function 57, 58, 73input 24, 40input parameters 56, 87installation prerequisites 4installations, testing 14interactive features 22Interactive Viewer. See BIRT Interactive

VieweriportalURL variable 71, 73isConnected function 74isExceptionType function 77isInitialized function 74

JJAR files 11Java Development Kit (JDK) 4Java Virtual Machine (JVM) 5, 16JavaScript API

accessing 56closing sessions for 59developing with 56, 68initializing sessions for 57, 58providing security with 58–60

JavaScript API class libraries 56, 68, 74JavaScript API class reference 69JavaScript API classes 56, 68JavaScript API functions 57JavaScript framework 56JBoss servers 4, 11, 17

Llanding page (BIRT Viewer Toolkit) 14large reports 61LDAP environments 59libraries 11, 56, 68, 74licensing options 22line charts 45

I n d e x 117

Link To This Page dialog box 25linking to reports 25literal strings 105load function

actuate 57, 58, 74Parameter 62

loadingclass libraries 56JavaScript API library 68report components 58, 74reports 60

locale parameters 8locale-specific reports 30, 34localization

converting parameters for 88getting current locale for 96setting locale for 97viewing data and 57, 84

LOG_FILE_LOCATION parameter 9logout function 59, 75

Mmargins 101, 104measures (cross tabs) 50, 51memory 9meta tag 57meter charts 45Microsoft Office applications 36mobile applications 22multi-clue parameters 87

NNameValuePair class 91navigate function 81navigation buttons 81, 86navigation options 24No Condition operator 40null values

authentication and 71getting 95, 111reserved parameters and 58, 59setting 95, 111

numeric values 44

OON_EXCEPTION constant 90, 109

ON_EXCEPTION event 112ON_SESSION_TIMEOUT constant 90, 109online documentation v, 102, 105online help. See online documentationonUnload function 81opening

connections 56, 57, 73Excel output 33PDF output 35PostScript output 35PowerPoint output 37reports 60Word document files 36

opening BIRT Viewer Toolkit 14operating systems 4operators 40, 41optimizing performance 9output 62output formats 100

bidirectional text and 34exporting charts and 46, 47exporting cross tabs and 51exporting data and 28, 30, 31pagination properties and 33

Ppage components 86, 101, 104page counts 102page layouts 57page navigation constants 86page navigation tool 24page numbers 101page position (viewer) 103page ranges 100Parameter class 62, 79parameter components 62, 70, 74, 79parameter convert utility class 87parameter definitions 91parameter global constants 86parameter lists

defining name-value pairs for 91setting autosuggest delays for 82setting column names for 111setting fetch size of 82setting length of 83

parameter maps 88


parameter names 94, 110parameter objects 79, 81, 84parameter pages

changing 81displaying parameters and 64, 79, 82loading 74navigating through 63, 81, 86setting fonts for 83setting HTML container for 83

parameter panels 108parameters

authenticating web services and 59, 71changing 40, 41, 79converting values for 87displaying reports and 60downloading 63, 64, 80getting custom URL 96getting data types for 94getting file names for 80getting values for 88, 94, 95, 110, 111initializing HTTP sessions and 58, 73linking to web services 84localizing 84removing authentication information

and 60retrieving data and 24, 40, 56retrieving from reports 63, 64, 84running reports and 62, 81, 105selecting 83setting properties for 88setting values for 40, 41, 87, 93, 95, 111specifying null values for 95, 111submitting requests for 85, 93unloading 81viewing 63, 64, 79, 82

Parameters command 24, 40Parameters dialog box 40, 41ParameterValue class 93, 110passback variable 56path parameters 9PDF emitter 33PDF formats 28, 33, 100performance parameters 9pie charts 45pipe-separated values files 28, 31pixel values (viewer) 101PostScript emitter 35

PostScript formats 34, 35, 100PowerPoint formats 36, 100.ppt files. See PowerPoint formats.pptx files. See PowerPoint formatsprinting 108privileges 5processParameters function 63prompting for input 24, 40.ps files. See PostScript formatsPSV files 28, 31pyramid charts 44

Rrenaming deployment archives 10renderContent function 82rendering

parameter components 79, 82reports 57, 106

report components 58, 74report design files 62, 84, 106report designs 22, 40report document files 9, 40, 81, 84, 106report elements 29

getting bookmarks for 102, 103loading 58

report emitters 28report executables 62report files 80, 102report parameters 62, 79Reportlets 102, 105reports

counting pages in 102displaying 22, 40, 60, 62, 98downloading 100embedding in web pages 56, 57exporting 100, 107generating 81getting parameters for 79limiting data retrieved for 24linking to 25navigating through 24, 103, 104opening 60printing 108rendering 57, 106retrieving content for 56retrieving parameters from 63, 64, 80, 84

I n d e x 119

retrieving specific pages 100running 41, 105setting locale for 97viewing specific pages 24viewing specific parts of 61

REPOSITORY_CACHE_TIMEOUT_SEC parameter 9

RequestOptions class 58, 71, 96requestOptions parameter 96requests

authenticating 96closing HTTP sessions and 60displaying reports and 61, 108getting options for 72retrieving data and 56retrieving parameters and 63, 64, 85, 93specifying default settings for 58, 59

reserved parameters 58, 59resizing viewers 100, 102, 107resources 59rows 29, 50running reports 62, 105

Ssaving

Excel output 33PDF output 35PostScript output 35PowerPoint output 37Word document files 36

Scalable Vector Graphics 107Scalable Vector Graphics formats 34scatter charts 46scientific data 46script tag 57, 68scrolling 61security 58–60semicolon-separated values files 28, 31series. See data seriesserver errors 76, 86servers 4, 5, 10, 16, 59setAutoSuggestDelay function 82setAutoSuggestFetchSize function 82setAutoSuggestListSize function 83setColumnName function 111setContainer function 83

setContentMarg function 104setCustomParameter function 96setFont function 83setHeight function 104setHelpBase function 104setLocale function 97setName function 92setParameters function 105setParameterValues function 64, 105setReportletBookmark function 61, 105setReportName function

Parameter 63, 84Viewer 60, 106

setService function 84, 106setShowDisplayType function 84setSize function 107setSupportSVG function 107setValue function 92, 95, 111setValueIsNull function 95, 111setWidth function 107sharing reports 24, 28showDownloadReportDialog function 107showFacebookCommentPanel function 108showParameterPanel function 108showPrintDialog function 108SOAP message error descriptions 76source code 56spreadsheet output formats 100spreadsheets 32

See also Excel formatsSSV files 28, 31standards compliance mode 57statistical data 46stock charts 45strings 57, 105subclasses 56submit function

Parameter 63, 85Viewer 60, 108

summary data 50SVG flag 107SVG formats 34system requirements 4

Ttable views 32


tables 28, 29, 62See also cross tabs

tab-separated values files 28, 31target service URL 106TEMP_FOLDER_LOCATION parameter 9temporary files 9, 81testing connections 74testing installations 14text 34time values 30time zones 9Tomcat servers 59toolbars 24totals 44, 51transient files 9, 81TRANSIENT_STORE_PATH parameter 9TSV files 28, 31tube charts 44types. See data types

Uuncategorized exceptions 76URL parameters 58, 71, 84, 96URLs

accessing JavaScript library and 68accessing resources and 59BIRT Viewer Toolkit landing page 14connecting to web services and 106displaying help documentation and 102,

105retrieving parameters and 84returning default web service 72testing connections for 74

usage errors 76, 86user credentials 59, 71userid variable 71UTF8 character encoding 57

Vvalue series (charts) 44

See also data seriesvalueIsNull value 95, 111values

converting 87downloading parameters and 80getting parameter 88, 94, 95, 110, 111

setting display names for 91setting parameter 87, 93, 95, 111specifying null 95, 111

variables 56, 81viewContainer parameter 98viewContainerId parameter 98Viewer class 60, 62, 98viewer components 60, 70, 75, 98viewer event constants 109viewer objects 98Viewer Toolkit. See BIRT Viewer ToolkitViewerException class 112viewers

displaying parameters in 63, 64displaying reports in 60, 62, 98getting browser size for 100, 101getting file names for 102getting margins for 101getting size 102, 103getting specific instance 72, 103handling events for 109handling exceptions for 112instantiating 60loading 60reloading 108resizing 100, 102, 107setting margins for 104setting size 104, 107submitting requests for 108

viewingcross tabs 50data 44report elements 29report parameters 63, 64, 79, 82Reportlets 102, 105reports 22, 24, 40, 60, 62, 98tables 62

WWAR files 8, 10web browser exceptions 76web browser windows 101web browsers 76, 100web pages

accessing class libraries for 56, 68adding JavaScript functions to 57

I n d e x 121

displaying reports in 60, 62, 98embedding report parameters in 62, 63, 64embedding reports in 56, 57enabling SVG support for 107initializing HTTP sessions for 57, 58loading report components for 58, 74retrieving data for 56

web servicesauthenticating users for 58closing connections to 75getting default URL for 72linking parameters to 84opening connections for 56, 57, 73setting URLs for 106

WebLogic servers 4WebSphere servers 4Word document formats 36Word document output formats 100worksheets 32

See also Excel formats

Xx-axis values (charts) 44

Yy-axis values (charts) 44

Using BIRT Viewer Toolkitotadocs.opentext.com/documentation/ManualsBVT/... · 8 Installing BIRT...

Documents

Transcript of Using BIRT Viewer Toolkitotadocs.opentext.com/documentation/ManualsBVT/... · 8 Installing BIRT...