Actuate BIRT Application Developer Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 828

DownloadActuate BIRT Application Developer Guide Application-developer-guide
Open PDF In BrowserView PDF
Actuate BIRT Application Developer Guide

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 - 2014 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
Content Services, BIRT Data Analyzer, BIRT for Statements, BIRT iHub, BIRT Metrics Management, 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, Source Sans Pro font.
Amazon Web Services, Incorporated: Amazon Web Services SDK. Apache Software Foundation (www.apache.org): Ant, Axis,
Axis2, Batik, Batik SVG library, Commons Command Line Interface (CLI), Commons Codec, Commons Lang, Commons Math,
Crimson, Derby, Hive driver for Hadoop, Kafka, log4j, Pluto, POI ooxml and ooxml-schema, Portlet, Shindig, Struts, Thrift,
Tomcat, Velocity, Xalan, Xerces, Xerces2 Java Parser, Xerces-C++ XML Parser, and XML Beans. Daniel Bruce (www.entypo.com):
Entypo Pictogram Suite. Castor (www.castor.org), ExoLab Project (www.exolab.org), and Intalio, Inc. (www.intalio.org): Castor.
Alessandro Colantonio: CONCISE. 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), Jetty, and Eclipse Web Tools Platform (WTP). Dave Gandy: Font Awesome. Gargoyle Software Inc.:
HtmlUnit. GNU Project: GNU Regular Expression. Groovy project (groovy.codehaus.org): Groovy. Guava Libraries: Google
Guava. HighSlide: HighCharts. headjs.com: head.js. Hector Project: Cassandra Thrift, Hector. Jason Hsueth and Kenton Varda
(code.google.com): Protocole Buffer. H2 Database: H2 database. Groovy project (groovy.codehaus.org): Groovy.
IDAutomation.com, Inc.: IDAutomation. IDRsolutions Ltd.: JBIG2. InfoSoft Global (P) Ltd.: FusionCharts, FusionMaps,
FusionWidgets, PowerCharts. Matt Inger (sourceforge.net): Ant-Contrib. Matt Ingenthron, Eric D. Lambert, and Dustin Sallings
(code.google.com): Spymemcached. International Components for Unicode (ICU): ICU library. JCraft, Inc.: JSch. jQuery: jQuery.
Yuri Kanivets (code.google.com): Android Wheel gadget. LEAD Technologies, Inc.: LEADTOOLS. The Legion of the Bouncy
Castle: Bouncy Castle Crypto APIs. Bruno Lowagie and Paulo Soares: iText. MetaStuff: dom4j. Microsoft Corporation (Microsoft
Developer Network): CompoundDocument Library. Mozilla: Mozilla XML Parser. MySQL Americas, Inc.: MySQL Connector.
Netscape Communications Corporation, Inc.: Rhino. nullsoft project: Nullsoft Scriptable Install System. OOPS Consultancy:
XMLTask. OpenSSL Project: OpenSSL. Oracle Corporation: Berkeley DB, Java Advanced Imaging, JAXB, JDK, Jstl, Oracle JDBC
driver. PostgreSQL Global Development Group: pgAdmin, PostgreSQL, PostgreSQL JDBC driver. Progress Software
Corporation: DataDirect Connect XE for JDBC Salesforce, DataDirect JDBC, DataDirect ODBC. Quality Open Software: Simple
Logging Facade for Java (SLF4J), SLF4J API and NOP. Rogue Wave Software, Inc.: Rogue Wave Library SourcePro Core,
tools.h++. Sam Stephenson (prototype.conio.net): prototype.js. Sencha Inc.: Ext JS, Sencha Touch. Shibboleth Consortium:
OpenSAML, Shibboleth Identity Provider. Matteo Spinelli: iscroll. StAX Project (stax.codehaus.org): Streaming API for XML
(StAX). SWFObject Project (code.google.com): SWFObject. ThimbleWare, Inc.: JMemcached. Twittr: Twitter Bootstrap. VMWare:
Hyperic SIGAR. Woodstox Project (woodstox.codehaus.org): Woodstox Fast XML processor (wstx-asl). World Wide Web
Consortium (W3C) (MIT, ERCIM, Keio): Flute, JTidy, Simple API for CSS. XFree86 Project, Inc.: (www.xfree86.org): xvfb. ZXing
Project (code.google.com): ZXing.
All other brand or product names are trademarks or registered trademarks of their respective owners, companies, or
organizations.

Document No. 131215-2-745300 August 29, 2014

Contents
About Actuate BIRT Application Developer Guide . . . . . . . . . . . . . . . . . .xiii

Part 1

Getting started using BIRT Designer Professional
Chapter 1
Planning a BIRT application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Introducing BIRT applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
About BIRT application file structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Accessing BIRT application content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2
Designing and deploying an application . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Overview of the BIRT application design process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Planning the BIRT application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Add content to the BIRT project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Using a BIRT data object to access data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Using a dashboard to display data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Using a BIRT design for custom presentations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Publishing to a server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Editing the landing page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Publishing as a BIRT application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Previewing and testing the BIRT application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Tutorial 1: Building a data object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Task 1: Create a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Task 2: Build a data object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Task 3: Build a data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Task 4: Build a data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Tutorial 2: Building a simple dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Task 1: Create a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Task 2: Add a table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Task 3: Add a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Task 4: Add a data selection gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Designing a landing page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Tutorial 3: Deploy the BIRT application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Task 1: Edit the landing page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Task 2: Deploy the BIRT application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Task 3: Test the URL entry points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

i

Part 2

Designing applications
Chapter 3
Designing a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
About dashboard applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Planning dashboard layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Creating a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Adding a dashboard tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Choosing a dashboard layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Formatting a dashboard tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
Adding data objects to a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Importing an existing dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Saving a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Opening a dashboard file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Adding gadgets to a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Placing a gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Formatting a gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Testing dashboard content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Chapter 4
Displaying a file on a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
About files on a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Displaying BIRT documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Displaying BIRT report items from a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Displaying BIRT parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Displaying parameters in a data selector gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Displaying parameters in a parameter gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Displaying web content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Displaying HTML content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Displaying content from a URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Displaying embedded HTML code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Displaying Adobe Flash content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Displaying images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Displaying Google gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Displaying text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Displaying video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Chapter 5
Visualizing data on a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
About displaying data on a dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Displaying data in a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68

ii

Selecting a chart type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
About area charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
About bar charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
About bubble charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
About column charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
About Gantt charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
About line charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
About pie charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
About radar charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
About scatter charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
About stock charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Selecting data for charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Using category groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Using legend groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Using aggregate expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Formatting charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Choosing a chart theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Enabling chart zoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Enabling a timeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Displaying data in a table or cross tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Choosing a table type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Using a table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Selecting data for tabular display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Aggregating tabular data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Formatting tabular gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Using a cross tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Selecting data for cross tab gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Aggregating cross tab data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Formatting cross tab gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Displaying data in measurement gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Choosing a measurement type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Selecting data for measurement gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Aggregating measurement data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Formatting measurement gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Using regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Changing color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Using pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Enabling data selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Displaying data for user selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Formatting data selection gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Formatting number values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Formatting date-and-time values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

iii

Formatting string values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Using a data version gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Selecting a data object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Choosing a selector type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Formatting a data version gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Organizing multiple user selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Building cascade selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
Building group selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Using a selector group gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Selecting fields to display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Choosing a selector type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Formatting a selector group gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Using an apply button gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Using parameter selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

Chapter 6
Designing a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Formatting features in BIRT Designer Professional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Creating an accessible PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Selecting features for interactive viewing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Interactive scripting sample 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Interactive scripting sample 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Embedding HTML5 content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Removing the default themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Hiding columns in a table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Using a Quick Response code to link to content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Designing for optimal viewer performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122

Part 3

Building application components
Chapter 7
Building interactive maps and gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . 127
About maps and gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Adding a gadget or map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Providing data to a map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Validating map data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Formatting a map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Highlights properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Rendering platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
Adding scripts to a map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137

iv

Writing event handlers that respond to user interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding tooltips to a map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using event handlers before map generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About the map functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting map options through scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using map markers and connection lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting a gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scale properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Needle properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Needle base or pivot properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Number formatting properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Region properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tick properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Threshold properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Anchor properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plot properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Value indicator properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tooltip properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Font properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Padding and margin properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AddOn properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

138
138
140
141
141
144
146
146
149
150
152
154
155
156
158
161
162
164
165
166
166
167

Chapter 8
Building an interactive chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
About interactive charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comparing HTML5 and BIRT charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rendering platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating an interactive chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatting an interactive chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Applying a chart theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a chart theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a general chart theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a JavaScript chart theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding scripts to a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing event handlers that respond to user interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing event handlers that respond to chart events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About the HTML5 chart events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting chart options through scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

v

174
174
174
175
176
177
178
179
180
182
184
186
186
187
189
190
193

Chapter 9
Building a template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
About report templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
Design considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
Separating or combining visual and data elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
Designing themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
Improving usability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
Creating a report template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
Providing data with a report template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Using a CSV file as a data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
Excluding a data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Creating themes for a report template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Publishing a template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Setting the default template category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206

Part 4

Enhancing application components
Chapter 10
Writing expressions using EasyScript . . . . . . . . . . . . . . . . . . . . . . . . . . 211
About EasyScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
Choosing between EasyScript and JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
Syntax rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
Using the EasyScript expression builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
Changing the default expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214

Chapter 11
Adding web interactivity to a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
About HTML buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Creating an HTML button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Writing code for an HTML button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Accessing report data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Using the Actuate JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
Testing an HTML button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
Changing the appearance of an HTML button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225

Chapter 12
Implementing data security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
About the security model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
About access control lists and security IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
ACL expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231

vi

Controlling user access to report pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding page-level security to a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling and disabling page-level security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring page numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing page-level security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling user access to data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding security to a data object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding security to a data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding security to a cube . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling and disabling data security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing data security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

231
235
238
239
240
241
241
241
246
250
250

Chapter 13
Linking and scripting gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
About linking gadgets together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building gadget links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Understanding automatic linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a field to receive link data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scripting linked gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using JavaScript objects to retrieve values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying values in a JavaScript console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying values in Internet Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying selected values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using linked values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading and writing parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

254
255
255
256
257
259
261
261
263
263
264

Chapter 14
Building Google gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
About Google gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Google gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About gadget views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About gadget features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Flash feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the minimessage feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the pubsub feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the tabs feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking Google gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking an import gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking multiple Google gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking Google gadgets together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking public Google gadgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

vii

266
266
267
268
269
269
270
270
271
271
272
274
275

Part 5

Using Actuate JavaScript API in an application
Chapter 15
Creating dynamic report content using
the Actuate JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
About Actuate JavaScript API scripting in a BIRT report design . . . . . . . . . . . . . . . . . . . . . . . . . 280
Using the Actuate JavaScript API in an HTML button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Tutorial 4: Adding scripted chart controls to a BIRT design . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Task 1: Add HTML buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .282
Task 2: Script the chart sub_type controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Task 3: Script the chart size controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
Task 4: Test the scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
Tutorial 5: Using HTML buttons to apply filters to a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Task 1: Add a filter button to the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
Task 2: Add HTML buttons for the remaining product lines . . . . . . . . . . . . . . . . . . . . . . . . .289
Task 3: Add the final HTML button to the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
Task 4: Test the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Using the Actuate JavaScript API in chart interactive features . . . . . . . . . . . . . . . . . . . . . . . . . .293
Tutorial 6: Adding an interactive chart filter to a BIRT report . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Task 1: Add bookmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
Task 2: Add a filter script to chart interactivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299
Using the Actuate JavaScript API in chart themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300
Tutorial 7: Adding scripted HTML5 Chart controls to a BIRT design . . . . . . . . . . . . . . . . . . . . 301
Task 1: Adding HTML buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Task 2: Scripting the client chart controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .303
Task 3: Scripting the client option controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304
Task 4: Testing the scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Chapter 16
Working with Interactive Crosstabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
About cross tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Tutorial 8: Viewing and pivoting a cross tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
About cubes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Handling Interactive Crosstabs viewer events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Working with dimensions, measures, and levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Adding a dimension with levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Removing a dimension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Adding and removing measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
Changing measures and dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
Working with totals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315
Sorting and filtering cross tab data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

viii

Drilling down within a cross tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Controlling the Interactive Crosstabs viewer user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Chapter 17
Actuate JavaScript API classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Actuate JavaScript API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About the actuate namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Actuate library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Actuate JavaScript API classes quick reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Actuate JavaScript API reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.AuthenticationException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.ConnectionException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.dashboard.DashboardDefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.dashboard.EventConstants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.dashboard.GadgetScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.dashboard.Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.data.Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.data.ReportContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.data.Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.data.ResultSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.data.Sorter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.DataService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.parameter.Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.parameter.ConvertUtility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.parameter.EventConstants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.parameter.NameValuePair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.parameter.ParameterData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.parameter.ParameterDefinition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.parameter.ParameterValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.DataItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.FlashObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.Gadget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.HTML5Chart.ClientChart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.HTML5Chart.ClientOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.HTML5Chart.ClientPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.HTML5Chart.ClientSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.HTML5Chart.Highcharts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.report.HTML5Chart.Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ix

322
322
322
322
325
326
333
335
336
346
347
348
351
353
358
359
364
366
369
371
374
385
386
389
390
392
400
416
424
432
436
440
445
452
456
459
464
465

Class actuate.report.Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .471
Class actuate.report.Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .475
Class actuate.report.TextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .483
Class actuate.ReportExplorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .487
Class actuate.reportexplorer.Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .494
Class actuate.reportexplorer.EventConstants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .495
Class actuate.reportexplorer.File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .496
Class actuate.reportexplorer.FileCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Class actuate.reportexplorer.FileSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Class actuate.reportexplorer.FolderItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .514
Class actuate.reportexplorer.PrivilegeFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Class actuate.RequestOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Class actuate.Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Class actuate.viewer.BrowserPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .546
Class actuate.viewer.EventConstants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
Class actuate.viewer.PageContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
Class actuate.viewer.ParameterValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Class actuate.viewer.RenderOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
Class actuate.viewer.ScrollPanel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .556
Class actuate.viewer.SelectedContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .558
Class actuate.viewer.UIConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Class actuate.viewer.UIOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .562
Class actuate.viewer.ViewerException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .576

Chapter 18
BIRT Interactive Crosstabs API classes . . . . . . . . . . . . . . . . . . . . . . . . . 579
About the BIRT Interactive Crosstabs JavaScript API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .580
Interactive Crosstabs API reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .581
Interactive Crosstabs JavaScript classes quick reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .583
Class actuate.XTabAnalyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
Class actuate.xtabanalyzer.Crosstab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .601
Class actuate.xtabanalyzer.Dimension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .615
Class actuate.xtabanalyzer.Driller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Class actuate.xtabanalyzer.EventConstants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
Class actuate.xtabanalyzer.Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Class actuate.xtabanalyzer.Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .628
Class actuate.xtabanalyzer.GrandTotal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .635
Class actuate.xtabanalyzer.Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .638
Class actuate.xtabanalyzer.LevelAttribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
Class actuate.xtabanalyzer.Measure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .642
Class actuate.xtabanalyzer.MemberValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .647
Class actuate.xtabanalyzer.Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .650
Class actuate.xtabanalyzer.PageContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657

x

Class actuate.xtabanalyzer.ParameterValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.xtabanalyzer.Sorter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.xtabanalyzer.SubTotal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.xtabanalyzer.Total . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Class actuate.xtabanalyzer.UIOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

659
662
666
670
674

Part 6

Deploying applications
Chapter 19
Deploying and sharing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
About deploying and sharing applications and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing the landing page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sharing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sharing project files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Publishing a resource file to iHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Downloading files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploying Java classes used in BIRT reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing a custom JDBC driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing custom ODA drivers and custom plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

682
684
687
690
691
694
695
697
699
699

Chapter 20
Working with BIRT encryption in iHub . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
About BIRT encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About the BIRT default encryption plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About supported encryption algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About the components of the BIRT default encryption plug-in . . . . . . . . . . . . . . . . . . . . . . .
About acdefaultsecurity.jar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About encryption.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About META-INF/MANIFEST.MF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About plugin.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a BIRT report that uses the default encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploying multiple encryption plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploying encryption plug-ins to iHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating encryption keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a custom encryption plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using encryption API methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

702
702
703
703
703
704
706
706
707
709
712
713
715
715

Chapter 21
Configuring data source connections in iHub . . . . . . . . . . . . . . . . . . . . 717
About data source connection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718

xi

Using a connection profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .718
Creating a connection profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .718
Managing a connection profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .726
Exporting connection profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .726
Importing connection profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .727
Editing connection profile properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .728
Deploying a connection profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .729
Encrypting connection profile properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .730
Binding connection profile properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
Binding the Connection Profile Store URL property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Binding a connection profile name to a report parameter . . . . . . . . . . . . . . . . . . . . . . . . . .732
Accessing BIRT report design and BIRT resource path in custom ODA plug-ins . . . . . . . . . . . 737
Accessing resource identifiers in the run-time ODA driver . . . . . . . . . . . . . . . . . . . . . . . . . . .737
Accessing resource identifiers in the design ODA driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . .738

Chapter 22
Using custom emitters in iHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
About custom emitters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .742
Deploying custom emitters to iHub and BIRT Visualization Platform . . . . . . . . . . . . . . . . . . . .743
Rendering in custom formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .744
Configuring the default export options for a BIRT report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751

xii

About Ac tu ate BI RT
Application D ev el o p e r
Guide

Actuate BIRT Application Developer Guide provides information about using the
Actuate BIRT Designer Professional report design tool. This material explains
how to design, configure, customize, and deploy applications, gadgets, and
reports.
■

About Actuate BIRT Application Developer Guide. This chapter provides an
overview of this guide.

■

Part 1. Getting started using BIRT Designer Professional. This part describes the
tasks that users complete to design a BIRT application.

■

Chapter 1. Planning a BIRT application. This chapter introduces BIRT
applications, their file structure and how to access the content once you have
deployed the application.

■

Chapter 2. Designing and deploying an application. This chapter describes how to
how to build a BIRT application for use in web pages and includes a tutorial to
demonstrate the process.

■

Part 2. Designing applications. This part describes the tasks necessary to build a
BIRT application using dashboards and reports.

■

Chapter 3. Designing a dashboard. This chapter explains how to personalize the
layout of a dashboard

■

Chapter 4. Displaying a file on a dashboard. This chapter explains how to display
files such as BIRT documents and web content such as images, videos and web
pages on a dashboard.

■

Chapter 5. Visualizing data on a dashboard. This chapter explains how to display
data using visualizations such as charts, gadgets, tables and cross tabs.

About Actuate BIRT Application Developer Guide

xiii

xiv

■

Chapter 6. Designing a report. This chapter describes how to format BIRT reports
and documents.

■

Part 3. Building application components. This part describes how to use BIRT
Designer Professional to add interactive components to a BIRT application.

■

Chapter 7. Building interactive maps and gadgets. This chapter explains how to
visualize data in maps and measurement gadgets using BIRT Designer
Professional.

■

Chapter 8. Building an interactive chart. This chapter describes the requirements
and methods for adding interactive charts with BIRT Designer Professional.

■

Chapter 9. Building a template. This chapter describes how to build templates of
BIRT designs using BIRT Designer Professional.

■

Part 4. Enhancing application components. This part describes the tasks that can
enhance BIRT application data using interactivity, scripts, and security.

■

Chapter 10. Writing expressions using EasyScript. This chapter describes how to
write expressions using EasyScript, which is an expression syntax similar to
the syntax used in Excel formulas. The chapter also provides a reference to the
EasyScript functions and operators.

■

Chapter 11. Adding web interactivity to a report. This chapter describes how to
use HTML buttons to run JavaScript code.

■

Chapter 12. Implementing data security. This chapter describes how to use the
page-level security and data security features in Actuate iHub to control user
access to particular sections in a report and a particular set of data in a data
object.

■

Chapter 13. Linking and scripting gadgets. This chapter provides information
about linking and scripting gadgets on a dashboard.

■

Chapter 14. Building Google gadgets. This chapter provides information about
building Google gadgets for use with BIRT dashboards.

■

Part 5. Using Actuate JavaScript API in an application. This part describes how a
report developer uses Actuate JavaScript API to enhance report interactivity
and data presentation.

■

Chapter 15. Creating dynamic report content using the Actuate JavaScript API. This
chapter describes using Actuate JavaScript API code in a BIRT report.

■

Chapter 16. Working with Interactive Crosstabs. This chapter describes how to use
Actuate JavaScript API code to access and manipulate Interactive Crosstabs.

■

Chapter 17. Actuate JavaScript API classes. This chapter lists all of the standard
Actuate JavaScript API classes and their methods.

■

Chapter 18. BIRT Interactive Crosstabs API classes. This chapter lists all of the
cross tab classes and their methods.

Actuate BIRT Application Developer Guide

■

Part 6. Deploying applications. This part describes the tasks that an application
developer completes to deploy applications and configuration components,
such as data connections and encryption required by those applications.

■

Chapter 19. Deploying and sharing applications. This chapter explains the
different options for sharing dashboard and report files and describes how to
run and distribute BIRT applications to an Actuate iHub.

■

Chapter 20. Working with BIRT encryption in iHub. This chapter describes the
extension framework that supports users registering their own encryption
strategy with BIRT and how to deploy custom encryption to BIRT iHub.

■

Chapter 21. Configuring data source connections in iHub. This chapter describes
how to set up and use a data source configuration file using BIRT iHub.

■

Chapter 22. Using custom emitters in iHub. This chapter describes how to
provide custom output formats for BIRT reports on BIRT iHub.

About Actuate BIRT Application Developer Guide

xv

xvi

Actuate BIRT Application Developer Guide

Part

One

1

Getting started using
BIRT Designer Professional
Part 1

Chapter

1
Planning a BIRT
application

Chapter 1

This chapter contains the following topics:
■

Introducing BIRT applications

■

About BIRT application file structure

■

Accessing BIRT application content

Chapter 1, Planning a BIRT application

3

Introducing BIRT applications
A BIRT application is a self-contained package that includes all the files and data
of a BIRT project. This package enables developers to quickly deploy secure and
interactive applications to an iHub server or cloud instance. After deployment,
the application is accessible from a web browser and includes an HTML landing
page to describe or navigate the application files.
When a project is published as a BIRT application, developers can offer uniform
resource locator (URL) entry points to the content of the application using a
unique URL for each BIRT or dashboard file in the project. These URLs can also
link the application content together, such as drill down reports or hyperlinks to
additional content.
Developers use BIRT Designer Professional to build and preview all components
of the application before deployment such as data objects, data stores,
dashboards, BIRT design and document files, BIRT libraries, HTML files,
JavaScript libraries, and other standard web content. All of these components
work together in a relational structure.
For example, the landing page of a BIRT application can contain a description and
URL link to a dashboard file in the BIRT application. The dashboard can display
BIRT documents or display charts from BIRT data objects that are stored in the
BIRT application.

About BIRT application file structure
Each BIRT application is stored in its own project folder in the developer’s
workspace. This folder includes all the BIRT files and BIRT data objects necessary
to view the application. Table 1-1 lists the files required to deploy a BIRT project
as a BIRT application. These files exist in the root of BIRT project.
Table 1-1

BIRT application files

File name

File use

Description

.project

Project
description file

An XML file used by BIRT Designer Professional
to describe a project and the resources it needs.

BIRTApplication.xml

Application
definition file

An XML file containing the application name and
access permissions

index.html

Application
landing page

An HTML file to store a description of the
application, embed content from the application
using Actuate JSAPI, or to list and navigate to files
in the application.

4

Actuate BIRT Application Developer Guide

You can organize files in the BIRT application using folders. Use the following
predefined folder structure to enable URL access to the files in the application:
■

Dashboards folder

■

Data Objects folder

■

Report Designs folder

■

Report Libraries folder

■

Report Templates folder

■

BIRTApplication.xml

■

Index.html

■

.project

Each BIRT application is self-contained and is stored inside an iHub volume in
the Applications folder. You cannot reuse content from a BIRT application outside
the application it is stored in.
For example, you add a dashboard gadget file to the Dashboards folder of a BIRT
application. You can use this gadget file in a dashboard that is in the same BIRT
application. If you want to use the same gadget file in a different application,
upload or copy the gadget file and any resources it requires, such as a data object,
to a location inside the new application folder.
The iHub administrator can hide the Application folder from view. When hidden,
the Application folder is not visible to users of Visualization Platform but users
can still use the URL to view the contents of a BIRT application.

Accessing BIRT application content
Each BIRT application supports multiple entry points depending on the files
included in the BIRT application. Each entry point is a URL that gives users access
to a file in the BIRT application. Table 1-2 lists the URL conventions supported
when a BIRT application is deployed.
Table 1-2

URL conventions

URL address

Opens file in the BIRT application

/apps//

index.html

/apps//report

index.rptdesign

/apps//dashboard

index.dashboard

/apps///

the selected file in the selected folder

Chapter 1, Planning a BIRT application

5

Each URL starts with the URL of Visualization Platform.
http://:/iportal/

For example, to open the index.html file in the BIRT application use the URL:
http://:/iportal/apps//
■

 is the name or IP address of the web server hosting the Visualization
Platform web application.

■

 is the TCP port assigned to the Visualization Platform web application.

■

/ is the name of the BIRT application. The / after the application
name is required.

To open a file in the BIRT application use the following URL:
http://:/iportal/apps/// is the name of the folder or folders where the selected file is located.
No folder name is necessary if the file is in the BIRT application root.

■

 is the name of the file to open or download.

Table 1-3 lists the actions triggered when opening a file in a BIRT application.
Other file types are opened in the web browser as downloaded files.
Table 1-3

6

File type actions

File extension

File type

Action

.rptdesign

BIRT design

File is run and results open in BIRT Viewer

.rptdocument

BIRT document

Opens in BIRT Viewer

.dashboard

BIRT dashboard

Opens as a dashboard

Actuate BIRT Application Developer Guide

Chapter

2
Designing and deploying
an application

Chapter 2

This chapter contains the following topics:
■

Overview of the BIRT application design process

■

Designing a landing page

Chapter 2, Designing and deploying an application

7

Overview of the BIRT application design process
Designing a BIRT application involves the following tasks. You do not have to
perform all the tasks in the order in which they are presented here, but if you are
new to designing BIRT data objects and dashboards in BIRT Designer
Professional, you can use the following task list as a starting point:
■

Plan the application.

■

Add content to the project.

■

■

Add a BIRT data object.

■

Add a dashboard.

■

Add a BIRT design.

Publish to a server.
■

Edit the landing page.

■

Publish as a BIRT application.

■

Preview and test the BIRT application.

For more information about starting BIRT Designer Professional, navigating the
interface, and how to create a BIRT report, see BIRT: A Field Guide.

Planning the BIRT application
Before creating a BIRT application, identify the information and files that you
want the application to provide and decide how a user should navigate this
content. Your application enables users to visualize and interact with data sources
using various components such as BIRT designs, dashboards, and web pages.
These components are linked together using hyperlinks.

Add content to the BIRT project
You can add static files such as a PDF or an image file or dynamic files such as a
BIRT data object, dashboard or report design file. These files are stored in your
BIRT Designer Professional project folder until you publish them to an iHub
server. Once you publish the project as a BIRT application, you can access the
application’s HTML landing page or any of the files using URLs.

Using a BIRT data object to access data
After creating a new project to organize your application components you create
a BIRT data object to access your data source. The BIRT data object can access data
from a wide variety of sources, including databases, text files, XML documents,

8

Actuate BIRT Application Developer Guide

and web services. Dashboards and BIRT designs display interactive
visualizations of this data, such as charts and tables.

Using a dashboard to display data
There are many ways to present data with a dashboard. A dashboard uses
gadgets to display information such as a tabular list, a cross tab, a bar chart, a web
page. These different gadgets can link together to enable data searches and
display of external web services.
Different gadgets support features, such as zooming into chart data, timeline
selection in charts, cross tab analysis with Interactive Crosstabs, and interactive
table usage. Laying out a dashboard requires you to organize these gadgets in a
way that helps the user to understand and analyze the information.

Using a BIRT design for custom presentations
BIRT design files include scripting and layout options that are not available in a
dashboard. You can also use additional content such as HTML5 maps, using
HTML5 tags and advanced layout options such as a grid in a BIRT design. These
designs can contain multiple pages that can use include a table of contents. Users
can export the design file to multiple formats such as Adobe PDF, Microsoft
Excel, and Microsoft Word. Advanced parameter choices enable users to request
specific information in their report and developers to link multiple design files
together.

Publishing to a server
Publishing a BIRT applications make it accessible to a large number of users. A
published application is available to manage, meaning you can schedule data
object or BIRT design update its content from the data source. Use permissions to
limit user access to application content and data. When you publish a BIRT
application, the contents of the previous application are overwritten so all the
previous content is replaced.

Editing the landing page
Each BIRT application can include a landing page written in HTML. This landing
page is accessible using a URL and contains information about your project, such
as a description of the BIRT application, hyperlinks to the application content,
online help and BIRT content embedded using the Actuate JavaScript API.

Publishing as a BIRT application
Publishing the BIRT project as an application requires you to select the project,
select the server and choose publish.

Chapter 2, Designing and deploying an application

9

Previewing and testing the BIRT application
It is important to preview and test your BIRT application as you design it and
after you deploy it. Verify that the data retrieved from the data source is what you
expect. As you lay out and format the dashboard, confirm the visualization
throughout the design process. If you add code, test and debug it as you go. After
you deploy the BIRT application, verify the URL hyperlinks to the landing and to
any other content work as expected.

Tutorial 1:

Building a data object

This section provides step-by-step instructions for building a BIRT data design
file that contains customer and order data. The data object uses data from the
sample database that is supplied with BIRT Report Designer Professional,
Classic Models, Inc. This data object is used to build visualizations on a
dashboard.
In this tutorial, you perform the following tasks:
■

Create a project.

■

Build a data object.

■

Build a data set.

■

Build a data model.

Task 1:

Create a project

BIRT Report Designer Professional organizes files by projects. You can create one
project to organize all your reports or create multiple projects to organize your
reports by categories. For each project that you create, BIRT Report Designer
Professional creates a folder in your computer’s file system and adds default
content such as a BIRTApplication.xml file and an HTML landing page. The
contents of this project become the BIRT Application.
1 Choose File➛New➛Project. New Project, which appears in Figure 2-1,
displays the types of projects that you can create.
2 If necessary, expand Actuate BIRT, select BIRT Project, then choose Next.
3 In New BIRT Project, select Blank Project. In Project name, type the following
text, as shown in Figure 2-2:
My Application

4 To create the project, choose Finish. You can now see the project in the
Navigator view, as shown in Figure 2-3.

10

Actuate BIRT Application Developer Guide

Figure 2-1

New Project

Figure 2-2

New Blank Project

Figure 2-3

A project in the Navigator view

Task 2:

Build a data object

You typically use one or more data objects in your BIRT designs and dashboards.
The data object contains information to connect to a database or other type of data
source. This information typically contains a driver class, data source name, and
other connection information that is specific to the type of data source.

Chapter 2, Designing and deploying an application

11

For this tutorial, you use the sample database, Classic Models, that is already
configured for use with BIRT Report Designer. You do not need to specify the
connection information for this sample database.
1 Choose File➛New➛Data Object. New Data Object, displays possible locations
for your new data object.
2 In File name, type the following text, as shown in Figure 2-4:
OrderData.datadesign

Figure 2-4

New data object design

3 To add the data object to the project, choose Finish. You can now see the data
object in the Navigator view, as shown in Figure 2-5.

Figure 2-5

A data object in the Navigator view

4 Select the OrderData.datadesign file in the Navigator view. Choose Data
Explorer. If you use the default report design perspective, Data Explorer is to
the left of the layout editor, next to Palette, as shown in Figure 2-6. If Data
Explorer is not open, choose Window➛Show View➛Data Explorer.

Figure 2-6

12

Data Explorer

Actuate BIRT Application Developer Guide

5 Right-click Data Sources, then choose New Data Source from the context
menu. New Data Source displays the types of data sources you can create, as
shown in Figure 2-7.

Figure 2-7

New Data Source

6 Select Classic Models Inc. Sample Database from the list of data sources. Use
the default data source name, then choose Next. Connection information
about the new data source appears.
7 Choose Finish. BIRT Report Designer Professional creates a new data source
that connects to the sample database. It appears within Data Sources in Data
Explorer, shown in Figure 2-8.

Figure 2-8

Data Sources in Data Explorer

8 Choose File➛Save to save your changes.

Chapter 2, Designing and deploying an application

13

Task 3:

Build a data set

Now, you are ready to build your data set. A data set identifies the data to retrieve
from the data source. If your report connects to a JDBC data source, such as the
sample database, you use a SQL SELECT statement to specify the data to retrieve.
1 In Data Explorer, right-click Data Sets, and choose New Data Set from the
context menu.
2 In New Data Set, in Data Set Name, type the following text, as shown in
Figure 2-9:
Orders

Figure 2-9

New Data Set

Use the default values for the other fields.
■

Data Source Selection shows the type and name of the data source that you
created earlier.

■

Data Set Type indicates that the data set uses a SQL SELECT query.

3 Choose Next.
The Query page displays information to help you create a SQL query.
Available Items lists all the schemas in the data source, including
CLASSICMODELS, which you use for this tutorial. You can click the plus (+)
sign next to CLASSICMODELS to display the data tables. The text area on the

14

Actuate BIRT Application Developer Guide

right side of this dialog shows the following required keywords of a SQL
SELECT statement:
select
from

4 In the text area, type the following SQL SELECT statement to specify the data
to retrieve:
select *
from CLASSICMODELS.ORDERS

The SELECT statement that you created, which is shown in Figure 2-10,
retrieves all of the columns of data in the ORDERS table.

Figure 2-10

SQL SELECT statement in Edit Data Set

5 Choose Finish to save the data set. If you typed the query correctly, Edit Data
Set appears. If you made a mistake, an error message appears before Edit
Data Set opens. Edit Data Set displays the columns you specified in the query,
and provides options for editing the data set.

Chapter 2, Designing and deploying an application

15

6 Choose Preview Results to make sure the query is valid and that it returns
the correct data. Figure 2-11 shows some of the data rows that the query
returns.

Figure 2-11

Data rows returned by a SQL SELECT statement

7 Choose OK. BIRT Report Designer Professional creates a new data set that
connects to the sample database. It appears within Data Sets in Data Explorer,
shown in Figure 2-12.

Figure 2-12

Data Sets in Data Explorer

8 Repeat the previous steps to make a second data set with the following values:
■

The Data Set name is:
Customers

■

The SQL SELECT statement:
select *
from CLASSICMODELS.CUSTOMERS

The new data set appears within Data Sets in Data Explorer, shown in
Figure 2-13. You can click the plus (+) sign next to the Customers data set to
display the available data columns.

16

Actuate BIRT Application Developer Guide

Figure 2-13

Additional Data Set in Data Explorer

9 Choose File➛Save to save your changes.

Task 4:

Build a data model

Now, you are ready to build your data model. A data model joins data sets and
enables users to aggregate data for summarizing information. Once you have
added the data model you will generate a data object store in the BIRT application
that contains the data taken from the data source. This file is bigger than the data
object design file because it contains the data from the data source.
Use the data object file to avoid making additional queries to a data source and to
enable use of the BIRT application content without accessing the original data
source. You can use the data object design file but each use will make a new query
to the data source.
1 In Data Explorer, right-click Data Models and Data Cubes, and choose New
Data Model from the context menu. Data Model appears showing the
available data set tables and column names, as shown in Figure 2-14.

Figure 2-14

New Data Model

Chapter 2, Designing and deploying an application

17

2 In OrdersData.datadesign, in Data Model, choose Auto Join to search the
two data sets for possible column names to join the data.
3 In Column Link Selector, select Orders.CUSTOMERNUMBER <-> Customers
.CUSTOMERNUMBER to join the orders data set and the customers data set
using the column name CUSTOMERNUMBER, as shown in Figure 2-15.

Figure 2-15

New data set join using the selected columns

4 Choose OK to link the two data sets together. Figure 2-16 shows the updated
data model.

Figure 2-16

Verifying the layout of the data model

5 Choose File➛Save to save your changes.
The new data model appears within Data Models and Data Cubes in Data
Explorer, as shown in Figure 2-17.

18

Actuate BIRT Application Developer Guide

Figure 2-17

Data Model in Data Explorer

6 In the Navigator view, right-click OrderData.datadesign and choose Generate
Data Objects from the context menu.
7 In Generate Data Objects, choose OK to accept the data file name and generate
a data object, as shown in Figure 2-18.

Figure 2-18

Generating a data object

You can now see the new data object in the Navigator view, as shown in
Figure 2-19.

Figure 2-19

Tutorial 2:

A data object in the Navigator view

Building a simple dashboard

This section provides step-by-step instructions for building a dashboard to
display data from the data object you finished in the previous tutorial. In this
tutorial, you perform the following tasks:
■

Create a dashboard.

■

Add a table.

Chapter 2, Designing and deploying an application

19

■

Add a chart.

■

Add a data selection gadget.

Task 1:

Create a dashboard

1 Choose File➛New➛Dashboard. New Dashboard displays possible locations
for the dashboard.
2 In File name, type the following text, as shown in Figure 2-20:
CustomerOrders.dashboard

Figure 2-20

New dashboard

3 To add the dashboard to the project, choose Finish. The dashboard editor
appears, as shown in Figure 2-21. If you configured BIRT Designer
Professional to use an external web browser to display reports and
dashboards, the dashboard editor appears in your selected web browser.

Figure 2-21

Dashboard editor

Choose Data➛Manage Data. The available data objects in your project are
displayed, as shown in Figure 2-22.

20

Actuate BIRT Application Developer Guide

Figure 2-22

Available data objects

Select OrderData.data and choose Add to use this data object in the
dashboard. The selected data object appears in Selected Data, as shown in
Figure 2-23.

Figure 2-23

Selected data objects

4 Choose OK to close Manage Data.
5 Choose File➛Save to save your latest changes to the dashboard file.

Task 2:

Add a table

Now that the dashboard is created and data is assigned to it, you can choose
gadgets to display the data. When you choose a table gadget, data is either listed
row by row or summarized in groups. For this tutorial we use a summary table to
provide an overview of the data.
1 Choose Insert➛Table➛Table to open the Table Builder.
2 In Available Data, select Customers➛COUNTRY, and choose Add to add it to
Current Column Selections.

Chapter 2, Designing and deploying an application

21

3 In Available Data, select Orders➛ORDERDATE, and choose Add to add it to
Current Column Selections. In Date Value, select Years.
In Available Data, select Orders➛ORDERNUMBER, and choose Add to add it
to Current Measure Selections. In Sum, select Count. Figure 2-24 shows table
builder after these changes.

Figure 2-24

Building a table

Choose OK to add the table to the dashboard. The table appears on the
dashboard, as shown in Figure 2-25.

Figure 2-25

22

New table gadget

Actuate BIRT Application Developer Guide

4 Choose File➛Save to save your latest changes to the dashboard file.

Task 3:

Add a chart

Charts help users quickly visualize data. You can choose the chart that best
presents your data and enable interactive features such as drill down, zoom and
time selection. You can also filter and format data presented in your chart. In this
tutorial we are using a pie chart to display data.
1 Choose Insert➛Chart➛Pie Chart to open the chart builder.
2 In Slice—Category, select Orders➛ORDERDATE. In Slice—Time Interval,
select Years.
3 In Value—Select Value, select Orders➛ORDERNUMBER. In
Value—Aggregate Expression, select Count. Figure 2-26 shows Chart Builder
after these changes.

Figure 2-26

Building a chart

4 Choose Format.
5 Expand Legend and select Show Legend. In Position, select Below, as shown
in Figure 2-27.
Choose OK to add the chart to the dashboard. The chart appears on the
dashboard, as shown in Figure 2-28.

Chapter 2, Designing and deploying an application

23

Figure 2-27

Displaying a legend

Figure 2-28

New chart gadget

6 Choose File➛Save to save your latest changes to the dashboard file.

Task 4:

Add a data selection gadget

Use a data selection gadget such as a list to enable users to search for data on a
dashboard. One or more gadgets can link to the data selection so that a single user
selection can update multiple charts and tables on the dashboard. In this tutorial
we add a list of countries for a user to select. After the user selects a country, the
other gadgets update and display data about the selected country.
1 Choose Insert➛Data Selector➛List to open the Data Selector Gadget Wizard.
2 In Field, choose Customers➛COUNTRY, as shown in Figure 2-29.

24

Actuate BIRT Application Developer Guide

Figure 2-29

Building a data selector

3 Choose Format and select Enable Search, as shown in Figure 2-30.

Figure 2-30

Enabling user search

Choose OK to add the list of countries to the dashboard. The list appears on
the dashboard, as shown in Figure 2-31.

Figure 2-31

New list gadget

4 Click on the Pie Chart title. Drag the chart and drop it to the right side of the
list gadget.
5 Resize the bottom of the chart gadget so that it matches the bottom of the table
gadget.
6 In the COUNTRY list, choose Canada. Your dashboard should look similar to
Figure 2-32.

Chapter 2, Designing and deploying an application

25

Figure 2-32

Using a list to filter data

7 Choose File➛Save to save your latest changes to the dashboard file.
8 Close the dashboard editor. You can now see the dashboard in the Navigator
view, as shown in Figure 2-33.

Figure 2-33

A data object in the Navigator view

Designing a landing page
BIRT Designer Professional creates an index.html page with every BIRT project.
This file displays in a web browser when the project is deployed as an application
on iHub. The default URL for a BIRT application includes the project name, as
shown below:
http://host:port/iportal/apps/appname/

26

Actuate BIRT Application Developer Guide

■

host is the name of the application or web host running BIRT Services.

■

port is the Actuate application services port set in the application or web
server.

■

iportal is the default context root for Actuate application services. if you have
a custom context root, use that in place of iportal.

■

apps is the application directory in the BIRT iHub repository.

■

appname is the name of you project as it is packaged for BIRT iHub. Set the
appname by changing the Application Name attribute in BIRTApplication.xml
before deploying the application to iHub.

The landing page is an HTML page.

Tutorial 3:

Deploy the BIRT application

This section provides step-by-step instructions for editing a BIRT application
landing page and deploying the finished BIRT application to a server.
In this tutorial, you perform the following tasks:
■

Edit the landing page.

■

Deploy the BIRT application.

■

Test the URL entry points.

Task 1:

Edit the landing page

1 In Navigator, expand your project and open index.html. Index.html appears in
the editor with the Project Name as an H1 title, as shown in as shown in
Figure 2-34.

Figure 2-34

Viewing the default H1 title in index.html

2 Type the following text under the first line.
This application contains the following content:


Chapter 2, Designing and deploying an application

27

3 Choose File➛Save to save your latest changes to the landing page.

Task 2:

Deploy the BIRT application

Now that you have added data and visualizations to your BIRT project, you can
deploy the entire project as a BIRT application to an iHub server. After the BIRT
application is deployed, users can access the content using URLs to the landing
page or to the files included in the BIRT application.
1 In BIRT Report Designer Professional, open Server Explorer. If you do not see
the Server Explorer view in the designer, select Windows➛Show view
➛Server Explorer.
2 In Server Explorer, right-click Servers, and choose New Server Profile, as
shown in Figure 2-35.

Figure 2-35

Adding a new server profile

3 In New Server Profile, specify the connection information. Figure 2-36
displays an example of connection properties provided for a server named
localhost that is installed on the same computer as BIRT Designer Professional.

Figure 2-36

Setting properties in a new Server profile

1 In Profile type, select Server.
2 In Profile name, type a unique name that identifies the new profile.

28

Actuate BIRT Application Developer Guide

3 In Server, type the name or IP address of the BIRT iServer server.
4 In Port number, type the port number to access BIRT iServer.
5 In Volume, select the iHub Encyclopedia volume if multiple volumes exist.
6 In User name, type the user name required to access the volume.
7 In Password, type the password required to access the volume.
8 Select Remember Password, if you want to save the password.
4 Choose Finish to save the Server profile. The Server profile appears in the
Server Explorer. You can expand the server profile to see the content of the
volume, as shown in Figure 2-37.

Figure 2-37

Expanding a server profile

5 Select the My Application project in Navigator, as shown in Figure 2-38.

Figure 2-38

Selecting a BIRT project to publish as an application

6 Choose File—Publish. In Publish, select Publish Project if it is not already
selected.
7 Select a server profile and choose Publish. Figure 2-39 shows the BIRT
application named My Application set to publish to the server profile Server 1.

Figure 2-39

Selecting a server profile to publish to

Chapter 2, Designing and deploying an application

29

8 After all items have been published choose OK. Figure 2-40 shows that all files
were successfully published.

Figure 2-40

Verifying all items were published

9 Choose Close to return to BIRT Designer Professional.

Task 3:

Test the URL entry points

BIRT applications include a URL for the landing page and additional URLs for
each file included in the BIRT application. For more information about URLs that
can access your BIRT application content, see Chapter 1, “Planning a BIRT
application.”
1 Verify that the application’s landing page is accessible by using a web browser
to visit the URL of the application. For example, the server name in this
tutorial is localhost so the URL to the application is the following:
http://localhost:8700/iportal/apps/My Application/

If you are asked to log in to the iHub Visualization Platform, type your user
name and password. Your landing page should look similar to Figure 2-41.

Figure 2-41

Visiting the landing page

2 Verify that URL links displayed in the landing page function as expected.
3 Verify that the content in the application is accessible. This tutorial includes
one dashboard file named CustomerOrders.dashboard in the folder named
Dashboards. If the server name was localhost, then the URL to the dashboard
is the following:
http://localhost:8700/iportal/apps/My Application/Dashboards
/CustomerOrders.dashboard

30

Actuate BIRT Application Developer Guide

Part

Two

2

Designing applications

Part 2

Chapter

3
Chapter 3

Designing a dashboard

This chapter contains the following topics:
■

About dashboard applications

■

Planning dashboard layout

■

Creating a dashboard

■

Adding gadgets to a dashboard

Chapter 3, Designing a dashboard

33

About dashboard applications
A dashboard is a self-contained web application which delivers business
performance data in interactive charts, cross tab tables, BIRT documents and
external web services. Dashboards are quickly built using gadgets that display
data driven visualizations, files, or enable user choices. These gadgets can link
together to display data related to user requests, as shown in Figure 3-1.

Figure 3-1

Displaying a sample dashboard layout

When you build a dashboard you add gadgets to one or more tab pages of a
dashboard, similar to web pages. You choose the content to display in each
gadget and users of the dashboard can interact with that content, such as a chart
or table of data. The following gadget types are available:

34

■

Report gadgets display BIRT content such as BIRT documents, libraries, and
user input parameters from BIRT documents.

■

Chart gadgets organize and display data using symbols such as bars and lines.

■

Table gadgets display data values in cross tabs and in a row and column
format.

Actuate BIRT Application Developer Guide

■

Data selector gadgets show values for users to query data in other gadgets.

■

Extras gadgets display external content such as web applications, video,
HTML, JavaScript code, and Google gadgets.

You can create dashboards using the BIRT Designer Professional desktop
application. Finished dashboards are deployed to a BIRT iHub or cloud server,
such as BIRT onDemand and available to users in the following formats:
■

A dashboard file in Visualization Platform

■

A URL address when deployed as a BIRT application

■

A web page using Actuate JavaScript API (JSAPI) to embed the dashboard

Users can then interact with, export, or print data displayed in existing
dashboards or include your published dashboard as a page in their own
dashboard file when using Visualization Platform.

Planning dashboard layout
Planning dashboard usage assures that users receive and interact with the
expected data. After choosing the content and data to display on the dashboard
select the gadgets to display this information. Verify that user permissions, such
as file permissions necessary to view BIRT documents or BIRT data objects,
enable target users to access this information. Then consider how you want users
to interact with these gadgets. For example, do you filter the displayed data for
the user or do you enable users to select filter values with data selection gadgets.
Finally, determine the dashboard layout for the expected web browser and screen
size. Each dashboard supports four different layout formats; one column, two
column, three column and freeform. You can change gadget placement on the
dashboard to find the best balance of presentation and interaction. For example,
keep related user interaction gadgets together. Users can also view any gadget,
except the data selection gadgets at full screen.

Creating a dashboard
You create a new dashboard file using the dashboard editor in BIRT Designer
Professional. These files are stored in the project folder. If you plan to display
charts verify that your BIRT data object file exists in the project.
How to create a new dashboard

1 In BIRT Designer Professional choose File➛New➛Dashboard.
New Dashboard appears as shown in Figure 3-2.

Chapter 3, Designing a dashboard

35

Figure 3-2

Displaying the dashboard editor

2 The current project and the default folder for dashboards is selected.
■

If you want to use a different project or folder to store the dashboard file,
remove the selection Use Default Location to access the tree view of the
available folders.

■

If you want to change the dashboard file name, type the new name in File
name.

3 Choose Finish. The dashboard editor appears, as shown in Figure 3-3.

Figure 3-3

Displaying the dashboard editor

4 Choose Save to save the new dashboard file to the project.

36

Actuate BIRT Application Developer Guide

Adding a dashboard tab
A dashboard is divided into one or more pages called tabs. These tab pages
enable you to organize the gadgets. For example, one tab page contains gadgets
necessary to make a new customer order and another tab page can contain
gadgets displaying a customer’s order history. You can name each tab page to
identify its contents and change the order that the tab appears in relation to other
tabs.
How to add a dashboard tab

1 In the dashboard editor, choose Edit➛New Tab to create an empty, new tab
page.
2 Choose Edit➛Rename Tab to change the tab name.

Choosing a dashboard layout
Dashboard layout defines how gadgets appear on a dashboard. Each gadget uses
either a column or freeform layout. Gadgets in column layouts do not overlap
and appear either above or below another gadget in the same column. You can
place gadgets in freeform layout anywhere on the dashboard. If a freeform gadget
overlaps another gadget, the user can move the gadget to the front or back of the
other gadgets.
Dashboards support a one-, two-, or three-column layout in addition to a
freeform layout. You can use the columns to organize gadgets on the dashboard.
Dashboard columns are a percentage of the user’s web browser size. If the web
browser changes size, the dashboard columns are resized. Gadgets in a resized
column also resize to match the new width of the column.
Choose the freeform layout if you need to move or resize gadgets anywhere on
the dashboard. Freeform layout supports overlapping gadgets and changing the
width of individual gadgets.
For example, a single-column dashboard expands to fill the width of the web
browser, and the gadgets in the column are resized accordingly. Floating gadgets,
such as gadgets in a freeform layout, do not change their width or location on the
dashboard when the browser size changes.
For complex visualization layout, use BIRT design features available in BIRT
Designer Professional. For example, use BIRT Designer Professional to put
multiple charts into a grid element or cross tab container. You can display the
finished BIRT design file on a dashboard using a report gadget.
How to change a dashboard layout

In the dashboard editor, choose Layout➛Two Columns, as shown in Figure 3-4.

Chapter 3, Designing a dashboard

37

Figure 3-4

Configuring gadget layout in columns and freeform

How to resize a column in a dashboard

This example begins with a dashboard that uses a two-column layout.
1 In the dashboard editor, hover the mouse pointer over the vertical space
between two gadgets, as shown in Figure 3-5. The column bar appears.

Column bar

Figure 3-5

Resizing a column in a dashboard

2 Drag the bar to the left, to a new location, as shown in Figure 3-6.

Figure 3-6

Choosing a new column width in a dashboard

Existing gadgets are resized to fit within the new column widths.

38

Actuate BIRT Application Developer Guide

Formatting a dashboard tab
You can personalize the tab page of a dashboard with the following formatting
options:
■

Auto refresh, to refresh the dashboard at a selected interval

■

Background color, to set the background color of the dashboard page

■

Background image, to display an image as the background of the dashboard
page

■

Show Headers On, to show headers on selected gadgets

■

Show Tab Footer, to include HTML text at the bottom of the dashboard page

■

Show Tab Header, to include HTML text at the top of the dashboard page

■

Tab Name, to customize the name of the dashboard tab

For example, you can add a row of HTML hyperlinks to the top of your
dashboard or other HTML content with customized CSS styles inside the tab
header.
Activating auto refresh sets the dashboard to refresh at the selected interval. Data
and reports update at the selected interval. Set refresh settings to a speed that
your BIRT iHub supports. Each refresh requests an update for all content on the
dashboard tab page. Check with your BIRT iHub administrator for the supported
refresh frequency.
These formatting options are available from the dashboard editor when you
choose Edit➛Options, as shown in Figure 3-7.

Figure 3-7

Setting dashboard options

Chapter 3, Designing a dashboard

39

Adding data objects to a dashboard
When you add a BIRT data object to a dashboard, all new gadgets added to that
dashboard can use the data object. This can save time when adding multiple
gadgets that use the same data object. If you add multiple data objects to a
dashboard, each time you add a new gadget, the data objects you have added
appear in the category Current Data Selection.
How to add a data object to a dashboard

1 In the dashboard editor, Choose Data➛Manage Data to select data objects to
assign to the dashboard, as shown in Figure 3-8.

Figure 3-8

Displaying Opening Manage Data to add data objects

2 In Available Data, select a data object inside the project and choose the right
arrow. The selected data object appears in Selected Data, as shown in
Figure 3-9.
Data
preview
Refresh
Data
object
version

Data
object
contents

Figure 3-9

Selecting a data object to use in a dashboard

If multiple versions of a BIRT data object are available, you can select which
version to use in the dashboard. You can browse the contents of a data object
to verify it contains the data you require.

40

Actuate BIRT Application Developer Guide

Importing an existing dashboard
You can add a shared dashboard file to a dashboard that you are editing. Choose
Insert➛Dashboard From Gallery to import a dashboard file into your new
dashboard. This enables you to quickly add existing dashboards as new pages in
your own dashboard file.
Imported dashboards appear on your dashboard as tab pages with a share icon in
the tab title. You cannot edit the content of a shared dashboard. Dashboard tabs
with the shared icon link to the original dashboard file and changes to the original
dashboard file appear in the imported dashboard when it is refreshed. Figure 3-10
shows two imported tabs called Customers and Orders.

Figure 3-10

Importing dashboard tabs

To change the content of imported tab pages, either duplicate the tab pages or edit
the original dashboard file. Choose Edit➛Duplicate Tab to copy the selected tab
into a new tab page. You can edit a copied tab page because it is no longer linked
to changes in the original dashboard file.
For example, you want to include an existing dashboard file in your new
dashboard but you want to also change the layout and replace a chart gadget
with a table gadget. After importing the existing dashboard, you then duplicate
it. A new tab page appears in your dashboard with the same content as the
imported dashboard. You can edit the duplicated tab page. Finally, you do not
need the imported tab page with the share icon and can delete it.

Saving a dashboard
Save changes to a dashboard by choosing File➛Save. To save the dashboard with
a new name, choose File➛Save as, navigate to a new location and give a new
name for the dashboard file, as shown in Figure 3-11.
When you save a dashboard file using BIRT Designer Professional, you save the
file to a folder in a BIRT project or a BIRT application. You can then deploy the
project or application to a BIRT iHub or cloud server, such as BIRT onDemand or
export the dashboard file.

Chapter 3, Designing a dashboard

41

Figure 3-11

Saving a dashboard file to a new folder

Opening a dashboard file
You can open a dashboard file in a BIRT project or BIRT application using the
Navigator. Navigate to the folder containing the file and double-click the
dashboard file, as shown in Figure 3-12.

Figure 3-12

Navigating to a dashboard file

Dashboard files require additional files such as BIRT data objects and BIRT
documents. These files must exist where the dashboard file expects to find them.
If you need to send dashboard files for editing or review to someone that does not
have access to your iHub server, put the dashboard and its resources into a BIRT
application file. The recipient of the BIRT application file can then open the
dashboard in BIRT Designer Professional or their BIRT onDemand account to
view and edit the dashboard file.

Adding gadgets to a dashboard
Use the dashboard editor to add new or existing gadgets to the dashboard.
Choose Insert and select a gadget category, such as charts. Then choose the type

42

Actuate BIRT Application Developer Guide

of chart gadget, such as a bar chart. The gadget builder for the selected gadget
type appears for you to select content to display in the gadget.
If you have existing gadget files in your BIRT application folder, choose
Insert➛Gadget Gallery to display the file browser and search for the gadget file to
add to the dashboard. After the gadget appears on the dashboard, you can place
it where you want and edit the gadget options to change the format and other
settings of the gadget. You can save dashboard gadgets as gadget files using
Visualization Platform.

Placing a gadget
New gadgets use the dashboard layout when added. You can move existing
gadgets on the dashboard to a different column or set the gadget to float when the
dashboard uses the column layout. You can place floating gadgets anywhere on
the dashboard while other gadgets remain in the column layout. Select Dock from
the gadget menu to return a floating gadget to the column layout of the
dashboard.
If the dashboard uses a column layout, you can move the gadgets above or below
other gadgets in the same column. Gadgets in a column layout do not overlap
and have an adjustable height. If the dashboard uses a freeform layout, all
gadgets are floating. Floating gadgets have an adjustable height and width. When
the freeform grid is displayed, you can snap gadgets to a grid for precise
placement. Figure 3-13 shows gadgets in a three-column layout with two floating
gadgets. Gadget 5 and gadget 6 are floating, in this example.

Figure 3-13

Gadgets in a three-column layout with floating gadgets

How to add a new gadget to a dashboard

BIRT Designer Professional includes gadget templates to quickly add visual
content to your dashboard. Use BIRT iHub to create your own gadgets that you
can import into your project.

Chapter 3, Designing a dashboard

43

1 In the dashboard editor, choose Insert➛Extra➛Text to open the gadget
builder, as shown in Figure 3-14.

Figure 3-14

Adding a gadget to the dashboard

2 Complete the gadget configuration depending on the gadget you choose. This
example uses a text gadget. Choose OK when you are finished configuring the
gadget, as shown in as shown in Figure 3-15.

Figure 3-15

Configuring a new gadget

The selected gadget appears on the dashboard.
How to change the size of a gadget

1 Hover the mouse pointer over the border of a gadget. A solid line appears,
highlighting the borders that you can modify, as shown in Figure 3-16.

Mouse pointer

Figure 3-16

44

Selecting a gadget border to change

Actuate BIRT Application Developer Guide

2 Drag the border and drop it at a new position to resize the gadget, as shown in
Figure 3-17.

Figure 3-17

Changing the size of a gadget

3 The gadget resizes to the new dimension, as shown in Figure 3-18.

Figure 3-18

Displaying the new gadget dimensions

Formatting a gadget
Gadget formatting options are available in the general properties of a gadget. To
reach the general properties of a gadget, choose Edit. Then, choose General.
Figure 3-19 shows the general gadget properties of a column chart gadget. Each
gadget type includes additional formatting options, depending on the content of
the gadget.

Figure 3-19

Navigating to a dashboard file

Chapter 3, Designing a dashboard

45

You can personalize gadgets with the following formatting options:
■

Auto Refresh, to refresh the gadget at a selected interval

■

Dimensions, to set the width and height of the gadget after it is added to the
dashboard

■

Enable Scroll Bar, to display a scrollbar if the gadget is too small for the
content it displays

■

Font, to select a font for the gadget title

■

Gadget Title, to customize the name of the gadget

■

Show Border, to display the gadget border

■

Show Header, to display the header

■

Show Menu Icon, to display a gadget’s editing icon

■

Show Toolbar, to display a toolbar for a cross tab, parameter, report, or table
gadget

■

Title Alignment, to set the alignment of the gadget title

Testing dashboard content
After adding the gadgets you require, it is important to verify that the dashboard
meets your expectations. In the dashboard editor you can choose View➛Run to
open the dashboard in a read-only mode.
The following considerations assist in optimizing a dashboard:

46

■

Avoid long queries when on-demand data is not required by using data object
store files instead of data object design files. Object store files are cached in the
BIRT iHub, enabling multiple users to quickly access data.

■

Avoid delays in rendering BIRT content by using BIRT report document files
in place of BIRT report design files when possible. This avoids the additional
time necessary for data population of a report design file.

■

If you are showing only selected parts of a BIRT design file, consider using a
BIRT library. A BIRT design file renders every item in the file, even if only part
of the file is being used, such as content displayed in a Reportlet gadget. A
BIRT library only renders the requested content.

■

Activate dashboard auto refresh only when necessary to monitor changing
data.

■

If you display data selection gadgets, such as a list, consider using data objects
with optimized indexes for quick population of the gadget.

■

Consider building data cubes to aggregate data before the data is displayed.
For example, a table gadget that aggregates values requires the browser to

Actuate BIRT Application Developer Guide

load all values before it can calculate the aggregate values. If a cross tab was
used to display a data cube of the same data, there is less network traffic and
less processing done by the web browser.

Chapter 3, Designing a dashboard

47

48

Actuate BIRT Application Developer Guide

Chapter

4
Chapter 4

Displaying a file on
a dashboard

This chapter contains the following topics:
■

About files on a dashboard

■

Displaying BIRT documents

■

Displaying BIRT report items from a library

■

Displaying BIRT parameters

■

Displaying web content

Chapter 4, Displaying a file on a dashboard

49

About files on a dashboard
You can display external content on a dashboard and link this content to other
gadgets to build interactive applications. For example, display your company
logo in an image gadget. Use an HTML gadget to display your company web chat
application and use a Google gadget to display map locations of customer orders
and to verify order delivery status.
Use report gadgets to display and interact with BIRT content, such as report files,
BIRT library files, and parameters. Extra gadgets display content that does not
reside on a BIRT iHub server, such as web applications, HTML files, Google
gadget files, image and video files. These gadgets enable developers to bring
external content that is stored on external servers into their dashboard.
If you use Actuate Metrics Management, you can display the scorecards in
performance gadgets.

Displaying BIRT documents
BIRT design files contain many features to enhance chart types, document layout
and scripting. BIRT document files are created using BIRT Designer Professional
and Report Studio. These files and their content are displayed in dashboards
using report and Reportlet gadgets.
Use report gadgets to display entire BIRT files. If the document contains multiple
pages, the user can navigate through those pages or use the table of contents in
the BIRT document to find the information they need. The BIRT document retains
the file access permissions of the original BIRT document and users can interact
with the report using the same features as Interactive Viewer.
Use Reportlet gadgets to display a report element from a BIRT document that is
identified by a bookmark. For example, a single element such as a BIRT map or
multiple elements in a BIRT report grid such as a chart, a table, a map, and some
dynamic text.
Report gadgets support drill-through of charts when the BIRT developer enables
this functionality. Figure 4-1 shows a report gadget’s toolbar menu.
Users can interactively change the appearance, content and layout of a BIRT
document when the user maximizes the report gadget. Figure 4-2 shows a
maximized report gadget. Maximize the report by choosing Analyze from the
gadget menu.

50

Actuate BIRT Application Developer Guide

Gadget menu
Toolbar menu

Toolbar

Report content

Figure 4-1

Exporting content from a report gadget

Toolbar
Report
content

Group detail
Context
menu

Figure 4-2

Opening the context menu of a maximized report gadget

How to add a Reportlet gadget

This procedure requires a dashboard you can edit and a BIRT document with
bookmarks added using BIRT Designer Professional. Create a new dashboard if
one does not already exist.

Chapter 4, Displaying a file on a dashboard

51

To create a Reportlet gadget, complete the following steps:
1 In the dashboard editor, choose Insert➛Report➛Reportlet.
2 Choose Browse to display available reports.
3 Select a BIRT report document or report design file to display and choose OK.
4 Choose Select to display available bookmarks in the document.
5 Select a bookmark to display and choose OK, as shown in Figure 4-3.

Figure 4-3

Creating a Reportlet gadget

6 Select default values for any parameters in New Reportlet Gadget—
Parameter.
7 In New Reportlet Gadget, choose OK to create the new gadget.

Displaying BIRT report items from a library
Use report library gadgets to display visual report items from a BIRT library.
Report items include interactive viewing options for users to explore and
customize the data presentation. A BIRT library file is created in BIRT Designer
Professional and contains customized report elements, such as data sources,
visual report items, styles, images, scripts and parameters.
For example, a report library file contains a chart, a cross tab, a Flash object, a
grid, a map, and an image. You can add a separate report library gadget for the
chart and the map items to the dashboard. Each of the report items you selected
appear in their own gadget and can link to data selection gadgets.
When adding report items from the BIRT library, these items are copied to the
dashboard. When the report library gadget is displayed, only the selected report
items are rendered. If a report library is updated and you want to display the new
version of the report item in the library, you must add a new report library gadget
to the dashboard.
The report items in a BIRT library file are only generated if they are displayed on
the dashboard. When using a Reportlet gadget to display items in a BIRT design
file, the entire BIRT design is generated, if any part of the design is displayed on
the dashboard. Large reports can cause a delay to retrieve the content of a

52

Actuate BIRT Application Developer Guide

Reportlet gadget. If the developer uses a BIRT library, only the requested content
is delivered, offering better performance and a shorter delay to display the
desired content.
How to add a report library gadget

This procedure requires a dashboard you can edit and a BIRT library file with
report items added using BIRT Designer Professional. Create a new dashboard if
one does not already exist.
To create a report library gadget, complete the following steps:
1 In the dashboard editor, choose Insert➛Report➛Report Library.
2 Select a report item in a BIRT library file to display and choose OK. Figure 4-4
shows the report items available in the SalesReportItems BIRT library file.

Figure 4-4

Selecting a report item in a BIRT library

The report item appears in a gadget on the dashboard.

Displaying BIRT parameters
Parameters in a BIRT document prompt users to type or select values to pass into
the BIRT document. These values are used to add, change or filter data in the
BIRT document. You can set default parameter values in the gadget
configuration, display the parameters in the gadget for the user to select values,
or use a data selection or parameter gadget that is already on the dashboard to
send parameter values to the BIRT document.
For example, a BIRT design file displays order history for each customer and uses
parameters to prompt the user for a customer name before generating the
document. Other possible uses of parameters include requesting a report in a
specific language or adding comments into a final report.
When you display a BIRT document in a report or Reportlet gadget you can set
default values for any parameters in the BIRT document. To enable users to

Chapter 4, Displaying a file on a dashboard

53

change parameter values and update the BIRT document, display the parameters
on the dashboard.
When using a report or Reportlet gadget you can display parameters in the
following ways:
■

Do not display parameter.
The parameter is not displayed on the dashboard. A default value is selected
when creating or editing the gadget. Users cannot change this value.

■

Display parameter as part of the gadget.
The parameter is displayed as part of the report or Reportlet gadget. A user
selects a value for the parameter, then chooses Run to update the BIRT
document. Figure 4-5 shows a report gadget with parameters displayed in the
gadget.

Report
parameters
Run report

Figure 4-5

54

Displaying parameters as part of a gadget

■

Display parameter as a new selector.
Create a new data selection gadget that displays the parameter. Other report
and Reportlet gadgets can use this gadget. Figure 4-6 shows a report gadget
with a parameter displayed as a new selector gadget. When a user changes the
value, the linked document updates.

■

Link to this selector.
Use an existing parameter or data selection gadget to send parameter values
to the BIRT document.

Actuate BIRT Application Developer Guide

Report
parameter

Report with
parameters

Figure 4-6

Displaying parameters as a separate gadget

How to set default parameter values

This procedure requires a dashboard you can edit and a BIRT document that uses
parameter values. Create a new dashboard if one does not already exist.
To set default parameter values in a gadget, complete the following steps:
1 In the dashboard editor, choose Insert➛Report➛Report.
2 Choose Browse to display available reports.
3 Select a BIRT report document or report design file to display and choose OK.
4 In Parameter, set default values for the report’s parameters and choose OK.
Figure 4-7 shows default values set for a sample report.

Figure 4-7

Setting default parameter values in a report gadget

5 In New Report Gadget, choose OK to add the new gadget to the dashboard.

Chapter 4, Displaying a file on a dashboard

55

Displaying parameters in a data selector gadget
Use data selector gadgets to display parameters when you want to use the user’s
selected value in other gadgets, such as a chart. You can display parameters from
BIRT design and BIRT data object files.
When you choose to display a parameter as a new data selector, the Data Selector
Gadget Wizard launches. Use this wizard to build a data selection gadget using
the parameter choices in the BIRT file as a data source. You can choose the selector
type, such as list or check box, you can choose the formatting options, such as
formatting the displayed values, and you can link other gadgets to the user
selections.
Once the data selection gadget appears on the dashboard, you can edit it like
other data selection gadgets except that you cannot change the data source or
filter settings.
You can also link a report gadget with parameters to data selection gadgets from
other data sources. For example, a BIRT document displays customer invoices
and uses a parameter named Customer to generate the invoice of specific
customers. The dashboard includes a list for users to select customer names. You
create a report gadget to display the BIRT document. In the gadget’s Parameter
Display Settings, select the list of customer names in the section Link to this
selector. Now, each user selection from the list updates the BIRT document.
How to create a new selector for a parameter

This procedure requires a dashboard you can edit and a BIRT document that uses
parameter values. Create a new dashboard if one does not already exist.
To display parameter values in a separate gadget, complete the following steps:
1 In the dashboard editor, choose Insert➛Report➛Report.
2 Choose Browse to display available reports.
3 Select a BIRT report document or report design file to display, and choose OK.
4 In New Report Gadget—Parameter Display Settings, select Display parameter
as a new selector. Figure 4-8 shows the parameter display settings for an
example report.

Figure 4-8

56

Configuring parameter display settings for a report gadget

Actuate BIRT Application Developer Guide

Data Selector Gadget Wizard appears.
5 In Data Selector Gadget Wizard—Type, select a gadget type. The example in
Figure 4-9 shows a radio data selector.

Figure 4-9

Selecting a radio gadget

6 Choose OK. New Report Gadget—Parameter Display Setting appears.
7 Choose OK. The data selection gadget and report gadget appear, displaying
the default value for the parameter, as shown in Figure 4-10. Other gadgets
can now link to the new data selection gadget.
Data
selection
gadget

Report
gadget

Figure 4-10

Displaying a parameter for a report in a data selection gadget

Chapter 4, Displaying a file on a dashboard

57

Displaying parameters in a parameter gadget
Use parameter gadgets to display cascading or dynamic filter parameters from a
BIRT document on a dashboard. There are two types of parameters, values and
conditions (sometimes called dynamic filters). Values are used when the BIRT
report requires only a single value. When conditions are also used, as in the case
of dynamic filter parameters, the user can select a condition like less than, greater
than, equal to in addition to a value.
Parameter gadgets enable users to send values to BIRT documents displayed in
one or more report or Reportlet gadgets. These gadgets display all or selected
parameter choices in a BIRT document file. You can also assign default parameter
values and if the parameter includes filter conditions, such as a dynamic filter
parameter you can also assign default conditions, such as greater than. User
selections in the parameter gadget update the linked BIRT document when the
user chooses Apply Changes.
For example, two report gadgets contain a parameter to select a credit limit for
potential clients. The parameter gadget displays the filter condition and value of
the credit limit. The user selects less than for the filter condition and enters a
value of 80,000. When the user chooses Apply Changes, both report gadgets
update and use the credit limit parameter of less than 80,000.
Parameter gadgets are also used to create data selection gadgets on a dashboard
using a BIRT file as the data source instead of a BIRT data object. Other dashboard
visualization gadgets that do not use conditions, such as a chart, can link to the
parameter gadgets but require additional scripting when conditions and values
appear in the parameter. Data visualization gadgets expect only values, not
conditions. For more information about data selection gadgets see Chapter 5,
“Visualizing data on a dashboard.”
How to create a parameter gadget

This procedure requires a dashboard you can edit and a BIRT document that uses
parameter values. Create a new dashboard if one does not already exist.
To create a parameter gadget, complete the following steps:
1 In the dashboard editor, choose Insert➛Report➛Parameter.
2 Choose Browse to display available reports.
3 Select a BIRT report document or report design file to display and choose OK.
4 Select which report parameters to display in the parameter gadget and
choose OK. Figure 4-11 shows three selected parameters to display from an
example report.

58

Actuate BIRT Application Developer Guide

Figure 4-11

Configuring parameter display settings for a report gadget

5 Select default values for any parameters in New Parameter Gadget—
Parameter. Figure 4-12 shows three selected parameters to display from the
example report.

Figure 4-12

Configuring default values for a parameter gadget

6 Choose OK to create the new parameter gadget on the dashboard. Figure 4-13
shows the new parameter gadget created from the example report.

Figure 4-13

Configuring default values for a parameter gadget

Chapter 4, Displaying a file on a dashboard

59

Displaying web content
Display external files, such as images, web pages, videos and Google gadgets on a
dashboard using gadgets from the Extra category. This category includes the
following gadget types:
■

HTML

■

Image

■

Import gadget

■

Text

■

Video

Displaying HTML content
Display a URL of external web content or embed HTML code on a dashboard
using an HTML gadget. When using a URL, the content of the external web site
displays in the HTML gadget. If the displayed web page is bigger than the
gadget, the user can maximize the gadget to see more of the web page or enable
scroll bars in the gadget.
You can also embed HTML, CSS, and JavaScript code directly in the HTML
gadget instead of using a URL address.

Displaying content from a URL
You can display a web site or web application on the dashboard using an HTML
gadget. For example, using a URL such as http://www.actuate.com loads the
Actuate web site into the HTML gadget, as shown in Figure 4-14.

Figure 4-14

Adding a URL to display in an HTML gadget

Figure 4-15 displays the content of the http://www.actuate.com URL in an
HTML gadget.

60

Actuate BIRT Application Developer Guide

Figure 4-15

Displaying the HTML gadget on the dashboard

Some web sites and web applications support receiving additional parameters in
the URL. If the additional parameters in the URL require special encoding you
can encode the URL or consider using JavaScript redirection with the same URL
in the HTML gadget.
To use an unencoded URL in an HTML gadget, replace the unencoded characters
as shown in Table 4-1.
Table 4-1

Encoding URL characters for an HTML gadget

Character

Replacement text

Backslash (\)

Slash (/) or the URL encoding of %5C

Space ( )

The URL encoding %20

Ampersand (&)

The HTML character entity &

For example, the following URL does not work in an HTML gadget:
http://localhost:8700/iportal/iv?__report=\Home
\US sales.rptdocument&__page=3

The following rewritten URL works in an HTML gadget:
http://localhost:8700/iportal/
iv?__report=%5CHome%5CUS%20sales.rptdocument&__page=3

Similarly, to use a URL inside a JavaScript redirection, replace any backslashes
with a slash or the URL encoding of %5C. The following code shows JavaScript
redirection used to display a URL:


Place this code in the HTML section of the HTML gadget, replacing URL with the
URL that retrieves the Actuate document. For example, the URL to a BIRT report
document file is:

Chapter 4, Displaying a file on a dashboard

61

http://localhost:8700/iportal/iv?__report=\Home
\US Sales.rptdocument&__page=3

The following JavaScript redirection script loads the BIRT report document into
an HTML gadget:


Some web sites do not permit embedding their content in another web site or
attempt to control the browser display to present their content.

Displaying embedded HTML code
You can display embedded HTML such as HTML, CSS, and JavaScript code on a
dashboard. Verify that your JavaScript code does not use "parent" or "top" to
access HTML components.
If you need to interact with the HTML content consider embedding it in a Google
gadget. Import gadgets can link to data selection gadgets and pass the value to
the Google gadgets that they display.
Web applications that require special network ports or protocols, such as a video
chat application, require access to those ports from the user’s computer.

Displaying Adobe Flash content
Adobe Flash content often appears above other content such as a gadget menu,
when displayed in a web browser. If a dashboard developer has access to the
source code of the HTML or Google gadget that displays the Adobe Flash
content, the developer can add the wmode parameter to enable other content to
appear above the Adobe Flash content. Verify that the wmode parameter is in the
object tag that displays the Adobe Flash content and has a value of opaque or
transparent. Opaque is less processor-intensive on the user’s web browser than
transparent.
The following code shows an example of setting the wmode parameter to opaque
for embedded Adobe Flash content:







62

Actuate BIRT Application Developer Guide

If you do not have access to the source code where the Adobe Flash content
appears, contact the web site administrator and ask them to set the wmode
parameter to transparent in the object tag displaying the Adobe Flash content.

Displaying images
Display images on a web server or from the internet using the image gadget.
This location starts with http:// or https:// in the URL address to the image,
such as http://www.actuate.com/logo.jpg, where logo.jpg is the name of the
image file.
If the image is larger than the gadget, the user can maximize the gadget or enable
scroll bars to see more of the image.
The image gadget supports the following image formats:
■

GIF

■

JPG

■

PNG

■

ICO

Displaying Google gadgets
Google gadgets display dynamic web content using HTML and JavaScript.
Google gadgets can also receive user selections on a dashboard. Display Google
gadgets on a dashboard using the import gadget. The Google gadget is stored
on a connected network like the internet. This location starts with
http:// or https:// in the URL address to the Google gadget, such as
http://www.google.com/ig/modules/calculator.xml, where calculator.xml is
the name of the Google gadget file, as shown in Figure 4-16.

Figure 4-16

Adding a URL to display in an import gadget

Figure 4-17 displays the content of the http://www.google.com/ig/modules
/calculator.xml URL in an import gadget.

Chapter 4, Displaying a file on a dashboard

63

Figure 4-17

Displaying the import gadget on the dashboard

You can create a custom URL with JavaScript and link that to a user selection.
With this URL you can request a map, video, or other file when the user makes a
selection on the dashboard. For example, a Google gadget uses JavaScript to
generate a map of service routes for a company that delivers packages. The
Google gadget is displayed on the dashboard using an import gadget. When you
link the import gadget to a list displaying customer names, the Google gadget can
access the selected customer location, and generates a map using the customer’s
address.
For more information about creating and using Google gadgets, see Chapter 14,
“Building Google gadgets.”

Displaying text
When you need to display text on a dashboard, use the text gadget. This gadget
enables you to add text such as explanations, online help, and hyperlinks
anywhere on a dashboard.
When you add a text gadget to a dashboard, an HTML text editor appears,
providing text formatting options, as shown in Figure 4-18.

Add link
Edit code
Text
preview

Figure 4-18

64

Adding text to a text gadget

Actuate BIRT Application Developer Guide

You can type and format text directly in the HTML editor. Along with text
formatting options, the HTML editor supports adding HTML links to text and
editing the HTML source code of the text.
If you need to add JavaScript, custom HTML code or CSS code, use an HTML
gadget.

Displaying video
Display video files from a URL address or embedded HTML code on a dashboard
using a video gadget. The video content is stored on a connected network like the
internet. This location starts with http:// or https:// in the URL address to the
video content, such as http://www.youtube.com/watch?v=kxAMwt0hZDQ, as
shown in Figure 4-19.

Figure 4-19

Adding a URL to a video gadget

Figure 4-20 displays the content of the
http://www.youtube.com/watch?v=kxAMwt0hZDQ URL in a video gadget.

Figure 4-20

Displaying a video file in a video gadget

Chapter 4, Displaying a file on a dashboard

65

You can also add HTML code and JavaScript code directly in the video gadget.
For example, some video web sites embed video with options that display
playback controls, a related video list, and video size. You set these options using
the HTML code that embeds the video in the gadget.

66

Actuate BIRT Application Developer Guide

Chapter

5
Visualizing data
on a dashboard

Chapter 5

This chapter contains the following topics:
■

About displaying data on a dashboard

■

Displaying data in a chart

■

Displaying data in a table or cross tab

■

Displaying data in measurement gadgets

■

Enabling data selection

■

Organizing multiple user selections

Chapter 5, Visualizing data on a dashboard

67

About displaying data on a dashboard
You can display and summarize data on a dashboard using many gadget types
such as charts, cross tabs, lists, and tables. These gadgets support rich interaction
to help users analyze information and identify root causes. Link these gadgets
together to present synchronized visualizations, helping users explore data
scenarios and find and compare the data they need.
Users can perform the following actions using data visualization gadgets:
■

Explore data, for example, by drilling up to see summaries, or drilling down
or zooming in to see data details.

■

Export data and visual content into multiple file formats.

■

Interact with data using filters to select data, and hyperlinks to see related
information.

Some gadgets offer special user interaction. For example, chart gadgets support
zooming in to one or more axes, and users can launch Interactive Crosstabs to
explore and edit cross tab gadgets. You can link these gadgets to data selection
gadgets, such as a list, to enable users to select and filter data.
Visualization gadgets display data from BIRT data object files. These data object
files connect to, organize, and store data from external data sources such as a
database. BIRT Designer Professional is required to create data object files.

Displaying data in a chart
Chart gadgets are graphical representations of data from a BIRT data object.
Charts are useful for summarizing numeric data and showing the relationship
between sets of values, called series. For example, a chart can show sales by
region, average temperatures by month, or the price of a stock over three months.
Because a chart presents a picture, it reveals trends that are not apparent in a
table.
When adding a chart to a dashboard, you perform the following tasks:

68

■

Choose a chart type.

■

Specify the data to present in the chart.

■

Format the chart.

■

Choose a location for the chart on the dashboard.

Actuate BIRT Application Developer Guide

How to create a chart gadget

This procedure requires a dashboard you can edit and a BIRT data object. Create a
new dashboard if one does not already exist. To create a chart gadget, complete
the following steps:
1 Choose a chart type in the dashboard editor by selecting Insert➛Chart and
choosing a chart type. In this example, choose Insert➛Chart➛Bar Chart.
2 Select the data to display in the chart by completing the following steps:
1 In Chart Builder—Data—Use Data, select a data source. If no data source
appears, choose New Data to select a BIRT data object from available data
objects in the BIRT project.
2 Select a data column to display in the chart category axis.
3 Select a data column to display in the chart value axis.
3 Group and aggregate the data if it is not already aggregated in a data cube by
completing the following steps:
1 Enable Group Categories to aggregate data on the value axis.
If you use date values to group categories, select a time interval by which
to group the dates, such as years or months.
2 Specify data aggregations for each data column on the value axis.
3 To display a legend, set group legend items to the name of a data column.
If you use date values to group legend items, select a time interval by
which to group the dates, such as years or months.
4 The following optional tasks are available when you create the chart or after
the chart has been added to the dashboard:
■

Specify gadget appearance, such as name and size, in Chart Builder—
General.

■

Limit displayed data with filter conditions, in Chart Builder—Filter.

■

Format the chart, in Chart Builder—Format. For example, select a chart
theme and a chart subtype, enable zoom, enable the timeline range selector,
or customize the display of each axis.

Figure 5-1 shows the data configuration of a finished chart.
5 Choose OK to create the new gadget on the dashboard. Figure 5-2 shows the
data configuration of a finished bar chart.

Chapter 5, Visualizing data on a dashboard

69

Figure 5-1

Configuring data to display in a chart

Figure 5-2

Displaying the finished chart on the dashboard

Enable interactive filtering, if desired, by linking the chart to a data selection
gadget. After the chart is placed on the dashboard, it links to data selection

70

Actuate BIRT Application Developer Guide

gadgets that use the same data source. You can remove these links or add
new ones.

Selecting a chart type
BIRT dashboards provide several chart types. The following sections describe the
chart types BIRT dashboards support. Several of the chart types include subtypes.

About area charts
An area chart displays data values as a set of points, connected by a line, with the
area below the line filled. You typically use an area chart to present data that
occurs over a continuous period of time. There are three subtypes of area charts:
overlay, stacked, and percent stacked.
In an overlay area chart, shown on the left in Figure 5-3, the areas of multiple
series overlap. Use the overlay area chart to show only one series, for example,
only sales for Asia. The overlay chart subtype is not suitable for showing multiple
series if the data values overlap. For example, in a chart displaying sales values
for global territories, if the values in one territory, the U.S., are the highest for
every quarter, the data for the U.S. obscures the data for Europe and Asia.

Figure 5-3

Overlay, stacked, and percent stacked area charts

In a stacked area chart, multiple series are stacked vertically, as shown in the chart
at the center in Figure 5-3. The example shows that the stacked area chart is

Chapter 5, Visualizing data on a dashboard

71

suitable for multiple series of data because the chart displays totals for all series
and displays the proportion that each series contributes to the total. The height of
the top line shows the total value for each quarter. Each shaded area represents
the sales amount for a specific region.
In a percent stacked area chart, as shown on the right in Figure 5-3, multiple series
are stacked vertically, and the values appear as a percentage of the whole. As the
chart in Figure 5-3 shows, the sales values are displayed in percentages instead of
the actual numbers, as shown in the previous area charts. The percent stacked
area chart is meaningful only when displaying and comparing multiple series.

About bar charts
A bar chart, by default, displays data values as a set of horizontal bars, but you
can transpose the axes to display vertical bars. A bar chart is useful for displaying
data side by side for easy comparison. There are three subtypes of bar charts:
side-by-side, stacked, and percent stacked. The stacked and percent stacked bar
charts are functionally similar to the stacked area chart and percent stacked area
chart subtypes.
In a side-by-side bar chart, multiple series appear as side-by-side bars, as shown
in the chart on the left in Figure 5-4. This bar chart uses the same data as the area
charts shown in earlier sections.

Figure 5-4

72

Side-by-side, stacked, and percent stacked bar charts

Actuate BIRT Application Developer Guide

In a stacked bar chart, multiple series are stacked vertically, as shown in the chart
in the center in Figure 5-4. The stacked bar chart shows totals for each category, as
well as the proportion that each series contributes to the total.
In a percent stacked bar chart, multiple series are stacked vertically, and the
values are shown as a percentage of the whole. As seen in the chart on the right in
Figure 5-4, the sales values are shown in percentages instead of actual numbers,
as shown in the previous bar charts.
Like the percent stacked area chart, the percent stacked bar chart is meaningful
only when displaying and comparing multiple series. This chart subtype is
typically not used if you are displaying only one series, for example, only sales
for Asia.

About bubble charts
A bubble chart displays three sets of numeric data values at a time, two values are
data points with x-y coordinates on the axes. The third value defines the size of
the bubble at each point. A typical use of a bubble chart is to present financial
data such as quantity sold, profit margin, and total profit sales of multiple
product lines. Figure 5-5 shows a bubble chart where the size of the circle
indicates the quantity sold.

Figure 5-5

A bubble chart

About column charts
A column chart displays data values as a set of vertical bars, with categories on
the horizontal axis and values on the vertical axis. This layout is useful for
displaying data side by side for easy comparison, as shown in the chart on the left
in Figure 5-6.
This chart supports a stacked or percent stacked chart subtype that also shows the
relationships of values in each category to the whole, as shown in the charts in the
center and on the right in Figure 5-6.

Chapter 5, Visualizing data on a dashboard

73

Figure 5-6

Side-by-side, stacked, and percent stacked column charts

About difference charts
A difference chart displays the variation between two values by shading the
area between those values. Figure 5-7 shows profit by displaying the difference
between the revenue and the cost of goods sold, for cities in France. You typically
use a difference chart to show deviation between two sets of values, such as the
high and low temperature for each day.

Figure 5-7

74

A difference chart

Actuate BIRT Application Developer Guide

About doughnut charts
A doughnut chart is a circular chart that is divided into sectors or slices. Each
sector represents a value that is proportional to the total value, as shown in
Figure 5-8.

Figure 5-8

A doughnut chart

About Gantt charts
A Gantt chart graphically presents project scheduling information by displaying
the duration of tasks. One axis contains the time series, and the other contains
tasks. You can use color-coded bars to show the planned duration of the stages to
complete the tasks. Bars can use multiple colors to differentiate between stages.
Gantt charts use symbols on bars to mark beginning and ending dates. The colors
of the bars represent the task status. Optionally, markers designate the start and
end dates of tasks. Figure 5-9 shows a Gantt chart.

Figure 5-9

A Gantt chart

About line charts
A line chart displays data values as a set of points that are 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 the most basic type of chart in finance.
The chart on the left in Figure 5-10 shows an example of an overlay line chart.

Chapter 5, Visualizing data on a dashboard

75

Figure 5-10

Overlay, stacked, and percent stacked line charts

A line chart is similar to an area chart, except that the line chart does not fill in the
area below the line. In an overlay line chart, multiple series appear as overlapping
lines, as shown in the chart on the left in Figure 5-10. The line chart supports
stacked and percent stacked subtypes.
In a stacked line chart, multiple series are stacked vertically, as shown in the chart
in the center in Figure 5-10. The stacked line chart shows totals for each series, as
well as the proportion that each series contributes to the total.
In addition, as the example shows, a user can easily misinterpret the data in a
stacked line chart. There is no obvious indication that the top line shows the total
sales amount for each quarter, and the middle line shows the difference in the
sales amount between EMEA and APAC. Verify that the title of the chart or other
text describing the chart explains the purpose of the chart.
In a percent stacked line chart, multiple series are stacked vertically and the
values are shown as a percentage of the whole. As shown in the chart on the right
in Figure 5-10, the sales values appear in percentages instead of numbers. Like the
percent stacked area chart, the percent stacked line chart makes sense only when
displaying and comparing multiple series. If you are displaying only one series,
such as sales for EMEA, an overlay subtype is the most effective line chart. Both
the stacked line chart and the percent stacked line chart are not as effective as
their area chart counterparts.

76

Actuate BIRT Application Developer Guide

About pie charts
A pie chart is a circular chart that is divided into sectors or slices. Each sector
represents a value that is proportional to the sum of the values. Use a pie chart to
show the relationship of parts to the whole, for example, the order quantity each
product line contributes to the total, as shown in Figure 5-11.

Figure 5-11

A pie chart

About radar charts
Radar charts compare the aggregate values of one or more series of data. A
separate spoke from the chart center is shown for each category and each spoke is
connected by an arc. A line is drawn connecting the data values for each spoke,
giving the chart a star-like appearance. Radar charts have two subtypes: standard
radar charts and spider radar charts, as shown in Figure 5-12.

Figure 5-12

Standard and spider radar charts

A spider radar chart connects the outer spokes using lines and a standard radar
chart uses arcs, as shown in the chart on the left in Figure 5-12. Radar charts are
most effective for small data sets containing only a few hundred data rows. For
larger data sets, or those containing a time series, use a line chart.

Chapter 5, Visualizing data on a dashboard

77

About scatter charts
A scatter chart presents data as x-y coordinates by displaying two sets of numeric
values as 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. For example, use a scatter chart to compare salaries and years of
experience or weight and exercise. The more data values you include in a scatter
chart, the clearer the trends the data reveals.
The scatter chart in Figure 5-13 shows the relationship between quantity ordered
and profit over three years. Each pair of values, quantity ordered and profit, is
plotted as a single x-y value.

Figure 5-13

A scatter chart

About stock charts
A stock chart displays a stock’s open, close, high, and low values for a set of
trading dates. A stock chart can show the data for one stock or for multiple stocks.
Although a stock chart is typically used to display stock data, you can also use it
to chart other values such as four daily temperature values for a set of dates: high,
low, sunrise, sunset. The stock chart has two subtypes: the candlestick and bar
stick stock charts.
A candlestick stock chart consists of a series of boxes with lines extending up and
down from the ends, as shown in the chart on the left in Figure 5-14. The top and
bottom points of each line indicate the high and low values, respectively. The top
and bottom of each box indicate the open and close values. If the close value is
higher than the open value, the box is white. If the open value is higher than the
close value, the box is shaded. This style enables you to see immediately whether
a value posted a gain or a loss for a given day.
A bar stick stock chart consists of a series of vertical bars with horizontal tick
marks, as shown in the chart on the right in Figure 5-14. The top and bottom
points of each bar indicate the high and low values, respectively. The horizontal
tick marks indicate the open and close values. The tick mark on the left of the bar
is the open value. The tick mark on the right of the bar is the close value. A bar
stick stock chart typically shows the change in price over a period of time. The

78

Actuate BIRT Application Developer Guide

candlestick stock chart shows the gain or loss pattern more clearly than the bar
stick stock chart.

Figure 5-14

A candlestick and bar stick stock chart

Selecting data for charts
You can select, filter, group, and aggregate data when you create the chart.
Adding a chart gadget to a dashboard displays Chart Builder—Data, where the
developer selects data to display in the chart. Choose a BIRT data object and
select a data set, data cube, or data model. Then, assign the data columns to the
different parts of the chart. Figure 5-15 displays an example bar chart’s data
configuration.

Figure 5-15

Selecting data to display in a bar chart

Chapter 5, Visualizing data on a dashboard

79

You can select one data column from the data source to display on the category
axis of the chart and up to two data columns to display as series on the value axis
of the chart. The pie and doughnut chart only support a single series.
If hyperlinks exist in the data object file, they can appear in the chart by selecting
Chart Builder➛Data➛Enable Interactivity. Hyperlinks enable users to open a URI
or drill through to another BIRT document file when choosing a value such as a
customer name in a table. This is similar to a hyperlink on a web page.
Data cubes and data models can include a hierarchy structure. This enables users
to drill into the chart categories for details by selecting a part of the chart, such as
sales activity for a specific month in a specific year. You can break this hierarchy if
you want to aggregate values without their parent level.
For example, if you keep a data cube’s hierarchy and group legend items by a
time interval of quarters, the legend displays an each quarter of each year. If you
disable Keep Hierarchy in the chart, then the legend groups values only by the
quarter and not by year.
Figure 5-16 displays an example bar chart’s data configuration.

Figure 5-16

Grouping by quarters with and without hierarchy

Using category groups
Data sets and data models displayed in charts support grouping by category,
typically shown on the horizontal axis. When a category is grouped, values for
the selected category are aggregated. For example, a chart about customer orders
groups data by country and displays the total sum of sales orders. The resulting
chart displays each country name once with a sum of all sales for each country.

Using legend groups
You can display subgroups of values using legend items. When legend items are
grouped by a data column, the different values in that data column appear next to
the chart as legend items. For example, you have a bar chart that already groups

80

Actuate BIRT Application Developer Guide

the data series by product line. If you group legend items by order date and
choose an interval of years, each product line category displays an additional bar
for each year of sales.
If you choose to also display the legend, each year appears as a legend item next
to the chart. When the chart data source is a data set or a data model, users can
select a legend item to hide the values in the selected legend group. The pie and
doughnut chart do not support legend groups.
When the chart data source is a data cube, users can select a legend item to drill
down into the data hierarchy. Users can drill down into both the category and
series data at the same time.
For example, consider a bar chart that displays data from a data cube. The
category axis displays country names and the value axis displays the quantity of
goods sold. The chart also displays a legend that groups the axis of values by the
year of the sales data. If a user views the chart and selects the bar for a country,
they drill down into details of the country category and the chart displays cities in
the country. If the user selects the legend item for one of the displayed years, they
drill down into the chart and see details of the selected year, such as data by the
months of the year.

Using aggregate expressions
You can create aggregate expressions to summarize values from a data set or data
model and display the results in a chart. Table 5-1 shows the functions available
in chart gadgets.
Table 5-1

Aggregate functions for charts

Function

Description

Average

Returns the average of the values

Count

Returns the number of values, including duplicate values

Distinct Count

Returns the number of values, excluding duplicate values

First

Returns the first value among the values

Last

Returns the last value among the values

Max

Returns the largest value among the values

Min

Returns the smallest value among the values

Sum

Returns the sum of the values

Formatting charts
Once a chart is selected, you can format and enhance your chart in Chart
Builder—Format. You can replace the automatic title, change fonts, change the
chart size, select a chart theme, display a legend, change the label presentation,

Chapter 5, Visualizing data on a dashboard

81

and add titles to the axis. Different charts include additional features such as
subtypes and zoom in to axis.
When a chart title is set to auto, the title is based on the values displayed, and
updates when a user changes the displayed values, such as drilling down into
details of a data cube. To set a fixed title that does not change, remove the auto
title selection and type a new title.

Choosing a chart theme
Chart themes customize the appearance of a chart and can change color, font, and
display properties for charts. These themes are created in BIRT Designer
Professional.
The following section shows examples of themes used in area charts:
■

The chart on the left uses no theme and the one on the right uses the modern
theme, as shown in Figure 5-17.

Figure 5-17
■

The example shown in Figure 5-18 displays area charts using the clean blue,
warm red, and grayscale themes.

Figure 5-18

82

Area charts using no theme and the modern chart theme

Area charts using the clean blue, warm red, and grayscale
themes

Actuate BIRT Application Developer Guide

Chart themes customize the appearance of a chart and can contain custom
JavaScript for enhanced interactivity. Each theme changes a chart’s colors, fonts,
and display. These themes are created in BIRT Designer Professional. Themes are
stored in a BIRT design file when they are used in a single report. You can store a
theme in a BIRT library file to enable multiple chart gadgets and BIRT design files
to use the same theme.

Enabling chart zoom
Chart users can zoom in to the chart to view details of the selected data when
zoom is enabled for categories or values. Zoom is available in area, bar, bubble,
column, difference, Gantt, line, scatter, and stock charts. Zoom options are set in
Chart Builder—Format.
Users can zoom in to charts to see greater detail by selecting a start point on the
x-axis, dragging the mouse to the end point, and then releasing the mouse button,
as shown in Figure 5-19.

Start
End

Figure 5-19

Zooming on the x-axis

Figure 5-20 shows the results of an x-axis zoom. Choose Reset zoom to return the
chart to the default display or continue to zoom in to view additional detail.

Figure 5-20

Finished zoom on the x-axis

Chapter 5, Visualizing data on a dashboard

83

Enabling a timeline
When the category is a time field, you can select the time range selector and
bottom slider. You can enable a time range selector and a timeline slider for users
to select time intervals in area, bar, column, difference, line, scatter, and stock
charts. Timeline options are set in Chart Builder—Format.
The time range selector appears under the chart title and enables a user to zoom
in to 1-, 3-, or 6-month intervals, year to date, 1 year, and all values on the chart.
The time range slider appears at the bottom of the chart and enables users to
select a time period by sliding a bar to the beginning and end of the period.
Figure 5-21 shows a chart displaying the time range selector and bottom slider.

Timeline
range
selectors

Timeline
bottom
slider

Figure 5-21

Displaying a time range selector and bottom slider on a chart

Displaying data in a table or cross tab
Table and cross tab gadgets display tabular data on a dashboard. These gadgets
organize values into a row-and-column matrix that appears in a table format,
similar to a spreadsheet. Tables and cross tabs are useful to present detailed
evidence to justify a conclusion and to display reports containing specific values
such as the exchange value of multiple currencies. Users can interact with tables
to format and export data using the table context menu.
You can aggregate data to create a concise summary overview of your data. For
example, a detailed table displays a row for each order number, order date, and
the total profit of the order. This creates a large table if you have many orders, and
is difficult to identify trends. When you aggregate this data with a monthly time
interval and an aggregate function such as sum, the table groups values by month
to show the monthly sum of order profit. If you change the aggregate function to
average, then the table displays the average order profit for each month. You can
display multiple aggregations together, such as creating a table of orders,
grouped by month, that displays the total sales and average sales for each month.
Cross tabs display a data source that is already aggregated, such as a data cube.
You can display grand totals and subtotals in a cross tab and users can open the

84

Actuate BIRT Application Developer Guide

cross tab in the Interactive Crosstabs tool to analyze the aggregated data and add
an optional chart. If your data source is a data model, you can also use a cross tab
to build aggregations. Calculations are typically faster using data cubes than in a
data set because the data is aggregated when the data object is created. Users can
drill down into the data displayed in cross tabs. For example, in a cross tab of
order status, the user can drill down to see the order numbers for a selected
status, such as canceled orders.
If you designed your data objects to include links, you can select the values in the
table to open the link. For example, a data object of orders includes a link on each
order number to the invoice for the order.

Choosing a table type
The following tabular data formats are available:
■

Cross tab
A cross tab displays data cubes and data models in a row-and-column matrix
that has a spreadsheet-like appearance. The cross tab is ideal for summarizing
data in a compact and concise format, and displays summary, or aggregate
values such as sums, counts, or averages. The cross tab groups these values by
one set of data listed down the left side of the matrix and another set of data
listed across the top of the matrix. If your data source is a data model, you can
select aggregation functions while building the cross tab. If your data source is
a data cube, you use the aggregation functions that are included in the data
cube when it was created. Figure 5-22 shows a cross tab gadget.

Figure 5-22

Displaying data in a cross tab gadget

Users can open and edit cross tabs in Interactive Crosstabs for additional
analysis and to add a chart view to the cross tab. Users can format displayed

Chapter 5, Visualizing data on a dashboard

85

values, export content, and export data using the context menu. Exporting
cross tabs to Microsoft Excel pivot tables is also supported.
■

Table
A table displays data sets and data models in a row-and-column format. You
can display data row by row, as in the data set or you can summarize the table
data. Summarizing table data presents aggregate data information in a report,
providing users with an overview of the data. For example, a table can display
order dates, order numbers, and the total value of every order or group of
values by month to show the monthly sum of orders. Figure 5-23 shows a table
gadget.

Hyperlink in
data object

Figure 5-23

Displaying data in a table gadget

If you want to offer table users options for interacting with tabular data,
display the data details in the table without summarizing the data. For
example, conditional formatting, grouping, sorting, aggregation, and
computed column creation are available to users when the tabular data is not
already aggregated into summary data. If you want to offer the users concise
summaries of the data but with fewer interaction options, display the data in a
summary table.

Using a table
How to create a table gadget

This procedure requires a dashboard you can edit. Create a new dashboard if one
does not already exist. To create a table gadget, complete the following steps:
1 In the dashboard editor, choose Insert➛Table➛Table.
2 To select the data to display in the table gadget, complete the following steps:
1 In Table Builder—Data—Data—Use Data, select a data source. If no data
source appears, choose New Data to select a BIRT data object from
available data objects in the BIRT project.

86

Actuate BIRT Application Developer Guide

2 In Available Data, select fields to display in tabular format and choose the
Add arrow to add to Current Column Selections.
3 If your data source includes links in the data, select Enable Interactivity to
display the links in the table.
3 Group and aggregate the data as a summary table, if desired, by completing
the following steps:
1 Select Summarize.
2 If you have a date field in Current Column Selections, choose to group the
values by a time period such as years or weeks.
3 Select any fields that you want to aggregate and choose Add to Current
Measure Selections.
4 In Current Measure Selections, select an aggregation method for each data
field.
4 The following optional tasks are available when you create the table or after
the table is added to the dashboard:
■

Specify gadget appearance, such as title and gadget size, in
Table Builder—General. Display a border, header, menu icon, scroll bar,
and toolbar.

■

Limit displayed data with filter conditions, in Table Builder—Filter.

■

Format the table, in Table Builder—Format. For example, set the
background color, border, font, and the table alignment for the header and
the table body. Set a page break interval to break the table rows into pages
of data.

5 Choose OK to create the new gadget.
Enable interactive filtering by linking the table to a data selection gadget. After
the table is placed on the dashboard, it links to data selection gadgets that use the
same data source. You can remove these links or add new ones.

Selecting data for tabular display
A table gadget displays tabular data on a dashboard. Adding a table gadget to a
dashboard or editing it displays Table Builder—Data.
After choosing an available BIRT data object, choose a data set or data model.
Next, select data fields to display in the table columns. To select multiple values,
press Ctrl as you select each value. A typical table displays a row for every row in
the data source. Figure 5-24 shows the data source of a table gadget.

Chapter 5, Visualizing data on a dashboard

87

Enable
interactive
hyperlinks in
data object

Figure 5-24

Selecting data to display in a table gadget

Table gadgets can display hyperlinks from data objects. If hyperlinks exist in the
data object file, they can appear in the table by selecting Table Builder➛Data
➛Enable Interactivity. Hyperlinks enable users to open a URI or drill through to
another BIRT document file when choosing a value such as a customer name in a
table. This is similar to a hyperlink on a web page.

Aggregating tabular data
To aggregate data in a table gadget, choose Summarize in Table Builder—Data.
Figure 5-25 shows a table gadget that summarizes values from a data model.

Aggregated
values

Figure 5-25

88

Aggregating data in a table gadget

Actuate BIRT Application Developer Guide

Use Summarize to aggregate numeric values in the data set or data model, such
as displaying the total sales for each month instead of each order. Table 5-2 shows
the aggregation functions you can select for values displayed in a table.
Table 5-2

Aggregate functions for tables

Function

Description

Average

Returns the average of the values.

Count

Returns the number of values, including duplicate values.

Distinct Count

Returns the number of values, excluding duplicate values.

First

Returns the first value among the values.

Last

Returns the last value among the values.

Max

Returns the largest value among the values.

Median

Returns the median, or middle value among the values.

Min

Returns the smallest value among the values.

Mode

Returns the mode, or the value that occurs most frequently
among the values.

Standard
Deviation

Returns the standard deviation of a set of values. Standard
deviation is a statistic that shows how widely values disperse
from the mean value. If a set of values contains 50, 75, 80, 90,
and 95, standard deviation returns 17.536.

Sum

Returns the sum of the values.

Variance

Returns the variance of a set of values. Variance is a statistical
measure expressing the size of the differences between the
values. The variance increases as the differences between the
numbers increase. If a set of values contains 50, 75, 80, 90, and
95, variance returns 307.5. If a set of values contains 5, 2, 5, 7,
and 10, variance returns 8.7.

Formatting tabular gadgets
You can customize the background, border, and font attributes used in the table
rows, such as alignment, color, font, and size. You can also define how many rows
to display before creating a page break using Page Break Interval.
Table gadgets also support formatting, conditional formatting, grouping, sorting,
aggregation, and computed column creation using the interactive context menu.
These features enable users to explore and personalize the data for display or
export. Figure 5-26 shows a table gadget that summarizes values from a data
model.

Chapter 5, Visualizing data on a dashboard

89

Figure 5-26

Displaying the interactive context menu in a table gadget

Using a cross tab
How to create a cross tab gadget

This procedure requires a dashboard you can edit. Create a new dashboard if one
does not already exist. To create a cross tab gadget, complete the following steps:
1 In the dashboard editor, choose Insert➛Table➛Crosstab.
2 To select the data to display in the cross tab gadget, complete the following
steps:
1 In Crosstab Builder—Data—Data Models and Cubes—Use Data, select a
data source. If no data source appears, choose New Data to select a BIRT
data object from available data objects in the BIRT project.
2 If your data source includes links in the data, select Enable Interactivity to
display the links in the table.
3 In Available Data, select fields to display as rows, and choose the Add
arrow to add to Row.
4 In Available Data, select fields to display as columns, and choose the Add
arrow to add to Column.
5 If you display a date in a row or column, select the date groups such as
years and quarters.
6 In Available Data, select fields to display as aggregated summary fields,
and choose the Add arrow to add to Summary Fields.
7 If your data source is a data model, select an aggregation method for each
data field in Summary Fields.

90

Actuate BIRT Application Developer Guide

3 The following optional tasks are available when you create the cross tab or
after the cross tab is added to the dashboard:
■

Specify gadget appearance, such as title and gadget size, in Crosstab
Builder—General. Display a border, header, menu icon, scroll bar, and
toolbar.

■

Limit displayed data with filter conditions in Crosstab Builder—Filter.

■

Format the cross tab in Crosstab Builder—Format. For example, enable
grand totals and subtotals for rows and columns. Set a page break interval
to break the cross tab row and column content into multiple pages.

4 Choose OK to create the new cross tab gadget.
Enable interactive filtering by linking the cross tab to a data selection gadget.
After the cross tab is placed on the dashboard, it links to data selection gadgets
that use the same data source. You can remove these links or add new ones.

Selecting data for cross tab gadgets
Adding a cross tab gadget to a dashboard or editing it displays Crosstab Builder.
Figure 5-27 shows an example of Crosstab Builder.

Enable
interactive
hyperlinks
in data
Move
selection
up

Aggregate
expression

Figure 5-27

Selecting data to display in a cross tab gadget

Chapter 5, Visualizing data on a dashboard

91

After choosing an available BIRT data object, choose a data cube or data model.
Next, select data fields to display in the cross tab columns, rows, and summary
fields. To select multiple values, press Ctrl as you select each value. For example,
if the columns display the fields order date, order number, order value, and order
status, these are the columns that display in the table.
Each data field in a row displays horizontally in a cross tab and each field in a
column displays vertically on a cross tab. Measure fields display aggregated
totals in each intersection of a column and row. You can enable grand totals and
subtotals for columns and rows in Crosstab Builder—Format.
Cross tab gadgets can display hyperlinks from data objects. If hyperlinks exist in
the data object file, they can appear in the cross tab by selecting Crosstab Builder
➛Data➛Enable Interactivity. Hyperlinks enable users to open a URI or drill
through to another BIRT document file when choosing a value such as a customer
name displayed in a table. This is similar to a hyperlink on a web page.

Aggregating cross tab data
When you display a data cube in a cross tab, you select from existing
aggregations that are included in the data cube. These aggregated fields are called
measures, and were added to the data cube when it was created in BIRT Designer
Professional.
When you display a data model in a cross tab, you can aggregate any field by
adding it to Summary Fields in Crosstab Builder—Data. In the final step you
select an aggregation function. Table 5-3 shows the aggregation functions you can
select for values displayed in a cross tab.
Table 5-3

Function

Aggregate functions for cross tabs

Measure

Dimension Description

Average

92

Returns the average of the values.

Count

✓

✓

Returns the number of values,
including duplicate values.

Count Distinct

✓

✓

Returns the number of values,
excluding duplicate values.

First

✓

✓

Returns the first value among the
values.

Last

✓

✓

Returns the last value among the
values.

Max

✓

✓

Returns the largest value among the
values.

Median

✓

Actuate BIRT Application Developer Guide

Returns the median, or middle value
among the values.

Table 5-3

Function

Aggregate functions for cross tabs

Measure

Dimension Description

Min

✓

✓

Mode

✓

Returns the mode, or the value that
occurs most frequently among the
values.

Standard
Deviation

✓

Returns the standard deviation of a
set of values. Standard deviation is a
statistic that shows how widely
values disperse from the mean value.
If a set of values contains 50, 75, 80,
90, and 95, standard deviation
returns 17.536.

Sum

✓

Returns the sum of the values.

Variance

✓

Returns the variance of a set of
values. Variance is a statistical
measure expressing the size of the
differences between the values. The
variance increases as the differences
between the numbers increase. If a
set of values contains 50, 75, 80, 90,
and 95, variance returns 307.5. If a set
of values contains 5, 2, 5, 7, and 10,
variance returns 8.7.

Returns the smallest value among
the values.

Formatting cross tab gadgets
Cross tab formatting supports the display of grand totals and subtotals for all
rows and columns that contain two or more dimensions. You can minimize
loading time of large tables by enabling page breaks at the selected column and
row intervals.
Users can open a cross tab in Interactive Crosstabs to add an alternative chart
display, apply conditional formatting, apply advanced filters such as relative
time, pivot the table display, and apply drill up or drill down to selected fields in
the cross tab. You can also open the cross tab in Interactive Crosstabs to select a
visual theme for the cross tab.
Choose Analyze from the gadget menu to open the cross tab in Interactive
Crosstabs for additional analysis and formatting. You can also double-click the
title of the cross tab gadget to open the cross tab in Interactive Crosstabs.
Figure 5-28 shows a table gadget that summarizes values from a data model.

Chapter 5, Visualizing data on a dashboard

93

Figure 5-28

Reviewing a cross tab gadget after formatting in
Interactive Crosstabs

Displaying data in measurement gadgets
Measurement gadgets are visualizations that typically measure a value in a visual
range. These visualizations display values from a BIRT data object and are
typically smaller than a multi-axis chart.

Choosing a measurement type
The following types of measurement gadgets are available in the dashboard
editor:
■

Bullet
A bullet gadget is a variation of a bar chart that measures the value of a single
data column in a horizontal or vertical orientation. You can display colored
regions for comparison. Figure 5-29 shows a bullet gadget.

Figure 5-29
■

94

Displaying a horizontal bullet gadget

Cylinder
A cylinder gadget displays the value of a single data column as the fill level of
a vertical cylinder. Figure 5-30 shows a cylinder gadget.

Actuate BIRT Application Developer Guide

Figure 5-30
■

Linear gauge
A linear gauge gadget displays the value of one or more data columns as
needles on a horizontal scale. You can display colored regions for comparison.
Figure 5-31 shows a linear gauge gadget.

Figure 5-31
■

Displaying a linear gauge gadget

Meter
A meter gadget is an angular gauge that displays the value of one or more
data columns as dial values on a radial scale. You can display colored regions
for comparison. Figure 5-32 shows a meter gadget.

Figure 5-32
■

Displaying a cylinder gadget

Displaying a meter gadget

Sparkline
A sparkline gadget is a small variation of a line chart that displays the value of
a numeric data column and highlights the high, low, open, and close values.
You can group values with a second data column when displaying a data
cube. Figure 5-33 shows a sparkline gadget.

Figure 5-33

Displaying a sparkline gadget

Chapter 5, Visualizing data on a dashboard

95

■

Thermometer
A thermometer gadget displays the value from a single data column as the fill
level of a vertical thermometer. Figure 5-34 shows a thermometer gadget.

Figure 5-34

Displaying a thermometer gadget

Selecting data for measurement gadgets
You select data to display in Gadget Builder—Data when you create or edit a
measurement gadget. Choose a BIRT data object and select a data set, data model,
or data cube. Next, select a data column to display in the measurement gadget.
Meter and linear gauges can display one, two, or three different data columns.
Sparklines support using a second data column to group the primary data
column values. Figure 5-35 shows the data sources for a linear gauge gadget.

Figure 5-35

Selecting data to display in a linear gauge gadget

If hyperlinks exist in the data object file, they can appear in the measurement
gadget by selecting Gadget Builder➛Data➛Enable Interactivity. Hyperlinks
enable users to open a URI or drill through to another BIRT document file when

96

Actuate BIRT Application Developer Guide

choosing a value in the measurement gadget. This is similar to a hyperlink on a
web page.

Aggregating measurement data
When you display a data cube in a measurement gadget, you select from
aggregations that are included in the data cube. These aggregated fields are called
measures and were added to the data cube when it was created in BIRT Designer
Professional.
When you display a data set or a data model in a measurement gadget, you can
aggregate the field by selecting an aggregation function. You can use the count
and distinct count aggregate functions for data columns that contain non-numeric
values such as strings and dates. Table 5-4 shows the aggregation functions
available for numeric data displayed in a measurement gadget.
Table 5-4

Aggregate functions for measurement gadgets

Function

Description

Average

Returns the average of the values

Count

Returns the number of values, including duplicate values

Distinct Count

Returns the number of values, excluding duplicate values

First

Returns the first value among the values

Last

Returns the last value among the values

Max

Returns the largest value among the values

Min

Returns the smallest value among the values

Sum

Returns the sum of the values

Formatting measurement gadgets
You can format and enhance your gadget in Gadget Builder—Format. You can
show values on the measurement, change the size of the measurement, and
control the scale of the visualization by setting minimum and maximum values.
You can also change the number of tick marks to display and their position on the
visualization, except for the sparkline gadget, which displays open, close, high,
and low plot points in place of tick marks.
You can also change the font, font size, and font color used to display values in
measurement gadgets. Enable tooltips to display values when a mouse hovers
over points in the visualization.

Using regions
The bullet, linear gauge, and meter gadgets support highlighting multiple ranges
of values using regions. Regions is a formatting option where you determine the

Chapter 5, Visualizing data on a dashboard

97

start and end value, color, and name of each region. If a region overlaps another,
the last region that you create takes precedence. Figure 5-36 shows settings for the
Medium region.

Figure 5-36

Defining region values and color

Changing color
You can change the color of the bullet, cylinder, and thermometer gadgets.

Using pointers
The linear gauge gadget uses needles and a meter gadget uses dials as pointers to
indicate values. You can display the value next to these pointers and for linear
gauge gadgets, you can choose the position of these pointers on the gadget.

Enabling data selection
To enable interactive filtering, add data selection gadgets. Data selection gadgets
display unique values in a data set, data cube, or data model. These gadgets
enable users to select and search for data to display on the dashboard.
Link other gadgets to a data selection gadget to use the selected value as a filter of
the displayed data or to process the value with JavaScript code. For example, link
a chart gadget to a data selection gadget showing customer names. When the user
selects a customer name in the data selection gadget, the chart updates to show
the values related to the selected customer.
The following data selection gadgets are available:
■

98

Calendar
Calendar gadgets display dates from a data object as a calendar, where a user
can select day, month, or year. You can set a start and end date to limit user
selection to a specific time period. Calendar gadgets do not require a BIRT
data object to display choices to the user. You can choose default dates when
you create the calendar gadget. Figure 5-37 shows a calendar gadget.

Actuate BIRT Application Developer Guide

Figure 5-37
■

Figure 5-38
■

Displaying data in a check box gadget

Combo box
Combo box gadgets display values from a data object in a drop-down box.
This gadget supports manual typing and autosuggestion of values.
Figure 5-39 shows a combo box gadget.

Figure 5-39
■

Displaying dates in a calendar gadget

Check box
Check box gadgets display values from a data object with a check box next to
each value. Users can select multiple values. Figure 5-38 shows a check box
gadget.

Displaying data in a combo box gadget

Data version
Data version gadgets display available versions of BIRT data stores for a user
to choose. Changing a data store version causes gadgets to display values
from the selected data store. Figure 5-40 shows a data version gadget.

Chapter 5, Visualizing data on a dashboard

99

Figure 5-40
■

Displaying versions of a data store file in a data version gadget

List
List gadgets display data object values in rows. Users can search and select
multiple values. Press Ctrl while selecting multiple non-adjacent values. Press
Shift while selecting multiple adjacent values. Figure 5-41 shows a list gadget.
Search
values

Figure 5-41
■

Radio button
Radio button gadgets display values from a data object with a radio button
next to each value. Users can select a single value to include. Figure 5-42
shows a radio button gadget.

Figure 5-42
■

Displaying data in a radio button gadget

Selector group
Selector group gadgets enable users to select cascading values from multiple
fields and apply all their selected values at the same time. Each selection filters
the values displayed in the next field. Figure 5-43 shows a selector group
gadget.

Figure 5-43

100

Displaying data in a list gadget

Displaying data in a selector group gadget

Actuate BIRT Application Developer Guide

■

Slider
Slider gadgets display a range of values from a data object as a sliding bar
with tick marks next to known values. This gadget supports single and dual
selections using thumb selectors. Sliders do not require a BIRT data object to
display choices to the user. You can choose default values when you create the
slider. Figure 5-44 shows a slider gadget.

Thumb
selector

Figure 5-44

Displaying data in a slider gadget

Multiple data selection gadgets can link to each other to enable users to select
cascading information. For example, a list gadget showing customer names and a
list gadget showing order numbers can link together. When a user selects a
customer name, the order numbers from the selected customer appear in the list
gadget showing order numbers.
You can also link a report gadget to a data selection gadget if the displayed
report uses parameter values. For more information about linking options, see
Chapter 13, “Linking and scripting gadgets.”
How to create a data selection gadget

This procedure requires a dashboard you can edit. Create a new dashboard if one
does not already exist. To add a data selection gadget, complete these steps:
1 In the dashboard editor, select Insert➛Data Selector, and choose a data
selection gadget type. In this example, choose Insert➛Data Selector➛List.
2 Select the data to display in the data selection gadget by completing the
following steps:
1 In Data Selector Gadget Wizard—Data—Use Data, select a data source. If
no data source appears, choose New Data to select a BIRT data object from
available data objects in the BIRT project.
2 In Field, select a data column to display in the data selection gadget.
3 In Display field, select a data column to display in the data selection gadget
if it is different from the Field value.
4 In Sort direction, choose None, Ascending, or Descending to sort the data
in the gadget.
3 The following optional tasks are available when you create the data selection
gadget or after the gadget is added to the dashboard:
■

Specify gadget appearance, such as title and gadget size, in Data Selector
Gadget Wizard—General. Display a border, header, and menu icon.

Chapter 5, Visualizing data on a dashboard

101

■

Limit displayed data with filter conditions in Data Selector Gadget
Wizard—Filter.

■

Format the cross tab in Data Selector Gadget Wizard—Format. Each data
selection gadget has different formatting options. For example, in a list
gadget you can set a default value, limit the entries in the list, enable
multiple value selections, enable search, and format the values that appear
in the list.

4 Choose OK to create the new data selection gadget.
Enable interactive filtering by linking other gadgets to the data selection gadget.
After the data selection gadget is placed on the dashboard, it links to gadgets that
use the same data source. You can remove these links or add new ones.

Displaying data for user selection
A data selection gadget displays values from a BIRT data object. When you add
or edit a data selection gadget, you select data to display. Choose a BIRT data
object and select a data set, data cube, or data model. Next, select the name of a
data column to display in the data selection gadget. When you create a data
selection gadget, you can choose a default value. This value appears when the
dashboard is opened.
You can display a different value than what is published to the dashboard. This
can link different data sources together on the dashboard. For example, you add a
list gadget to display customer names from a client database. Next, set the list to
publish the customer’s account number instead of the customer’s name. A report
gadget displays orders from a sales database and links to the list gadget. When
the user selects a customer name, the report gadget runs a report using the
customer’s account number and displays the customer’s order history.
Figure 5-45 shows the data source setting for a list gadget that displays a list of
customer names but sends the customer number when a name is selected.

Value published
to linked gadgets
Value displayed
in gadget

Figure 5-45

Selecting data to display in a list gadget

Figure 5-46 shows the finished list gadget on the dashboard.

102

Actuate BIRT Application Developer Guide

Figure 5-46

Reviewing values in a list gadget

Formatting data selection gadgets
Each gadget type includes different formatting options to assist users in finding
and selecting values. You can format the displayed data values, set default values,
select a vertical or horizontal orientation, and limit the displayed values.
A combo box gadget supports autosuggest and allows typing options that can
assist users to type partial values and find possible value matches. For example,
when the allow typing and autosuggest options are enabled, a user can type the
letters po in a combo box displaying countries. The values Poland and Portugal
appear for the user to select from because both values start with the letters po.
A list gadget supports multi-value selections and searching for values in the
gadget.

Formatting number values
Using Format as, you can change the look of displayed values. Number values
support the following formatting options: general number, currency, fixed,
percent, scientific, and custom options.

Formatting date-and-time values
You can display date-and-time values in different formats such as short, medium,
long, and custom formats.

Formatting string values
String values support uppercase, lowercase, and custom formatting options.

Using a data version gadget
Data version gadgets display the version number and version name of multiple
BIRT data object store files for a user to select. When a user selects one of the
versions, gadgets displaying values from the same BIRT data object store file
display values from the selected version of the BIRT data object.

Chapter 5, Visualizing data on a dashboard

103

For example, a dashboard displays sales results in a chart and table from a data
object of this year’s sales data. When the user selects last year’s data object in the
data version gadget, the dashboard displays the data from last year in the chart
and table. Figure 5-47 shows a finished data version gadget on the dashboard.

Figure 5-47

Displaying versions of a data store file as a list

Multiple versions of the same data object are supported only on an iHub server.

Selecting a data object
When you select a BIRT data object store file to display in a data version gadget,
the version number and version name of each version of that file appears in the
data version gadget. For example, if you choose to display the data store file
Sales.data in a data version gadget, all versions of the Sales.data file are displayed
in the data version gadget.

Choosing a selector type
You can display data version gadgets in combo box or list types using Data
Selector Gadget Wizard. Choose Type to select how the data version gadget is
displayed.

Formatting a data version gadget
When a data version gadget displays radio buttons, you can format the content of
the gadget. Select the number of choices per row and whether the gadget displays
choices in a horizontal or a vertical display. You can also limit how many different
versions are displayed.

Organizing multiple user selections
Gadgets can combine multiple user selections on a dashboard in the following
ways:

104

■

Cascade

■

Group

Actuate BIRT Application Developer Guide

■

Apply button

■

Parameter

The current selections gadget from the dashboard menu can display or clear all
data selections on the dashboard at the same time or clear selected values, as
shown in Figure 5-48.

Figure 5-48

Displaying a current selections gadget

Building cascade selections
You can link data selection gadgets together so that choices in one gadget filter
the available choices in another gadget. Each user selection is published to all
linked gadgets, and users can make selections in any order. Selection gadgets
update the dashboard after each user selection in the gadget.
For example, if you have three lists, one for country, city, and customer name on a
dashboard with a chart, selecting a country updates the chart. Selecting a city
updates the chart, and selecting a customer name also updates the chart. The
following solutions avoids unnecessary updates to the dashboard:
■

Remove the links in the country list to the city and customer names. Selections
in the other gadgets do not update the country list.

■

Remove the links in the chart to the country and city gadget. Leave only the
link to the customer name. The chart only updates when a customer name is
chosen.

You can also use a selector group or apply gadget to send multiple values at the
same time and avoid unnecessary dashboard updates.

Building group selections
Use the selector group gadget to display related user selections and enable users
to finish all selections before updating linked gadgets. Users must make their
selections in a fixed order. When the user chooses Apply, the dashboard updates
to display data related to the user selection. This gadget displays values from a
single BIRT data object.

Chapter 5, Visualizing data on a dashboard

105

Figure 5-49 shows a finished selector group gadget on the dashboard.

Search fields

Figure 5-49

Displaying a selector group gadget on the dashboard

Using a selector group gadget
Selector group gadgets display multiple values as cascading choices for users. A
user picks from related values, one after the other in the order displayed, and
publishes those values to linked gadgets when all selections are finished. When
the user chooses Apply, gadgets that are linked to the selector group update to
display data related to the user selection. This avoids unnecessary updates to the
dashboard. Other data selection gadgets apply the changes each time a user
makes a selection.

Selecting fields to display
All data displayed in a selector group gadget comes from a single BIRT data
object. After selecting the data object, you can select one or more data fields to
display together. You can sort and format each data field differently. Each data
field filters the values displayed from the next field.
For example, if the first data field is country and the second is city, the gadget
displays countries for a user to select. Each selected country displays city names
from the selected countries.
Figure 5-50 shows the selection of data to display in a selector group gadget.

Figure 5-50

106

Selecting data to display in a selector group gadget

Actuate BIRT Application Developer Guide

Choosing a selector type
You can display selector group gadgets in combo box or list types using Data
Selector Gadget Wizard. Choose Type to select how the selector group gadget is
displayed.

Formatting a selector group gadget
Use Format from Data Selector Gadget Wizard to change the selector group
orientation, set a limit to the quantity of displayed values, and change the format
of each displayed field. A list type also supports multi-value selections and
searching for values in the gadget, as shown in Figure 5-51.

Figure 5-51

Formatting a selector group gadget using the list type

Each displayed field also supports formatting, depending on the content of the
field. For example, country names can display in capital letters and phone
numbers can display using the regional phone number format.

Using an apply button gadget
Data selection gadgets update all linked gadgets after each user selection. Use the
apply button gadget to collect and hold user selections from multiple data
selection gadgets. When the user makes selections, the selections are held by the
apply button gadget until the user chooses the apply button. Other gadgets link
to the apply button and receive the user selections only when the user chooses to
apply their selected values.
After adding data selection gadgets and one or more apply button gadgets to a
dashboard, you use Link from the gadget menu to choose which apply button to
forward user selections. Figure 5-52 shows a chart using an apply button with the
name Send.

Chapter 5, Visualizing data on a dashboard

107

Select an apply
button for the
selected link

Figure 5-52

Setting a gadget to use an apply button

Figure 5-53 shows an apply button gadget holding user selections until the user
chooses the apply button. The chart updates only after the user chooses the apply
button.

Figure 5-53

Using an apply button gadget with multiple data selection gadgets

You can set the button name and change the general options of the apply button
gadget to display it with or without a gadget header and border.
For more information about linking gadgets together, see Chapter 13, “Linking
and scripting gadgets.”

Using parameter selections
Link to a parameter gadget to receive user-selected parameter values. Parameter
gadgets display parameters from BIRT design files. If the parameter includes
filter conditions such as from a dynamic filter parameter, then you must process

108

Actuate BIRT Application Developer Guide

the selected condition using JavaScript. The BIRT document that contains this
parameter can already process the selected condition but a visualization gadget,
such as a chart, requires additional JavaScript to handle the selected condition.
For example, a user selects the following values from a parameter gadget: the
filter condition greater than, and the value 300. A chart is linked to this parameter
gadget and receives the selected condition and value, but chart gadgets require
only a value, not a filter condition. Figure 5-54 shows a parameter gadget
displaying parameters from a BIRT design file.

Figure 5-54

Displaying report parameters in a parameter gadget

Add JavaScript to the chart gadget to extract the value from the user selection and
to optionally process or remove the selected filter condition. For more
information about parameter gadgets, see Chapter 4, “Displaying a file on
a dashboard.”

Chapter 5, Visualizing data on a dashboard

109

110

Actuate BIRT Application Developer Guide

Chapter

6
Chapter 6

Designing a report

This chapter contains the following topics:
■

Formatting features in BIRT Designer Professional

■

Creating an accessible PDF

■

Selecting features for interactive viewing

■

Removing the default themes

■

Hiding columns in a table

■

Using a Quick Response code to link to content

■

Designing for optimal viewer performance

Chapter 6, Designing a report

111

Formatting features in BIRT Designer Professional
BIRT Designer Professional supports all the formatting features available in the
open-source version, and provides additional features. The reports you create
using BIRT Designer Professional are typically published to the BIRT iHub, where
they can be viewed in Interactive Viewer, opened in Report Studio, or added to a
dashboard. Often, when designing a report, you consider how the report is
viewed and used by these applications.
This chapter describes the additional report formatting options in BIRT Designer
Professional. For information about other formatting options, see BIRT: A Field
Guide. This chapter also describes the design issues to consider when designing
reports that users view in the web viewer.

Creating an accessible PDF
BIRT Designer Professional supports the creation of accessible PDF content based
on the ISO 14289-1 (PDF/UA-1) specification. When this feature is enabled in a
report design file, PDF files created from the design file are appropriately tagged
for use with assistive reading technology for the visually impaired. The
appropriate license is required to generate accessible PDF on the iHub server.
Report items include the following accessible properties:
■

Reading order
Indicates the order the report item is read in relation to other elements on the
page

■

Alternate text

■

Tag types

■

Language

■

URL links for images and charts

The following accessible tags types are set by the BIRT developer:

112

■

artifact elements that do not fit into other tags

■

div for division elements for generic block-level

■

figure for images

■

H1 for level 1 headings

■

H2 for level 2 headings

■

H3 for level 3 headings

Actuate BIRT Application Developer Guide

■

H4 for level 4 headings

■

H5 for level 5 headings

■

H6 for level 6 headings

■

p for text as a paragraph

■

sect for containers of other elements and items

■

table for text in a table format

See the following web site for additional information about accessible PDF
documents:
http://adobe.com/accessibility
http://www.adobe.com/enterprise/accessibility/pdfs/acro7_pg_ue.pdf
How to enable accessible PDF output

1 Right-click in the report design and choose PDF Accessibility Properties, as
shown in Figure 6-1.

Figure 6-1

Choosing PDF Accessibility Properties

If PDF accessibility is currently disabled and you are asked to enable it,
choose Yes.
2 Verify the reading order of the report items in the BIRT design using Up,
Down, Top, Bottom. Choose Reorder to reset the order of the report items.
3 Select root document node and set a language and title for the entire
document.
4 Select each report item in the BIRT design and set the accessibility properties.
Figure 6-2 shows the accessibility properties for a text item.

Chapter 6, Designing a report

113

Expression
builder

Figure 6-2

Setting PDF accessibility properties

If a report item has a language value, this value takes precedence over the
language setting for the entire document.
Use the Expression builder to create a dynamic value for the alternate text. If
you choose to use a static value, type the value between a beginning and
ending quotation mark.
5 Choose OK.
6 Create a sample PDF to verify that the accessibility features are enabled. Use
one of the following methods to verify that the PDF file is accessible:
■

Load the PDF into a screen reader software, such as JAWS or NVDA.

■

Load the PDF into Adobe Acrobat Professional and run the Accessibility
check.

■

Load the PDF into a PDF checking software, such as PDF Accessibility
Checker, to verify that the PDF meets accessibility requirements.

Selecting features for interactive viewing
You can select which interactive features are available when a BIRT design file is
displayed in Interactive Viewer. For example, you can limit editing, exporting, or
filtering options in a report. A user cannot see disabled interactive features when

114

Actuate BIRT Application Developer Guide

viewing a report. You can also start a report in interactive mode and remove the
option to disable it.
Using the onContentUpdate event in client scripts, you can add script using the
uiOptions class to change the interactive options of a report. This event is visible
in the Script page of a BIRT design, as shown in Figure 6-3.

Figure 6-3

Customizing interactive features

Interactive scripting sample 1
The interactive viewer menu shown in Figure 6-4 shows the following scripts
changing interactive features:
■

A script removes the user option to enable interactivity.

■

A script removes the user option to export report content and data.

■

A script enables interactivity when the BIRT design is viewed.

Figure 6-4

Custom interactive viewer menu

The script written to change the toolbar menu appears in Listing 6-1.

Chapter 6, Designing a report

115

Listing 6-1

Removing edit report and export options

// Get the Viewer's current UI Options
var uiOptions = this.getViewer().getUIOptions();
// Remove ability for user to export, extract,
// and change interactivity options
uiOptions.enableExportReport(false);
uiOptions.enableDataExtraction(false);
uiOptions.enableEditReport(false);
// Set the modified UI Options back into the Viewer
this.getViewer().setUIOptions(uiOptions);
// If Interactivity is not enabled, enable it
if (!this.getViewer().isInteractive())
this.getViewer().enableIV();

Interactive scripting sample 2
The interactive context menu shown in Figure 6-5 shows the following scripts
changing interactive features:
■

A script removes the user option to enable interactivity.

■

A script removes the user option to filter, group, and aggregate values in the
report.

■

A script enables interactivity when the BIRT design is viewed.

Figure 6-5

Custom interactive context menu

The script written to change the context menu appears in Listing 6-2.
Listing 6-2

Removing filter, group, and aggregation options

// Get the Viewer's current UI Options
var uiOptions = this.getViewer().getUIOptions();
//
//

116

For security reasons, enable Interactive Viewer with only a
fixed set of interactive functionality to the users.

Actuate BIRT Application Developer Guide

//hide Enable/Disable Interactivity
uiOptions.enableEditReport(false); //hide interactivity option
uiOptions.enableGroupEdit(false); //hide move/add/delete Group
uiOptions.enablePageBreak(false); //hide page break
uiOptions.enableAggregation(false); //hide Aggregation
uiOptions.enableFilter(false); //hide Filter
// Set the modified UI Options back into the Viewer
this.getViewer().setUIOptions(uiOptions);
// If Interactivity is not enabled, enable it
if (!this.getViewer().isInteractive())
this.getViewer().enableIV();

Embedding HTML5 content
You can display HTML5 tags in a BIRT design using a text item or a dynamic text
item. These tags are used when the BIRT design is viewed or output as HTML.
For example, HTML5 tags that display a canvas tag are used when the design file
is displayed or output as HTML but are not displayed when the design file is
output as a PDF or Word document.
This content appears in web browsers that support HTML5.
Figure 6-6 shows the HTML5 canvas tag receiving formatting using JavaScript.

Figure 6-6

Embedding HTML5 tags in a text item

Figure 6-7 shows the HTML5 content in Interactive Viewer.

Figure 6-7

Viewing HTML5 content in Interactive Viewer

Chapter 6, Designing a report

117

Removing the default themes
By default, new reports that you create use a set of themes that apply formatting
to charts, gadgets, tables, and cross tabs. Figure 6-8 shows a table with the default
formats.

Figure 6-8

Table with the default formats

The themes are defined in a library, ThemesReportItems3.rptlibrary, which is
added to every new report.
To apply your own themes or styles in a report, disable the default themes by
doing one of the following:
■

When creating a new report using the New Report wizard, remove the
selection for Include the default themes. Figure 6-9 shows this option selected,
which is the default.

Option to include or
exclude default themes

Figure 6-9

118

Include the default themes selected by default

Actuate BIRT Application Developer Guide

■

If a report already includes the default themes, in the Outline view, expand
Libraries, then right-click ThemesReportItems3 and choose Remove Library,
as shown in Figure 6-10.

Figure 6-10

Removing ThemesReportItems3.rptlibrary from a report

The previous procedures remove all the default themes from a report. You can,
however, choose to remove themes from specific report elements while
maintaining default themes for other report elements. Figure 6-11 shows an
example of removing a default theme, ThemesReportItems3.default-table, from a
table by setting the Theme property to None.

Figure 6-11

Setting a table’s Theme property to None

Hiding columns in a table
There are two ways to hide a column in a table. You can:
■

Set the column’s Display property to No Display.

■

Set the column’s Visibility property to Hide.

Chapter 6, Designing a report

119

Use the Display property if you are designing a report for Interactive Viewer and
you want to hide one or more columns when the report is first displayed in
Interactive Viewer. After selecting a column, the Display property is available
under Advanced properties in Property Editor, as shown in Figure 6-12.

Figure 6-12

Display property of a table column set to No Display

Use the Visibility property to hide a column based on the output format or on a
specific condition. For example, you can hide a column in all formats except PDF,
or hide a column if it contains no values. The Visibility property is available
under Properties in the Property Editor, as shown in Figure 6-13.

Figure 6-13

Visibility property of a table column set to Hide Element

In releases prior to 11SP1, columns hidden by the Visibility property were
available for display in the Interactive Viewer. In releases 11SP1 and later, they are
not. Reports created in a release prior to 11SP1 and which used the Visibility
property to hide or display a column now exhibit different behavior in Interactive
Viewer. To restore the original behavior, change the report to use the Display
property instead of the Visibility property.

120

Actuate BIRT Application Developer Guide

Using a Quick Response code to link to content
A Quick Response (QR) code is a type of two-dimensional bar code that contains
encoded information. Figure 6-14 shows an example of a QR code.

Figure 6-14

A QR code

QR codes are used by a wide range of applications targeted to document
management and mobile phone users. QR codes can store URLs, business card
information, contact details, meeting schedules or any kind of text. Use a QR code
in a report to provide contact information or links to other reports. Mobile phone
users who have a QR code reader on their phone can scan the image of a QR code
to display the contact information or open a report.
BIRT Designer Professional includes a QR code generator, for generating
QR codes. To insert a QR code in a report, insert an image element to display the
QR code. In the image’s onCreate or onRender event, write code to dynamically
create the QR code.
To test QR code generation in BIRT Designer Professional, add core.jar or the
most recent version of it to your Resources folder. This JAR file is available from
the ZXing library at following URL:
http://code.google.com/p/zxing/

The code example in Listing 6-3 creates a QR code that, when scanned, opens a
report, qrreport.rptdesign, on a BIRT iHub.
Listing 6-3

Code to create a QR code that opens a report

var size = 350; // image width and height in pixels
var bgnd = new Packages.java.awt.Color(1.0, 1.0, 1.0); // white
background
var fgnd = new Packages.java.awt.Color(0, 0, 0); // black
foreground
// Report URL to encode.
var message = "http://athena:8700/iportal/
executereport.do?__executablename=/
qrreport.rptdesign&invokeSubmit=true;"
var writer = new Packages.com.google.zxing.qrcode.QRCodeWriter();
var matrix = writer.encode(message,
Packages.com.google.zxing.BarcodeFormat.QR_CODE, size, size);

Chapter 6, Designing a report

121

var bi = new Packages.java.awt.image.BufferedImage(size, size,
Packages.java.awt.image.BufferedImage.TYPE_INT_RGB);
var g = bi.getGraphics();
g.setColor(bgnd);
g.fillRect(0,0,size,size);
g.setColor(fgnd);
for (var y = 0; y < size; y++) {
for (var x = 0; x < size; x++) {
if (matrix.get(x, y)) {
g.fillRect(x, y, 1, 1);
}
}
}
baos = new Packages.java.io.ByteArrayOutputStream();
Packages.javax.imageio.ImageIO.write(bi, "png", baos);
this.data = baos.toByteArray();

QR codes support up to 4,296 characters. The higher the number of characters,
the higher the resolution of the QR code. Note, however, that low-resolution
mobile phone cameras might have difficulty reading high-resolution codes.

Designing for optimal viewer performance
Actuate BIRT viewers support a feature called progressive viewing, which
displays the first few pages as soon as they are generated instead of waiting until
the entire report is generated. For long reports, this feature can significantly
reduce the amount of time a user waits before the first page appears.
The design and functionality of a report affect the time it takes for BIRT to
generate the initial pages. A major factor that hinders performance is the retrieval
of data from an underlying data source, and the storage and processing of all that
data before BIRT can render the first report page. Optimal viewing performance
occurs when BIRT renders a page as soon as the data for that page has been
retrieved, before data for the entire report is processed.
To achieve optimal progressive viewing performance, observe the following
guidelines:
■

Ensure that data sets return only the data that you want to display in each
report element (tables, lists, or charts).
For example, if you must filter, group, sort or aggregate table data, perform
these tasks at the data source level. To manipulate data at the table level, BIRT
not only has to retrieve and store more data, it also has to spend more time
processing the data.

122

Actuate BIRT Application Developer Guide

■

If, as recommended in the previous point, you create a data set to return data
rows that are already grouped, disable the group sorting in BIRT, which
otherwise occurs when you create a group using the group editor.
To disable group sorting in BIRT, select the table in which grouping is defined.
In Property Editor, choose Advanced, then set the Sort By Groups property to
false.

■

If creating nested tables (a table in another table) as is common in master detail
reports, create a data set for each table instead of creating a single data set that
both the outer and inner tables use.

■

Avoid the following items:
■

Top n or bottom n filters. These filters require that BIRT process an entire
set of data to determine the subset of data to display.

■

Aggregations that require multiple passes through data, for example,
subtotals as a percentage of a grand total.

■

Summary tables. Even though these tables do not display detail rows, BIRT
must still process all the detail rows to calculate and display the summary
data.

Chapter 6, Designing a report

123

124

Actuate BIRT Application Developer Guide

Part

Part 3

Three

3

Building application components

Chapter

7
Chapter 7

Building interactive maps
and gadgets

This chapter contains the following topics:
■

About maps and gadgets

■

Adding a gadget or map

■

Providing data to a map

■

Validating map data

■

Formatting a map

■

Adding scripts to a map

■

Formatting a gadget

Chapter 7, Building interactive maps and gadgets

127

About maps and gadgets
BIRT Designer Professional supports the creation of maps and gadgets. Maps
enable you to visualize geographic data. Gadgets are visualizations that measure
a value in a visual range.
Maps are vector maps suitable for displaying data by geographical divisions,
such as population distribution, electoral results, office locations, survey results,
weather patterns, and real-estate sales. BIRT Designer Professional provides
hundreds of maps, including maps of the world, continents, countries, European
regions, USA states, and so on. Figure 7-1 shows examples of maps.

Figure 7-1

128

US map and Europe map

Actuate BIRT Application Developer Guide

Like charts, measurement gadgets display data graphically and with animation.
The difference between the two elements is that a gadget typically displays a
single value whereas a chart plots multiple values for comparison. The supported
gadgets, shown in Figure 7-2, are meter, linear gauge, sparkline, cylinder,
thermometer, and bullet.

Figure 7-2

Measurement gadgets

Adding a gadget or map
The procedure for creating a gadget or map is the same as the procedure for
creating a BIRT chart. To create a gadget or map, perform the following tasks:
■

Drag the map or gadget element from the palette and drop it in the report.

■

Choose a map or gadget type.

■

Specify the data to present.

■

Format the gadget or map.

The formatting options available to the gadgets are different from the formatting
options available to BIRT charts. While many of the chart parts and formatting
attributes are the same, a measurement gadget supports visual effects to parts of
the gadget. A map enables you to highlight locations and values on the map.
Figure 7-3 shows an example of the Select Map page.

Chapter 7, Building interactive maps and gadgets

129

Figure 7-3

Previewing a selected map

Providing data to a map
Each map defines different location entities depending on the map. The names of
these entities must match location names in your data for the values to display
correctly. Check with your database administrator if you need assistance to find
your location data. Each map is made up of smaller location entities. For example,
a world map displays continent entities, a map of Europe displays country
entities, and a country map displays different entities such as provinces, counties,
regions and states, depending on the structure of the country. Each location entity
displays numeric and color values using values from your data source.
After you match location data to the location entity of the map you select a value
to display on map locations.

130

Actuate BIRT Application Developer Guide

Figure 7-4 shows an example of the Select Data page.

Entity

Figure 7-4

Showing available data to display on the map

Validating map data
Use the Validate Data page to match your location data to location entity names
in a map and to verify if the map displays any entities that are not in your data.
For example, if your data uses foreign names or alternate names for a location,
you can match these to a location in the map.

Chapter 7, Building interactive maps and gadgets

131

You can export matching entity values to a text file using Save Rule and import
matching entity rules from a text file using Load Rule. Figure 7-5 shows an
example of the Validate Data page.

Figure 7-5

Matching data columns with map locations

Formatting a map
Like the standard chart builders the map builder provides a separate page for
formatting tasks. Figure 7-6 shows an example of the Format Map page
displaying the general properties for a map.
Format Map lists formatting properties for each visual part of a map.

General properties
The general properties of a map control overall appearance, such as location
colors, hover style, background and border style. General properties can also
define the connector line, the number format, and the map legend. For example,
Figure 7-7 shows custom background, outline, connector line, and hover effect
color.

132

Actuate BIRT Application Developer Guide

Categories
of formatting
properties

Figure 7-6

A map and its general formatting properties

Figure 7-7

Sample formatting of a map’s general properties

Table 7-1 shows all the general properties.

Chapter 7, Building interactive maps and gadgets

133

Table 7-1

General properties

Property

Usage

Background Color

Sets the background color of the map.

Canvas Border Color

Specifies the color of the border around the entire map.

Caption

Adds a caption to the map.

Connector Line Color

Specifies the color of the line between the entity name and the
entity location.

Drop Shadow

Enables or disables the appearance of a shadow below the map.

Entities Border Color

Specifies the color of the border around the location entities.

Entities Fill Color

Specifies the color in the border of an entity location.

Font Color

Specifies the color of the text.

Font Faces

Specifies the name of the font.

Font Size

Specifies the font size in points.

Format Number

Enables or disables number formatting.

Format Number Scale

Abbreviates a number to an appropriate number factor. For
example, 10,000 becomes 10K.

Fraction Digits

Specifies the number of digits displayed after the decimal point.

Hover Effect Color

Specifies the color of the location entity under the mouse pointer.

Include Name in Labels

Enables or disables the display of location entity names.

Include Value in Labels

Enables or disables the display of the location entity’s value.

Legend Caption

Specifies the name displayed above the map legend.

Legend Position

Specifies the position of legend in relation to the map.

Number Prefix

Specifies a text value to display before a number.

Number Suffix

Specifies a text value to display after a number.

Short Name in Tool Tip

Enables or disables the display of the short name of a location
entity in a tooltip. For example, NA is the short name of North
America.

Show Border

Enables or disables the border around the map.

Show Entity Tool Tip

Enables or disables the display of a tooltips when a mouse pointer
is placed over the entity.

Show Labels

Enables or disables the display of labels.

Show Legend

Enables or disables the display of a legend when highlight ranges
exist.

Use Hover Effect

Enables or disables the highlighting of a location entity when the
mouse pointer moves over the entity.

134

Actuate BIRT Application Developer Guide

Highlights properties
Use highlights to change the color of map entities based on defined ranges of
values. For example, sales values in a certain range can display as yellow for low
sales and green for expected sales. When ranges are defined for highlights, the
color assigned to a range can display in a legend with the range description or
value range. The legend name and its position are defined in the general
properties of the map.
Figure 7-8 shows highlights properties set for a map.

Figure 7-8

A map and its highlights formatting properties

When ranges are defined, you can display an interactive gradient legend that
enables users to highlight map location entities using a start and an end needle.
Location entities with values between the two needles display on the map, other
location entities are hidden.

Chapter 7, Building interactive maps and gadgets

135

Figure 7-9 shows a gradient legend with multiple ranges of values.
Start label
Range value
Needle
Range
display name
End label

Figure 7-9

Using an interactive gradient legend with value ranges

Table 7-2 shows all the highlight properties and lists the gadgets to which they
apply.
Table 7-2

Highlights properties

Property

Usage

Color

Specifies the color of the region.

Display

Specifies the name of the region to display in
the legend.

Enable Gradient Legend

Enable the gradient legend.

End Label

Specifies the name to display at the end of the
gradient legend.

Gradient Legend Color

Specifies a starting color for the gradient
legend.

Max

Specifies the value where the range ends.

Min

Specifies the value where the range starts.

Start Label

Specifies the name to display at the start of the
gradient legend.

Rendering platform
BIRT Designer Professional uses a third-party map library from Fusion Charts, to
render maps. This map library is integrated into BIRT Designer Professional’s
standard map builder, where you create maps using the familiar user interface.
Fusion Charts also provides a full API, which you can use to programmatically
add, remove, or modify map elements after creating the map in the map builder.
Access to the Fusion Charts API is through the map builder’s script editor.

136

Actuate BIRT Application Developer Guide

Adding scripts to a map
You can write scripts in JavaScript that specify the task to perform when a
particular event occurs. This type of script is called an event handler. Like BIRT
and HTML5 charts, maps support two types of event handlers:
■

Event handlers that respond to user interactions, such as a mouse click on a
location when viewing the map. For example, you can create an event handler
to link to a report when a user selects a location in a map.

■

Event handlers that occur before BIRT renders the map. Use this type of event
handler to conditionally change map elements before the map is generated.
For example, you can add markers and connection lines to cities where you
have offices.

For both types of event handlers, you use the script editor in the chart builder, as
shown in Figure 7-10. To launch the script editor, choose the Format Map tab.

Choose Format
Map to open
the script editor

Choose
Interactivity to
write an event
handler for a
user action
Choose Script
to write an
event handler
for a map event

Figure 7-10

Script editor displaying the UI for writing a user action handler

To create an event handler that responds to a user interaction, choose
Interactivity. To create an event handler that responds to a chart event, choose
Script, as shown in Figure 7-10.

Chapter 7, Building interactive maps and gadgets

137

Writing event handlers that respond to user
interactions
Depending on what you want to accomplish, you can create some of these
interactivity event handlers without scripting. For typical event handlers, the
script editor in the map builder simplifies the process by providing a list of
actions. Choose an action, such as Show Tooltip or Mouse Click. Selecting Mouse
Click enables the action types Hyperlink or Invoke Script. Select Hyperlink to link
to a URI, internal bookmark or drill-through report. To implement a custom
action, choose Invoke Script, then write JavaScript code. For maps, this code can
use the Fusion Charts Map API.

Adding tooltips to a map
Tooltips display values when the user places the mouse pointer over a map
location. This can display additional information about a location such as its full
name and the value displayed in the location.
Figure 7-11 shows an example of an event handler that manages the Show Tooltip
action. In this example, the tooltip is set to display the data value, which is
typical. You can change the Tooltip Text to create your own tooltip values using
the expression builder.

Expression
builder

Figure 7-11

138

Script editor displaying the tooltip event handler

Actuate BIRT Application Developer Guide

Adding hyperlinks to a map
You can create hyperlinks to external content such as a document or web page, to
a different section in the same report, and to a section in a different report. For
example, you can create a hyperlink that opens a new map of country locations
when a user selects a continent.
Choose Edit base URL to access all hyperlink options. These options are the same
as hyperlink options for charts. For more information about adding hyperlinks to
BIRT report items, see BIRT: A Field Guide.
Figure 7-12 shows an example of a mouse click event handler that creates
hyperlinks for locations on the map.

Edit hyperlink
options
Query string
field names

Figure 7-12

Adding hyperlinks to map locations

You can also add query string fields to any URL created by the mouse click action.
This enables you to create custom URLs for each location on the map. When you
type a field name for the category and value of the selected location a query string
using the selected name and value are appended to the base URL. The base URL
is defined in Edit base URL.

Chapter 7, Building interactive maps and gadgets

139

For example, if you type location in Category and you type sold in Value, then
any URL that is generated from the mouse click event includes location and sold
in the URL as a query string in the following format:
?location=&sold=

When the user selects a location,  is replaced with the name of the
location and  is replaced with the value of the location. If the user selects
the North American continent which is displaying 10,000 units sold, the
following query string is generated and appended to the base URL:
?location=NA&sold=10000

If the base URL is http://webserver.com/ then the URL created for the user
selection in this example is:
http://webserver.com/?location=NA&sold=10000

If you need to create more complex URLs, such as to open another BIRT
document or file, you can leave the query string names empty and choose Edit
base URL for additional hyperlink options.

Adding interactive script to a map
You can add your own JavaScript that runs at the selected map action. Figure 7-13
shows an example of an event handler that adds interactive script to locations on
the map. You can add JavaScript that starts when a user selects a location on the
map.

Using event handlers before map generation
Unlike event handlers that respond to user interactions with the map, the event
handlers that you write require programming in JavaScript. You also have to
learn the Fusion Charts API to know what map options you can manipulate and
how.
In the script editor, you select a map function, such as handleMap( ) or
handleData( ), then you write code that performs a specific task or tasks before
the map is rendered. These event handlers execute on the client-side.
Write client-side scripts using the script editor accessible from the Format Map
tab in the map builder. Write server-side scripts using the script editor accessible
from the Script tab in the report editor. Only the following server-side event
functions are supported for maps: onPrepare( ), onCreate( ), onRender(), and
onPageBreak( )
This section provides information about writing client-side event handlers for
map events. For information about writing server-side event handlers, see
Integrating and Extending BIRT.
For documentation about the Fusion Charts API, go to the following location:
http://docs.fusioncharts.com/maps/Contents/DataFormats/XML.html

140

Actuate BIRT Application Developer Guide

Expression
builder

Figure 7-13

Adding interactive script to the mouse click action

About the map functions
Table 7-3 lists the map functions available before the map is rendered.
Table 7-3

Map event functions

Map functions

Description

handleMap(map)

Called to change map formats

handleData(data)

Called to change data

handleMarkers(markers)

Called to add markers or pins

handleColorRange(colorrange)

Called to add color ranges

handleEntityDef(entitydef)

Called to change entity definitions

Setting map options through scripting
The map event functions are called after BIRT generates the static JavaScript
options, which are based on the map’s data and formatting options set in the map
builder. Use the map event functions to add map options that Fusion Charts
provides, but that are not available through the map builder’s format page, such
as adding custom markers or changing the name of location entities.

Chapter 7, Building interactive maps and gadgets

141

For example, Fusion Charts provides an option to change the background of a
legend on a map. To remove the legend’s background color set the transparency
value to zero using the following code:
handleMap: function(map)
{
map.legendBgAlpha = 0;
},

As the code example shows, handleMap( ) receives a map object. You use this
map object to configure map options. When you type the word, map, followed by
a period (.), the script editor displays a list of options, as shown in Figure 7-14.
Click an option to view summary information about it. Double-click an option to
add it to your code.

Figure 7-14

The script editor displaying the available options

How to preview formatting changes on a map

You can preview your formatting changes in Format Map. This example uses a
world map and changes the location entity names displayed in the map.
1 In Format Map, choose Script to add scripts to the map.
2 In Script, choose handleEntityDef, as shown in Figure 7-15.

142

Actuate BIRT Application Developer Guide

Figure 7-15

Adding script to a map

3 Delete the following text:
//Example:
entitydef.push({internalId:'AU',lName:'Oceania',sName:'OC'});

4 Type the following script where the example script was removed:
entitydef.push({internalId:'NA',lName:'North America',
sName:'North{br}America'});
entitydef.push({internalId:'AF',lName:'Africa',
sName:'Africa'});

5 Select Preview and choosing Refresh in the Format Map tab, as shown in
Figure 7-16. The new labels appear in the map preview.

Figure 7-16

Previewing the map after adding scripts

Chapter 7, Building interactive maps and gadgets

143

6 Choose Finish to save the map or Cancel to delete it.

Using map markers and connection lines
You can create your own custom defined markers on a map using scripts. Custom
markers include changing the color and size of a default marker like a circle or
triangle. Custom markers can also display images. After defining the shape of the
map marker, you can define the x-axis and y-axis location of the marker on the
map and give it a label. Any two markers can also display a connection line
between the markers.
The following script enables custom markers, assigns each one a different shape,
and draws a connector line between the two markers:
handleMarkers: function(markers)
{
markers.shapes = [];
markers.shapes.push({id: 'Airplane', type: 'image', url: 'http:/
/urup:8700/iportal/resources/airport.png', labelpadding:
'10'});
markers.shapes.push({id: 'myCustomShape', type: 'circle',
fillcolor: 'FFFFFF,333333', fillpattern: 'radial', radius:
'3'});
markers.definition.push({id: '1', x: 233, y: 205, label:
'Seattle', labelpos: "top"});
markers.definition.push({id: '2', x: 719, y: 192, label:
'Spokane', labelpos: "top"});
markers.application.push( {id: '1', shapeid: 'Airplane'});
markers.application.push( {id: '2', shapeid: 'myCustomShape'});
markers.connectors = [];
markers.connectors.push({from: '1', to: '2', dashed: '1', color:
'00577F', alpha: '40'});
}

Using images for a custom marker requires a URL address to the image location.
Use an absolute path URL for the marker image enables PDF exports of the map
to include the marker image. Using an absolute path URL also enables the marker
image to display in the BIRT Designer Professional map preview. Using a relative
path URL enables deployment of the marker image inside a BIRT application but
limits preview and export options.
Figure 7-17 shows an example of using script to add custom markers to a map.
This example uses an absolute path URL to display the custom marker image. In
this example http://urup:8700/iportal/resources/airport.png is the URL
address to an image file that is copied directly to the a folder in Visualization
Platform. This image is not in a volume.

144

Actuate BIRT Application Developer Guide

Figure 7-17

Adding custom markers to a map

If your map is part of a BIRT application you can save the image inside the same
application folder and use a relative URL to the image. In this case you can only
preview the image when viewing the map as a BIRT application, either in BIRT
Designer Professional or in Visualization Platform.
For example, you have an airport.png image file that you want to display as a
marker on a map. The image is in an images folder inside the application. Using
the BIRT application URL conventions, the relative URL path to the image is:
apps/MapMarkers/images/airport.png

The following script loads an image as a custom map marker using a relative
URL:
markers.shapes.push({id: 'Airplane', type: 'image', url: 'apps/
MapMarkers/airport.png'})

Chapter 7, Building interactive maps and gadgets

145

Formatting a gadget
Like the standard chart builders the gadget builder provides a separate page for
formatting tasks. Figure 7-18 shows an example of the Format Gadget page
displaying the general properties for a linear gauge.

Categories
of formatting
properties

Figure 7-18

A linear gauge and its general formatting properties

Format Gadget lists formatting properties of each visual part of a gadget. As
Figure 7-18 shows, for a linear gauge, you can format its scale, needle, numbers,
regions, ticks, thresholds, and so on. Each gadget has a different set of formatting
properties, which change specific aspects of the gadget’s appearance.

General properties
The general properties of a gadget control overall appearance, such as color
scheme, background and border style, and whether animation is enabled. General
properties can also define the radius of a cylinder, the needle position of a linear
gauge, or the start and end angles of a meter gauge. For example, Figure 7-19
shows how changing the Radius, Height, and Viewing Angle properties affects
the view of a cylinder gadget. Radius and Height values are expressed as
percentages of the gadget area.

146

Actuate BIRT Application Developer Guide

Radius: 20%(default)
Height: 0% (default)
Viewing Angle: 30 (default)

Figure 7-19

Radius: 30%
Height: 50%
Viewing Angle: 0

Examining results of setting properties for a cylinder

Figure 7-20 shows examples of setting the Start Angle and End Angle properties
to change the shape and orientation of a meter. The examples also show how to
use the Outer Radius and Inner Radius properties to set the thickness of the arc in
the gauge.
Start Angle: 180 (default)
End Angle: 0 (default)
Outer Radius: 70% of Radius (default)
Inner Radius: 40% of Radius (default)

Start Angle: 90
End Angle: -90
Outer Radius: 40% of Radius
Inner Radius: 25% of Radius

Start Angle: 225
End Angle: -45
Outer Radius: 30% of Radius
Inner Radius: 25% of Radius

Start Angle:45
End Angle: 135
Outer Radius: 50% of Radius
Inner Radius: 50% of Radius

Figure 7-20

Examining results of setting properties for a meter gadget

Table 7-4 shows all the general properties and lists the gadgets to which they
apply. Some properties appear for only one type of gadget. Other properties are
common to multiple types of gadgets.

Chapter 7, Building interactive maps and gadgets

147

Table 7-4

148

General properties

Property

Gadget

Usage

Backgroun
d Color

All

Sets the background color of the gadget.

Base Color

All

Sets the color scheme of the gauge. You can use
either a base color or a preset color scheme. All
other selections derive from this selection.

Center X
Coordinate

Meter

Specifies the x coordinate of the gauge center.

Center Y
Coordinate

Meter

Specifies the y coordinate of the gauge center.

Color

All

Specifies the color of the border around the
gadget.

Connect
Missing
Data

Sparkline

Connects a line between missing points of data.

End Angle

Meter

Specifies the angle where the gauge ends
drawing.

Fill color

Cylinder,
thermometer

Specifies the internal color of a gadget, such as a
cylinder or thermometer.

Height

Cylinder,
thermometer

Specifies the percentage of the gadget area that
the gadget image height occupies.

Inner
Radius

Meter

Specifies the radius of the inner portion of the
gauge.

Outer
Radius

Meter

Specifies the radius of the outer portion of the
gauge.

Preset
Scheme

All

Selects a preset color scheme for the gauge. You
can use either a base color or a preset color
scheme. All other selections derive from this
selection.

Radius
(or Bulb
Radius)

Cylinder,
thermometer

Species the percentage of the gadget area that the
gadget image radius occupies.

Show
Border

All

Enables or disables the border around the gadget.

Show Dial
Values

Meter

Enables or disables the value display on the dial.
Set dial position above or below the dial.

Show
Needle On

Linear gauge

Set to top to have needles appear on top of the
gadget, set to bottom to have them appear on the
bottom.

Actuate BIRT Application Developer Guide

Table 7-4

General properties

Property

Gadget

Usage

Show
Needle
Value

Linear gauge

Enables or disables the display of the value at the
needle. If enabled, set to Above Needle to display
the value above the needle, or set to Below
Needle to display the value below the needle.

Show
Value

Cylinder,
thermometer

Enables or disables the display of the value the
gadget is illustrating.

Start Angle

Meter

Specifies the angle where the gauge begins
drawing.

Start X
Coordinate

Cylinder

Chooses a starting x coordinate percentage that
positions the image in the gadget. Selecting 0
starts the image at the left side of the gadget.

Start Y
Coordinate

Cylinder

Chooses a starting y coordinate percentage that
positions the image in the gadget. Selecting 0
places the starting y coordinate at the top of the
gadget, selecting 100 places it at the bottom.

Style

All

Supports adding a style to the gadget.

Sub-Title

All

Adds a subtitle to the gadget.

Title

All

Adds a title to the gadget.

Turn Off
All
Animation

All

Enables or disables all animation effects.

Turn Off
Default
Animation

All

Enables or disables default animation.

Viewing
angle

Cylinder

Specifies the angle at which the gadget is viewed.
Valid values are 0 through 50. 0 appears flat, 50 is
tilted toward the viewer.

Width

All

Specifies the thickness of the border around the
gadget.

Scale properties
Scale properties define the range of values and the number of tick marks that a
gadget displays. The scale properties affect the numbers displayed on the gadget,
not its size. Minimum Value and Maximum Value specify the lowest and highest
numbers, respectively. If the data set value (represented by the needle value) is
lower than the minimum value or higher than the maximum value, the minimum
or maximum value is ignored.
Figure 7-21 shows scale properties set for a linear gauge.

Chapter 7, Building interactive maps and gadgets

149

Figure 7-21

A linear gauge and its scale formatting properties

Table 7-5 shows all the scale properties and lists the gadgets to which they apply.
Table 7-5

Scale properties

Property

Gadget

Usage

Auto Adjust
Tickmarks

All but
sparkline

Enables or disables tick marks created
evenly across the scale

Major Tickmarks
Count

All but
sparkline

Specifies the number of major tick marks
to display on the scale

Maximum Value

All

Sets the highest value of the scale

Minimum Value

All

Sets the lowest value of the scale

Minor Tickmarks
Count

All but
sparkline

Specifies the number of minor tick marks
to display between major tick marks

Needle properties
Needle properties define the shape, size, and color of a needle. A needle points to
a data value and appears only in a linear gauge and in a meter gauge. Figure 7-22
shows the needle properties set for a meter gauge.

150

Actuate BIRT Application Developer Guide

Figure 7-22

Selecting options for the needle of a meter gauge gadget

For a meter gauge, the needles properties apply only to the pointer part of the
needle. To format the base, or pivot, of the needle (represented by the circle),
choose Needle Base/Pivot.
Table 7-6 shows all the needle properties and lists the gadgets to which they
apply.
Table 7-6

Needle properties

Property

Gadget

Usage

Base Width

Meter

Sets the size of the bottom part of the
needle, as a percent of the size of the
gadget.
(continues)

Chapter 7, Building interactive maps and gadgets

151

Table 7-6

Needle properties (continued)

Property

Gadget

Usage

Border Color

Linear gauge,
meter

Sets the border color of the needle.

Border Width

Linear gauge,
meter

Sets the thickness of the needle border.

Fill Background
Color

Meter

Sets the background color of needle.

Fill Color

Linear gauge

Sets the interior color of the needle.

Rear Extension

Meter

Sets the size of the portion of the needle
behind the pivot as a percent of the size of
the gadget.

Shape

Linear gauge

Sets the shape of the needle.

Show Value

Meter

Enables or disables the display of the
value to which the needle points.

Size

Linear gauge,
meter

Sets the size in pixels, or in percent of
gadget width, of the needle.

Tooltip

Linear gauge,
meter

Specifies text for the tooltip.

Top Width

Meter

Sets the size of the tip of the needle as a
percent of the size of the gadget.

Value

Linear gauge,
meter

Sets which needle to format. Several
needles can co-exist, based on the data
used to create the gadget.

Value Textbox
X Co-ordinate

Meter

Sets the x coordinate of the value text, as a
percent of gadget width.

Value Textbox
Y Co-ordinate

Meter

Sets the y coordinate of the value text, as a
percent of gadget height.

Needle base or pivot properties
Needle base or pivot properties define the appearance of a needle base, or pivot.
Drawn as a circle, the base is the point around which the needle rotates. A needle
base appears only for a meter gauge. Figure 7-23 shows the needle base
properties set for a meter gauge. The size of the needle base is larger than the
default size, and the fill color is set to a radial gradient.

152

Actuate BIRT Application Developer Guide

Needle
base

Figure 7-23

Selecting options for the needle base of a meter gauge

Table 7-7 shows all the needle base or pivot properties. These properties are used
only in a meter gauge.
Table 7-7

Needle base/pivot properties

Property

Usage

Border Color

Sets the border color of the needle base.

Border Thickness

Sets the width of the needle base border.

End Color

Sets the ending color to use in a fill gradient.
(continues)

Chapter 7, Building interactive maps and gadgets

153

Table 7-7

Needle base/pivot properties (continued)

Property

Usage

Fill Color

Sets the interior color of the needle base to a solid
color.

Fill Gradient

Sets the interior color of the needle base to a color
gradient.

Pattern

Specifies the pattern of the fill gradient. Choose
Radial or Linear.

Rotation

Sets the angle of a linear fill gradient.

Show Border

Displays or hides the border around the needle base.

Size

Sets the size of the needle base as a percent of the
meter radius.

Start Color

Sets the starting color to use in a fill gradient.

Number formatting properties
Number formatting properties define how numbers are displayed in a gadget.
Use these properties to abbreviate numbers, to add text before or after a number,
or to specify the number of digits to display after a decimal point. Figure 7-24
shows the number formatting properties set for a bullet gauge. Numbers display
with the dollar symbol ($) before the number and they appear in abbreviated
format, such as $30K instead of $30,000.
Table 7-8 shows all the number formatting properties. These properties are used
in all the gadgets.

154

Table 7-8

Number formatting properties

Property

Usage

Auto Abbreviation

Abbreviates a number to an appropriate number
factor. For example, 10,000 becomes 10K.

Force Trailing Zeros

Enables or disables the display of trailing zeros after
the decimal point.

Format Numbers

Enables and disables number formatting.

Fraction Digits

Specifies the number of digits displayed after the
decimal point.

Prefix

Specifies a text value to display before a number.

Suffix

Specifies a text value to display after a number.

Actuate BIRT Application Developer Guide

Figure 7-24

Examining a bullet gadget and its number formatting properties

Region properties
Region properties enable the division of the data plot into regions. Use regions to
provide more information about values in a gadget. Compare the linear gauges in
the following figures. The gauge in Figure 7-25 does not show regions. The gauge
in Figure 7-26 displays three regions, labeled Fair, Good, and Excellent.

Figure 7-25

Linear gauge without regions

Figure 7-26

Linear gauge with three regions

Figure 7-27 shows the properties set for the region labeled Fair in Figure 7-26.

Chapter 7, Building interactive maps and gadgets

155

Figure 7-27

Properties specified for a region labeled Fair

Table 7-9 shows all region properties and lists the gadgets to which they apply.
Table 7-9

Region properties

Property

Gadget

Usage

Color

Linear gauge, meter, bullet

Specifies the color of the region.

End Value

Linear gauge, meter, bullet

Specifies where the region ends.

Label

Linear gauge, meter, bullet

Specifies the name of the region.

Region

Linear gauge, meter, bullet

Chooses the region for which the
settings apply. You can also add
or remove a region from the list.

Show Labels

Linear gauge

Display or hide the region labels.

Start Value

Linear gauge, meter, bullet

Specifies where the region starts.

Tick properties
Tick properties define the size, color, and position of tick marks on a gadget.
Figure 7-28 shows the tick properties set for a linear gauge. Tick marks appear at

156

Actuate BIRT Application Developer Guide

the top and inside the gauge. The first and last tick values display Min and Max
instead of numbers.

Figure 7-28

Format Gadget displaying a linear gauge and its tick properties

Table 7-10 shows all the tick properties and lists the gadgets to which they apply.
Table 7-10

Tick properties

Property

Gadget

Usage

Major Tick
Marks Color

Linear gauge, meter, bullet,
cylinder, thermometer

Sets the color of major tick marks.

Major Tick
Linear gauge, meter, bullet,
Marks Height cylinder, thermometer

Sets the height of major tick
marks.

Major Tick
Marks Width

Sets the width of major tick
marks.

Linear gauge, meter, bullet,
cylinder, thermometer

(continues)

Chapter 7, Building interactive maps and gadgets

157

Table 7-10

Tick properties (continued)

Property

Gadget

Usage

Maximum
Label

Linear gauge, meter, bullet,
cylinder, thermometer

Sets the highest tick mark value.
Text replaces the numeric value.

Minimum
Label

Linear gauge, meter, bullet,
cylinder, thermometer

Sets the lowest tick mark value.
Text replaces the numeric value.

Minor Tick
Marks Color

Linear gauge, meter, bullet,
cylinder, thermometer

Sets the color of minor tick marks.

Minor Tick
Linear gauge, meter, bullet,
Marks Height cylinder, thermometer

Sets the height of minor tick
marks.

Minor Tick
Marks Width

Linear gauge, meter, bullet,
cylinder, thermometer

Sets the width of minor tick
marks.

Position
Above

Linear gauge, bullet

Sets tick marks to appear above
the gadget.

Position
Below

Linear gauge, bullet

Sets tick marks to appear below
the gadget.

Position Left

Cylinder, thermometer

Positions tick marks on the left
side of the gadget.

Position
Right

Cylinder, thermometer

Positions tick marks on the right
side of the gadget.

Show Limits
Value

Linear gauge, meter, bullet,
cylinder, thermometer

Enables or disables the display of
the first and last values.

Show Tick
Marks

Linear gauge, meter, bullet,
cylinder, thermometer

Enables or disables the display of
tick marks on the gadget.

Show Tick
Values

Linear gauge, meter, bullet,
cylinder, thermometer

Enables or disables the display of
values on tick marks.

Ticks Inside

Linear gauge, meter

Sets tick marks to appear inside
or outside of the gadget.

Values Inside

Linear gauge, meter

Sets tick mark values to appear
inside or outside of the gadget.

Threshold properties
Threshold properties define thresholds, which you use to identify meaningful
values. For example, in a linear gauge that displays a sales total, you can add a
threshold that identifies the target sales amount, as shown in Figure 7-29. By
displaying this threshold value, the gauge shows whether the actual sales total is
over or under the sales target.
Figure 7-29 also shows the threshold properties set to create the threshold. You
can specify a label, create a threshold line or a threshold zone, specify a threshold

158

Actuate BIRT Application Developer Guide

value or range of values, and format the line and marker. You can create multiple
thresholds for a gadget.

Figure 7-29

Examining a linear gauge and its threshold properties

Table 7-11 shows all the threshold properties and lists the gadgets to which they
apply.
Table 7-11

Threshold properties

Property

Gadget

Usage

Arc Inner Radius

Meter

Specifies the inner radius of arc for
the threshold area

Arc Outer Radius

Meter

Specifies the outer radius of arc for
the threshold area
(continues)

Chapter 7, Building interactive maps and gadgets

159

Table 7-11

160

Threshold properties (continued)

Property

Gadget

Usage

Border Color

Linear gauge, meter

Sets the border color of the
threshold marker

Color

Linear gauge, meter,
sparkline, bullet

Sets the color of the threshold area
on the gadget

End Value

Linear gauge, meter,
sparkline

Sets the end value of the threshold
zone

Label

Linear gauge, meter

Specifies the text to apply to the
threshold

Length

Bullet

Specifies the length of the threshold
as a percent of gadget size

Line Style

Linear gauge, meter,
sparkline

Sets the line style of the threshold

Marker Color

Linear gauge, meter

Sets the color of the threshold
marker

Radius

Linear gauge

Sets the size of the threshold
marker

Show as Zone

Sparkline

Enables or disables display of the
threshold as a zone

Show Border

Meter

Enables or disables display of a
border around the threshold

Show Marker

Linear gauge, meter

Enables or disables display of the
marker on the threshold

Show Threshold

Sparkline, bullet

Enables or disables display of the
threshold

Show Label

Meter

Enables or disables display of the
threshold value

Show Label
Inside

Meter

Displays value inside or outside of
the arc on the gadget

Show Label on
Top

Linear gauge

Enables or disables display of the
threshold value

Size

Meter

Sets the size of the threshold
marker

Start Value

Linear gauge, meter,
sparkline

Sets start value of the threshold
zone

Threshold

Linear gauge, meter

Sets which threshold the settings
affect

Actuate BIRT Application Developer Guide

Table 7-11

Threshold properties (continued)

Property

Gadget

Usage

Threshold Line/
Threshold Zone

Linear gauge, meter

Sets whether the threshold is a
single line or a zone

Tooltip

Linear gauge, meter

Sets tooltip text for the marker on
the threshold

Width

Sparkline, bullet

Sets the width of the threshold

Anchor properties
Anchor properties control the shape, size, color, and visibility of markers, or
anchors, in a sparkline gadget. Unlike other gadgets that display only one or two
data values, a sparkline gadget plots multiple values and, by default, uses
anchors to highlight the first, last, lowest, and highest values. Figure 7-30 shows
the anchor properties set for a sparkline gadget.

Figure 7-30

Examining a sparkline gadget and its anchor properties

Chapter 7, Building interactive maps and gadgets

161

Table 7-12 shows all the anchor properties. These properties are used only in a
sparkline gadget.
Table 7-12

Anchor properties

Setting

Usage

Shape

Sets the shape of the anchors.

Size

Sets the size of the anchor in pixels.

Visibilities

Sets the visibility and color of the anchors. Open,
Close, High, and Low anchors are visible by default.
To display anchors for all the other values, select
Other Anchors.

Plot properties
Plot properties control the appearance of elements in the data plot area of bullet
and sparkline gadgets. For a bullet gadget, you can add a border around the
gadget or a shadow below it. You can also specify whether to display the value
label and whether to display the value indicator as a line or as a dot.
For a sparkline gadget, you can specify whether to display the first, last, lowest,
or highest values, change the color and width of the data line, and add bars in the
background to represent period blocks. For example, if a sparkline displays daily
stock quotes over a year, you can show period blocks that have a length of 3 to
divide the stock values into quarters. The value of 3 assumes that each quarter
has three months.
For example, Figure 7-31 shows the preview of a sparkline gadget. The gadget
displays period bars where each period contains three values. Alternate bars
appear in color.

Figure 7-31

Format Gadget displaying a sparkline gadget

Figure 7-32 shows the plot properties specified for the plot that appears in the
sparkline gadget example shown in Figure 7-31.

162

Actuate BIRT Application Developer Guide

Figure 7-32

Examining the plot properties for a sparkline gadget

Table 7-13 shows all the plot properties.
Table 7-13

Plot properties

Property

Gadget

Usage

Border

Bullet

Enables or disables the border around the
gadget.

Border Color

Bullet

Sets the color of the border around the
gadget.

Border Width

Bullet

Sets the thickness of the border around the
gadget.

Line Color

Sparkline

Sets the color of the plot line.

Line Width

Sparkline

Sets the thickness of the plot line.

Period Bars Color

Sparkline

Sets the color of the period bars. The color
is applied to alternate bars.

Period Bars Length

Sparkline

Sets the number of values that each period
bar highlights.

Show as Dot

Bullet

Enables or disables the display of the
value indicator as a dot instead of a solid
line.

Show Close Value

Sparkline

Enables and disables the display of the
close value.

Show High and Low
Values

Sparkline

Enables and disables the display of the
high and low values.
(continues)

Chapter 7, Building interactive maps and gadgets

163

Table 7-13

Plot properties (continued)

Property

Gadget

Usage

Show Open Value

Sparkline

Enables and disables the display of the
open value.

Show Period Bars

Sparkline

Enables and disables the display of period
bars.

Show Shadow

Bullet

Enables or disables the appearance of a
shadow below the gadget.

Show Value Label

Bullet

Enables or disables the display of the
value on the gadget.

Value indicator properties
Value indicator properties control the size, color, and border of the value indicator
in a bullet gadget, as shown in Figure 7-33.

Value
indicator

Figure 7-33

Examining a bullet gadget and its value indicator properties

Table 7-14 shows the value indicator properties. These properties are used only in
a bullet gadget.

164

Table 7-14

Value indicator properties

Property

Gadget

Usage

Border Color

Bullet

Sets the color of the border

Border Width

Bullet

Sets the thickness of the border

Actuate BIRT Application Developer Guide

Table 7-14

Value indicator properties

Property

Gadget

Usage

Color

Bullet

Sets the color of the value indicator

Show Border

Bullet

Enables or disables a border around the
value indicator

Width

Bullet

Sets the value indicator width as a percent
of the plot thickness

Tooltip properties
Tooltip properties control the visibility and appearance of tooltips in a gadget. A
tooltip displays a data value when the mouse pointer is placed over a value
marker. Figure 7-34 shows a meter gadget that displays a tooltip and the
properties set for the tooltip.

Figure 7-34

Format Gadget displaying a meter gadget and its tooltip properties

Chapter 7, Building interactive maps and gadgets

165

Table 7-15 shows the tooltip properties. These properties are available to all the
gadgets.
Table 7-15

Tooltip properties

Property

Usage

Show Tooltip

Enables and disables the display of a tooltip

Background

Sets the background color for the tooltip

Border

Sets the border color for the tooltip

Font properties
Font properties define the type, size, and color of the font used for any text in a
gadget. Table 7-16 shows the font properties. These properties are available to all
the gadgets.
Table 7-16

Font properties

Property

Usage

Font

Specifies the name of the font

Size

Specifies the font size in points

Color

Specifies the color of the text

Padding and margin properties
Padding and margin properties support the addition of space on all sides of a
gadget, between a title and the plot, and between a data value and the plot.
Compare the sparkline gadgets in Figure 7-35 and Figure 7-36. The gadget in
Figure 7-35 uses default values for all the padding and margin properties.
The gadget in Figure 7-36 uses the margin and padding properties to add extra
space between the elements in the gadget.
Table 7-17 shows the padding and margin properties.
Table 7-17

166

Padding and margin properties

Property

Gadget

Usage

Padding Title

All

Adds space, in pixels, between the title
and the element next to it

Padding Value

All

Adds space, in pixels, between the data
value and the element next to it

Margins Left,
Right, Top,
Bottom

All

Adds space, in pixels, around the entire
gadget on the left, right, top, and bottom
sides

Actuate BIRT Application Developer Guide

Figure 7-35

Format Gadget displaying a sparkline gadget and its default padding
and margin property settings

Padding
Title

Margin
Top
Margin
Right

Margin
Left
Padding
Value

Margin
Bottom

Figure 7-36

Format Gadget displaying a sparkline gadget that uses padding
and margin properties to add extra space between elements

AddOn properties
AddOn properties support the creation of custom objects, called AddOns, to add
to a gadget. You can add rectangles, polygons, circles, arcs, lines, text, and images

Chapter 7, Building interactive maps and gadgets

167

to any gadget to enhance its appearance. You can create any number of objects
and arrange objects on top of or behind one another.
Figure 7-37 shows an example of adding two rectangles with rounded corners
behind a meter gauge. To create this image, create one rectangle with a white
border, then create another rectangle that is slightly larger. Use the same fill color
for both rectangles. Place the larger rectangle behind the smaller rectangle.

Figure 7-37

AddOn objects used to enhance a meter gadget

Figure 7-38 shows the AddOns page. AddOns lists the two rectangles added to
the meter gauge. The objects are listed in z order, which is the order from front
to back.

Objects
listed in
z order

Figure 7-38

Format Gadget displaying a meter gauge and its AddOn properties

Figure 7-39 shows the properties set for the larger rectangle. Notice that the size
of the rectangle is not fixed. Rather, the size is a percentage of the gadget’s size.
You define an AddOn’s size by specifying values for these four properties:
Start X coordinate, Start Y coordinate, End X coordinate, and End Y coordinate.
By using a relative size, AddOns adjust to the size of the gadget area.

168

Actuate BIRT Application Developer Guide

Figure 7-39

Properties of an AddOn object

Table 7-18 shows the properties for creating the different types of objects that you
can add to a gadget.
Table 7-18

AddOn properties

Property

Object Type

Usage

Center X
coordinate

Polygon, Circle, Arc Specifies the location, as a percentage of the size
of the gadget, of the x coordinate of the object.

Center Y
coordinate

Polygon, Circle, Arc Specifies the location, as a percentage of the size
of the gadget, of the y coordinate of the object.

Color

Line, Text

Specifies the color of the line.
(continues)

Chapter 7, Building interactive maps and gadgets

169

Table 7-18

AddOn properties (continued)

Property

Object Type

Usage

Dash Gap

Line

Specifies the length of gaps between dashes, in
pixels.

Dash Length

Line

Specifies the length of dashes, in pixels.

End Angle

Circle, Arc

Specifies the end angle of the object.

End Color

Rectangle, Polygon,
Circle, Arc

Specifies the end color of the gradient fill.

End X coordinate

Rectangle, Line

Specifies the location, as a percentage of the size
of the gadget, of the end x value of the object.

End Y coordinate

Rectangle, Line

Specifies the location, as a percentage of the size
of the gadget, of the end y value of the object.

Fill Color

Rectangle, Polygon,
Circle, Arc

Select to use a solid fill color for the object. Select a
color from the associated drop-down list box.

Font

Text

Specifies the font for the object. You can also select
Bold, Italic, or Underline.

Font Size

Text

Specifies the font size in points.

Horizontal

Text

Supports the selection of horizontal text
alignment in the gadget.

Inner Radius

Arc

Specifies the radius of the inner portion of the
object, as a percent of the size of the gadget.

Gradient

Rectangle, Polygon,
Circle, Arc

Select to have a gradient type of fill. Choose a
Radial or Linear pattern.

Label

Text

Specifies the text that appears on the object.

Name

All

Specifies the name of the object. This name
appears in the list on AddOns options.

Outer Radius

Arc

Specifies the radius of the outer portion of the
object, as a percent of the size of the gadget.

Radius

Circle

Specifies the radius, as a percent of the gadget, of
the object.

Rotation

Rectangle, Polygon,
Circle, Arc

Specifies the rotation angle for the fill in the
object.

Rotation Angle

Polygon

Specifies the rotation angle of the object.

Scale Image

Image

Enables or disables image scaling. Adjust the
height and width of the image by percent.

Show as Dashed

Line

Enables or disables dashed lines.

170

Actuate BIRT Application Developer Guide

Table 7-18

AddOn properties (continued)

Property

Object Type

Usage

Show Border

Rectangle, Polygon,
Circle, Arc

Enables or disables the drawing of a border line
around the object. Select the color and thickness of
the border with the Color and Thickness
drop-down menus.

Show Round
Corners

Rectangle

Enables or disables rounded corners. Type the
percent of a circle to round the corner.

Sides

Polygon

Specifies the number of sides on the object.

Size

Polygon

Specifies the size, as a percent of the gadget, of the
object.

Start Angle

Circle, Arc

Specifies the beginning angle of the object.

Start Color

Rectangle, Polygon,
Circle, Arc

Specifies the start color of the gradient fill.

Start X coordinate

Rectangle, Line,
Text, Image

Specifies the location, as a percentage of the size
of the gadget, of the beginning x value of the
object.

Start Y coordinate

Rectangle, Line,
Text, Image

Specifies the location, as a percentage of the size
of the gadget, of the beginning y value of the
object.

TextBox
Background Color

Text

Specifies the background color of the text box.

TextBox Border
Color

Text

Sets the border color of the text box.

Text Wrap

Text

Disables or enables text wrap. Choose, by percent
of the gadget, the maximum height and width for
the wrap.

Thickness

Line

Specifies the thickness of the line.

Tooltip

All

Specifies text for the tooltip.

Transparent

Image

Specifies the amount of transparency, in percent,
of the image.

URL

Image

Specifies the location of the image for AddOn file
types of .gif, .jpg, .png, or .swf.

Vertical

Text

Supports the selection of vertical text alignment in
the gadget.

Chapter 7, Building interactive maps and gadgets

171

172

Actuate BIRT Application Developer Guide

Chapter

8
Chapter 8

Building an interactive
chart

This chapter contains the following topics:
■

About interactive charts

■

Creating an interactive chart

■

Formatting an interactive chart

■

Adding scripts to a chart

Chapter 8, Building an interactive char t

173

About interactive charts
BIRT Designer Professional supports BIRT charts and HTML5 charts. BIRT charts
generate images in the following formats; SVG, BMP, JPG, and PNG using the
BIRT chart engine and are used for static, print-based documents. BIRT charts
support extensive scripting, but not animation.
HTML5 charts use an open standard for structuring and presenting content for
the World Wide Web, and is increasingly regarded as the alternative to Flash for
creating interactive and animated content for traditional and mobile devices. You
can control chart presentation, design-time and generation-time properties
through the user interface and scripting. For example, an HTML5 column chart
can highlight a column with the highest value and display an overlay on each
column that defines a 10% chance of error.

Comparing HTML5 and BIRT charts
Use the information in Table 8-1 to decide which chart format to use in a report.
Table 8-1

Features available in HTML5 and BIRT charts

Feature

HTML5

BIRT

Displays in the web viewer

✓

✓

Displays in PDF

✓

✓

Displays in other document formats (DOC, PPT, XLS,
etc.) as a static image

✓

✓

Supported on mobile devices

✓

✓

Provides animation

✓

–

Supports customization through scripting

✓

✓

Table 8-1 does not list the chart types or chart properties supported by each chart
format because that list is too long. As you design HTML5 charts, you discover
that many of the properties available to BIRT charts are also available to HTML5
charts.
If creating animated charts, use HTML5 charts. If you need to present data in a
chart that is not available in HTML5 (for example, complex combination charts),
use a BIRT chart. For information about building BIRT charts, see BIRT: A Field
Guide.

Rendering platform
BIRT Designer Professional uses Highcharts, a third-party charting library, to
render HTML5 charts. This charting library, written in JavaScript, is integrated

174

Actuate BIRT Application Developer Guide

into BIRT Designer Professional’s standard chart builder, where you create
HTML5 charts using the familiar user interface.
Highcharts also provides a full API, which you can use to programmatically add,
remove, or modify chart elements after creating the chart in the chart builder.
Access to the Highcharts API is through the chart builder’s script editor and
through the JavaScript chart theme editor.

Creating an interactive chart
The procedure for creating an HTML5 chart is the same as the procedure for
creating a BIRT chart. To create an HTML5 chart, perform the following tasks:
■

Drag the chart element from the palette and drop it in the report.

■

In the chart builder, choose a chart type, and set Output Format to HTML5, as
shown in Figure 8-1. This is the default format if you select a chart type
supported by HTML5.

Select
HTML5
format

Figure 8-1

Select Chart Type page showing the HTML5 output format
selected

Chapter 8, Building an interactive char t

175

■

Specify the data to present in the chart.

■

Format the chart.

This chapter describes the features that are unique to HTML5 charts, for example,
scripting with the Highcharts API and designing chart themes using JavaScript.
For information about specifying data for a chart, see BIRT: A Field Guide.

Formatting an interactive chart
As with a BIRT chart, you format an HTML5 chart using one or both of the
following methods:
■

Use the chart builder’s Format Chart page to set style properties for the
different parts of the chart.

■

Apply a chart theme, which defines styles for the different parts of a chart.
Themes provide a flexible way to define and maintain styles in one place and
reuse them for any chart that you create. BIRT Designer Professional provides
several predefined themes for HTML5 charts. For a custom look, create your
own chart themes.

If using both methods to format a chart, the properties in the chart theme function
as the basis for the chart’s appearance. Properties that you set in the Format Chart
page override properties set by the theme.
The user interface indicates clearly whether a property is set by a theme or set in
the chart builder. Properties presented as a list box or as radio buttons display the
value Auto for default values that are set by a theme or by the software. These
properties display a specific value if set in the chart builder.
Properties set through check boxes have three states—on, off, and default. A
check mark indicates the on state, an empty check box indicates the off state, and
a check box with a gray check mark or a blue square indicates the default state.
The symbol for the default state changes depending on the Windows theme that
your machine uses.
A default state is set by a theme or the software, and the default state is either on
or off. Even though it can appear counter-intuitive, a gray check mark does not
necessarily mean that a property is on by default. For example, the Use Glass
Style property, available in the Format Chart page, as shown in Figure 8-2, is set
to the default state, and the software’s default value is off. To apply the glass style
to the chart, you would click the check box until it displays a check mark.
Similarly, the property below it, Turn Off Animation, is set to the default state,
which is off. In other words, animation is turned on by default. To disable
animation, you would click the check box until it displays a check mark. For
information about standard chart formatting options, see BIRT: A Field Guide.

176

Actuate BIRT Application Developer Guide

Figure 8-2

Selecting themes and effects for a bar chart

Applying a chart theme
On the Format Chart page, Theme displays the theme currently applied to the
chart, or None, if a theme is not applied. To change the theme or apply one, select
a theme from the drop-down list. The list displays all the predefined themes, as
well as, the themes that you created. When you select a theme, the chart
previewer shows the changes instantly.

Chapter 8, Building an interactive char t

177

Creating a chart theme
HTML5 charts support two types of chart themes:
■

A general chart theme that you create with the graphical chart theme builder,
and which you can apply to both BIRT and HTML5 charts.

■

A JavaScript theme that you can apply to HTML5 charts only. These themes
use JavaScript and the Highcharts API. Use this programming option to define
chart attributes that are not available through the graphical chart theme
builder, or if you are more comfortable writing scripts and prefer to view all
attributes in text format on a single page.

A typical approach to designing chart themes, whether general or JavaScript, is to
create one theme for all chart types. Use this approach to design a consistent
presentation style for all chart types, one that uses corporate styles, for example.
Such a theme can define general attributes, such as color schemes for the chart
background and plot areas, font styles for chart titles, value labels, or axis labels,
border styles, and legend styles.
The charts in Figure 8-3 and Figure 8-4 are examples of how a bar chart and a line
chart appear in a consistent style when the same theme is applied. The charts use
the same color schemes, fonts, grid, border and legend styles. In these examples,
the charts use a predefined chart theme, ThemesReportItems3.Modern. You can
use the same design principles when creating custom themes.

178

Figure 8-3

Bar chart using a predefined theme, ThemesReportItems3.Modern

Figure 8-4

Line chart using the same theme, ThemesReportItems3.Modern

Actuate BIRT Application Developer Guide

You can create a chart theme in a report design or in a library. Create a chart
theme in a library—the typical approach—to share the theme with other report
developers or to use the theme in other reports. A chart theme defined in a report
design is available only to charts in that report.
If an existing chart contains the formatting attributes you want to set in a theme,
export the attributes to a theme. To do so, open the chart in the chart builder, then
click the button at the top right side of the chart builder, and specify a name for
the new theme. BIRT creates a theme that contains all the formatting attributes
from the chart. The theme is created in the report that contains the source chart
and is accessible through the Outline view for the report design. To place this
theme in a library, copy it from the Outline view and paste it into a library.
The predefined chart themes included with BIRT Designer Professional are
defined in a library, ThemesReportItems3.rptlibrary. You can download this
library from the Resources folder in Actuate BIRT iServer to use as an example
when creating your own library of themes.

Creating a general chart theme
The chart theme builder, which you use to create a general chart theme, organizes
and presents properties in a similar way as the Format Chart page of the chart
builder. Figure 8-5 shows the Format Chart Theme page where you set formatting
attributes for the different parts of a chart. The preview section shows your
formatting changes for the selected chart type, which you choose in the Preview
Type page.
Use the Script page to write event-handling code for a theme. This code applies
only to HTML5 charts. It is ignored when the theme is applied to a BIRT chart.
Information about writing event handlers is provided later in this chapter.
How to create a general chart theme

1 In Outline, right-click Themes and choose New Report Item Theme.
2 In New Report Item Theme, specify the following information:
■

In Name, type a name for the theme.

■

In Type, select Chart.

Choose OK.
3 In Chart Theme Wizard, select the first option, General, to define a theme.
Choose Next.
4 In the chart theme builder, shown in Figure 8-5, define the style properties for
the chart theme.
5 Choose Finish.

Chapter 8, Building an interactive char t

179

Figure 8-5

Format Chart Theme page of the chart theme builder

Creating a JavaScript chart theme
As mentioned earlier, BIRT Designer Professional uses Highcharts, a third-party
charting library, to render HTML5 charts. To create a JavaScript chart theme, you
set the Highcharts chart options to values that provide the visual attributes you
desire. Every option has a default value. You define attributes only to change
default settings, or to add items that do not appear by default.
Listing 8-1 shows the JavaScript code for the tooltips of predefined chart theme,
Modern. The charts in Figure 8-3 and Figure 8-4 use this theme. As the code
shows, options are set using a JavaScript object notation structure. Keys and
values are connected by colons, separated by commas, and grouped by curly
brackets.
For a complete reference of the options and their descriptions, see the Highcharts
documentation at the following location:
http://api.highcharts.com/highcharts

180

Actuate BIRT Application Developer Guide

The Highcharts reference contains two sections, the Configuration options and
Methods and properties. Look at the Configuration options for information about
the options you can set in a chart theme.
Listing 8-1

JavaScript code for the chart theme Modern

//You can change options here.
options.tooltip={
animation:false,
backgroundColor: "#fff",
borderRadius: 0,
borderColor: "#e1e1e1",
borderWidth: 1,
style: {
color:"#363636",
fontSize: "16px",
fontWeight: 400,
padding: "12px"
},
useHTML: true,
headerFormat: '
{point.key}
', pointFormat: '
{series.name}: {point.y}
' } How to create a JavaScript chart theme 1 In Outline, right-click Themes and choose New Report Item Theme. 2 In New Report Item Theme, specify the following information: ■ In Name, type a name for the theme. ■ In Type, select Chart. Choose OK. 3 In Chart Theme Wizard, select the second option, HTML5, to define a theme. Choose Next. 4 In the JavaScript chart theme builder, shown in Figure 8-6, write code that defines the desired style properties for the chart theme. The Preview section displays the results of your code for a selected chart type. 5 To write event-handling code, described in the next section, choose the Script tab. Choose Finish to close the theme editor. Chapter 8, Building an interactive char t 181 Select the type of chart in which to preview the results of your code Type your JavaScript code here Figure 8-6 Example of JavaScript code and preview of a bar chart Adding scripts to a chart You can write scripts in JavaScript that specify the task to perform when a particular event occurs. This type of script is called an event handler. Like BIRT charts, HTML5 charts support two types of event handlers: 182 ■ Event handlers that respond to user interactions, such as a mouse click on a legend or a mouse over a series, when viewing the report. For example, you can create an event handler to link to another report when a user clicks a bar in a bar chart or reorders values displayed in a tooltip from highest to lowest. ■ Event handlers that respond to chart events, which occur when BIRT renders an HTML5 chart. Use this type of event handler to conditionally change or add chart elements as the chart is being generated. For example, you can write an event handler to calculate an average value and display this value as a marker line. Actuate BIRT Application Developer Guide For both types of event handlers, you use the script editor in the chart builder, as shown in Figure 8-7. To launch the script editor, choose the Script tab. Choose Script to open the script editor Choose Client Script to write an event handler for a chart event Choose Interactivity to write an event handler for a user action Figure 8-7 Script editor displaying the UI for writing a chart event handler To create an event handler that responds to a user interaction, choose Interactivity. To create an event handler that responds to a chart event, choose Client Script, as shown in Figure 8-7. Scripts that you write using Client Script apply to HTML5 charts only. If you later change a chart’s output format from HTML5 to SVG, BIRT ignores these client-side scripts when generating the chart. You can also add Client Scripts to the JavaScript chart theme to share the script among multiple HTML5 charts using the script editor in the Chart Theme Wizard, as shown in Figure 8-8. Figure 8-8 Script editor displaying the chart event handler interface Chapter 8, Building an interactive char t 183 Writing event handlers that respond to user interactions Depending on what you want to accomplish, you can create some of these interactivity event handlers without scripting. For typical event handlers, the script editor in the chart builder simplifies the process by providing a list of chart elements, a list of events, and a list of actions. Select the chart element you want to make interactive, select an event, such as Mouse Click or Mouse Over, then select an action, such as Show Tooltip or Hyperlink. To implement a custom action, choose Invoke Script, then write JavaScript code. For HTML5 charts, this code can use the Highcharts API. Figure 8-9 shows an example of an event handler defined for a chart’s Y series. The event handler runs when the Mouse Over event is triggered. When triggered, the Show Tooltip action runs. In this example, the tooltip is set to display the series data, which is typical. Figure 8-9 Script editor displaying an interactivity event handler Figure 8-10 shows the results of the previous event handler. When the user places the mouse pointer over the first bar in the bar chart, a tooltip displays the series data value. Figure 8-10 184 A tooltip displays a bar’s data value when the user places the mouse pointer over the bar Actuate BIRT Application Developer Guide Figure 8-11 shows an example of an event handler defined for a chart’s legend. The event handler runs when the Mouse Click event is triggered. When triggered, the Invoke Script action runs. In this example, the following script brings a series in an area chart to the front when the user clicks the series name in the legend: evt.target.group.toFront(); This line of code calls a method in the Highcharts API. Figure 8-11 Script editor displaying an event handler that runs a script Figure 8-12 shows the results of the previous event handler. When the user clicks the In Process value in the area chart’s legend, the corresponding series in the chart displays in front of the other overlapping series. Figure 8-12 In Process series displayed in front when the user clicks the series name in the legend Compared to BIRT charts, HTML5 charts support fewer events and actions, and fewer chart elements on which to define event handlers. The additional events that BIRT charts support, but that HTML5 charts do not, include Mouse Down, Mouse Up, Mouse Move, Key Down, and Key Up. The additional chart elements for which you can define event handlers in a BIRT chart, but not an HTML5 chart, include the chart title, y-axis, and x-axis. Chapter 8, Building an interactive char t 185 If you begin by creating a BIRT chart, then later change the output format to HTML5, BIRT ignores the event handlers defined for events that are specific to a BIRT chart when generating the chart. This behavior provides the flexibility of creating and maintaining event handlers for either chart format with the option of changing the chart format at any time without any additional changes to the design. Writing event handlers that respond to chart events Unlike event handlers that respond to user interactions with the chart, the event handlers that you write for chart events require programming in JavaScript. You also have to review the Highcharts API to know what chart options you can manipulate and how. In the script editor, you select an event function, such as beforeRendering( ) or beforeDrawAxis( ), then you write code that performs a specific task or tasks when the chart event occurs. The event handlers that you write for HTML5 chart events differ from the event handlers for BIRT charts in several important aspects, as described in Table 8-2. Table 8-2 Comparison of event handlers in HTML5 charts and BIRT charts Event handlers in HTML5 charts Event handlers in BIRT charts Support only JavaScript Support JavaScript and Java Use client-side scripting and limited server-side scripting Use server-side scripting only Use the Highcharts API Use BIRT charting API Write client-side scripts using the script editor accessible from the Script tab in the chart builder. Write server-side scripts using the script editor accessible from the Script tab in the report editor. Only the following server-side event functions are supported for HTML5 charts: beforeDataSetFilled( ), afterDataSetFilled( ), and beforeGeneration( ) This section provides information about writing client-side event handlers for HTML5 chart events. For information about writing server-side event handlers, see Integrating and Extending BIRT. For documentation about the Highcharts API, go to the following location: http://api.highcharts.com/highcharts About the HTML5 chart events The set of events for an HTML5 chart is much smaller than the set of events for a BIRT chart. Table 8-3 lists the HTML5 chart event functions and describes when they are called. 186 Actuate BIRT Application Developer Guide Table 8-3 HTML5 chart event functions Event function Called afterRendering(chart) After the chart is rendered beforeDrawAxis(axis, axisOptions, chart, axisIndex) Before rendering each axis beforeDrawDataPoint(point, pointOptions, chart, seriesIndex, pointIndex) Before drawing each data point graphical representation or marker beforeDrawSeries(series, seriesOptions, chart, seriesIndex) Before rendering the series beforeGeneration(options) Before the chart is created beforeRendering(options, chart) Before the chart is rendered Setting chart options through scripting The before functions are called after BIRT generates the static JavaScript options, which are based on the chart’s data and formatting options set in the chart builder. The beforeGeneration( ) function is the first function called after the generation of the static JavaScript options, but before a chart object is created. Use beforeGeneration( ) to add chart options that Highcharts provides, but that are not available through the chart builder’s format page. For example, Highcharts provides a credits option to display a credits label in the chart. To add this label to the lower right corner of the chart (the default position), you would write code as follows: beforeGeneration: function(options) { options.credits = { enabled: true, text: 'Acme Inc.' }; }, As the code example shows, beforeGeneration( ) receives an options object. You use this options object to configure chart options. When you type the word, options, followed by a period (.), the script editor displays a list of options, as shown in Figure 8-13. Click an option to view summary information about it. Double-click an option to add it to your code. The other before functions also receive an options object, for example, axisOptions or seriesOptions, which is specific to the associated chart element. Your code typically makes changes to the options object to change the appearance of an axis, series, or data point. The following code example shows how to use Chapter 8, Building an interactive char t 187 beforeDrawSeries( ) and the seriesOptions object to display a legend for all series types except pie: beforeDrawSeries: function(series, seriesOptions, chart, seriesIndex) { if ( series.type == "pie" ) { seriesOptions.showInLegend = false; } else { seriesOptions.showInLegend = true; } }, Figure 8-13 The script editor displaying the available options All the before functions, except beforeGeneration( ), also receive the chart object, which represents the chart that is created based on the original static options and any options created with beforeGeneration( ). With the exception of beforeGeneration( ), your code can query the chart object to determine what changes to make to the options. You typically use these before functions to dynamically add, change, or remove a chart element based on specified conditions. Avoid making make any changes with your code to the chart object itself because it is a temporary object. Changes to this temporary chart are discarded along with the chart. After the before functions run, BIRT passes the original options and your scripted options into a constructor to create a new chart object. The afterRendering( ) function provides the final opportunity to make changes to this new chart object. 188 Actuate BIRT Application Developer Guide To get the chart object, use the getCore( ) method, as shown in the following code snippet: afterRendering: function(Chart) { myChart=Chart.getCore(); ... Scripting example 1 The bar chart in Figure 8-14 shows the following custom options that are added through scripting: ■ A script in beforeDrawSeries( ) calculates the average sales total, and changes the color of bars that show data values above the average value. ■ A script in afterRendering( ) draws a plot line on the y-axis to show the average value, and adds a legend item to display the average value. Bars that display data values above the average value appear in a different color Plot line added to show the average sales value Custom legend item added to display the average sales value Figure 8-14 Customized options in a bar chart The event handlers written for the bar chart appear in Listing 8-2. Listing 8-2 Event-handling script for the bar chart with customized options beforeDrawSeries: function(series, seriesOptions, tempChart, seriesIndex) { var totalValue = 0; // First, find the average value for the series for ( var i = 0; i < series.data.length; i++ ) { totalValue += series.data[i].y; } aveValue = totalValue / series.data.length; for ( var j = 0; j < series.data.length; j++ ) { // Find out if this data point is above average if ( series.data[j].y <= aveValue ) Chapter 8, Building an interactive char t 189 { continue; } // The data point is above average. Color it green var pointOptions = seriesOptions.data[j]; pointOptions.color = 'green'; } }, afterRendering: function(myChart) { var chart=myChart.getCore(); var mySeries = chart.series[0]; // Assuming aveValue was set in the beforeDrawSeries function, // draw a plot line at the average value. mySeries.yAxis.addPlotLine({ color: 'green', width: 2, value: aveValue, id: 'averageValuePlotLine', zIndex: 2 }); // Add a legend item that labels the plot line // Do this by adding an empty series chart.addSeries({ color: 'green', name: 'Ave: $' + aveValue.toFixed(2), marker: { enabled: false } }); }, Scripting example 2 The bar chart in Figure 8-15 shows custom objects, stars, that are added through scripting. Each star indicates the highest value for each order status series. A script in afterRendering( ) performs the following tasks: ■ Calculates the highest (max) value for each y-series ■ Draws a star based on the width of the bar ■ Positions the stars at the top of the appropriate bars This script showcases Highchart’s renderer object, which supports drawing shapes, such as circles, rectangles, and stars, and adding images and text to a 190 Actuate BIRT Application Developer Guide chart. The renderer is useful for adding annotations to a chart. For example, instead of a star, you can annotate the max value by creating text and enclosing it in a rectangle. Figure 8-15 Bar chart with custom objects The JavaScript code written for this bar chart appears in Listing 8-3. Listing 8-3 Event-handling script for the bar chart with custom objects afterRendering: function(myChart) { // Annotate the max value in each series with a // star drawn above the column var chart=myChart.getCore(); // Loop through each series for ( var i = 0; i < chart.series.length; i++ ) { var mySeries = chart.series[i]; var maxValue = mySeries.data[0].y; var maxValueIdx = 0; if ( !maxValue ) { maxValue = 0; } // First, find the max value for this series for ( var j = 1; j < mySeries.data.length; j++ ) { var curValue = mySeries.data[j].y; if ( !curValue ) { continue; } if ( maxValue < mySeries.data[j].y ) { maxValue = mySeries.data[j].y; maxValueIdx = j; Chapter 8, Building an interactive char t 191 } } var maxPoint = mySeries.data[maxValueIdx]; // Now that we have the max value, annotate its column // with a star. Create a group to hold each annotation. var group = chart.renderer.g().add(); var barW = maxPoint.shapeArgs.width; var barX = maxPoint.shapeArgs.x; var barY = maxPoint.shapeArgs.y; // Draw a star based on the width of the column, // and add it to the group var star = chart.renderer.path(['M', barW/2, 0, 'L', barW*.4, barW/4, barW*.05, barW/4, barW*.325, barW*.475, barW*.2, barW*.85, barW/2, barW*.6, barW*.8, barW*.85, barW*.675, barW*.475, barW*.95, barW/4, barW*.6, barW/4, 'Z']) .attr({ fill : 'yellow', stroke: 'black', 'stroke-width': 1 }).add(group); // // // // // // The following tags add interactivites to the star using SMIL animation. SMIL is a subset of SVG that is not supported in all browser environments. These tags are added to demonstrate additional interactivity and animation that can be added via SVG tags - best previewed using Firefox. Add jump animation on mouse over. var jump = chart.renderer.createElement('animateMotion') .attr({ begin : 'mouseover;touchstart', calcMode : 'paced', path : "M 0 0 L 0 -25 L 0 0", dur : '1s', fill : 'freeze', additive : 'sum' }).add(star); // Add rotate animation on mouse over 192 Actuate BIRT Application Developer Guide var rotate = chart.renderer.createElement('animateTransform') .attr({ begin : 'mouseover;touchstart', attributeName : 'transform', type : 'rotate', from : '0 ' + barW/2 + ' ' + barW/2, to : "360 " + barW/2 + " " + barW/2, dur : '1s', additive : 'sum' }).add(star); // Add turn to red fill to the star on mouse click var turnToRed = chart.renderer.createElement('set') .attr({ begin : 'click', attributeName : 'fill', to : 'red' }).add(star); // Move the group to the top of the correct bar, // and set it to draw in front of everything in the chart group.attr({ translateX: barX + chart.plotLeft, translateY: barY + chart.plotTop - barW - 10 }); group.toFront(); } }, Scripting example 3 The scatter chart in Figure 8-16 shows a vertical and horizontal plot line and tooltip that appear when the mouse pointer is placed over a data point. The plot line and tooltip disappear when the mouse pointer is moved away from a data point. Figure 8-16 Scatter chart displaying a dynamic plot line and tooltip Chapter 8, Building an interactive char t 193 The event-handling script to display and remove the plot line dynamically appears in Listing 8-4. Listing 8-4 Event-handling script to display a plot line dynamically beforeGeneration: function(options) { options.xAxis.maxZoom = 3600000*24*90; }, beforeRendering: function(options, chart) { options.plotOptions = { series : { point : { events : { mouseOver: function() { this.series.xAxis.addPlotLine({ color: this.series.color, width: 1, value: this.x, id: 'dynamicVerticalPlotLine' }); this.series.yAxis.addPlotLine({ color: this.series.color, width: 1, value: this.y, id: 'dynamicHorizontalPlotLine' }); }, mouseOut: function() { this.series.xAxis.removePlotLine('dynamicVerticalPlotLine'); this.series.yAxis.removePlotLine('dynamicHorizontalPlotLine'); } } } } }; }, 194 Actuate BIRT Application Developer Guide Chapter 9 Chapter 9 Building a template This chapter contains the following topics: ■ About report templates ■ Design considerations ■ Creating a report template ■ Providing data with a report template ■ Creating themes for a report template ■ Publishing a template ■ Setting the default template category Chapter 9, Building a template 195 About report templates A report template defines the basic report structure for all new reports. Templates are used by applications such as Actuate BIRT Designer Professional and Report Studio. Users sometimes need custom templates that are more appropriate for the data they want to present. An organization typically also requires that reports have a specific look and feel. You create templates using the Report Design perspective in Actuate BIRT Designer Professional, an Eclipse-based application for creating reports. Design considerations A template typically contains visual elements, such as tables, charts, and labels, and can also contain defined data sets which provide the data for a report. A template can also be a complete report that presents professionally formatted data. As you create a template, consider what data the user needs to use in the report, how the user wants to present the data, and what the user needs as a starting point for the report. The following section provides tips for creating effective templates. Separating or combining visual and data elements When designing a template, you can either include both visual and data elements in the template or keep them separate. Templates that contain only visual elements are more versatile. The user can mix and match data objects or information objects with these templates. Separating presentation from data can be efficient and optimal, if developers with design and data-retrieval expertise closely collaborate to ensure that the templates and data are suitable for use together. Designing themes A theme is a collection of styles that can specify the colors used in a report, the font used for different text, label, or data items, the spacing or alignment of items, border styles, and so on. Designers create a theme to apply a consistent style or appearance to a report. When you create a template, consider creating different themes, so that the user can choose from multiple styles. The creation of a theme is optional. Themes are stored in a BIRT library file, separate from the template file. Defining all the styles in a theme within a library makes it easier to maintain and update the appearance of a template. When a user requests new or modified 196 Actuate BIRT Application Developer Guide styles to use with a particular template, update the theme in the library, then publish the latest version of the library to the server. You do not need to modify the template file each time. Improving usability A template should enable the user to quickly determine how to use and freely edit most elements in it. The following guidelines enable you to improve the usability of a template: ■ Set the following optional template properties: ■ The display name of the template The display name should represent the purpose of the template, such as a list or cross tab. If you do not specify a display name, the name of the template file is used. ■ A brief description of the template A description provides additional information that helps the user decide which template to use, appearing as a tooltip when the user hovers the mouse pointer over the thumbnail image of the template. ■ The image to use as the thumbnail image of the template An image provides a graphical preview of the template. If you do not provide an image, a gray box appears displaying the text, “No preview”. Report Template, shown in Figure 9-1, compares two template images in Report Studio. The first thumbnail image shows a template for which properties are not specified. The next one shows a template for which general properties are set. As shown in Figure 9-1, it is easier for a user to decide which template to select if you specify properties when creating the template. Figure 9-1 ■ Displaying two templates: one without properties set and the other with properties set Decide which report elements in the template are editable. Examples of editable elements include labels for displaying report titles, section titles, or column headings, and empty tables into which users insert data. Examples of Chapter 9, Building a template 197 non-editable elements include company logos and standard copyright statements. ■ Provide meaningful names for each report element, so the user can easily identify the element. If you do not specify a name, Report Studio displays the name of the element type, such as Text or Label. The View menu, shown in Figure 9-2, lists all the elements in one of the default templates, so users can choose whether to display or hide the elements in the report. List of elements in the template Figure 9-2 ■ Report items listing all the template elements Provide instructions for using each editable element. For example, a table can display a message, such as “To get started, drag available data from the left or click here if no data is available,” shown in Figure 9-3. Figure 9-3 Template table with instructions Creating a report template You design a template in the same way that you design a BIRT report. You can also create a BIRT design and save it as a template. The file-name extension for a template file is .rpttemplate. To create globally usable templates, localize the text in the templates as you would in a BIRT design. This section describes the key steps for creating a template but does not provide information about the report elements you can use in a template. For information about designing BIRT reports and templates, see BIRT: A Field Guide. How to create a report template 1 To create a new template, in BIRT Designer Professional, in the Report Design perspective, complete the following steps: 198 Actuate BIRT Application Developer Guide 1 Choose File➛New➛Template. 2 In New Template—Template: 1 Select the folder in which to create the template file. 2 Specify a file name. Choose Next. 3 In New Template—Set Template Property: 1 In Display Name, specify a display name for the template. 2 In Description, provide a description of the template. 3 In Template Image, browse to the thumbnail image of the template. This step assumes that you have created the image you want to use as the thumbnail image and placed it in the Shared Resources folder. Choose Finish. A blank report page appears in the layout editor. 2 From the palette, drag the elements you want to include in the template and drop them in the layout editor. 3 Identify elements that you want to allow Report Studio users to edit as template report items. Only labels and tables can be edited in Report Studio: 1 Right-click the element, then choose Create Template Report Item. 2 Specify a descriptive name for the element, so the Report Studio user can easily identify the purpose of the element. 3 Provide instructions for using the element. The instructions appear in the report item in the template. Figure 9-4 shows an example of an element name and instructions for using the element. Figure 9-4 Specifying name and instructions for an editable element 4 For elements that you do not want the Report Studio user to edit, also specify a descriptive name. Figure 9-5 shows setting a label’s name as Copyright. Chapter 9, Building a template 199 Figure 9-5 Specifying a name for a label element that users cannot edit Choose OK. Providing data with a report template To enable the Report Studio user to use a template with an information object or a data object, add an editable table element to the template. When a user selects a template containing an editable table element, Report Studio prompts the user to select a data object or information object data source. Report Studio then prompts the user to select the data fields to display in the report table. If you are creating a template that includes data, create a data source and data set that specifies the data that the Report Studio user can display in the report. You can define multiple data sources and multiple data sets in a template. When the user selects a template with multiple data sets, Report Studio prompts the user to select one of the data sets to use for the report. For information about defining data sources and data sets, see BIRT: A Field Guide. Using a CSV file as a data source A Report Studio report design can use a comma-separated values (CSV) file as a data source if the CSV file is a predefined data set in a report template. To use the file as a data source, copy the CSV file to the appropriate directory. To determine which directory to use, download the report template (.rpttemplate) file to a local directory and save it as an XML file. In the XML code, locate the element, shown in the following example: Data Source C:\ UTF-8 YES 200 Actuate BIRT Application Developer Guide The HOME or URI property shows the directory in which to place the CSV file. Excluding a data set You can exclude a data set in a template from the Select Data dialog in Report Studio. For example, you want to display stock quote data from a web service in the report, but you do not want the user to manipulate the data. To exclude a data set from the Select Data dialog, set the data set’s UsageInBRS property to excluded in the template’s XML representation. For example, the following code excludes the Orders data set: UsageInBRS string true excluded Creating themes for a report template A library can contain any number of themes, and a theme can contain any number of styles. You create themes in a library, then associate the library with a template. Actuate BIRT Designer Professional provides support for the following two types of styles: ■ Create a custom style, and apply it to a report element. For example, you can create a style named Report Title, then apply the style to a label that displays the report title. ■ Apply style properties to predefined style names, or selectors. These predefined style names correspond to the different types of report elements. For example, you can apply style properties to a predefined style named table-header, and all table headers in the report are formatted accordingly. This technique is similar to defining styles in CSS where you associate styles with HTML elements, such as

or

. How to create a theme 1 Create a library: 1 Choose File➛New➛Other. 2 In New, in Select a wizard, expand Actuate BIRT, then select Library. Choose Next. Chapter 9, Building a template 201 3 In New Library, specify the folder in which to create the library, specify a file name, then choose Finish. If a warning message appears, choose OK. 2 Choose Outline view. Outline view, shown in Figure 9-6, displays the types of report elements you can add to a library. Figure 9-6 Outline view 3 In Outline view, expand Themes. 4 Right-click defaultTheme, and choose Rename to change the name of the theme. 5 Right-click the theme, and choose New Style to create a style for the theme. 6 On New Style, select one of the following options: ■ To apply style properties to a specific type of report element, select Predefined Style, and select a style from the drop-down list. ■ To create a user-named style, select Custom Style, and specify a unique descriptive name, such as Report Title or Copyright. 7 Set the desired properties for the style by selecting a property category on the left and specifying property values. 8 When you finish setting style properties, choose OK to save the style. 9 Repeat steps 5 to 8 to create additional styles for the theme. 10 To create a new theme, right-click Themes, and choose New Theme. How to associate a library with a template 1 If the BIRT resource folder is not the current project folder, place the library in the BIRT resource folder, so that it is available to the template. To specify a folder as the resource folder: 1 Choose Window➛Preferences. 2 In Preferences, shown in Figure 9-7, expand Actuate BIRT, and choose Resource. 3 Choose File System to select a folder to use as the resource folder. 202 Actuate BIRT Application Developer Guide Figure 9-7 Specifying the location of the resource folder in Preferences 4 On Directory Selection, navigate to a folder on your computer or on the network, or choose Make New Folder to create a new folder. 5 Choose OK to confirm your folder selection. Preferences displays the path to the resource folder. 6 Choose OK to save the resource folder location information, and close the Preferences window. 7 In Navigator, select the library, then choose File➛Copy Library to Shared Resource Folder. Share Library displays the library name and the location of the resource folder. 8 Choose Finish to confirm placing a copy of the library in the resource folder. 2 Open the template file, and choose Outline view. 3 In Outline view, shown in Figure 9-8, right-click Libraries and choose Use Library. Figure 9-8 Choosing Use Library in the Outline view Chapter 9, Building a template 203 4 In Use Library, expand Shared Resources to display the libraries in the BIRT resource folder. Figure 9-9 shows an example of Use Library. Figure 9-9 Displaying libraries in the resource folder 5 Select the library that contains the themes you want to use with the template, then choose OK. Publishing a template Templates must be published in specific locations for Report Studio to be able to display them. BIRT Designer Professional publishes the templates to the BizRDTemplates folder that it creates in the Resources folder of the volume. Report Studio displays templates by categories. When you publish a template, you can create a new category or select an existing category in which to display your template. You can, for example, organize templates by report types (budget reports, expense reports, stock purchase plan reports) or by departments in your organization (Human Resources, Sales, Customer Support). Figure 9-10 shows an example of Report Studio displaying additional categories by report types. The Standard category appears at the top of the list because it is the default category supplied with Report Studio. All other categories that you create are listed in alphabetical order. You can designate a different template category as the default category, as described later in this section. Typically, each template uses the following external resources that you must also publish to a specific location: ■ An image file that functions as the thumbnail image of the template ■ A library file containing the themes available to the report If a template contains localized text and you have created resource files that translate text into different languages, you must also publish these (.properties) files. You publish all resources associated with a template when publishing the template. BIRT Designer Professional publishes these files to specific locations from which Report Studio can access them. 204 Actuate BIRT Application Developer Guide Figure 9-10 Displaying available template categories in Report Studio How to publish a report template 1 In Actuate BIRT Designer Professional, in Navigator, right-click the template file, then choose Publish➛Publish Templates. Publish Templates appears with the template file selected, as shown in Figure 9-11. Figure 9-11 Publishing templates using BIRT Designer Professional 2 In Publish Templates, select Report Libraries to publish the themes and images associated with the template. 3 Select a server profile from the drop-down list. A server profile specifies the connection properties to connect to a specific Encyclopedia volume. To create a new server profile, complete the following steps: 1 Choose Add. Server Profile appears. In Server Profile, complete the following steps: 2 In Server Type, select one of the following: ❏ Server If you select this option, complete steps 3 to 8. Chapter 9, Building a template 205 ❏ Cloud Server If you select this option, complete steps 9 to 13. 3 In Profile name, type a unique name that identifies the new profile. 4 In Server, type the name or IP address of the computer on which Actuate BIRT iHub is installed. 5 In Port number, type the number of the port to access Actuate BIRT iHub. 6 If necessary, select the option to use a secure connection. 7 In User name, type the user name for accessing the volume. 8 In Password, type the password for accessing the volume. Choose Finish. Proceed to step 4. 9 In Profile name, type a unique name that identifies the Cloud profile. 10 In Cloud Service URL, type the address for your cloud service. 11 Choose Login. 12 In Server Name, select the server to log in to. 13 In Volume, select a volume. Choose Finish. 4 In Publish Templates, in Template Category, select an existing category from the drop-down list in which to publish the template. Alternatively, create a new category by choosing Browse, then specifying the name of the new category. 5 In Version, select a version option. To copy the privileges from the last published version of the template, select Copy permissions from last version. 6 Choose Publish, then after the file is published, choose Close. The first time you publish a template to an Encyclopedia volume, you must grant users access to the appropriate template folders and files. For more information about assigning privileges for folders and files on an Actuate BIRT iHub Encyclopedia volume, see Managing Volumes and Users. Setting the default template category To select a custom template, select a different category from the Category drop-down list. You can configure Report Studio so that the Report Template dialog displays a different template category as the default category. 206 Actuate BIRT Application Developer Guide How to set the default template category 1 Navigate to the WEB-INF directory of your Actuate web application. By default, the file path is: \WEB-INF 2 Open web.xml for editing. 3 Change the value of the DEFAULT_REPORT_TEMPLATE_CATEGORY _NAME parameter from Standard to the name of the category whose templates you want the Report Template dialog to display by default. The following example shows the Sales category set as the default template category: DEFAULT_REPORT_TEMPLATE_CATEGORY_NAME Sales 4 Restart the web or application service for your Actuate web application to apply the changes you made. Chapter 9, Building a template 207 208 Actuate BIRT Application Developer Guide Part Part 4 Four 4 Enhancing application components Chapter 10 Chapter 10 Writing expressions using EasyScript This chapter contains the following topics: ■ About EasyScript ■ Using the EasyScript expression builder ■ Changing the default expression syntax Chapter 10, Writing expressions using EasyScript 211 About EasyScript EasyScript is an expression syntax similar to the syntax used in Excel formulas. Like Excel, EasyScript provides functions for performing calculations on report data. In BIRT Designer Professional, EasyScript is supported in most places an expression is required. For example, when specifying an expression for a computed column, a column binding, a filter condition, or a map rule, you can use either JavaScript or EasyScript. Choosing between EasyScript and JavaScript You can use both JavaScript and EasyScript expressions in a report. For simple expressions or common calculations, the choice is often based on syntax familiarity or simplicity. Users who work with Excel functions will find EasyScript syntax familiar and easy to use. The following example is an EasyScript expression that rounds values in a Price field to the nearest integer: ROUND([Price]) The following example is the equivalent JavaScript expression: Math.round(row["Price"]) Both expressions are straightforward, although one could argue that the EasyScript syntax is simpler. Now, compare the expressions used to round the Price values to 2 decimal places. In the following expressions, the first shows EasyScript syntax, and the second shows JavaScript syntax: ROUND([Price], 2) Math.round(row["Price"]*100)/100 In this case, the EasyScript syntax is clearly simpler and more intuitive. The EasyScript ROUND( ) function provides a second argument that lets you specify the number of decimal places to which to round the number. The JavaScript round( ) function does not, and, therefore, requires additional mathematical operations. If a report needs complex calculations that require lines of code or calculations that cannot be done with EasyScript, use JavaScript. For information about writing JavaScript expressions, see BIRT: A Field Guide. Syntax rules When writing an EasyScript expression, observe the following rules: ■ 212 Enclose field names within square brackets ([ ]), for example, [CustomerID]. Actuate BIRT Application Developer Guide ■ Field names and function names are case-sensitive. All function names are uppercase. ■ When creating an expression that contains a literal date, always type the date according to the conventions of the US English locale. For example, if working in the French locale, type 07/10/2010 to represent July 10, 2010. Do not type 10/07/2010, which is the convention for dates in the French locale. The following expression, which calculates the number of days from the current date to Christmas, includes a literal date: DIFF_DAY(TODAY(), "12/25/10") ■ When creating an expression that contains a literal number, always type the number according to the conventions of the US English locale. Use a period (.), not a comma (,) as the decimal separator. Using the EasyScript expression builder When specifying an expression, the JavaScript syntax is the default. Figure 10-1 shows the icon that represents JavaScript syntax. Clicking on this icon opens the JavaScript expression builder. Icon representing JavaScript syntax Figure 10-1 An expression property set to use a JavaScript expression To switch to EasyScript syntax, click the arrow button next to the JavaScript syntax icon and choose EasyScript Syntax, as shown in Figure 10-2. Figure 10-2 Switching to EasyScript This action opens the EasyScript expression builder, shown in Figure 10-3. Chapter 10, Writing expressions using EasyScript 213 Figure 10-3 EasyScript expression builder Like the JavaScript expression builder, the EasyScript expression builder provides help selecting functions and fields to use in an expression. To use a function in an expression, type the first letter of the function, then select a function from the list that appears. To use a field, type the left square bracket ([), then select a field from the list. When you finish creating an expression, choose Validate to verify the expression. Changing the default expression syntax If you consistently use EasyScript or use it more than JavaScript, you can change the Default Syntax property in Preferences to EasyScript syntax. To access this property, select Window➛Preferences, and choose Report Design—Expression Syntax. After changing the default syntax, the EasyScript syntax icon appears by default every time you create a new expression. The Default Syntax property does not convert existing JavaScript expressions to EasyScript expressions, and vice versa. To change the syntax of an expression, you must select the syntax type and edit the expression accordingly. 214 Actuate BIRT Application Developer Guide Chapter 11 Adding web interactivity to a report Chapter 11 This chapter contains the following topics: ■ About HTML buttons ■ Creating an HTML button ■ Writing code for an HTML button ■ Changing the appearance of an HTML button Chapter 11, Adding web interactivity to a repor t 215 About HTML buttons In a BIRT report, an HTML button is a report element that provides the same functionality as a button defined with the HTML

]]> Optionally, gadget developers can use the object tag to embed the Adobe Flash content in HTML code. For more information about using Adobe Flash, see “Displaying Adobe Flash content” in Chapter 4, “Displaying a file on a dashboard.” Using the minimessage feature Use the minimessage feature to display a temporary message to users. Figure 14-3 shows the minimessage feature in a gadget. Figure 14-3 Using the minimessage feature Chapter 14, Building Google gadgets 269 The following code shows the minimessage feature used in a Google gadget: ]]> Using the pubsub feature The pubsub feature of a Google gadget is also called the publish and subscribe gadget framework. This framework enables gadgets to send and receive messages from one Google gadget to another and to link Google gadgets to Actuate gadgets. For more information about linking gadgets, see “Linking Google gadgets,” later in this chapter. Using the tabs feature Use the tabs feature to organize the gadget content with tabs. Figure 14-4 shows the tabs feature in a gadget. Figure 14-4 Using the tabs feature The following code shows the tabs feature in a Google gadget: 270 Actuate BIRT Application Developer Guide var tabs = new gadgets.TabSet(__MODULE_ID__, "Two"); function init() { tabs.addTab("One", { contentContainer: document.getElementById("id_1")}); tabs.addTab("Two", { contentContainer: document.getElementById("id_2")}); tabs.addTab("Three", { contentContainer: document.getElementById("id_3")}); } gadgets.util.registerOnLoadHandler(init); ]]> Linking Google gadgets Google gadgets display on the dashboard using import gadgets. Google gadgets link to other gadgets to share values in the following ways: ■ Link to a data selection gadget by choosing Link from the import gadget menu. ■ Link to another Google gadget using the Google publish subscribe framework. Link Google gadgets to data selection gadgets to receive user selections. The value of the user selection is processed using JavaScript and displays in the import gadget using HTML. For example, a list gadget can send a user selection to a Google gadget. After the Google gadget processes the value it displays a JavaScript alert that contains the user selected value. If you need to process the linked values before the value is passed to the Google gadget, add JavaScript to the link configuration of the import gadget. For more information about scripting, see Chapter 4, “Displaying a file on a dashboard.” Linking an import gadget Link an import gadget to a data selection gadget, such as a list, to receive user selection values. You can now use the Google gadget pubsub feature to receive and process the user selection. Use the gadgets.pubsub.subscribe(channelName, Chapter 14, Building Google gadgets 271 callback) method in the Google gadget to receive the linked value and send it to a callback function, as shown in the following code: gadgets.pubsub.subscribe("ON_SELECTOR_GADGET_CHANGED", callbackFunction); The callback function in the Google gadget XML file processes the received value. For example, a callback function reads the incoming message and extracts a value, such as a customer’s address. The callback function then sends the address to an external web service such as Google maps. When the web service responds, the gadget updates with the map showing the location of the address. Listing 14-2 shows an example Google gadget that displays changes from a linked data selection gadget. After saving the Google gadget code as an XML file and placing it on a web server, load the file into an import gadget. Link the import gadget to a data selection gadget on the dashboard. Each time the linked data selection gadget changes, the selected value displays in the Google gadget. Listing 14-2 Example Google gadget with linking enabled function onEventChange(sender, message) { document.getElementById('changeme').innerHTML=message; } gadgets.pubsub.subscribe("ON_SELECTOR_GADGET_CHANGED", onEventChange);
DEFAULT TEXT

The above text changes according to the current selection of the gadgets it is linked to.
]]>
Linking multiple Google gadgets BIRT dashboards support displaying multiple Google gadgets on the same dashboard. When an import gadget links to a data selection gadget, the message sent by the user selection is a global message. This global message is published across the dashboard on the ON_SELECTOR_GADGET_CHANGED channel and all subscribing import gadgets that listen on the ON_SELECTOR_GADGET_CHANGED channel receive the same message. 272 Actuate BIRT Application Developer Guide Google gadgets must listen on unique channel names unless you want them to receive the same user selected values. For example, a dashboard developer adds an import gadget to show a map of customer addresses and another import gadget to show shipping status on orders. When a user selects the order number from a list gadget that links to both import gadgets, then those import gadgets receive the value and process it. The import gadget that shows shipping status can process the value. The import gadget showing a map expects an address and is unable to retrieve a valid map from an order number. The issue is resolved when both import gadgets listen on different channels for user selections. Once each Google gadget listens for a unique channel event name, messages go to the correct gadget. To use a unique channel name in a Google gadget, change the channel name when calling the gadgets.pubsub.subscribe( ) method. The following code shows the channel name changed to Unique_channel_name: gadgets.pubsub.subscribe("Unique_channel_name", onEventChange); Only data arriving on the unique channel name triggers the onEventChange function of the Google gadget. Once the Google gadget is listening for a unique channel name, the channel name used to send the value must also change to match the unique channel name. Add a script to the link settings of the import gadget to match the channel name used in the embedded Google gadget. The following code shows an example of JavaScript that changes the channel event name to Unique_channel_name. data.event = 'Unique_channel_name'; This script overrides the default channel name before the import gadget passes the information to the Google gadget. The unique channel name must match the name that the embedded Google gadget is listening for. Figure 14-5 shows JavaScript in a link event for an import gadget. Figure 14-5 Changing the channel event name All import gadgets listening for the new channel name receive messages from the list gadget. In this example the new channel name is Unique_channel_name. Chapter 14, Building Google gadgets 273 For more information about adding script to a linking gadget, see “Scripting linked gadgets” in Chapter 13, “Linking and scripting gadgets.” Linking Google gadgets together Gadget developers can build Google gadgets that communicate with one to another using Google’s publish subscribe framework API. One gadget can publish a message and another gadget can subscribe to it. For example, one Google gadget can offer choices to users and another Google gadget can process and display the user’s selections. Google gadgets that communicate with each other on a dashboard must display inside an import gadget and communicate on the same channel name. The dashboard developer does not link the two import gadgets together because the Google gadget contains all the necessary code to publish and to receive the messages. Listing 14-3 shows an example Google gadget that publishes the current date to a custom channel when a user selects the HTML button. Listing 14-3 Example of a publishing Google gadget ...

]]> Create a second import gadget using the code from Listing 14-2. Change the channel that the new Google gadget subscribes to so that it matches the channel name of the publishing Google gadget. In the previous example, the channel 274 Actuate BIRT Application Developer Guide name was MY_CHANNEL_NAME. Change the subscribe method to use this channel name, as shown in the following code: gadgets.pubsub.subscribe("MY_CHANNEL_NAME", onEventChange); Use import gadgets to add both Google gadgets to the same dashboard. When the user chooses the HTML button, the subscribing Google gadget receives the published message. Figure 14-6 shows the two gadgets communicating. Figure 14-6 Communicating between Google gadgets You do not need to link the two import gadgets together because the Google gadget contains all the necessary code to communicate, to publish, and to receive the message. Linking public Google gadgets Google gadgets that the dashboard developer does not own and cannot modify, can receive user selections if the gadget uses the pubsub feature. The dashboard developer adds a script to the import gadget that displays the Google gadget. This script changes the link channel name to match the channel name of the Google gadget. For example, you look at the source code of a Google gadget and see the following code: gadgets.pubsub.subscribe("MY_PERSONAL_GOOGLE_GADGET", onEventChange); The channel name used by this Google gadget is MY_PERSONAL_GOOGLE_GADGET. After linking to a data selection gadget, such as a list gadget, add a script to the link configuration of the import gadget to match the channel name required by the public Google gadget. The following code shows an example of this script, changing the name of the event to MY_PERSONAL_GOOGLE_GADGET: data.event = "MY_PERSONAL_GOOGLE_GADGET"; When the user makes a selection from the list, the import gadget changes the channel name and passes the message to the Google gadget. For more information about adding script to a linked gadget, see “Scripting linked gadgets” in Chapter 13, “Linking and scripting gadgets.” Chapter 14, Building Google gadgets 275 276 Actuate BIRT Application Developer Guide Part Five 5 Using Actuate JavaScript API in an application Part 5 Chapter 15 Creating dynamic report content using the Actuate JavaScript API Chapter 15 This chapter contains the following topics: ■ About Actuate JavaScript API scripting in a BIRT report design ■ Using the Actuate JavaScript API in an HTML button ■ Using the Actuate JavaScript API in chart interactive features ■ Using the Actuate JavaScript API in chart themes Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 279 About Actuate JavaScript API scripting in a BIRT report design The scripting features of the BIRT designers support using the JSAPI for the following operations: ■ Using the Actuate JavaScript API in an HTML button ■ Using the Actuate JavaScript API in chart interactive features ■ Using the Actuate JavaScript API in chart themes Most Actuate JavaScript API functions run when an event occurs. The report element defines the events that it supports. For example, the onRender event occurs when the report renders in the viewer or on a page. A BIRT report or Reportlet renders in the following ways: ■ In BIRT Viewer or Interactive Viewer ■ In BIRT Studio ■ In Actuate BIRT Designer ■ In an Actuate JavaScript API viewer object on a mashup page All of these products load the actuate.Viewer and actuate.Dialog classes when they render a report, except for the preview functionality in BIRT Designer. Use the View Report in Web Viewer function to view and test Actuate JavaScript API scripts with BIRT Designer, as shown in Figure 15-1. Figure 15-1 Accessing Web Viewer in Actuate BIRT Designer Most of the classes and functions in the actuate.Viewer class can be used in a BIRT report design without loading or initializing the actuate.Viewer class and. Most of the viewers also load the actuate.Parameters and actuate.DataService classes by 280 Actuate BIRT Application Developer Guide default. Define the classes loaded for Actuate JavaScript API mashup page explicitly. Load the DataService, Parameters, and Viewer classes before the API initializes the connection to the reporting web service. Using the Actuate JavaScript API in an HTML button The HTML button element can execute client-side JavaScript code based on button events. Access the HTML button in the BIRT designer by selecting a button element, choosing the script tag, and selecting the event from the event drop-down list, as shown in Figure 15-2. Figure 15-2 Choosing HTML button event handlers Use event functions to add JavaScript functionality to HTML buttons. For example, a button that swaps columns of data, filters data, sorts data, hides information, or groups the rows of a table by some data column can be created with event functions. The following script groups the rows of a table by the quantity of items in each order when the HTML button is clicked: this.onclick = function(event){ var btable = this.getViewer( ).getCurrentPageContent( ) .getTableByBookmark("TableBookmark"); btable.groupBy("QUANTITYORDERED"); btable.submit( ); } When the HTML button triggers the example event above, the table grouping changes and the display refreshes, as shown in Figure 15-3. HTML buttons can be arranged into sets of controls for the user to use once a report runs. For example, when these buttons are used in the header for a table, the header can provide controls similar to those in the header shown in Figure 15-4. Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 281 Figure 15-3 Using a GroupBy HTMLButton control Figure 15-4 HTML button header Tutorial 4: Adding scripted chart controls to a BIRT design In this tutorial, you add HTML buttons to a BIRT design that implement controls for a chart in the BIRT design. You perform the following tasks: ■ Add bookmarks. ■ Add a filter script to chart interactivity. ■ Script the chart size controls. ■ Test the scripts. Task 1: Add HTML buttons In this task, you review a BIRT report design called ChartWithHTMLButtons.rptdesign and create a grid of HTML buttons. 282 Actuate BIRT Application Developer Guide 1 Open BIRT Designer Professional. In Navigator, navigate to and open ChartWithHTMLButtons.rptdesign. 2 Preview the report, as shown in Figure 15-5. Figure 15-5 Previewing the report 3 Choose Layout to return to the layout editor. 4 Right-click the first cell of the table. Choose Insert➛Grid. On Insert Grid, set Number of columns to 2 and Number of rows to 2, then choose OK. A new grid appears above the chart, as shown in Figure 15-6. Figure 15-6 Inserting a grid Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 283 5 To create HTML buttons for the report, perform the following steps: 1 Right-click the first cell of the grid. Choose Insert➛HTML Button. 2 On HTML Button, type "2D with Depth" into the value field. 3 Choose OK. If a warning message appears, choose OK. 6 Repeating the process of step 6, create an HTML button in the remaining empty cells of the grid with the values "2D", "resize 400x600", and "resize 600x400". Task 2: Script the chart sub_type controls In this task, you add event handler scripts to HTML buttons that change the subtype controls of the chart. 1 Select the chart. In the property editor, open Properties➛Bookmark. Set the bookmark value to "ChartBookmark" as shown in Figure 15-7. Figure 15-7 Setting the chart bookmark property 2 Select the 2D with Depth HTML button and choose Script. 3 In the New Event Function drop-down list, select onclick. The onclick event handler appears in the script editor text box. 4 After the first curly brace ({), add the following code: var bchart = this.getViewer().getCurrentPageContent() .getChartByBookmark("ChartBookmark"); bchart.setChartTitle("Orders by Country (2D with Depth)"); bchart.setDimension(actuate.report.Chart .CHART_DIMENSION_2D_WITH_DEPTH ); bchart.submit(); 5 Return to the layout editor. Select the 2D HTML button and choose Script. 6 In the New Event Function drop-down list, select onclick. The onclick event handler appears in the script editor text box. 7 After the first curly brace ({), add the following code: var bchart = this.getViewer().getCurrentPageContent() 284 Actuate BIRT Application Developer Guide .getChartByBookmark("ChartBookmark"); bchart.setChartTitle("Orders by Country"); bchart.setDimension(actuate.report.Chart.CHART_DIMENSION_2D ); bchart.submit(); Task 3: Script the chart size controls In this task, you add event handler scripts to HTML buttons that change the display dimensions of the chart. 1 Select the Resize 400x600 HTML button and choose Script. 2 In the New Event Function drop-down list, select onclick. The onclick event handler appears in the script editor text box. 3 After the first curly brace ({), add the following code: var bchart = this.getViewer().getCurrentPageContent() .getChartByBookmark("ChartBookmark"); bchart.setChartTitle("Orders by Country (400x600)"); bchart.setSize(400,600); bchart.submit(); 4 Return to the layout editor. Select the Resize 600x400 HTML button and choose Script. 5 In the New Event Function drop-down list, select onclick. The onclick event handler appears in the script editor text box. 6 After the first curly brace ({), add the following code: var bchart = this.getViewer().getCurrentPageContent() .getChartByBookmark("ChartBookmark"); bchart.setChartTitle("Orders by Country (600x400)"); bchart.setSize(600,400); bchart.submit(); Task 4: Test the scripts In this task, you run the report and test the HTML button scripts. 1 Save the report. 2 View the report by choosing Run➛View Report➛In Web Viewer. 3 In the Actuate viewer, choose Resize 600x400. The report title changes and the report changes size, as shown in Figure 15-8. 4 In the Actuate viewer, choose 2D with Depth. The report title changes and the report subtype changes to 2D with depth, as shown in Figure 15-9. Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 285 Figure 15-8 A chart displaying 600x400 size Figure 15-9 A chart with a 2D with Depth subtype 5 Choose other buttons to test scripted changes to the report display. 286 Actuate BIRT Application Developer Guide Tutorial 5: Using HTML buttons to apply filters to a chart In this tutorial, you add multiple HTML buttons to an existing report that each add a filter for a different product line. An additional HTML button removes all filters to display data for all product lines.You perform the following tasks: ■ Add a filter button to the report. ■ Add HTML buttons for the remaining product lines. ■ Add the final HTML button to the report. ■ Test the report. Task 1: Add a filter button to the report In this task, you preview a report called ButtonFilterChart.rptdesign and add the first HTML button that implements event handlers to apply a filter to the chart. 1 In Navigator, open ButtonFilterChart.rptdesign. 2 Choose Run➛View Report➛In Web Viewer to view the report, as shown in Figure 15-10. Figure 15-10 Previewing the line chart report Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 287 3 Close the Web Viewer window. From Palette, drag an HTML button element into the first grid cell, as shown in Figure 15-11. Place button in grid cell Figure 15-11 Viewing the location of the first HTML button 4 In HTML Button, type the following text for Value: Classic Cars 5 Choose OK. If a warning appears displaying a message about adding functionality, choose OK. 6 Choose Script, as shown in Figure 15-12, to access the script editor. Figure 15-12 Choosing Script 7 In New Event Function, select onclick. 8 In the function body for the onclick event handler, copy the code for the Classic Cars button shown in Listing 15-1. Listing 15-1 Classic Cars JSAPI code var bviewer = this.getViewer( ); var bpagecontents = bviewer.getCurrentPageContent( ); var bchart = bpagecontents.getChartByBookmark("ChartBookmark"); if (bchart == null) return;// unable to get handle to chart in case where chart becomes hidden var filter = new actuate.data.Filter("PRODUCTLINE", actuate.data.Filter.EQ, "Classic Cars"); var filters = new Array( ); filters.push(filter); bchart.setFilters(filters); bchart.setChartTitle("Orders By Country (Classic Cars)"); bchart.submit( ); 9 Preview the report in the web viewer by choosing Run➛View Report ➛In Web Viewer. Click on the Classic Cars HTML button that appears in the top left corner and the filtered chart appears as shown in Figure 15-13. 288 Actuate BIRT Application Developer Guide Figure 15-13 Previewing the report with the Classic Cars data 10 Close Actuate Viewer. Task 2: Add HTML buttons for the remaining product lines In this task, you add six HTML buttons, one for each of the remaining product lines. 1 Choose Layout to return to the layout editor. From Palette, drag an HTML button element into the next available grid cell. In HTML Button, for Value, type: Motorcycles Choose OK. If a warning appears displaying a message about adding functionality, choose OK. The HTML button appears in the layout editor. 2 Choose the Script tab. In New Event Function, select onclick. Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 289 3 Copy the code for the Classic Cars button shown in Listing 15-1, and paste the code in the function body of the onclick event handler. 4 In Script, replace Classic Cars with Motorcycles in the following two lines: var filter = new actuate.data.Filter("PRODUCTLINE", actuate.data.Filter.EQ, "Classic Cars"); and: bchart.setChartTitle("Orders By Country (Classic Cars)"); The edited event handler appears as shown in Listing 15-2. Listing 15-2 Motorcycles JSAPI code var bviewer = this.getViewer( ); var bpagecontents = bviewer.getCurrentPageContent( ); var bchart = bpagecontents.getChartByBookmark("ChartBookmark"); if (bchart == null) return;// unable to get handle to chart in case where chart becomes hidden var filter = new actuate.data.Filter("PRODUCTLINE", actuate.data.Filter.EQ, "Motorcycles"); var filters = new Array( ); filters.push(filter); bchart.setFilters(filters); bchart.setChartTitle("Orders By Country (Motorcycles)"); bchart.submit( ); 5 Repeat steps 1 through 4 of this task for the following five buttons and data values: ■ Planes ■ Ships ■ Trains ■ Trucks and Buses ■ Vintage Cars When complete, the report layout appears as shown in Figure 15-14. 290 Actuate BIRT Application Developer Guide Figure 15-14 Task 3: Viewing filter buttons in Layout Add the final HTML button to the report In this task, you add the final filter button to the report. This button is different from the previous buttons, in that it will clear any filter and display summary data for all product lines. 1 From Palette, drag an HTML button element into the remaining grid cell. In HTML Button, in Value, type: Show All Choose OK. 2 Choose Script. In New Event Function, select onclick. 3 In the function body for the onclick event handler, copy the code for the Show All button shown in Listing 15-3. Listing 15-3 JSAPI code to remove filters from charts var bviewer = this.getViewer( ); var bpagecontents = bviewer.getCurrentPageContent( ); var bchart = bpagecontents.getChartByBookmark("ChartBookmark"); if (bchart == null) return;// unable to get handle to chart in case where chart becomes hidden bchart.clearFilters("PRODUCTLINE"); bchart.setChartTitle("Orders By Country"); bchart.submit( ); 4 Choose Layout. The Show All button appears as shown in Figure 15-15. Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 291 Figure 15-15 Task 4: Viewing all buttons in Layout Test the report In this task, you test the report by selecting the various product line buttons. 1 Choose Run➛View Report➛In Web Viewer. 2 Choose the Planes HTML button. The chart changes, as shown in Figure 15-16. Figure 15-16 292 Viewing the report after selecting the Planes HTML button Actuate BIRT Application Developer Guide Using the Actuate JavaScript API in chart interactive features BIRT reports support adding interactive features to a chart to enhance the behavior of a chart in the viewer. The interactive chart features are available through the chart builder. Implement Actuate JavaScript API functions within interactive features. An interactive chart feature supports a response to an event, such as the report user choosing an item or moving the mouse pointer over an item. The response can trigger an action, such as opening a web page, drilling to a detail report, or changing the appearance of the chart. For example, use a tooltip to display the series total when a user places the mouse over a bar in a bar chart, as shown in Figure 15-17. Figure 15-17 Chart showing a tooltip Interactive features can be added to a value series, the chart area, a legend, marker lines, the x- and y-axis, or a title. Figure 15-18 identifies these elements. Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 293 Y Axis Chart Title Chart Area Marker Line Value Series Legend X Axis Figure 15-18 Elements selectable for chart interactivity To add an interactive feature to a chart, either choose Format Chart in the chart builder and select a chart element to make interactive, or choose Script in the chart builder and select the chart element to make interactive. Figure 15-19 shows the location of the Interactivity button for a value series. Interactivity button Figure 15-19 Accessing interactivity for a value series Figure 15-20 shows the elements accessible using the script feature. 294 Actuate BIRT Application Developer Guide Figure 15-20 Accessing interactivity for a legend The location of the Interactivity button varies by chart element. Click the Interactivity button to display the interactivity editor. Figure 15-21 shows the interactivity editor. Figure 15-21 Interactivity editor The Action Details window displays a script that runs when the user clicks an item in the series. The script adds a filter to the table that displays below the chart. The filter restricts the data by the selected element. The code performs the following three tasks to handle this interactivity: ■ Obtains the bookmark for the table when the event occurs: Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 295 var viewer = actuate.getViewer(evt.srcElement || evt.originalTarget) var table = viewer.getTable( ); The event is taken from the Invoke Script action of a BIRT chart. Set the Invoke Script action in the second field of the interactivity editor. The Invoke Script action contains the following variables: ■ evt: browser event object ■ categoryData: value of the selected category ■ valueData: numeric value of the selected item ■ valueSeriesName: name of the selected series The code above uses getViewer and the evt object to obtain a handle for the viewer when an event occurs. The Firefox and Internet Explorer browsers implement the event differently. For Firefox, evt.originalTarget contains the name of the viewer object. For Internet Explorer, evt.srcElement contains the name of the viewer object. The getTable( ) function retrieves the Table object for the first table in the viewer. To target a different table, use a specific table bookmark as the input parameter for getTableByBookmark( ). ■ Performs an operation on the target: table.setFilters(new actuate.data.Filter("Country", actuate.data.Filter.EQ, categoryData)); This code example creates a new filter using the actuate.data.Filter constructor. The constructor takes three arguments: ■ ■ column name: The column name is the name of the series. In this case, the y-axis is a list of countries, so a mouse click filters the table according to the Country column. ■ operator: actuate.data.Filter.EQ is the constant definition for the equal to operator. ■ value: the value of the categoryData object generated by the event, which is a country. The filter returns rows with a Country value that matches the value selected by the user. Submits the action for processing: table.submit( ); The Actuate JavaScript API processes operations asynchronously. Actions are performed when submit( ) is called. Figure 15-22 shows the chart before interaction. 296 Actuate BIRT Application Developer Guide Figure 15-22 An interactive chart and table before any user action When the user selects the bar for Australia in the value series, the table is filtered for Australia, as shown in Figure 15-23. Figure 15-23 An interactive chart and table after the user selects Australia Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 297 Tutorial 6: Adding an interactive chart filter to a BIRT report In this tutorial, you add an interactive chart control to a BIRT report design that implements a filter on the other charts in the report design. You perform the following tasks: ■ Add bookmarks. ■ Add a filter script to chart interactivity. Task 1: Add bookmarks In this task, you preview a report called InteractiveChartandTable.rptdesign and add a bookmark to the chart and table. 1 In Navigator, open InteractiveChartandTable.rptdesign. 2 Choose Run➛View Report➛In Web Viewer to view the report, as shown in Figure 15-24. 3 Choose Layout to return to the layout editor. Figure 15-24 298 Previewing the report Actuate BIRT Application Developer Guide 4 Select the chart entitled Sales by Quarter. In the property editor, open Properties➛Bookmark. Set the bookmark value to "SalesChart", as shown in Figure 15-25. Figure 15-25 Setting the chart bookmark property 5 Repeating the process of step 5, for the table entitled Product Line, set the bookmark value to "ProductTable". Task 2: Add a filter script to chart interactivity In this task, you add a filter script to the Sales by Quarter chart to affect the other charts. 1 Double-click on the Sales by Quarter chart. In Edit Chart, select Format Chart ➛Series➛Value (Y) Series. Then choose Interactivity. 2 On Series Interactivity, select Mouse Click for event, and Invoke Script for action, as shown in Figure 15-26. Figure 15-26 Interactivity settings for invoking a script on mouse click 3 In the Script text box, add the following code: var atable = actuate.getViewer(evt.srcElement || evt.target) .getCurrentPageContent( ).getTableByBookmark("ProductTable" ); atable.setFilters(new actuate.data.Filter("QUANTITYORDERED", actuate.data.Filter.GREATER_THAN, valueData/200)); atable.submit(); In Edit Chart, choose Finish. 4 View the report by choosing Run➛View Report➛In Web Viewer. Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 299 5 Select a bar in the table to activate the filter, as shown in Figure 15-27. Figure 15-27 Filtered product table after selecting a chart value Using the Actuate JavaScript API in chart themes BIRT reports support adding themes to a chart to apply common elements to similar charts. Access chart themes by exporting and then editing a theme or by creating a new theme. Implement Actuate JavaScript API functions within specific theme elements or in the script feature of the theme. A chart theme supports executing a script before or after certain events, such as before rendering the chart. For example, you can add scripts for beforeGeneration, beforeRendering, beforeDrawAxis, beforeDrawSeries, beforeDrawDataPoint, and afterRendering when editing a chart theme, as shown in Figure 15-28. 300 Actuate BIRT Application Developer Guide Figure 15-28 Adding script elements in edit chart theme In an HTML5 chart, you can use the actuate.report.HTML5Chart classes to alter the report display. For example, to render every data point in the series that is greater than avgValue in a green color, use code similar to the following: beforeDrawSeries: function(series, seriesOptions, tempChart, seriesIndex){ for ( var i = 0; i < series.data.length; i++ ){ // Find out if this data point is above average if ( series.data[i].y <= aveValue ){ // The data point is above average. Color it green var pointOptions = seriesOptions.data[i]; pointOptions.color = 'green'; } } Tutorial 7: Adding scripted HTML5 Chart controls to a BIRT design In this tutorial, you add HTML buttons to a BIRT design that implement controls for an HTML5 chart in the BIRT design. You perform the following tasks: ■ Adding HTML buttons ■ Scripting the client chart controls ■ Scripting the client option controls ■ Testing the scripts Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 301 Task 1: Adding HTML buttons In this task, you preview a report called HTML5ChartWithHTMLButtons.rptdesign and create a grid of HTML buttons. 1 Open BIRT Designer Professional. In Navigator, navigate to and open HTML5ChartWithHTMLButtons.rptdesign. 2 Preview the report, as shown in Figure 15-29. Figure 15-29 Previewing the HTML5 Chart report 3 Choose Layout to return to the layout editor. 4 Right-click the first cell of the table. Choose Insert➛Grid. On Insert Grid, set the Number of columns to 2 and Number of rows to 2, then choose OK. A new grid appears at the top of the table, as shown in Figure 15-30. 5 To create HTML buttons for the report, perform the following steps: 1 Right-click the first cell of the grid. Choose Insert➛HTML Button. 2 On HTML Button, type "Hide On Hold" into the value field. 3 Choose OK. If a warning message appears, choose OK. 6 Repeating the process of step 6, create an HTML button in the remaining empty cells of the grid with the values "Show On Hold", "Line Chart", and "Area Chart". 302 Actuate BIRT Application Developer Guide Figure 15-30 Task 2: Inserting a grid Scripting the client chart controls In this task, you add event handler scripts to HTML buttons that change the client chart series of the HTML5 chart. 1 Select the chart. In the property editor, open Properties➛Bookmark. Set the bookmark value to "HTML5ChartBookmark" as shown in Figure 15-31. Figure 15-31 Setting the chart bookmark property 2 Select the Hide On Hold HTML button and choose Script. 3 In the New Event Function drop-down list, select onclick. The onclick event handler appears in the script editor text box. 4 After the first curly brace ({), add the following code: var bchart = this.getViewer().getCurrentPageContent() .getChartByBookmark("HTML5ChartBookmark"); var clientChart = bchart.getClientChart(); clientChart.setTitle("HTML5 Chart: On Hold series is invisible"); clientChart.setSeriesVisibile('On Hold', false); 5 Return to the layout editor. Select the Show On Hold HTML button and choose Script. 6 In the New Event Function drop-down list, select onclick. The onclick event handler appears in the script editor text box. 7 After the first curly brace ({), add the following code: var bchart = this.getViewer().getCurrentPageContent() Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 303 .getChartByBookmark("HTML5ChartBookmark"); var clientChart = bchart.getClientChart(); clientChart.setTitle("HTML5 Chart: On Hold series is visible"); clientChart.setSeriesVisibile('On Hold', true); Task 3: Scripting the client option controls In this task, you add event handler scripts to HTML buttons that change the chart type using the client options of the HTML5 chart. 1 Select the Line Chart HTML button and choose Script. 2 In the New Event Function drop-down list, select onclick. The onclick event handler appears in the script editor text box. 3 After the first curly brace ({), add the following code: var bchart = this.getViewer().getCurrentPageContent() .getChartByBookmark("HTML5ChartBookmark"); var clientChart = bchart.getClientChart(); clientChart.getClientOptions().setChartType('line'); clientChart.getClientOptions().setTitle('Line chart'); clientChart.redraw(); 4 Return to the layout editor. Select the Area Chart HTML button and choose Script. 5 In the New Event Function drop-down list, select onclick. The onclick event handler appears in the script editor text box. 6 After the first curly brace ({), add the following code: var bchart = this.getViewer().getCurrentPageContent() .getChartByBookmark("HTML5ChartBookmark"); var clientChart = bchart.getClientChart(); clientChart.getClientOptions().setChartType('area'); clientChart.getClientOptions().setTitle('Area chart'); clientChart.redraw(); Task 4: Testing the scripts In this task, you run the report and test the HTML button scripts. 1 Save the report. 2 View the report by choosing Run➛View Report➛In Web Viewer. 3 In the Actuate viewer, choose Line Chart. The chart title changes and the HTML5 chart type changes to line, as shown in Figure 15-32. 304 Actuate BIRT Application Developer Guide Figure 15-32 An HTML5 chart displayed as a line chart 4 In the Actuate viewer, choose Area Chart. The chart title changes and the HTML5 chart type changes to area, as shown in Figure 15-33. Figure 15-33 An HTML5 chart displayed as an area chart 5 Choose other buttons to test scripted changes to the HTML5 chart display. Chapter 15, Creating dynamic repor t content using the Actuate JavaScript API 305 306 Actuate BIRT Application Developer Guide Chapter 16 Working with Interactive Crosstabs Chapter 16 This chapter contains the following topics: ■ About cross tabs ■ About cubes ■ Handling Interactive Crosstabs viewer events ■ Working with dimensions, measures, and levels ■ Working with totals ■ Sorting and filtering cross tab data ■ Drilling down within a cross tab ■ Controlling the Interactive Crosstabs viewer user interface Chapter 16, Working with Interactive Crosstabs 307 About cross tabs A cross tab, or cross tabulation, displays data in a row-and-column matrix similar to a spreadsheet. A cross tab is ideal for concisely summarizing data. A cross tab displays aggregate values such as averages, counts, or sums in the cross tab’s cells. Figure 16-1 shows a cross tab that organizes state groups in the row area and product line groups in the column area. Aggregate revenue values appear in the cells of the data area. Row area displays state groups Column area displays product line groups Data area displays aggregate revenue values Figure 16-1 Viewing a cross tab A cell displays a revenue value by product line and by state, as shown in Figure 16-2. The revenue total for Classic Cars for New Hampshire Figure 16-2 A cell displaying a revenue total A cross tab uses data from at least three fields. The cross tab in Figure 16-1 uses the following data fields: 308 ■ One field provides the values for column headings in the cross tab. The cross tab displays one column for each unique value in the field. In Figure 16-1, the cross tab displays five unique values from the productline field: Classic Cars, Motorcycles, Planes, Ships, and Trains. ■ One field provides the values for row headings in the cross tab. The cross tab displays one row for each unique value in the field. In Figure 16-1, the cross tab displays eight unique values from the state field: CA, CT, MA, NH, NJ, NV, NY, and PA. Actuate BIRT Application Developer Guide ■ Interactive Crosstabs aggregates one field’s values, and displays these values in the cross tab cells. In this example, each cell displays a revenue total by product line and state. Interactive Crosstabs calculates the revenue total using the SUM function on the values in the extendedprice field. Tutorial 8: Viewing and pivoting a cross tab This tutorial provides step-by-step instructions for authoring a web page that displays a cross tab and provides controls to the user. The file in this tutorial that contains a cross tab is Sales by Territory.rptdesign.In this task, you open or create a copy of JSAPITemplate.html and edit its contents to open a cross tab Reportlet and display it in Interactive Crosstabs Viewer. 1 Using a code editor, open or create a JSAPITemplate.html file that contains the essential components for any web page that implements the JSAPI. JSAPI Template
2 Navigate to the following line: JSAPI Template In title, change: JSAPI Template to: CrossTab Analyzer Page 3 Navigate to the following line:
Chapter 16, Working with Interactive Crosstabs 309 In id, change: sample to: analyzer 4 Navigate to the empty line after the following line: To call JavaScript functions, use additional script tags after the script tag that adds these libraries for the page. Actuate JavaScript API classes quick reference Table 17-1 lists the Actuate JavaScript API classes. 322 Actuate BIRT Application Developer Guide Table 17-1 Actuate JavaScript API classes JavaScript class Description actuate Entry point to the Actuate JavaScript API library actuate.AuthenticationException Exception caused by failed authentication actuate.ConnectionException Exception caused by a failed connection actuate.Dashboard Dashboard class actuate.dashboard.DashboardDefinition Dashboard wrapper class actuate.dashboard.EventConstants Global constants for the dashboard events class actuate.dashboard.GadgetScript Dashboard gadget script class actuate.dashboard.Tab Dashboard tab class actuate.data.Filter Conditions to filter data actuate.data.ReportContent Represents downloaded content actuate.data.Request Represents and processes a request for report data actuate.data.ResultSet Results retrieved from a report document in response to a request actuate.data.Sorter Sort conditions to sort data actuate.DataService Data services to retrieve data from a report document 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 (continues) Chapter 17, Actuate JavaScript API classes 323 Table 17-1 Actuate JavaScript API classes (continued) JavaScript class Description actuate.parameter.ParameterData A high-level wrapper for an actuate.parameter .ParameterDefinition object actuate.parameter.ParameterDefinition Qualities, options, name, and format for a parameter as the parameter displays and accepts values actuate.parameter.ParameterValue The parameter’s value as processed by a report actuate.report.Chart A report chart actuate.report.DataItem A report data item actuate.report.FlashObject A report Flash object actuate.report.Gadget A report gadget actuate.report.HTML5Chart.ClientChart An HTML5 enabled chart actuate.report.HTML5Chart.ClientOption Options for an HTML5 enabled chart 324 actuate.report.HTML5Chart.ClientPoint A data point for an HTML5 enabled chart actuate.report.HTML5Chart.ClientSeries A data series for an HTML5 enabled chart actuate.report.HTML5Chart.Highcharts A Highcharts object actuate.report.HTML5Chart.Renderer A Highcharts renderer object actuate.report.Label A report label element actuate.report.Table A report table element actuate.report.TextItem A report text element actuate.ReportExplorer The report explorer general container actuate.reportexplorer.Constants Global constants used for ReportExplorer class actuate.reportexplorer.EventConstants Global EventConstants used for ReportExplorer class actuate.reportexplorer.File A file listed in the ReportExplorer and the file’s properties actuate.reportexplorer.FileCondition A JavaScript version of com.actuate.schemas.FileCondition Actuate BIRT Application Developer Guide Table 17-1 Actuate JavaScript API classes (continued) JavaScript class Description actuate.reportexplorer.FileSearch A JavaScript version of com.actuate.schemas.FileSearch actuate.reportexplorer.FolderItems A JavaScript version of com.actuate .schemas.GetFolderItemsResponse actuate.reportexplorer.PrivilegeFilter A JavaScript version of com.actuate .schemas.PrivilegeFilter actuate.RequestOptions URL parameters for requests to an iHub volume actuate.Viewer A report viewer component that can be embedded in an HTML page actuate.viewer.BrowserPanel A non-scrolling panel display actuate.viewer.EventConstants Defines the events for the viewer this API library supports actuate.viewer.PageContent Content shown on the viewer actuate.viewer.ParameterValue Parameter values in the viewer actuate.viewer.RenderOptions Options for downloading reports actuate.viewer.ScrollPanel A scrolling panel display actuate.viewer.SelectedContent Selected report element actuate.viewer.UIConfig Enables UI elements of the scrolling panel display actuate.viewer.UIOptions Enables UI elements of the viewer actuate.viewer.ViewerException Exception constants supported for the viewer Actuate JavaScript API reference This section provides an alphabetical listing of the JavaScript API classes. Chapter 17, Actuate JavaScript API classes 325 actuat e Class actuate Description The entry point to the Actuate JavaScript API library. The actuate class uses load( ) to generate data, viewer, cross tab, parameter, explorer, and other components. The actuate class uses initialize( ) and authenticate( ) to connect to an Actuate web application service. Use actuate.load( ) before calling actuate.initialize( ). The actuate.initialize( ) function loads all of the components added with load( ). The initialize( ) function connects to an initial Actuate web application service. To connect to additional services simultaneously, use authenticate( ). Call initialize( ) before calling authenticate( ). Constructor The static actuate class loads when the a ... The viewer variable points to the XTabAnalyzer object. The content variable points to the data within the web page. The crosstab variable points to the cross tab. These variables are used throughout the examples as needed. Place example functions in the area marked "JavaScript application functions". The section marked "Other HTML code" contains
and other tags necessary for the web page. Call the examples as any other JavaScript function. For example, the following HTML code creates a button with the label "Job 1" on it. When a user clicks that button, the page runs the JavaScript function Job1. 582 Actuate BIRT Application Developer Guide Interactive Crosstabs JavaScript classes quick reference Table 18-1 lists the Interactive Crosstabs JavaScript classes. Table 18-1 Actuate Interactive Crosstabs JavaScript classes JavaScript class Description actuate.XTabAnalyzer An Interactive Crosstabs viewer component that can be embedded in an HTML page actuate.xtabanalyzer.Crosstab A cross tab element actuate.xtabanalyzer.Dimension A data dimension actuate.xtabanalyzer.Driller A helper class for drilling down through cross tab data actuate.xtabanalyzer.EventConstants Global constants for Interactive Crosstabs events class actuate.xtabanalyzer.Exception Exception object sent to calling function actuate.xtabanalyzer.Filter Filter conditions to filter data actuate.xtabanalyzer.GrandTotal A cross tab grand total actuate.xtabanalyzer.Level A cross tab level actuate.xtabanalyzer.LevelAttribute An attribute for a level actuate.xtabanalyzer.Measure A data measure actuate.xtabanalyzer.MemberValue Data as a member value actuate.xtabanalyzer.Options Options for the cross tab actuate.xtabanalyzer.PageContent The content shown in the Interactive Crosstabs viewer actuate.xtabanalyzer.ParameterValue A cross tab parameter value actuate.xtabanalyzer.Sorter Conditions for sorting data actuate.xtabanalyzer.SubTotal A cross tab subtotal actuate.xtabanalyzer.Total A cross tab total actuate.xtabanalyzer.UIOptions Enables UI elements of Interactive Crosstabs Chapter 18, BIRT Interactive Crosstabs API classes 583 actuat e.X TabA nalyzer Class actuate.XTabAnalyzer Description The XTabAnalyzer class represents an Interactive Crosstabs viewer, used to view and operate a cross tab. Constructor Syntax actuate.XTabAnalyzer( ) Constructs a new Interactive Crosstabs object. actuate.XTabAnalyzer(object xtabContainer, actuate.xtabanalyzer.UIOptions uiOptions) actuate.XTabAnalyzer(string xtabContainerId, actuate.xtabanalyzer.UIOptions uiOptions) Constructs a new Interactive Crosstabs object in the specified container. Parameters xtabContainer Object. A document object referencing the HTML
element that contains the XTabAnalyzer viewer. xtabContainerId String. The value of the ID parameter for an HTML
element to hold the XTabAnalyzer viewer. For example, with 'containerName' as the xtabContainer parameter, a
tag on the page displays the viewer at the location of the
element. uiOptions actuate.xtabanalyzer.UIOptions object. Optional. UIOptions references display options for the viewer. Function summary Table 18-2 lists actuate.XTabAnalyzer functions. Table 18-2 actuate.XTabAnalyzer functions Function 584 Description commit( ) Commits all changes to the report design forceSoftRestart( ) Forces the viewer to restart getCurrentPageContent( ) Returns the Current Page Content object }getCurrentPageNum( ) Returns the current page number getGadgetId Returns the gadget ID of the shown cross tab getHeight( ) Returns the viewer height Actuate BIRT Application Developer Guide actuate.XTabAnalyzer Table 18-2 actuate.XTabAnalyzer functions (continued) Function Description getLeft( ) Returns the viewer left margin getParameterValues( ) Returns the parameter values getPosition( ) Returns the CSS position attribute value getTop( ) Returns the viewer top margin getTotalPageCount( ) Returns the total page count getUIOptions( ) Returns the actuate.xtabanalyzer.UIOptions object assigned to this viewer getViewer( ) Gets a viewer within a container getWidth( ) Returns the viewer width getXTabBookmark( ) Returns the bookmark of the cross tab displayed in the viewer getXTabIid( ) Returns the instance ID of the cross tab displayed in the viewer isActive( ) Checks if current viewer pop-up is active isDashboard( ) Checks if the current viewer pop-up is a dashboard isInteractive( ) Checks if the current viewer is interactive registerEventHandler( ) Registers an event handler removeEventHandler( ) Removes an event handler reset( ) Resets the viewer object resizeTo( ) Resizes the viewer rollback( ) Rolls back all changes in the viewer and refreshes its content setGadgetId Sets the gadget id of the cross tab setHeight( ) Sets the viewer height setIVMode( ) Sets whether the viewer is in IV mode setLeft( ) Sets the viewer left margin setOnClosed( ) Sets callback when the pop-up window is closed setPageNum( ) Sets the page number setParameterValues( ) Sets the parameter values setPosition( ) Sets the CSS position attribute (continues) Chapter 18, BIRT Interactive Crosstabs API classes 585 actuat e.X TabA nalyzer Table 18-2 actuate.XTabAnalyzer functions (continued) Function Description setReportletDocumentMode( ) Sets a Reportlet to document mode setReportName( ) Sets the report to load into the interactive cross tab setService( ) Sets the BIRT iServer System and request options setSupportSVG( ) Sets whether or not the client browser supports SVG setTop( ) Sets the top margin setUIOptions( ) Sets the user interface options for the viewer setWidth( ) Sets the viewer width setXTabBookmark( ) Sets a bookmark for the cross tab setXTabIid( ) Sets the instance ID of the cross tab submit( ) Submits asynchronous operations and renders the requested components commit Syntax void XTabAnalyzer.commit(function callback) Commits all design changes to a generated document as a single operation. If ivMode is not set to true, call setIVMode( ) to set the value of ivMode to true before calling commit( ). Parameter callback Function. The callback function called after commit finishes. Example This example opens a design with a cross tab and pivots the cross tab: function pivot( ){ // make a change to the cross tab. crosstab.pivot( ); crosstab.submit( ); viewer.commit( ); } forceSoftRestart Syntax void XTabAnalyzer.forceSoftRestart( ) Forces the viewer to restart. 586 Actuate BIRT Application Developer Guide actuate.XTabAnalyzer Example This example restarts the viewer: this.onclick = function(event){ forceSoftRestart( ); } getCurrentPageContent Syntax actuate.xtabanalyzer.PageContent XTabAnalyzer.getCurrentPageContent( ) Returns the Current Page Content object. Returns Example actuate.xtabanalyzer.PageContent object. Content from the current page. This example retrieves the cross tab from the current page: function getCrosstab(analyzerViewer){ var content = analyzerViewer.getCurrentPageContent( ); return content.getCrosstabByBookmark( ); } getCurrentPageNum } Syntax integer XTabAnalyzer.getCurrentPageNum( ) Returns the current page number. Returns Example Integer. The current page number. This example retrieves the page number: function retrievePageNum( ){ return analyzerViewer.getCurrentPageNum( ); } getGadgetId Syntax string XTabAnalyzer.getGadgetId( ) Returns the gadget ID of the shown cross tab. This function is used for dashboard integration. Returns Example String. A gadget ID. This example retrieves the gadget ID: function retrieveGadgetID( ){ return analyzerViewer.getGadgetId( ); } Chapter 18, BIRT Interactive Crosstabs API classes 587 actuat e.X TabA nalyzer getHeight Syntax integer XTabAnalyzer.getHeight( ) Returns the height of the viewer. Returns Example Integer. The height in pixels. This example retrieves the current height of the viewer and doubles the height if the current height is lower than 630 pixels: function doubleHeight( ){ var height = viewer.getHeight( ); if (height < 630){ viewer.setHeight(height * 2); viewer.submit( ); } } getLeft Syntax integer XTabAnalyzer.getLeft( ) Returns the left margin of the viewer. Returns Example Integer. The left margin in pixels. This example retrieves the position of the viewer’s left margin and moves the margin 20 pixels to the right if the left margin is fewer than 45 pixels from the left edge of the screen: function moveLeftMargin( ){ var left = viewer.getLeft( ); if (left < 45){ viewer.setLeft(left + 20); viewer.submit( ); } } getParameterValues Syntax actuate.xtabanalyzer.ParameterValue[ ] XTabAnalyzer.getParameterValues( ) Returns the parameter values. Returns actuate.xtabanalyzer.ParameterValue[ ] or actuate.parameter.ParameterValue[ ]. An array of parameter values. getPosition Syntax 588 string XTabAnalyzer.getPosition( ) Actuate BIRT Application Developer Guide actuate.XTabAnalyzer Returns the CSS position attribute for the viewer. Returns Example String. The CSS position attribute. This example changes the CSS positioning type from relative to absolute: function changePosition( ){ if (viewer.getPosition( ) == 'relative'){ viewer.setPosition('absolute'); viewer.submit( ); } } getTop Syntax integer XTabAnalyzer.getTop( ) Returns the top margin of the viewer. Returns Example Integer. The top margin in pixels. This example retrieves the value for the viewer’s top margin and moves the margin 20 pixels down the screen if the margin was fewer than 45 pixels from the top of the screen: function moveTopMargin( ){ var top = viewer.getTop( ); if (top < 45){ viewer.setTop(top + 20); viewer.submit( ); } } getTotalPageCount Syntax integer XTabAnalyzer.getTotalPageCount( ) Returns the total page count. Returns Example Integer. The total number of pages. This example displays an alert with the total page count from viewer: alert("Total pages: " + viewer.getTotalPageCount( )); getUIOptions Syntax actuate.xtabanalyzer.UIOptions getUIOptions( ) Returns the user interface options object for the cross tab analyzer. The UIOptions object specifies what features are used within the viewer. Chapter 18, BIRT Interactive Crosstabs API classes 589 actuat e.X TabA nalyzer Returns Example actuate.xtabanalyzer.UIOptions object. Interactive Crosstabs user interface options. This example retrieves the user interface options and sets one of the UIOptions values: function resetUIOptions( ){ var options = viewer.getUIOptions( ); options.enableToolbar(false); viewer.setUIOptions(options); } getViewer Syntax static XTabAnalyzer.getViewer(HTMLElement container) Returns a viewer by container. To retrieve the viewer for the current object, do not specify a container. This function is useful to retrieve the instance ID for a specific viewer when there are multiple viewers on a page. Parameter container HTMLElement. The container instance ID from which to retrieve the viewer. Returns Example XTabAnalyzer object. The Interactive Crosstabs viewer. This example retrieves the viewer: function retrieveViewer( ){ return viewer.getViewer( ); } getWidth Syntax string XTabAnalyzer.getWidth( ) Returns the width value of the viewer. Returns Example String. The width in pixels. This example retrieves the width of the viewer, then alters it based on the size: function doubleWidth( ){ var width = viewer.getWidth( ); if (width < 630){ viewer.setWidth(width * 2); viewer.submit( ); } } getXTabBookmark Syntax 590 string XTabAnalyzer.getXTabBookmark( ) Actuate BIRT Application Developer Guide actuate.XTabAnalyzer Returns the bookmark name for the cross tab set to render in the viewer. Returns Example String. The bookmark for a cross tab. This example retrieves the bookmark that the cross tab is associated with, changes the bookmark, and resets the bookmark. This functionality supports the use of multiple cross tab elements within a single design. function changeBookmark( ){ var oldBookMark = viewer.getXTabBookmark( ); viewer.setXTabBookmark("crosstab2"); viewer.submit( ); } getXTabIid Syntax string XTabAnalyzer.getXTabIid( ) Returns the current instance ID of the interactive cross tab. This function is useful in integration with Interactive Viewer and supports the ability of Interactive Viewer to obtain and use the interactive cross tab instance ID. Returns Example String. An interactive cross tab instance ID. This example retrieves the interactive cross tab instance ID: function retrieveXTablid( myviewer ){ return myviewer.getXTablid( ); } isActive Syntax boolean XTabAnalyzer.isActive( ) Returns true when a pop-up containing an interactive cross tab is active and false in all other cases. Returns Example Boolean. True indicates an active interactive cross tab pop-up window. This example checks if a viewer exists by checking two conditions: the viewer variable exists, or isActive( ) returns true. When both conditions fail, the example code creates a new viewer object within a container: function checkViewer( ){ if(!viewer || !viewer.isActive( )){ viewer = new actuate.XTabAnalyzer(container); } } Chapter 18, BIRT Interactive Crosstabs API classes 591 actuat e.X TabA nalyzer isDashboard Syntax boolean XTabAnalyzer.isDashboard( ) Returns true when dashboard mode is active and false in all other cases. Returns Boolean. True indicates dashboard mode. isInteractive Syntax boolean XTabAnalyzer.isInteractive( ) Returns whether this Interactive Crosstabs Viewer is in Interactive mode. Returns Example Boolean. True indicates dashboard mode. This example displays whether myDataAnalyzer is interactive: alert("Interactive mode: " + myDataAnalyzer.isInteractive( )); registerEventHandler Syntax void XTabAnalyzer.registerEventHandler(string viewerEvent, function handler) Registers an event handler for the specified event. This function throws actuate.xtabanalyzer.Exception when invalid arguments are passed. Parameters viewerEvent String. Specifies the event that triggers the handler call. For a list of supported events, see actuate.xtabanalyzer.EventConstants. handler Function. Called when the event occurs. Example This example changes an event handler from one function to another: function changeEventHandler( event ){ viewer.removeEventHandler(actuate.xtabanalyzer.EventConstants .ON_CONTENT_CHANGED, oldChangedHandler); viewer.registerEventHandler(actuate.xtabanalyzer .EventConstants.ON_CONTENT_CHANGED, newChangedHandler); } removeEventHandler Syntax void XTabAnalyzer.removeEventHandler(string viewerEvent, function handler) Removes an event handler from the specified event. This function throws actuate.xtabanalyzer.Exception when invalid arguments are passed. 592 Actuate BIRT Application Developer Guide actuate.XTabAnalyzer Parameters viewerEvent String. Specifies the event from which to remove the event handler. For a list of supported events, see actuate.xtabanalyzer.EventConstants. handler Function. The function to deregister from the event. Example This example changes an event handler from one function to another: function changeEventHandler( event ){ viewer.removeEventHandler(actuate.xtabanalyzer.EventConstants .ON_CONTENT_CHANGED, oldChangedHandler); viewer.registerEventHandler(actuate.xtabanalyzer .EventConstants.ON_CONTENT_CHANGED, newChangedHandler); } reset Syntax void XTabAnalyzer.reset( ) Resets the viewer to its initial state. Example This example resets the viewer. All changes to the viewer made prior to this call are lost: function resetViewer( ){ viewer.reset( ); } resizeTo Syntax void XTabAnalyzer.resizeTo(integer width, integer height) Resizes the viewer to the specified height and width. Parameters width Integer. The width in pixels. height Integer. The height in pixels. Example This example resizes the viewer when the new width is fewer than 1000 pixels and the new height is fewer than 650 pixels: function resizeViewer(width,height){ if ((width < 1000) && (height < 650)){ viewer.resizeTo(width,height); } } Chapter 18, BIRT Interactive Crosstabs API classes 593 actuat e.X TabA nalyzer rollback Syntax void XTabAnalyzer.rollback(function callback) Rolls back all changes in the viewer since the last commit( ) call and refreshes the viewer’s content. The value of ivMode must be true for rollback( ) to function. Parameter callback Function. The callback function called after rollback finishes. Example This example rolls back all changes to the viewer made since the last commit or submit function call: function rollbackViewer( ){ viewer.rollback( ); } setGadgetId Syntax void XTabAnalyzer.setGadgetId(string gadgetId) Sets the cross tab gadget ID. This function is used for dashboard integration. Parameter gadgetId String. The gadget ID used to render the cross tab. Example This example sets the gadget ID: function setGadgetID(id){ viewer.setGadgetId(id); } setHeight Syntax void XTabAnalyzer.setHeight(integer height) Changes the height of the viewer. Parameter height Integer. The height in pixels. Example This example retrieves the viewer’s current height. When the current height is fewer than 630 pixels, the example code doubles the viewer’s height. function doubleHeight( ){ var height = viewer.getHeight( ); if (height < 630){ height = height * 2; viewer.setHeight(height); viewer.submit( ); } } 594 Actuate BIRT Application Developer Guide actuate.XTabAnalyzer setIVMode Syntax void XTabAnalyzer.setIVMode(boolean ivMode) Sets IVMode for the viewer. Integrating a Data Analytics viewer with the Interactive Viewer affects the undo/redo feature. When set to true, all changes to the Data Analytics viewer must be committed as one transaction. The Interactive Viewer can undo or redo the entire batch. Parameter ivMode Boolean. Set to true if using IV mode. Example This example sets IVMode for the viewer: function setViewerMode(mode){ viewer.setIVMode(mode); } setLeft Syntax void XTabAnalyzer.setLeft(integer left) Sets the position of the viewer’s left margin. Parameter left Integer. The left margin for the viewer in pixels. Example This example retrieves the left margin of the viewer and moves the margin 20 pixels to the right when the margin is less than 45 pixels from the edge of the screen: function moveLeftMargin( ){ var left = viewer.getLeft( ); if (left < 45){ viewer.setLeft(left + 20); viewer.submit( ); } } setOnClosed Syntax void XTabAnalyzer.setOnClosed(function callback) Sets a callback function to call when a viewer pop-up closes. Parameter callback Function. The function to call when the pop-up closes. Example This example checks to see if a pop-up window is active and sets a callback function to trigger when the pop-up closes: function setPopupCloser( ){ Chapter 18, BIRT Interactive Crosstabs API classes 595 actuat e.X TabA nalyzer if(viewer.isActive( )){ viewer.setOnClosed(closerCallbackFunctionName); } } setPageNum Syntax void XTabAnalyzer.setPageNum(function pageNum) Sets the page number. Parameter pageNum Integer. The page number. Example This example sets the sets the page number to the first page: function setPageNumberToFirst( ){ if(viewer.isActive( )){ viewer.setPageNum(1); } } setParameterValues Syntax void XTabAnalyzer.setParameterValues(actuate.xtabanalyzer.ParameterValue[ ] parameterValues) Sets the parameter values. Parameter parameterValues actuate.xtabanalyzer.ParameterValue[ ] or actuate.parameter.ParameterValue[ ]. An array of parameter values. setPosition Syntax void XTabAnalyzer.setPosition(string position) Sets the CSS position attribute. Parameter position String. The value for the CSS position attribute. Example This example changes the type of CSS positioning in use: function changePosition( ){ var pos = viewer.getPosition( ); if (pos == 'relative'){ viewer.setPosition('absolute'); viewer.submit( ); } } 596 Actuate BIRT Application Developer Guide actuate.XTabAnalyzer setReportletDocumentMode Syntax void XTabAnalyzer.setReportletDocumentMode(boolean reportletMode) Sets whether the viewer displays documents as Reportlets. Parameter reportletMode Boolean. True indicates Reportlet display mode. setReportName Syntax void XTabAnalyzer.setReportName(string reportName, string connectionHandle) Sets the report file name for the viewer. The file must be a report document file or report design file. Parameters reportName String. The name of the report file. connectionHandle String. Optional. The unique identifier generated by iHub for a temporary report. Example This example sets the report name to reportfile.rptdocument and reloads the Interactive Crosstabs viewer with its content: function run( ){ container = document.getElementById("acviewer"); viewer = new actuate.XTabAnalyzer(container); viewer.setReportName("reportfile.rptdocument"); viewer.submit( ); } setService Syntax void XTabAnalyzer.setService(string iPortalURL, actuate.RequestOptions requestOptions) Sets the Actuate web application URL. This function can request options for that URL. Parameters iPortalURL String. The URL of the Actuate web application. requestOptions actuate.RequestOptions object. Request options for the web application. This parameter is optional. Example This example sets the service and request options: function setServerOptions(URL,options){ viewer.setService(URL,options); } Chapter 18, BIRT Interactive Crosstabs API classes 597 actuat e.X TabA nalyzer setSupportSVG Syntax void XTabAnalyzer.setSupportSVG(boolean svgFlag) Sets a flag indicating whether or not the browser supports SVG. Parameter svgFlag Boolean. Flag indicating SVG support in the browser. This parameter’s value is true when the browser supports SVG and false in all other cases. Example This example sets the browser’s level of SVG support: function setSVG(flag){ viewer.setSupportSVG(flag); } setTop Syntax void XTabAnalyzer.setTop(integer top) Sets the top margin for the viewer. Parameter top Integer. The top margin for the viewer in pixels. Example This example retrieves the current top margin for the viewer and moves the margin 20 pixels down the screen when the current position of the margin is fewer than 45 pixels from the top of the screen: function moveTopMargin( ){ var top = viewer.getTop( ); if (top < 45){ top = top + 20; viewer.setTop(top); viewer.submit( ); } } setUIOptions Syntax void XTabAnalyzer.setUIOptions(actuate.xtabanalyzer.uioptions options) Sets the user interface options enabled for the viewer. Parameter options Actuate.xtabanalyzer.uioptions object. The options object for the viewer. Example This example retrieves the user interface options and sets one of the UIOptions values: function resetUIOptions( ){ var options = viewer.getUIOptions( ); 598 Actuate BIRT Application Developer Guide actuate.XTabAnalyzer options.enableToolbar(false); viewer.setUIOptions(options); } setWidth Syntax void XTabAnalyzer.setWidth(integer width) Sets the width for the viewer. Parameter width Integer. The width for the viewer in pixels. Example This example retrieves the width of the viewer. When the viewer is fewer than 630 pixels wide, the example code doubles the viewer’s width: function doubleWidth( ){ var width = viewer.getWidth( ); if (width < 630){ viewer.setWidth(width * 2); viewer.submit( ); } } setXTabBookmark Syntax void XTabAnalyzer.setXTabBookmark(string bookmark) Sets the bookmark for a cross tab to render in the viewer. Parameter bookmark String. The bookmark for a cross tab. Example This example retrieves the bookmark for the cross tab the viewer is associated with, changes the bookmark, and reloads the bookmark. This functionality enables the use of multiple cross tab elements within a single design. function changeBookmark( ){ var oldBookMark = viewer.getXTabBookmark( ); viewer.setXTabBookmark("crosstab2"); viewer.submit( ); } setXTabIid Syntax void XTabAnalyzer.setXTabIid(string iid) Sets the instance ID for viewer rendering. This function is useful in integration with Interactive Viewer, and supports the ability of Interactive Viewer to obtain and use the cross tab instance ID. Chapter 18, BIRT Interactive Crosstabs API classes 599 actuat e.X TabA nalyzer Parameter iid String. The instance ID. Example This example sets the cross tab instance ID: function setxtabInstance(id){ viewer.setXTablid(id); } submit Syntax void XTabAnalyzer.submit(function callback, boolean rerun) Submits requests to the server for the Interactive Crosstabs viewer. This method triggers an AJAX request to submit all pending operations for this object. The server returns a response after processing the pending operations. The results render on the page in the Interactive Crosstabs container. The submit( ) function throws an exception when another submit( ) operation is pending. A CONTENT_CHANGED event fires when the Interactive Crosstabs content changes. Parameters callback Function. Optional. A function called when submit completes. This function receives the current XTabAnalyzer object as an input parameter. rerun Boolean. Optional. Indicates whether re-run the report design when it refreshes. Default to true. Example This example retrieves the left margin of the viewer and expands the margin. The change does not take effect until submit( ) executes. The submit( ) function calls the function in the submitCallback parameter when submit( ) finishes executing. The callback function contains any processing that must occur after submit( ) finishes. Do not place code after the submit( ) call in the same function because submit( ) is asynchronous. function moveLeftMargin( ){ var left = viewer.getLeft( ); if (left < 45){ viewer.setLeft(left + 20); viewer.submit(submitCallback); } } 600 Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Cr osstab Class actuate.xtabanalyzer.Crosstab Description The actuate.xtabanalyzer.Crosstab class represents a cross tab report element. Constructor Syntax actuate.xtabanalyzer.Crosstab( ) Constructs a new cross tab object. Function summary Table 18-3 lists actuate.xtabanalyzer.Crosstab functions. Table 18-3 actuate.xtabanalyzer.Crosstab functions Function Description addDimension( ) Adds a dimension to the cross tab addMeasure( ) Adds a measure to the cross tab applyOptions( ) Sets options for the cross tab changeMeasureDirection( ) Switches measure direction clearFilters( ) Clears cross tab filters drill( ) Drills up or down measure levels, replacing drill and filter conditions drillDown( ) Drills down a measure level, updating drill conditions drillUp( ) Drills up a measure level, updating drill conditions editMeasure( ) Edits a measure getBookmark( ) Retrieves the cross tab element bookmark getColumn( ) Retrieves table data by column index getData( ) Returns the data from a cross tab getHtmlDom( ) Retrieves the HTML DOM object getPageContent( ) Retrieves the content of the page the cross tab belongs to getRow( ) Retrieves table data by row index getType( ) Retrieves the report element type hideDetail( ) Hides the detail of a specified level (continues) Chapter 18, BIRT Interactive Crosstabs API classes 601 actuat e.xt abanalyzer .C rosst ab Table 18-3 actuate.xtabanalyzer.Crosstab functions (continued) Function Description pivot( ) Pivots the cross tab removeDimension( ) Removes a dimension from the cross tab removeMeasure( ) Removes a measure from the cross tab reorderDimension( ) Reorders a dimension reorderMeasure( ) Reorders a measure setFilters( ) Sets the cross tab’s filters setSorters( ) Sets the cross tab’s sorters setTotals( ) Sets the cross tab’s totals showDetail( ) Shows details to the lower level submit( ) Applies changes made to the cross tab addDimension Syntax void Crosstab.addDimension(actuate.xtabanalyzer.Dimension dimension) Adds a dimension to the cross tab object. Parameter dimension actuate.xtabanalyzer.Dimension object. The dimension to add. Example This example adds a date-based, multi-level dimension to a cross tab: function addDimension( ){ // Create a dimension for dates in the first column var dimension = new actuate.xtabanalyzer.Dimension( ); dimension.setIndex(0); dimension.setAxisType(actuate.xtabanalyzer.Dimension .COLUMN_AXIS_TYPE); dimension.setDimensionName("dates"); // Create levels using levels from the data cube. var level = new actuate.xtabanalyzer.Level( ); level.setLevelName("year"); dimension.addLevel(level); var level = new actuate.xtabanalyzer.Level( ); level.setLevelName("quarter"); dimension.addLevel(level); // Add the dimension to the cross tab. crosstab.addDimension(dimension); crosstab.submit( ); } 602 Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Cr osstab addMeasure Syntax void Crosstab.addMeasure(actuate.xtabanalyzer.Measure measure, integer options) Adds a measure to the cross tab object. Parameters measure actuate.xtabanalyzer.Measure object. The measure to add. options Integer. The options for the add measure operation. These options distinguish the origin of the function call, which can be from another dialog or directly from the Actuate JavaScript API. Example This example adds a measure to a cross tab: function addMeasure( ){ //Create a measure for revenue organized by date and product line. var measure = new actuate.xtabanalyzer.Measure( ); measure.setIndex(1); measure.setMeasureName("Quarter Rate"); measure.setExpression("[revenue]/[revenue_SalesDate /year_Product/PRODUCTLINE]"); // Apply the measure to the cross tab crosstab.addMeasure(measure); crosstab.submit( ); } In this example, the expression set with setExpression( ) is in EasyScript, which is described in Using Actuate BIRT Designer Professional. applyOptions Syntax void Crosstab.applyOptions(string | actuate.xtabanalyzer.Options measureDirection, string rowMirrorStartingLevel, string columnMirrorStartingLevel, string emptyCellValue) Sets measure direction, empty settings, row mirror starting level, column mirror starting level, and empty cell value. Parameters measureDirection String or actuate.xtabanalyzer.Options object. When measureDirection is a string, measureDirection is set to horizontal or vertical and the other parameters set options individually. When an actuate.xtabanalyzer.Options object is specified, all the options are set using settings from this object and applyOptions ignores all subsequent parameters. Chapter 18, BIRT Interactive Crosstabs API classes 603 actuat e.xt abanalyzer .C rosst ab rowMirrorStartingLevel String. Sets the mirror starting level empty setting for a row. columnMirrorStartingLevel String. Sets the mirror starting level empty setting for a column. emptyCellValue String. Sets the value of an empty cell. changeMeasureDirection Syntax void Crosstab.changeMeasureDirection( ) Switches the measure direction between horizontal and vertical. Example This example changes the measure direction: function changeMeasureDirection( ){ if( crosstab ){ crosstab.changeMeasureDirection( ); crosstab.submit( ); } } clearFilters Syntax void Crosstab.clearFilters(actuate.xtabanalyzer.Level level, String filterType) Clears the filters from a level. Parameters level actuate.xtabanalyzer.Level object. Optional. The level from which to clear the filters. To clear all filters, do not specify a level. filterType String. Optional. The filter type. To clear all filter types, do not specify a filter type. Example This example clears the filters from the level filterLevel: function clearLevelFilters( ){ if( crosstab ){ crosstab.clearFilters("filterLevel"); crosstab.submit( ); } } drill Syntax 604 void Crosstab.drill(actuate.xtabanalyzer.Driller driller) Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Cr osstab Drills up or down a dimension level. Removes all drill/filter conditions defined on specified dimension first, then adds new drill/filter conditions. Parameter driller actuate.xtabanalyzer.Driller object. The driller object specifies drill conditions on a dimension. Example This example drills to a level within a dimension. Any existing drill conditions are replaced. function drillToDimension(memberVal){ var driller = new actuate.xtabanalyzer.Driller( ); driller.setAxisType(actuate.xtabanalyzer.Dimension .ROW_AXIS_TYPE); driller.addMember(memberVal); myCrosstab.drill(driller); myCrosstab.submit( ); } drillDown Syntax void Crosstab.drillDown(actuate.xtabanalyzer.Driller driller) Drills down a dimension level. This method updates the drill conditions specified in the Driller object and leaves all other conditions in place. Parameter driller actuate.xtabanalyzer.Driller object. A drill condition object. Example This example drills down a level within a dimension. Any existing drill conditions are unchanged. function drillToDimension(memberVal){ var driller = new actuate.xtabanalyzer.Driller( ); driller.setAxisType(actuate.xtabanalyzer.Dimension .ROW_AXIS_TYPE); driller.addMember(memberVal); myCrosstab.drillDown(driller); myCrosstab.submit( ); } drillUp Syntax void Crosstab.drillUp(actuate.xtabanalyzer.Driller driller) Drills up a dimension level. This method updates the drill conditions specified in the Driller object and leaves all other conditions in place. Parameter driller A drill condition object. Chapter 18, BIRT Interactive Crosstabs API classes 605 actuat e.xt abanalyzer .C rosst ab Example This example drills up a level within a dimension. Any existing drill conditions are unchanged. function drillToDimension( ){ var driller = new actuate.xtabanalyzer.Driller( ); driller.setAxisType(actuate.xtabanalyzer.Dimension .ROW_AXIS_TYPE); // Add the member list to the Driller. Add the Driller to the // crosstab. driller.addMember(memberVal); myCrosstab.drillUp(driller); myCrosstab.submit( ); } editMeasure Syntax void Crosstab.editMeasure(actuate.xtabanalyzer.Meaure Measure, integer opts) Edits a measure in the Computed Measure view. Parameters Measure actuate.xtabanalyzer.Measure object. A measure to change. opts Integer. Optional. Options for the editMeasure function. These options distinguish the origin of the function call, which can be from another dialog or directly from the Actuate JavaScript API. Example This example edits a measure: function editComputedMeasure( ){ if( crosstab ){ var measure = new actuate.xtabanalyzer.Measure( ); measure.setMeasureName("measureName"); measure.setExpression("measureExpression"); crosstab.editMeasure(measure); crosstab.submit( ); } } getBookmark Syntax string Crosstab.getBookmark( ) Returns the bookmark that is associated with the cross tab element. Returns Example 606 String. The cross tab bookmark. The following code retrieves the bookmark that is associated with the cross tab object: Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Cr osstab function getCrosstabBookmark( ){ var crosstabBookmark = crosstab.getBookmark( ); if( !crosstabBookmark ){ alert( "No cross tab bookmark found!" ) return null; } return crosstabBookmark; } getColumn Syntax string[ ] Crosstab.getColumn(integer columnIndex) Returns the table data by column index. Parameter columnIndex Integer. The column index, starting with 1. Returns Example String[ ]. The column data as an array of strings. This function returns null when the value of columnIndex is out of range. This function only returns data from the current visible page. The following code retrieves data from a data column: function getColumnData(index,value){ var columnData = crosstab.getColumn(index); if( !columnData ){ alert( "Invalid column index!" ) return null; } return columnData[value]; } getData Syntax String[ ] Crosstab.getData(boolean forceReparse) Returns the data in a cross tab. Parameter forceReparse Boolean. Forces a cache refresh when true. Returns String[ ]. The data from the cross tab as an array of strings. getHtmlDom Syntax HTMLElement Crosstab.getHtmlDom( ) Returns the HTML element DOM object. Returns HTMLElement. The DOM element containing the cross tab. Chapter 18, BIRT Interactive Crosstabs API classes 607 actuat e.xt abanalyzer .C rosst ab Example The following code retrieves the DOM object and uses the DOM object to retrieve an element within the document: function getContainer(containerName){ var HTMLDom = crosstab.getHtmlDom( ); var container = HTMLDom.getElementById(containerName); return container; } getPageContent Syntax actuate.xtabanalyzer.PageContent Crosstab.getPageContent( ) Returns the page content from the current page to which this cross tab belongs. This function returns the same information as XTabAnalyzer.getCurrentPageContent( ). Returns Example actuate.xtabanalyzer.PageContent. The report content. This example retrieves the page content: function retrievePageContent( ){ return crosstab.getPageContent( ); } getRow Syntax string[ ] Crosstab.getRow(integer rowIndex) Returns table data based on row index. Parameter rowIndex Integer. The row index, starting with 1. Returns Example String[ ]. The row data as an array of string values. This function returns null when the value of rowIndex is out of range. This function only returns data from the current visible page. The following code retrieves data from a data row: function getRowData(index,value){ var rowData = crosstab.getRow(index); if( !rowData ){ alert( "Invalid row index!" ) return null; } return rowData[value]; } 608 Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Cr osstab getType Syntax string Crosstab.getType( ) Returns the report element type. Returns String containing the value "Crosstab". hideDetail Syntax void Crosstab.hideDetail(string levelName) Hides details of the specified level. Parameter levelName String. The full name of a dimension level to hide. Example This example hides lower level details in a level: function hideDetail( ){ if(crosstab){ var levelName = "rollLevelName"; crosstab.hideDetail(levelName); crosstab.submit( ); } } pivot Syntax void Crosstab.pivot( ) Pivots the cross tab. Example This example pivots a cross tab: function pivot(crosstab){ crosstab.pivot( ); crosstab.submit( ); } removeDimension Syntax void Crosstab.removeDimension(object dimension, integer axisType, integer[ ] levels) Removes a dimension from the cross tab. Parameters dimension actuate.xtabanalyzer.dimension object, a dimension index, or a dimension name. The dimension to remove. Chapter 18, BIRT Interactive Crosstabs API classes 609 actuat e.xt abanalyzer .C rosst ab axisType Integer. The dimension axis type. Axis type can be one of the following values: ■ actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE ■ actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE levels The levels assigned in the dimension, as an array of actuate.xtabanalyzer.Level objects, a level index array, or a level name array. Example This example removes a dimension with several layers. The level names are in a text control named levelNames and are separated by semicolons. function removeDimension( ){ if(crosstab){ crosstab.removeDimension("dimensionName",null,"levelName";); crosstab.submit( ); } } removeMeasure Syntax void Crosstab.removeMeasure(actuate.xtabanalyzer.Measure measure) void Crosstab.removeMeasure(integer measure) void Crosstab.removeMeasure(string measure) Removes a measure from the cross tab. Parameter measure actuate.xtabanalyzer.measure object, index, or name. The measure to remove. Example This example removes a measure from a cross tab: function removeMeasure( ){ crosstab.removeMeasure("measureName"); crosstab.submit( ); } reorderDimension Syntax void Crosstab.reorderDimension(actuate.xtabanalyzer.Dimension dimension, integer axisType, integer newIndex, integer newAxisType) Reorders a dimension within a cross tab. This function can change a dimension’s index or axis type. Parameters dimension actuate.xtabanalyzer.dimension object, or a dimension index or a dimension name. The dimension to reorder. 610 Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Cr osstab axisType Integer. The dimension axis type. Axis type can be one of the following values: ■ actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE ■ actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE newIndex The new index for the dimension. newAxisType The new axis type. Example This example changes the index and axis type of a dimension: function changeDimensionOrder( ){ var dimensionIndex = 5; var newDimensionIndex = 2; var axisType = actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE; var newAxisType = actuate.xtabanalyzer.Dimension .COLUMN_AXIS_TYPE; crosstab.reorderDimension(dimensionIndex, axisType, newDimensionIndex, newAxisType); crosstab.submit( ); } reorderMeasure Syntax void Crosstab.reorderMeasure(actuate.xtabanalyzerMeasure measure, integer newIndex) void Crosstab.reorderMeasure(integer measure,integer newIndex) void Crosstab.reorderMeasure(string measure,integer newIndex) Reorders a measure within a cross tab. Parameters measure actuate.xtabanalyzer.Measure object, or a measure index or a measure name. The measure to reorder. newIndex The new index for the measure. Example This example reorders a measure: function changeMeasureOrder( ){ var index = 6; var newIndex = 3; crosstab.reorderMeasure(index,newIndex); Chapter 18, BIRT Interactive Crosstabs API classes 611 actuat e.xt abanalyzer .C rosst ab crosstab.submit( ); } setFilters Syntax void Crosstab.setFilters(actuate.xtabanalyzer.Filter[ ] filters) Sets an array of filters for the cross tab. Parameter filters Array of actuate.xtabanalyzer.Filter objects. The filter conditions. Example This example creates a Filter object and then places it into the cross tab: function filterLevel( ){ var levelName = "levelName"; var operator = actuate.xtabanalyzer.Filter.BETWEEN; var filterValue = "20000;50000"; var filter = new actuate.xtabanalyzer.Filter(levelName, operator); filter.setValues(filterValue.split(";")); crosstab.setFilters(filter); crosstab.submit( ); } setSorters Syntax void Crosstab.setSorters(actuate.xtabanalyzer.Sorter[ ] sorters) Sets an array of sorters for the cross tab. Parameter sorters Array of actuate.xtabanalyzer.Sorter objects. The sort settings. Example This example creates a sorter and adds it to the cross tab: function sortLevel( ){ var levelName = "levelName"; var sortAscending = true; var sorter = new actuate.xtabanalyzer.Sorter(levelName); sorter.setAscending(sortAscending); crosstab.setSorters(sorter); crosstab.submit( ); } setTotals Syntax void Crosstab.setTotals(actuate.xtabanalyzer.GrandTotal[ ] grandTotals, actuate.xtabanalyzer.SubTotal[ ] subTotals) Sets totals for the cross tab. 612 Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Cr osstab Parameters grandTotals Array of actuate.xtabanalyzer.GrandTotal objects. Grand totals. To set a subtotal, set this parameter to null. subTotals Array of actuate.xtabanalyzer.SubTotal objects. Subtotals. Example This example adds a grand total to a cross tab: function addGrandTotal( ){ var grandTotal = new actuate.xtabanalyzer.GrandTotal( ); grandTotal.setAxisType( actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE); var total = new actuate.xtabanalyzer.Total( ); total.setMeasureIndex(1); total.setAggregationFunction("SUM"); total.setEnabled(true); grandTotal.addTotal(total); crosstab.setTotals(grandTotal); crosstab.submit( ); } showDetail Syntax void Crosstab.showDetail(string axisType) Shows a level of detail within a cross tab. Parameter axisType String. The dimension axis type. Axis type can be one of the following values: Example ■ actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE ■ actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE This example uses showDetail to expose extra detail on a level: function showDetail( ){ var axisType = actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE; crosstab.showDetail(axisType); crosstab.submit( ); } submit Syntax void Crosstab.submit(function callback) Applies the changes made to this element. This is an asynchronous operation. Chapter 18, BIRT Interactive Crosstabs API classes 613 actuat e.xt abanalyzer .C rosst ab Parameter callback Function. Optional. The function called when submit( ) completes. This function receives the current XTabAnalyzer object as an input parameter. Example This example uses submit( ) to confirm changes to the cross tab: function showDetail(crosstab){ var axisType = actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE; crosstab.showDetail(axisType); crosstab.submit( ); } 614 Actuate BIRT Application Developer Guide actuate.xtabanalyzer .Dimension Class actuate.xtabanalyzer.Dimension Description The Dimension class specifies a cross tab Dimension object. Constructor Syntax actuate.xtabanalyzer.Dimension( ) The Dimension class is used to specify a Dimension object. Function summary Table 18-4 lists actuate.xtabanalyzer.Dimension functions. Table 18-4 actuate.xtabanalyzer.Dimension functions Function Description addLevel( ) Adds the level to the dimension getAxisType( ) Returns the axis type getDimensionName( ) Returns the dimension name getIndex( ) Returns the index of the dimension getLevels( ) Returns cross tab levels getNewAxisType( ) Returns the new axis type getNewIndex( ) Returns the new index setAxisType( ) Sets the axis type setDimensionName( ) Sets the dimension name setIndex( ) Sets the index setLevels( ) Sets the levels setNewAxisType( ) Sets the new axis type setNewIndex( ) Sets the new index axis type addLevel Syntax void Dimension.addLevel(actuate.xtabanalyzer.Level level) Adds a level to the dimension. Parameter level actuate.xtabanalyzer.Level object. A level to add to the dimension. Example This example adds a level to a dimension: function addLvl(dimension,levelName){ Chapter 18, BIRT Interactive Crosstabs API classes 615 actuat e.xt abanalyzer .D imension var level = new actuate.xtabanalyzer.Level( ); level.setLevelName(levelName); dimension.addLevel(level); } getAxisType Syntax integer Dimension.getAxisType( ) Returns the axis type for the dimension. Returns Example Integer. The axis type can be one of the following values: ■ actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE ■ actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE This example retrieves and sets the axis type: function swapAxis(dimension){ if (dimension.getAxisType( ) == actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE){ dimension.setNewAxisType( actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE); else { dimension.setNewAxisType( actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE); } } getDimensionName Syntax string Dimension.getDimensionName( ) Returns the name of this dimension. Returns Example String. The dimension name. This example retrieves the dimension name: function getDimName(dimension){ if(dimension){ return dimension.getDimensionName( ); } return null; } getIndex Syntax 616 integer Dimension.getIndex( ) Actuate BIRT Application Developer Guide actuate.xtabanalyzer .Dimension Returns the dimension index. Returns Example Integer. The dimension index. This example retrieves and increments the index: function incrementIndex(dimension){ var newIndex = dimension.getIndex( ) + 1; dimension.setNewIndex(newIndex); } getLevels Syntax actuate.xtabanalyzer.Level[ ] Dimension.getLevels( ) Returns the dimension levels. Returns Example actuate.xtabanalyzer.Level[ ]. Array of dimension levels. This example retrieves the dimension levels: function getDimLevels(dimension){ if(dimension){ return dimension.getLevels( ); } return null; } getNewAxisType Syntax integer Dimension.getNewAxisType( ) Returns the new axis type. Returns Example Integer containing the new axis type. This example retrieves the new axis type: function getNewDimAxis(dimension){ if(dimension){ return dimension.getNewAxisType( ); } return null; } getNewIndex Syntax integer Dimension.getNewIndex( ) Returns the new index. Returns Integer. The new index. Chapter 18, BIRT Interactive Crosstabs API classes 617 actuat e.xt abanalyzer .D imension Example This example retrieves the new index: function getNewDimIndex(dimension){ if(dimension){ return dimension.getNewIndex( ); } return null; } setAxisType Syntax void Dimension.setAxisType(integer axisType) Sets the axis type when creating a new dimension. Use setNewAxisType( ) to change a dimension that already exists. Parameter axisType The axis type for the dimension. The axis type has the following legal values: Example ■ actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE ■ actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE This example sets the axis type for a new dimension: function setRowAxis(dimension){ dimension.setAxisType( actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE); } setDimensionName Syntax void Dimension.setDimensionName(string dimensionName) Sets the name for a dimension during its creation. Parameter dimensionName String. The name of the dimension. Example This example sets the dimension name to a value taken from a page element: function setDimensionName(dimension){ var dimensionName = document.getElementById("dimensionName") .value; dimension.setDimensionName(dimensionName); } setIndex Syntax void Dimension.setIndex(integer index) Sets the index for the dimension. 618 Actuate BIRT Application Developer Guide actuate.xtabanalyzer .Dimension Parameter index The index of the dimension. Example This example sets the dimension index to a value taken from a page element: function setDimensionIndex(dimension){ var dimensionIndex = document.getElementById("dimensionIndex") .value; dimension.setIndex(dimensionIndex); } setLevels Syntax void Dimension.setLevels(xtabanalyzer.Level[ ] levels) Sets levels for the dimension. Parameter levels Array of xtabanalyzer.Level objects representing the levels for the dimension. Example This example sets the dimension levels: function setDimensionLevels(dimension,levels){ if (dimension && levels){ dimension.setLevels(levels); } } setNewAxisType Syntax void Dimension.setNewAxisType(integer newAxisType) Sets the new axis type. Parameter newAxisType Integer. The new axis type. Example This example retrieves and changes the axis type: function swapAxis(dimension){ if (dimension.getAxisType( ) == actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE){ dimension.setNewAxisType( actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE); } else { dimension.setNewAxisType( actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE); } } Chapter 18, BIRT Interactive Crosstabs API classes 619 actuat e.xt abanalyzer .D imension setNewIndex Syntax void Dimension.setNewtIndex(integer newIndex) Sets the new index. Parameter newIndex Integer. The new index. Example This example retrieves and increments the index: function incrementIndex(dimension){ var newIndex = dimension.getIndex( ) + 1; dimension.setNewIndex(newIndex); } 620 Actuate BIRT Application Developer Guide actuate.xtabanalyzer. Driller Class actuate.xtabanalyzer.Driller Description The Driller class enables an application to drill down or up levels on a member within a dimension. Constructor Syntax actuate.xtabanalyzer.Driller( ) Creates a Driller object. Function summary Table 18-5 lists actuate.xtabanalyzer.Driller functions. Table 18-5 actuate.xtabanalyzer.Driller functions Function Description addMember( ) Adds a member to the drill condition getDimension( ) Retrieves the driller dimension getMembers( ) Retrieves the members used by the drill setDimension( ) Sets the driller dimension setMembers( ) Adds an array of members to the drill condition addMember Syntax void Driller.addMember(actuate.xtabanalyzer.MemberValue member) Adds a dimension member to the drill condition. Functional candidates are Dimension members with levels. Parameter member actuate.xtabanalyzer.MemberValue object. A member value to add. Example This example adds a member to a Driller object: function drillDownDimension( ){ var driller = new actuate.xtabanalyzer.Driller( ); driller.setDimension(actuate.xtabanalyzer.Dimension .ROW_AXIS_TYPE); var memberValue = new actuate.xtabanalyzer .MemberValue("drillLevelName"); memberValue.setValue("drillLevelValue"); driller.addMember(memberValue); crosstab.drill( driller ); Chapter 18, BIRT Interactive Crosstabs API classes 621 actuat e.xt abanalyzer .D rill er crosstab.submit( ); } getDimension Syntax string Driller.getDimension( ) Returns the dimension name for the drill condition. Returns Example String. A dimension name. This example retrieves the dimension of the driller: function getDrillerAxis(driller){ if (driller){ return driller.getDimension( ); } return null; } getMembers Syntax actuate.xtabanalyzer.MemberValue[ ] Driller.getMembers( ) returns the list of members assigned to the driller. Returns Example Array of actuate.xtabanalyzer.MemberValue. A dimension member. This example retrieves the members that a driller uses: function getDrillerMembers(driller){ if (driller){ return driller.getMembers( ); } return null; } setDimension Syntax void Driller.setDimension(string dimension) Sets the dimension for the driller by name. Parameter dimension String. A dimension name. Example This example sets the dimension name for the driller: function setRowAxis(driller){ if (driller){ dimension.setDimension("Row"); 622 Actuate BIRT Application Developer Guide actuate.xtabanalyzer. Driller } } setMembers Syntax void Driller.setMembers(actuate.xtabanalyzer.MemberValue[ ] member) Sets an array of members to the drill condition. Parameter member Array of actuate.xtabanalyzer.MemberValue objects. An array of members. Example This example sets the axis type for the driller: function setDrillerMembers(driller,members){ if (driller && members){ driller.setMembers(members); } } Chapter 18, BIRT Interactive Crosstabs API classes 623 actuat e.xt abanalyzer .E ventC onstan ts Class actuate.xtabanalyzer.EventConstants Description Defines constants for xtabanalyzer events. Table 18-6 lists the cross tab analyzer event constants. Table 18-6 624 actuate.xtabanalyzer.Dimension constants Constant Description ON_CONTENT_CHANGED Content changed event. Triggers when the displayed content has changed, for example when changing cross tab report content. The event handler takes an actuate.XTabAnalyzer object that represents the viewer for which the event occurred, as the only parameter. ON_CONTENT_SELECTED Content selected event. Triggers when a user clicks on report elements. The event handler takes the following parameters: ■ actuate.XTabAnalyzer: object viewer for which event occurred ■ actuate.xtabanalyzer.SelectedContent: the SelectedContent object ON_EXCEPTION Exception event. Triggers when an exception occurs during an asynchronous operation. The event handler takes the following arguments: ■ actuate.XTabAnalyzer: viewer for which the event occurred ■ actuate.Exception: Exception object ON_SESSION_TIMEOUT Session time-out event. When a session time-out event occurs and the user tries to perform any operation on a viewer, a prompt dialog appears asking the user whether or not to log in again. When the user chooses to log in again, the ON_SESSION_TIMEOUT event triggers. When no handler is registered for this event, a default built-in login dialog will be displayed. The event handler takes one parameter: an actuate.XTabAnalyzer object, representing the viewer where the event occurred. Actuate BIRT Application Developer Guide actuate.xtabanalyzer.E xception Class actuate.xtabanalyzer.Exception Description A container for an XTabAnalyzer exception that supports specific exceptions. The Exception class provides an object to pass to a callback function or event handler when an exception occurs. The Exception class contains references to the exception’s origin, description, and messages. Constructor The Exception object is constructed when unspecified exceptions occur. The exceptions are divided into three types, which determine the contents of the Exception object. These types are: ■ ERR_CLIENT: Exception type for a client-side error ■ ERR_SERVER: Exception type for a server error ■ ERR_USAGE: Exception type for a JSAPI usage error Function summary Table 18-7 lists actuate.xtabanalyzer.Exception functions. Table 18-7 actuate.xtabanalyzer.Exception functions Function Description getDescription( ) Returns details of the exception getElement( ) Returns the report element for which the exception occurred, if available getErrCode( ) Returns the error code for ERR_SERVER getMessage( ) Returns a short message about the error getType( ) Returns the type of error exception isExceptionType( ) Returns Boolean indicating whether exception is of certain type getDescription Syntax string Exception.getDescription( ) Returns exception details as provided by the Server, Client, and User objects. Returns String. A detailed description of the error. Information is provided according to the type of exception generated, as shown below: ■ ERR_SERVER: The SOAP string Chapter 18, BIRT Interactive Crosstabs API classes 625 actuat e.xt abanalyzer .E xception Example ■ ERR_CLIENT: For the Firefox browser, a list comprised of fileName+number+stack ■ ERR_USAGE: Any value set when the object was created This example consists of a function that registerEventHandler( ) set as a callback. The callback function takes an instance of the Exception class. Each of the functions for the Exception class can be called with the results formatted to create a message or for some other use. function errorHandler(viewerInstance, exception){ alert(exception.getDescription( )); } getElement Syntax string Exception.getElement( ) Returns the report element for which the exception occurred, if available. Returns Example String. The report element for which the exception occurred. This example uses getElement( ): function errorHandler(viewerInstance, exception){ alert("Error in " + exception.getElement( )); } getErrCode Syntax string Exception.getErrCode( ) Returns the error code for ERR_SERVER. Returns Example String. The error code for ERR_SERVER. This example uses getErrCode( ): function errorHandler(viewerInstance, exception){ alert(exception.getErrCode( )); } getMessage Syntax string Exception.getMessage( ) Returns a short message about the error. Returns Example String. A short message about the exception. This example uses getMessage( ): function errorHandler(viewerInstance, exception){ 626 Actuate BIRT Application Developer Guide actuate.xtabanalyzer.E xception alert(exception.getMessage( )); } getType Syntax string Exception.getType( ) Returns the type of exception error. Returns Example String. The errType exception type. This example uses getType( ): function errorHandler(viewerInstance, exception){ alert(exception.getType( )); } isExceptionType Syntax boolean Exception.isExceptionType(object exceptionType) Checks an exception’s type for a match against a specified type. Parameter exceptionType An exception type as string, or exception class. For example, "actuate.viewer.ViewerException" or actuate.viewer.ViewerException. Returns Example True if the exception is of the stated type, false otherwise. This example checks to see if the exception is a client error type: function errorHandler(viewerInstance, exception){ if (exception.isExceptionType(ERR_CLIENT){ alert("CLIENT ERROR"); } } Chapter 18, BIRT Interactive Crosstabs API classes 627 actuat e.xt abanalyzer .Fi lter Class actuate.xtabanalyzer.Filter Description The Filter class creates a filter condition on a cross tab dimension level. The condition is expressed as value1 operator value2. The values can either be a single value, or an array of values, depending on the operator. For example, IN can be expressed as value1 IN value2 value3 ... valueN. Constructor Syntax actuate.xtabanalyzer.Filter(string levelName, string levelAttributeName, string operator, string value, string filterType) actuate.xtabanalyzer.Filter(string levelName, string levelAttributeName, string operator, string value1, string value2, string filterType) actuate.xtabanalyzer.Filter(string levelName, string levelAttributeName, string operator, string[ ] values, string filterType) Constructs a cross tab Filter object. Parameters levelName String. The dimension level full name. levelAttributeName String. The dimension level attribute name. operator String. The operator can be any operator. Table 18-8 lists the valid filter operators and the number of arguments to pass to the constructor or setValues( ). Table 18-8 628 Filter operators Number of arguments Operator Description BETWEEN Between an inclusive range 2 BOTTOM_N Matches the bottom n values 1 BOTTOM_PERCENT Matches the bottom percent of the values 1 EQ Equal 1 FALSE Matches false Boolean values 0 GREATER_THAN Greater than 1 GREATER_THAN_OR_EQUAL Greater than or equal 1 Actuate BIRT Application Developer Guide actuat e.xtabanalyzer.Filter Table 18-8 Filter operators Operator Description IN Matches any value in a set of values LESS_THAN Less than Number of arguments 1+ 1 LESS_THAN_OR_EQUAL Less than or equal 1 LIKE Search for a pattern 1 MATCH Equal 1 NOT_BETWEEN Not between an inclusive range 2 NOT_EQ Not equal NOT_IN Does not match any value in a set of values 1+ 1 NOT_LIKE Searches for values that do not match a pattern 1 NOT_MATCH Not equal 1 NOT_NULL Is not null 0 NULL Is null 0 TOP_N Matches the top n values 1 TOP_PERCENT Matches the top percent of the values 1 TRUE Matches true Boolean values 0 value String. The value to compare to the column value. value1 String. The first value to compare to the column value for the BETWEEN or NOT_BETWEEN operators. value2 String. The second value to compare to the column value for the BETWEEN or NOT_BETWEEN operators. values Array of strings. The values to compare to the column value for the IN and NOT_IN operators. Chapter 18, BIRT Interactive Crosstabs API classes 629 actuat e.xt abanalyzer .Fi lter filterType String. The filter type. Function summary Table 18-9 lists actuate.xtabanalyzer.Filter functions. Table 18-9 actuate.xtabanalyzer.Filter functions Function Description getFilterType( ) Returns the filter type getLevelAttributeName( ) Returns the dimension level attribute name getLevelName( ) Returns the name of the filtered level getOperator( ) Returns the filter operator getValues( ) Returns the set of values the filter is using setFilterType( ) Sets the filter type setLevelAttributeName( ) Sets the dimension level attribute name setLevelName( ) Sets the dimension level name setOperator( ) Sets the filter operator setValues( ) Sets the values for the filter getFilterType Syntax string Filter.getFilterType( ) Returns the filter type. Returns Example String. The filter type. This example retrieves the filter type for a filter: function getType(filter){ if(filter){ return filter.getFilterType( ); }else{ return null; } } getLevelAttributeName Syntax string Filter.getLevelAttribute Name( ) Returns the name of the dimension level attribute to which this filter applies. 630 Actuate BIRT Application Developer Guide actuat e.xtabanalyzer.Filter Returns Example String. The level attribute name. This example retrieves the filter level attribute name for a filter: function getLevelAttribute(filter){ if(filter){ return filter.getLevelAttributeName( ); }else{ return null; } } getLevelName Syntax string Filter.getLevelName( ) Returns the name of the dimension level to which this filter applies. Returns Example String. A level name. This example retrieves the filter level name for a filter: function getLevel(filter){ if(filter){ return filter.getLevelName( ); }else{ return null; } } getOperator Syntax string Filter.getOperator( ) Returns the filter operator. Returns Example String. The filter operator. This example retrieves the filter operator: function getFilterOp(filter){ if(filter){ return filter.getOperator( ); }else{ return null; } } getValues Syntax string[ ] Filter.getValues( ) Chapter 18, BIRT Interactive Crosstabs API classes 631 actuat e.xt abanalyzer .Fi lter Returns an array containing the values used in the filter. Returns Example Array of strings. The values for the filter. This example retrieves the filter level name for a filter: function getFilterOp(filter){ if(filter){ return filter.getValues( ); }else{ return null; } } setFilterType Syntax void Filter.setFilterType(string filterType) Sets the filter type to filter. Parameter filterType String. The type of filter. Example This example sets the filter type to equality: function filterLevel( ){ var filterType = "equality"; var filter = new actuate.xtabanalyzer.Filter("levelName", "attributeName",actuate.xtabanalyzer.Filter.EQ, "2000","blank"); filter.setFilterType(filterType); crosstab.setFilters( filter ); crosstab.submit( ); } setLevelAttributeName Syntax void Filter.setLevelAttributeName(string levelAttributeName) Sets the dimension level attribute to filter on by name. Parameter levelAttributeName String. The name of the level attribute to filter. Example This example sets the level attribute name to attributeName: function filterLevel( ){ var attributeName = "attributeName"; var filter = new actuate.xtabanalyzer.Filter("levelName", "blank",actuate.xtabanalyzer.Filter.EQ, "2000","equality"); filter.setLevelAttributeName(attributeName); 632 Actuate BIRT Application Developer Guide actuat e.xtabanalyzer.Filter crosstab.setFilters( filter ); crosstab.submit( ); } setLevelName Syntax void Filter.setLevelName(string level) Sets the level to filter by name. Parameter level String. The name of the level to filter. Example This example sets the filter level name to levelName: function filterLevel( ){ var levelName = "levelName"; var filter = new actuate.xtabanalyzer.Filter("blank", "attributeName",actuate.xtabanalyzer.Filter.EQ, "2000","equality"); filter.setLevelName(levelName); crosstab.setFilters( filter ); crosstab.submit( ); } setOperator Syntax void Filter.setOperator(string operator) Sets the filter operator. Parameter operator String. The filter operator. Example This example sets the filter operator to EQ: function filterLevel( ){ var operator = "EQ"; var filter = new actuate.xtabanalyzer.Filter("levelName", "attributeName",actuate.xtabanalyzer.Filter.NOT, "2000","equality"); filter.setOperator(operator); crosstab.setFilters( filter ); crosstab.submit( ); } setValues Syntax void Filter.setValues(string[ ] value1, string[ ] value2) Sets the values for the filter. Chapter 18, BIRT Interactive Crosstabs API classes 633 actuat e.xt abanalyzer .Fi lter Parameters value1 String or array of strings. The first value of the filter. value2 String or array of strings. Optional. The second value of the filter. Example This example sets the filter values to 2000 and 2004: function filterLevel( ){ if(crosstab){ var filterValue = "2000;2004"; var filter = new actuate.xtabanalyzer.Filter ("levelName","attributeName", actuate.xtabanalyzer.Filter.BETWEEN); filter.setValues(filterValue.split(";") ); crosstab.setFilters( filter ); crosstab.submit( ); } } 634 Actuate BIRT Application Developer Guide actuate.xtabanalyzer.GrandTotal Class actuate.xtabanalyzer.GrandTotal Description The GrandTotal class specifies a cross tab GrandTotal object. Constructor Syntax actuate.xtabanalyzer.GrandTotal( ) Constructs a new GrandTotal object. Function summary Table 18-10 lists actuate.xtabanalyzer.GrandTotal functions. Table 18-10 actuate.xtabanalyzer.GrandTotal functions Function Description addTotal( ) Adds a total getAxisType( ) Returns the axis type getTotals( ) Returns the totals array getType( ) Returns the grand total type setAxisType( ) Sets the axis type setTotals( ) Sets the totals array addTotal Syntax void GrandTotal.addTotal(object total) Adds a total to the cross tab. Parameter total actuate.xtabanalyzer.total. The total to add to the cross tab. Example This example adds totals to a grand total: function addTotal(grandTotal){ // The indexStr can be set from a web page or other source as // necessary. var indexStr = "0;1;2;3;4"; var indexs = indexsStr.split(";"); var count = indexs.length; var measureIndexs = [ ]; for(var i = 0;i < count;i++){ measureIndexs.push(parseInt(indexs[i])); } for( var i = 0; i < measureIndexs.length; i++){ Chapter 18, BIRT Interactive Crosstabs API classes 635 actuat e.xt abanalyzer .Gra ndTot al var total = new actuate.xtabanalyzer.Total( ); total.setMeasureIndex(measureIndexs[i]); total.setAggregationFunction("SUM"); total.setEnabled(true); grandTotal.addTotal(total); } } getAxisType Syntax integer GrandTotal.getAxisType( ) Returns the axis type for the total. Returns Example Integer. The following values are legal axis types: ■ actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE ■ actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE This example retrieves and sets the axis type: function swapAxis(grandtotal){ if (grandtotal.getAxisType( ) == actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE){ grandtotal.setNewAxisType( actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE); } else { grandtotal.setNewAxisType( actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE); } } getTotals Syntax object[ ] GrandTotal.getTotals( ) Returns an array containing the totals. Returns Example Array of Total objects. The totals. This example retrieves totals from a GrandTotal object: var totalsArray = [ ]; function getTotals(grandTotal,totalsArray){ totalsArray = grandTotal.getTotals( ); } getType Syntax 636 string GrandTotal.getType( ) Actuate BIRT Application Developer Guide actuate.xtabanalyzer.GrandTotal Returns the type for the total. Returns String. The total type. setAxisType Syntax void GrandTotal.setAxisType(integer axisType) Sets the axis type for the total. Parameter axisType Integer. Axis type for the total. Example This example retrieves and sets the axis type: function swapAxis(grandtotal){ if (grandtotal.getAxisType( ) == actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE){ grandtotal.setNewAxisType( actuate.xtabanalyzer.Dimension.COLUMN_AXIS_TYPE); } else { grandtotal.setNewAxisType( actuate.xtabanalyzer.Dimension.ROW_AXIS_TYPE); } } setTotals Syntax void GrandTotal.setTotals(actuate.xtabanalyzer.Total[ ] totals) Sets totals as an array. Parameter totals Array of actuate.xtabanalyzer.Total objects to add to the grand total. Example This example copies the totals from grandtotal1 into grandtotal2: grandtotal2.setTotals(grandtotal1.getTotals( )); Chapter 18, BIRT Interactive Crosstabs API classes 637 actuat e.xt abanalyzer .Leve l Class actuate.xtabanalyzer.Level Description Defines a cross tab dimension level, its controls, and content. Constructor Syntax actuate.xtabanalyzer.Level( ) Creates a cross tab Level object. Function summary Table 18-11 lists actuate.xtabanalyzer.Level functions. Table 18-11 actuate.xtabanalyzer.Level functions Function Description addAttribute( ) Adds the level attribute getAttributes( ) Returns the level attributes getIndex( ) Returns the index of the level getLevelName( ) Returns the level name setIndex( ) Sets the index level setLevelName( ) Sets the level name addAttribute Syntax void Level.addAttribute(actuate.xtabanalyzer.LevelAttribute attr) Adds the level attribute. Parameter index actuate.xtabanalyzer.LevelAttribute object. A level attribute. Example This example sets a name for newly created level attribute and assigns the attribute to a level: var attribute = new actuate.xtabanalyzer.LevelAttribute( ); attribute.setName("pounds"); level.addLevelAttribute( attribute ); getAttributes Syntax actuate.xtabanalyzer.LevelAttribute[ ] Level.getAttributes( ) Returns the level attributes. 638 Actuate BIRT Application Developer Guide actuate.xtabanalyzer .Level Returns Example Array of actuate.xtabanalyzer.LevelAttribute objects. The level attributes. This example retrieves the level index and stores it in a variable called lattributes: var lattributes = new actuate,xtabanalyzer.LevelAttribute[ ]; lattributes = level.getAttributes( ); getIndex Syntax integer Level.getIndex( ) Returns the level index. Returns Example Integer. The level index. This example retrieves the level index: function levelIndex(level){ if (level){ return level.getIndex( ); } return null; } getLevelName Syntax string Level.getLevelName( ) Returns the level name. Returns Example String. The level name. This example retrieves the level name: function levelName(level){ if (level){ return level.getLevelName( ); } return null; } setIndex Syntax void Level.setIndex(integer index) Sets the level index. Parameter index Integer. The level index. Example This example sets the level index: function assignIndex(level,index){ Chapter 18, BIRT Interactive Crosstabs API classes 639 actuat e.xt abanalyzer .Leve l if (level){ return level.setIndex(index); } } setLevelName Syntax void Level.setLevelName(string levelName) Sets the level name. Parameter levelName String. The level name. Example This example sets level names for newly created levels: var levelNames ="year;month;day"; ... function addLevels(dimension,levelNames);{ var levelNamesArray = levelNames.split(";"); for( var i = 0; i < levelNames.length; i++ ){ var level = new actuate.xtabanalyzer.Level( ); level.setLevelName(levelNames[i]); dimension.addLevel( level ); } } 640 Actuate BIRT Application Developer Guide actuate.xtabanalyzer .LevelAtt ribute Class actuate.xtabanalyzer.LevelAttribute Description Defines an attribute for a level. Constructor Syntax actuate.xtabanalyzer.LevelAttribute( ) Creates a cross tab level attribute object. Function summary Table 18-12 lists actuate.xtabanalyzer.LevelAttribute functions. Table 18-12 actuate.xtabanalyzer.Level functions Function Description getName( ) Returns the level attribute name setName( ) Sets the level attribute name getName Syntax string LevelAttribute.getName( ) Returns the level attribute name. Returns Example String. A level attribute name. This example retrieves the level attribute name and stores it in a variable attname: var attname = levelattribute.getName( ); setName Syntax void LevelAttribute.setName(string attributeName) Sets the level attribute name. Parameter attributeName String. The level attribute name. Example This example sets a name for newly created level attribute and assigns the attribute to a level: var attribute = new actuate.xtabanalyzer.LevelAttribute( ); attribute.setName("pounds"); level.addLevelAttribute( attribute ); Chapter 18, BIRT Interactive Crosstabs API classes 641 actuat e.xt abanalyzer .Measur e Class actuate.xtabanalyzer.Measure Description Defines a cross tab measure. Constructor Syntax actuate.xtabanalyzer.Measure( ) Creates a cross tab measure object. Function summary Table 18-13 lists actuate.xtabanalyzer.Measure functions. Table 18-13 actuate.xtabanalyzer.Measure functions Function Description getAggregationFunction( ) Returns the aggregation function name getDataType( ) Returns the computed column data type getExpression( ) Returns the computed measure expression getIndex( ) Returns the measure index getMeasureName( ) Returns the measure name getNewIndex( ) Returns the new index setAggregationFunction( ) Sets the aggregation function name setDataType( ) Sets the computed column data type setExpression( ) Sets the computed measure expression setIndex( ) Sets the measure index setMeasureName( ) Sets the measure name setNewIndex( ) Sets the new index getAggregationFunction Syntax string Measure.getAggregationFunction( ) Returns the aggregation function name. Returns Example String. An aggregation function name. This example changes the aggregation function: function swapMeasureAggregation(measure){ if (measure.getAggregation( ) == "EQ"){ measure.setAggregation("NE"); 642 Actuate BIRT Application Developer Guide actuate.xtabanalyzer .Measure }else{ measure.setAggregation("EQ"); } } getDataType Syntax string Measure.getDataType( ) Returns the computed column data type. Returns Example String. The data type. This example retrieves the computed column data type: function getColumnDataType(measure){ if (measure){ return measure.getDataType( ); } return null; } getExpression Syntax string Measure.getExpression( ) Returns the computed measure expression. Returns Example String. An expression. This example retrieves the computed measure expression: function getMeasureExpression(measure){ if (measure){ return measure.getExpression( ); } return null; } getIndex Syntax integer Measure.getIndex( ) Returns the measure index. Returns Example Integer. The measure index. This example retrieves the measure index: function getMeasureIndex(measure){ if (measure){ return measure.getIndex( ); Chapter 18, BIRT Interactive Crosstabs API classes 643 actuat e.xt abanalyzer .Measur e } return null; } getMeasureName Syntax string Measure.getMeasureName( ) Returns the measure name. Returns Example String. The name of the measure. This example retrieves the measure name: function getMeasureName(measure){ if (measure){ return measure.getMeasureName( ); } return null; } getNewIndex Syntax integer Measure.getNewIndex( ) Retrieves the new index. The new index is set by setNewIndex and represents the index value the measure has after submit( ) finishes executing. Returns Example Integer. The new index. This example retrieves the new measure index: function getNewMeasureIndex(measure){ if (measure){ return measure.getNewIndex( ); } return null; } setAggregationFunction Syntax void Measure.setAggregationFunction(string aggregationFunction) Sets the aggregation function name. Parameter aggregationFunction String. The aggregation function name. Example This example changes the aggregation function: function swapMeasureAggregation(measure){ if (measure.getAggregation( ) == "EQ"){ 644 Actuate BIRT Application Developer Guide actuate.xtabanalyzer .Measure measure.setAggregation("NE"); }else{ measure.setAggregation("EQ"); } } setDataType Syntax void Measure.setDataType(string dataType) Sets the computed column data type name. Parameter dataType String. The data type. setExpression Syntax void Measure.setExpression(string expression) Sets the computed measure expression. Parameter expression String. The computed measure expression. Example This example uses setExpression: function addMeasure(viewer){ var crosstab = getCrosstab(viewer); if(crosstab){ var measureName = "measureName"; var measureExpression = "[revenue]/[revenue_SalesDate/year_Product/PRODUCTLINE]"; var measure = new actuate.xtabanalyzer.Measure( ); measure.setIndex(1); measure.setMeasureName(measureName); measure.setExpression(measureExpression); crosstab.addMeasure(measure); crosstab.submit( ); } } setIndex Syntax void Measure.setIndex(integer index) Sets the index. Chapter 18, BIRT Interactive Crosstabs API classes 645 actuat e.xt abanalyzer .Measur e Parameter index Integer. The index of this measure. Example This example uses setIndex to add a new measure to a cross tab: function setIndex(measure, index){ measure.setIndex(index); } setMeasureName Syntax void Measure.setMeasureName(string measureName) Sets the measure name. Parameter measureName String. The measureName. Example This example sets the measure name which is taken from a page element: function renameMeasure(measure){ var measureName = document.getElementById("measureName").value; measure.setMeasureName(measureName); } setNewIndex Syntax void Measure.setNewIndex(integer newIndex) Sets a new measure index. Parameter newIndex Integer. The new measure index. Example This example changes the index for the measure: function changeIndex(measure,index){ if (measure){ measure.setNewIndex(index); } } 646 Actuate BIRT Application Developer Guide act uat e. xtabanalyzer.MemberValue Class actuate.xtabanalyzer.MemberValue Description Defines a member value used for sort, filter, or drill functionality. Constructor Syntax actuate.xtabanalyzer.MemberValue(levelName, value, (MemberValue)) Creates a MemberValue object for a given level and value. The object can contain multiple member values. Parameters levelName String. Dimension level name of member. value String. Value for the member to contain. MemberValue Optional actuate.xtabanalyzer.MemberValue object. MemberValue object to add during construction. Function summary Table 18-14 lists actuate.xtabanalyzer.MemberValue functions. Table 18-14 actuate.xtabanalyzer.MemberValue functions Function Description addMember( ) Adds a member value object getLevelName( ) Retrieves the level name getMembers( ) Retrieves an array of members getValue( ) Returns the level value setLevelName( ) Sets the level name setValue( ) Sets the member value addMember Syntax void MemberValue.addMember(actuate.xtabanalyzer.MemberValue member) Adds a member value. Parameter member actuate.xtabanalyzer.MemberValue object. A member value. Example MemberValue is an embedded class that can be a single value or an array of values. This example has a single member that contains four members: Chapter 18, BIRT Interactive Crosstabs API classes 647 actuat e.xt abanalyzer .Member Val ue function addMembers(memberData){ var mv1 = new MemberValue('dim/state','CA'); var mv2 = new MemberValue('dim/state','CN'); var mv3 = new MemberValue(memberData); var mv = new MemberValue('dim/country','USA'); mv.addMember(mv1); mv.addMember(mv2); mv.addMember(mv3); return mv; } getLevelName Syntax string MemberValue.getLevelName( ) Returns the level name of the member. Returns Example String. The level name. This example retrieves the level name for the member value: function getLevelName(level){ if (level){ return level.getLevelName( ); } return null; } getMembers Syntax actuate.xtabanalyzer.MemberValue[ ] MemberValue.getMembers( ) Returns all the member value objects contained in this member value object. Returns Example Array of actuate.xtabanalyzer.MemberValue. An array of MemberValue objects. This example returns the number of members in a member object: function getMemberCount(members){ if (members){ var membersArray[] = members.getMembers( ); return membersArray.length; } return null; } getValue Syntax 648 string MemberValue.getValue( ) Actuate BIRT Application Developer Guide act uat e. xtabanalyzer.MemberValue Returns the level value. Returns Example String. The level value. This example returns the value for the level: function getMemberValue(members){ if (members){ return members.getValue( ); } return null; } setLevelName Syntax void MemberValue.setLevelName(string level) Sets the level name. Parameter level String. The name of the level. Example This example sets the level name: function getMemberValue(members){ if (members){ return members.getValue( ); } return null; } setValue Syntax void MemberValue.setValue(string level) Sets the level value. Parameter level String. The value for the level. Example This example sets the level value: function setMemberLevelValue(member,lvlValue){ if (member){ member.setValue(lvlValue); } } Chapter 18, BIRT Interactive Crosstabs API classes 649 actuat e.xt abanalyzer .Opti ons Class actuate.xtabanalyzer.Options Description The Options class specifies options for the cross tab. Constructor Syntax actuate.xtabanalyzer.Options(string measureDirection, string rowMirrorStartingLevel, string columnMirrorStartingLevel, string emptyCellValue, boolean enablePageBreak, integer rowPageBreakInterval, integer columnPageBreakInterval) Creates an options object that contains options for how the cross tab displays data. Parameters measureDirection String. The measure direction. Legal values for measure direction are: ■ DIRECTION_HORIZONTAL ■ DIRECTION_VERTICAL rowMirrorStartingLevel String. Row mirror starting level name. columnMirrorStartingLevel String. Column mirror starting level name. emptyCellValue String. Value to display for an empty cell. enablePageBreak Boolean. Enables page breaks when true. rowPageBreakInterval Integer. Row page break interval. columnPageBreakInterval Integer. Column page break interval. grandTotalsDisplayOption String. Grand totals display option. Legal values for total display options are: ■ DIRECTION_HORIZONTAL ■ DIRECTION_VERTICAL subtotalsDisplayOption String. Subtotals display option. Legal values for total display options are: 650 ■ DIRECTION_HORIZONTAL ■ DIRECTION_VERTICAL Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Options Function summary Table 18-15 lists actuate.xtabanalyzer.Options functions. Table 18-15 actuate.xtabanalyzer.Options functions Function Description getColumnMirrorStartingLevel( ) Returns the column mirror starting level full name getColumnPageBreakInterval( ) Returns the column page break interval getEmptyCellValue( ) Returns the empty cell value getEnablePageBreak( ) Returns the page break enabled or disabled status getMeasureDirection( ) Returns the measure direction getRowMirrorStartingLevel( ) Returns the row mirror starting level full name getRowPageBreakInterval( ) Returns the row page break interval setColumnMirrorStartingLevel( ) Sets the column mirror starting level full name setColumnPageBreakInterval( ) Sets the column page break interval setEmptyCellValue( ) Sets the empty cell value setEnablePageBreak( ) Sets the flag to enable page breaks setMeasureDirection( ) Sets the measure direction setRowMirrorStartingLevel( ) Sets the row mirror starting level full name setRowPageBreakInterval( ) Sets the row page break interval getColumnMirrorStartingLevel Syntax string Options.getColumnMirrorStartingLevel( ) Returns the column mirror starting level name. Returns Example String. Column mirror starting level name. This example retrieves the column mirror starting level: function getColumnMirrorStart(options){ if (options){ return options.getColumnMirrorStartinglevel( ); } return null; } Chapter 18, BIRT Interactive Crosstabs API classes 651 actuat e.xt abanalyzer .Opti ons getColumnPageBreakInterval Syntax integer Options.getColumnPageBreakInterval( ) Returns the column page break interval. Returns Example Integer. The column page break interval. This example retrieves the column page break interval: function getColumnPBInterval(options){ if (options){ return options.getColumnPageBreakInterval( ); } return null; } getEmptyCellValue Syntax string Options.getEmptyCellValue( ) Returns the empty cell value. Returns Example String. Value to display for an empty cell. This example retrieves the empty cell: function getEmptyCell(options){ if (options){ return options.getEmptyCellValue( ); } return null; } getEnablePageBreak Syntax boolean Options.getEnablePageBreak( ) Returns the page break status. Returns Example Boolean. Page breaks are enabled when the value is true. This example retrieves the column page break interval when page breaks are enabled: function getColumnPBEnabled(options){ if (options.getEnablePageBreak( )) return options.getColumnPageBreakInterval( ); else alert ("Page Breaks Not Enabled."); return null; } 652 Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Options getMeasureDirection Syntax string Options.getMeasureDirection( ) Returns the measure direction. Returns Example String. The measure direction. Legal values for measure direction are: ■ DIRECTION_HORIZONTAL ■ DIRECTION_VERTICAL This example retrieves the measure direction: function getMeasureDirection(options){ if (options){ return options.getMeasureDirection( ); } return null; } getRowMirrorStartingLevel Syntax string Options.getRowMirrorStartingLevel( ) Returns the row mirror starting level name. Returns Example String. Row mirror starting level name. This example retrieves the row mirror starting level: function getRowMirrorStart(options){ if (options){ return options.getRowMirrorStartinglevel( ); } return null; } getRowPageBreakInterval Syntax integer Options.getRowPageBreakInterval( ) Returns the row page break interval. Returns Example Integer. The row page break interval. This example retrieves the row page break interval: function getRowPBInterval(options){ if (options){ return options.getRowPageBreakInterval( ); } Chapter 18, BIRT Interactive Crosstabs API classes 653 actuat e.xt abanalyzer .Opti ons return null; } setColumnMirrorStartingLevel Syntax void Options.setColumnMirrorStartingLevel(string levelName) Sets the column mirror starting level name. Parameter levelName String. The column mirror starting level name. Example This example sets the column mirror starting level: function setColumnMirrorLevel(options,level)( if (options){ options.setColumnMirrorStartingLevel(level); } } setColumnPageBreakInterval Syntax void Options.setColumnPageBreakInterval(integer columnPageBreakInterval) Sets the column page break interval. Parameter columnPageBreakInterval Integer. The column page break interval. Example This example sets the column page break interval: function setColumnPBInterval(options,interval)( if (options){ options.setColumnPageBreakInterval(interval); } } setEmptyCellValue Syntax void Options.setEmptyCellValue(string emptyCellValue) Sets the empty cell value. Parameter emptyCellValue String. The empty cell value. Example This example sets the empty cell value: function setEmptyCell(options, cellValue)( if (options){ options.setEmptyCellValue(cellValue); 654 Actuate BIRT Application Developer Guide act uate.xtabanalyzer.Options } } setEnablePageBreak Syntax void Options.setEnablePageBreak(boolean enablePageBreak) Enables or disables page breaks. Parameter enablePageBreak Boolean. Enables page breaks when true. Example This example enables page breaks and sets the row page break interval: function enablesetRowPBInterval(options,interval)( if (options){ options.setEnablePageBreak(true); options.setRowPageBreakInterval(interval); } } setMeasureDirection Syntax void Options.setMeasureDirection(string measureDirection) Sets the measure direction. Parameter measureDirection String. The measure direction. The measure direction. Legal values for measure direction are: Example ■ DIRECTION_HORIZONTAL ■ DIRECTION_VERTICAL This example sets the measure direction: function setMeasureDirection(options,direction){ if (options){ options.setMeasureDirection(direction); } } setRowMirrorStartingLevel Syntax void Options.setRowMirrorStartingLevel(string levelName) Sets the row mirror starting level. Parameter levelName String. Row mirror starting level name. Chapter 18, BIRT Interactive Crosstabs API classes 655 actuat e.xt abanalyzer .Opti ons Example This example sets the row mirror starting level: function setRowMirrorLevel(options,level){ if (options){ options.setRowMirrorStartingLevel(level); } } setRowPageBreakInterval Syntax void Options.setRowPageBreakInterval(integer rowPageBreakInterval) Sets the row page break interval. Parameter rowPageBreakInterval Integer. The row page break interval. Example This example sets the row page break interval: function setRowPBInterval(options,interval)( if (options){ options.setRowPageBreakInterval(interval); } } 656 Actuate BIRT Application Developer Guide act uate. xtabanalyzer.P ageC ontent Class actuate.xtabanalyzer.PageContent Description A container for the content of a cross tab page. It contains a comprehensive list of report elements, such as tables, charts, labels, and data items. Constructor Syntax actuate.xtabanalyzer.PageContent( ) Creates a PageContent object that represents the report content that is generated by a report design file or document file. Function summary Table 18-16 lists actuate.xtabanalyzer.PageContent functions. Table 18-16 actuate.xtabanalyzer.PageContent functions Function Description getCrosstabByBookmark( ) Returns a report cross tab object getViewerId( ) Returns the cross tab viewer ID getCrosstabByBookmark Syntax actuate.xtabanalyzer.crosstab PageContent.getCrosstabByBookmark(string bookmark) Returns a cross tab object associated with a bookmark. Parameter bookmark The bookmark name of the item requested. Returns Example actuate.xtabanalyzer.crosstab object. This example retrieves the viewer ID, then retrieves the cross tab: function getCrosstab( ){ var viewer = PageContent.getViewerId( ); var content = viewer.getCurrentPageContent( ); var crosstab = content.getCrosstabByBookmark( ); return crosstab; } getViewerId Syntax string PageContent.getViewerId( ) Returns the XTabAnalyzer ID. The XTabAnalyzer is the cross tab viewer element. Chapter 18, BIRT Interactive Crosstabs API classes 657 actuat e.xt abanalyzer .P ageC onten t Returns Example String. The XTabAnalyzer ID. This example retrieves the viewer ID, then retrieves the cross tab: function getCrosstab( ){ var viewer = PageContent.getViewerId( ); var content = viewer.getCurrentPageContent( ); var crosstab = content.getCrosstabByBookmark( ); return crosstab; } 658 Actuate BIRT Application Developer Guide actuate.xtabanalyzer.P arameter Value Class actuate.xtabanalyzer.ParameterValue Description A container for the ParameterValue in the xtabanalyzer. Constructor Syntax actuate.xtabanalyzer.ParameterValue(string name, string value, boolean valueIsNull) The ParameterValue class is used to specify a cross tab ParameterValue object. Parameters name String. The parameter name. value String. The parameter value. valueIsNull Boolean. Whether the value is null. Function summary Table 18-17 lists actuate.xtabanalyzer.ParameterValue functions. Table 18-17 actuate.xtabanalyzer.ParameterValue functions Function Description getName( ) Returns the parameter name getValue( ) Returns the parameter value getValueIsNull( ) Returns whether the parameter has a null value setName( ) Sets the parameter name setValue( ) Sets the parameter value setValueIsNull( ) Sets whether the parameter has a null value getName Syntax string ParameterValue.getName( ) Returns the name for the parameter. Returns Example String. The parameter name. This example retrieves the parameter name: function getParameterName(parametervalue){ if (parametervalue){ return parametervalue.getName( ); Chapter 18, BIRT Interactive Crosstabs API classes 659 actuat e.xt abanalyzer .P aramet erV alue } return null; } getValue Syntax String[ ] Dimension.getValue( ) Returns the name for the ParameterValue. Returns Example String or array of strings. The parameter value or values. This example retrieves the parameter value: function getParameterValue(parametervalue){ if (parametervalue){ return parametervalue.getValue( ); } return null; } getValueIsNull Syntax boolean ParameterValue.getValueIsNull( ) Returns whether the parameter value is null. Returns Example Boolean. True indicates the parameter value is null. This example switches whether the parameter value is null: if (parametervalue){ if (parametervalue.getValueIsNull){ parametervalue.setValueIsNull(false); } else { parametervalue.setValueIsNull(true); } } setName Syntax void ParameterValue.setName(string name) Sets the parameter name. Parameter name String. The parameter name. Example 660 This example sets the parameter name: Actuate BIRT Application Developer Guide actuate.xtabanalyzer.P arameter Value function setParameterName(parametervalue, name){ parametervalue.setName(name); } setValue Syntax void ParameterValue.setValue(string[ ] value) Sets the parameter value. Parameter value String. The parameter value. Example This example sets the parameter value: function setParameterValue(parametervalue, value){ parametervalue.setValue(value); } setValueIsNull Syntax void ParameterValue.setValueIsNull(boolean valueIsNull) Sets the valueIsNull for the ParameterValue. Parameter valueIsNull Boolean. True switches the value to null. False disables the null value setting. Example This example switches whether the parameter value is null: if (parametervalue){ if (parametervalue.getValueIsNull){ parametervalue.setValueIsNull(false); } else { parametervalue.setValueIsNull(true); } } Chapter 18, BIRT Interactive Crosstabs API classes 661 actuat e.xt abanalyzer .S ort er Class actuate.xtabanalyzer.Sorter Description Defines a sort condition used to sort on a dimension level or measure. Constructor Syntax actuate.xtabanalyzer.Sorter(string levelName) Constructs a new sorter object. Function summary Table 18-18 lists actuate.xtabanalyzer.Sorter functions. Table 18-18 actuate.xtabanalyzer.Sorter functions Function Description getKey( ) Returns the sort key getLevelName( ) Returns the level name getMember( ) Returns the sort member isAscending( ) Returns the sort direction setAscending( ) Sets ascending or descending sort setKey( ) Sets the sort key setLevelName( ) Sets the level name setMember( ) Sets the sort member getKey Syntax string Sorter.getKey( ) Returns the sort key. This is the name of the measure or dimension level to sort the cross tab on. Returns Example String. The key to sort on. This example retrieves the sort key: function getSortKey(sorter){ if (sorter){ return sorter.getKey( ); } return null; } 662 Actuate BIRT Application Developer Guide actuate.xtabanalyzer.S or ter getLevelName Syntax string Sorter.getLevelName( ) Returns dimension level to sort on. Returns Example String. The name of a dimension level. This example retrieves the level name associated with the sorter: function getSortLevel(sorter){ if (sorter){ return sorter.getLevelName( ); } return null; } getMember Syntax actuate.xtabanalyzer.MemberValue Sorter.getMember( ) Returns the member value to sort on. Returns Example actuate.xtabanalyzer.MemberValue object. A member value. This example retrieves the sort member: function getSortMember(sorter){ if (sorter){ return sorter.getMember( ); } return null; } isAscending Syntax boolean Sorter.isAscending( ) Returns the sort order. Returns Boolean. True when the sorter is ascending and false in all other cases. Example This example retrieves the level name that is associated with the sorter: function ascending(sorter){ if (sorter){ return sorter.isAscending( ); } return null; } Chapter 18, BIRT Interactive Crosstabs API classes 663 actuat e.xt abanalyzer .S ort er setAscending Syntax void Sorter.setAscending(boolean ascending) Sets the sort order to ascending or descending. Parameter ascending Boolean. Set to true for ascending, set to false for descending. Example This example swaps the sort direction: sorter.setAscending(!(sorter.isAscending)); setKey Syntax void Sorter.setSortKey(string sortKey) Sets the key to sort on. Parameter sortKey String. The sort key. Example This example sets the sort key: function setSortKey(sorter,key){ sorter.setKey(key); } setLevelName Syntax void Sorter.setLevelName(string levelName) Sets the dimension level name to sort on. Parameter levelName String. A dimension level name. Example This example sets the level name to sort: function setSortLevel(sorter,level){ sorter.setLevelName(level); } setMember Syntax void Sorter.setMember(actuate.xtabanalyzer.MemberValue member) Sets the member value to sort on. Parameter member actuate.xtabanalyzer.MemberValue object. A member value. Example 664 This example sets the sort member: Actuate BIRT Application Developer Guide actuate.xtabanalyzer.S or ter function setSortMember(sorter,member){ sorter.setMember(member); } Chapter 18, BIRT Interactive Crosstabs API classes 665 actuat e.xt abanalyzer .S ubTot al Class actuate.xtabanalyzer.SubTotal Description A SubTotal object. Constructor Syntax actuate.xtabanalyzer.SubTotal( ) Constructs a new SubTotal object. Function summary Table 18-19 lists actuate.xtabanalyzer.SubTotal functions. Table 18-19 actuate.xtabanalyzer.SubTotal functions Function Description addTotal( ) Add a total getLevelName( ) Returns the full level name getLocation( ) Returns the location getTotals( ) Returns the totals array getType( ) Returns the type string setLevelName( ) Sets the full level name setLocation( ) Sets the location setTotals( ) Sets the totals array addTotal Syntax void SubTotal.addTotal(actuate.xtabanalyzer.Total total) Adds a total to the subtotal. Parameter total actuate.xtabanalyzer.Total. The total object being added. Example This example uses addTotal( ) to create a subtotal: function addSubTotal( ){ var subTotal = new actuate.xtabanalyzer.SubTotal( ); subTotal.setLevelName("year"); subTotal.setLocation("after"); var indexStr = "0;1;2;3;4"; var indexs = indexsStr.split(";"); var measureIndexs = [ ]; for(var i = 0;i < indexs.length;i++){ 666 Actuate BIRT Application Developer Guide actuate.xtabanalyzer.SubTotal measureIndexs.push(parseInt(indexs[i])); } for( var i = 0; i < measureIndexs.length; i++){ var total = new actuate.xtabanalyzer.Total( ); total.setMeasureIndex(measureIndexs[i]); total.setAggregationFunction("SUM"); total.setEnabled(true); subTotal.addTotal(total); } crosstab.setTotals(null,subTotal); crosstab.submit( ); } getLevelName Syntax string SubTotal.getLevelName( ) Returns the level for the subtotal. Returns Example String. The level name for the subtotal. This example retrieves the level name from the subtotal: function getLevelName(subTotal){ if (subTotal){ return subTotal.getLevelName( ); } return null; } getLocation Syntax string SubTotal.getLocation( ) Returns the location name for the subtotal. Returns Example String. The location name. This example retrieves the level name from the subtotal: function getLocation(subTotal){ if (subTotal){ return subTotal.getLocation( ); } return null; } getTotals Syntax object[ ] SubTotal.getTotals( ) Chapter 18, BIRT Interactive Crosstabs API classes 667 actuat e.xt abanalyzer .S ubTot al Returns the totals used to calculate the subtotal. Returns Example actuate.xtabanalyzer.Total[ ]. An array of total objects. This example retrieves the totals from a SubTotal object: var totalsArray = [ ]; function getTotals(subTotal,totalsArray){ totalsArray = subTotal.getTotals( ); } getType Syntax string SubTotal.getType( ) Returns the type for the subtotal. Returns Example String. The type for the subtotal. This example retrieves the type from the subtotal: function getLevelName(subTotal){ if (subTotal){ return subTotal.getType( ); } return null; } setLevelName Syntax void SubTotal.setLevelName(string levelName) Sets the level for the subtotal by name. Parameter levelName String. The level name. Example This example sets the level name for a subtotal: function subTotalLevel(subTotal,levelName){ if(subTotal){ subTotal.setLevelName(levelName); } } setLocation Syntax void SubTotal.setLocation(string location) Sets the location for the subtotal. Parameter location String. The location. Value can be either before or after. 668 Actuate BIRT Application Developer Guide actuate.xtabanalyzer.SubTotal Example This example sets the location for a subtotal: function subTotalLocation(subTotal,location){ if(subTotal){ subTotal.setLocation(location); } } setTotals Syntax void SubTotal.setTotals(actuate.xtabanalyzer.Total[ ] totals) Sets the totals using an array. Parameter totals Array of actuate.xtabanalyzer.Total objects to add to the subtotal. Example This example uses setTotals( ) to create a subtotal: function addSubTotal( ){ var subTotal = new actuate.xtabanalyzer.SubTotal( ); subTotal.setLevelName("year"); subTotal.setLocation("after"); var indexStr = "0;1;2;3;4"; var indexs = indexsStr.split(";"); var count = indexs.length; var measureIndexs = [ ]; for(var i = 0;i < count;i++){ measureIndexs.push(parseInt(indexs[i])); } var totals = Array(count); for( var i = 0; i < measureIndexs.length; i++){ var total = new actuate.xtabanalyzer.Total( ); total.setMeasureIndex( measureIndexs[i] ); total.setAggregationFunction( "SUM" ); total.setEnabled(true); totals[i] = total; } subTotal.setTotals(totals); crosstab.setTotals( null, subTotal ); crosstab.submit( ); } Chapter 18, BIRT Interactive Crosstabs API classes 669 actuat e.xt abanalyzer .To tal Class actuate.xtabanalyzer.Total Description A container for a total in the xtabanalyzer. Total handles numeric aggregation functions for a measure. Constructor Syntax actuate.xtabanalyzer.Total( ) The Total class is used to specify a cross tab total object. Function summary Table 18-20 lists actuate.xtabanalyzer.Total functions. Table 18-20 actuate.xtabanalyzer.Total functions Function Description getAggregationFunction( ) Returns the aggregation function name getMeasureIndex( ) Returns the measure index isEnabled( ) Returns whether or not the total is enabled setAggregationFunction( ) Sets the aggregation function name setEnabled( ) Sets the enabled flag setMeasureIndex( ) Sets the index for the total getAggregationFunction Syntax string Total.getAggregationFunction( ) Returns the aggregation function for the total. Returns Example String. An aggregation function. This example changes the aggregation function: function swapTotalAggregation(total){ if (total.getAggregationFunction( ) == "SUM"){ total.setAggregationFunction("COUNT"); } else { total.setAggregationFunction("SUM"); } } 670 Actuate BIRT Application Developer Guide actuate.xtabanalyzer.Total getMeasureIndex Syntax integer Dimension.getMeasureIndex( ) Retrieves the measure index for the total. Returns Example Integer. The measure index. This example retrieves the measure index: function getMeasureIndex(total){ if (total){ return total.getIndex( ); } return null; } isEnabled Syntax boolean Total.isEnabled( ) Returns whether the total is enabled. Returns Example Boolean. True indicates this total is enabled. This example enables and disables a total: if (total){ if (total.isEnabled){ total.setEnabled(false); } else { total.setEnabled(true); } } setAggregationFunction Syntax void Total.setAggregationFunction(string aggregationFunction) Sets the aggregation function name. Parameter aggregationFunction String. The aggregation function name. Example This example changes the aggregation function: function swapTotalAggregation(total){ if (total.getAggregationFunction( ) == "SUM"){ total.setAggregationFunction("COUNT"); } else { total.setAggregationFunction("SUM"); Chapter 18, BIRT Interactive Crosstabs API classes 671 actuat e.xt abanalyzer .To tal } } setEnabled Syntax void Total.setEnabled(boolean enabled) Sets whether total is enabled or disabled. Parameter enabled Boolean. True if the total is enabled. False for disabled. Example This example enables and disables a total: if (total){ if (total.isEnabled){ total.setEnabled(false); } else { total.setEnabled(true); } } setMeasureIndex Syntax void Total.setMeasureIndex(integer measureIndex) Sets the measure index for the total. Parameter measureIndex Integer. The measure index for the total. Example This example uses setMeasureIndex( ) to create a subtotal: function addSubTotal( ){ var subTotal = new actuate.xtabanalyzer.SubTotal( ); subTotal.setLevelName("year"); subTotal.setLocation("after"); var indexStr = "0;1;2;3;4"; var indexs = indexsStr.split(";"); var count = indexs.length; var measureIndexs = []; for(var i = 0;i < count;i++){ measureIndexs.push(parseInt(indexs[i])); } for( var i = 0; i < measureIndexs.length; i++) { var total = new actuate.xtabanalyzer.Total( ); total.setMeasureIndex(measureIndexs[i]); total.setAggregationFunction("SUM"); total.setEnabled(true); subTotal.addTotal(total); 672 Actuate BIRT Application Developer Guide actuate.xtabanalyzer.Total } crosstab.setTotals(null,subTotal); crosstab.submit( ); } Chapter 18, BIRT Interactive Crosstabs API classes 673 actuat e.xt abanalyzer .U IOptio ns Class actuate.xtabanalyzer.UIOptions Description Specifies feature availability for the Interactive Crosstabs viewer. Constructor Syntax void actuate.xtabanalyzer.UIOptions( ) Generates a new UIOptions object to manage the features of the xtabanalyzer. Function summary Table 18-21 lists actuate.xtabanalyzer.UIOptions functions. Table 18-21 actuate.xtabanalyzer.UIOptions functions Function Description enableCrosstabView( ) Enables the cross tab layout view feature enableCubeView( ) Enables the cube view feature enableFilterSummaryView( ) Enables the filter summary view enableToolBar( ) Enables the toolbar feature enableToolbarHelp( ) Enables the toolbar help feature enableToolbarSave( ) Enables the toolbar save feature enableToolbarSaveDesign( ) Enables the toolbar save design feature enableToolbarSaveDocument( ) Enables the toolbar save document feature getFeatureMap( ) Returns a list of enabled and disabled features enableCrosstabView Syntax void UIOptions.enableCrosstabView(boolean enabled) Enables or disables the cross tab layout view. Parameter enabled Boolean. True enables this option. Example This example enables or disables the cross tab view: function setCrosstabView(flag){ var uiOptions = new actuate.xtabanalyzer.UIOptions( ); uiOptions.enableCrosstabView(flag); myXTabAnalyzer.setUIOptions(uiOptions); } 674 Actuate BIRT Application Developer Guide actuate. xtabanalyzer.U IOptions enableCubeView Syntax void UIOptions.enableCubeView(boolean enabled) Enables or disables the cube view. Parameter enabled Boolean. A value of true enables this option. Example This example enables or disables the cube view: function setCubeView(flag){ var uiOptions = new actuate.xtabanalyzer.UIOptions( ); uiOptions.enableCubeView(flag); myXTabAnalyzer.setUIOptions(uiOptions); } enableFilterSummaryView Syntax void UIOptions.enableFilterSummaryView(boolean enabled) Enables or disables the filter summary view. Parameter enabled Boolean. A value of true enables this option. Example This example enables or disables the filter summary view: function setFilterSummary(flag) { var uiOptions = new actuate.xtabanalyzer.UIOptions( ); uiOptions.enableFilterSummaryView(enabled); myXTabAnalyzer.setUIOptions(uiOptions); } enableToolBar Syntax void UIOptions.enableToolBar(boolean enabled) Enables or disables the toolbar feature. Parameter enabled Boolean. A value of true enables this option. Example This example enables or disables the toolbar: function setToolbar(flag){ var uiOptions = new actuate.xtabanalyzer.UIOptions( ); uiOptions.enableToolBar(flag); myXTabAnalyzer.setUIOptions(uiOptions); } Chapter 18, BIRT Interactive Crosstabs API classes 675 actuat e.xt abanalyzer .U IOptio ns enableToolbarHelp Syntax void UIOptions.enableToolbarHelp(boolean enabled) Enables or disables the toolbar help feature. Parameter enabled Boolean. A value of true enables this option. Example This example enables or disables toolbar help: function setToolbarHelp(flag){ var uiOptions = new actuate.xtabanalyzer.UIOptions( ); uiOptions.enableToolbarHelp(flag); myXTabAnalyzer.setUIOptions(uiOptions); } enableToolbarSave Syntax void UIOptions.enableToolbarSave(boolean enabled) Enables or disables the toolbar save feature. Parameter enabled Boolean. A value of true enables this option. Example This example enables or disables toolbar save: function setToolbarSave(flag){ var uiOptions = new actuate.xtabanalyzer.UIOptions( ); uiOptions.enableToolbarSave(flag); myXTabAnalyzer.setUIOptions(uiOptions); } enableToolbarSaveDesign Syntax void UIOptions.enableToolbarSaveDesign(boolean enabled) Enables or disables the toolbar save design feature. Parameter enabled Boolean. A value of true enables this option. Example This example enables or disables toolbar save design: function setToolbarSave(flag){ var uiOptions = new actuate.xtabanalyzer.UIOptions( ); uiOptions.enableToolbarSaveDesign(flag); myXTabAnalyzer.setUIOptions(uiOptions); } 676 Actuate BIRT Application Developer Guide actuate. xtabanalyzer.U IOptions enableToolbarSaveDocument Syntax void UIOptions.enableToolbarSaveDocument(boolean enabled) Enables or disables the toolbar save document feature. Parameter enabled Boolean. A value of true enables this option. Example This example enables or disables toolbar save document: function setToolbarSave(flag){ var uiOptions = new actuate.xtabanalyzer.UIOptions( ); uiOptions.enableToolbarSaveDocument(flag); myXTabAnalyzer.setUIOptions(uiOptions); } getFeatureMap Syntax Object UIOptions.getFeatureMap( ) Returns the features and their Boolean values as an associative array. This function makes the name of each feature an object property and sets the value of that property to the associated enabled Boolean value. Returns Example Object. An associative array of string name and Boolean value pairs. This example retrieves the feature map: function retrieveFeatureMap( ){ var uiOptions = new actuate.xtabanalyzer.UIOptions( ); var features = uiOptions.getFeatureMap( ); return features; } Chapter 18, BIRT Interactive Crosstabs API classes 677 actuat e.xt abanalyzer .U IOptio ns 678 Actuate BIRT Application Developer Guide Part Six 6 Deploying applications Part 6 Chapter 19 Deploying and sharing applications Chapter 19 This chapter contains the following topics: ■ About deploying and sharing applications and files ■ Editing the landing page ■ Sharing applications ■ Sharing project files ■ Publishing a resource file to iHub ■ Downloading files ■ Managing permissions ■ Deploying Java classes used in BIRT reports ■ Installing a custom JDBC driver ■ Installing custom ODA drivers and custom plug-ins Chapter 19, Deploying and sharing applications 681 About deploying and sharing applications and files This chapter describes how to export and publish BIRT applications in the Actuate business reporting system. You can also download files from an iHub server to use in a BIRT application. The purpose of publishing a BIRT application to iHub is to make it accessible to a large number of users. A published application is available to manage. For example, you can schedule running a report to include updates from the data sources. You can also use permissions to control access to the application. To publish BIRT applications, you need to understand the environment in which the reports run. BIRT iHub provides a central location from which business users can access, run, and view reports. You can also use Actuate BIRT Visualization Platform to run report executables, and to manage, generate, view, and print report documents. BIRT Designer Professional, the tool that you use to develop BIRT applications, has built-in capabilities that facilitate the deployment process. The BIRT Designer Professional integrates with iHub in several important ways to support performing the following tasks: ■ Use an open data access (ODA) information object data source that resides on a volume. ■ Publish a BIRT application and its components to a volume. ■ Publish a resource to a volume. ■ Install a custom JDBC driver for use by BIRT reports running in the iHub environment. BIRT Designer Professional connects directly to an iHub server and deploys the files to selected iHub folders. The designer provides a Server Explorer view for managing iHub connections. Using Server Explorer, you can create connection profiles to store the connection properties to a specific Encyclopedia volume. Figure 19-1 shows Server Explorer displaying a server profile. Figure 19-1 682 Server Explorer view Actuate BIRT Application Developer Guide How to create a new server profile 1 In BIRT Designer Professional, open Server Explorer. If you do not see the Server Explorer view in the designer, select Windows➛Show view ➛Server Explorer. 2 In Server Explorer, right-click Servers, and choose New Server Profile. 3 In New Server Profile, specify the connection information. Figure 19-2 displays an example of connection properties provided for a server named Athena. Figure 19-2 Setting properties in a new Server profile 1 In Profile type, select Server. 2 In Profile name, type a unique name that identifies the new profile. 3 In Server, type the name or IP address of the iHub server. 4 In Port number, type the port number to access iHub. 5 In Volume, select the iHub Encyclopedia volume if multiple volumes exist. 6 In User name, type the user name required to access the volume. 7 In Password, type the password required to access the volume. 8 Select Remember Password, if you want to save the password. 4 Choose Finish to save the Server profile. The Server profile appears in the Server Explorer. Chapter 19, Deploying and sharing applications 683 Editing the landing page Each BIRT application has an HTML landing page that is accessible from a web browser. You can use this page to include additional content for your application such as a description of the application, online help, and HTML links to the contents of the application. You can run a project as a BIRT application to test how the application responds when published. How to edit the application landing page While you can put any HTML code into the landing page, this example adds a link to a dashboard and a report file in the BIRT application. To edit the landing page using BIRT Designer Professional, complete the following steps: 1 Use Navigator to right-click the index.html file in the BIRT project, as shown in Figure 19-3. Figure 19-3 Selecting the landing page 2 Choose Open With➛HTML Editor, as shown in Figure 19-4. Figure 19-4 Opening the landing page in the HTML editor 3 In the HTML editor type the following text on the second line of the landing page: Sales dashboard 6 Add another line to the landing page and type the text:
First quarter sales report 9 Choose File➛Save to save your changes to the landing page. Chapter 19, Deploying and sharing applications 685 How to run a project as a BIRT application To test how a BIRT application runs using BIRT Designer Professional, complete the following steps: 1 Right-click the BIRT project that you want to deploy as a BIRT application in Navigator, as shown in Figure 19-8. Figure 19-8 Selecting a BIRT project to test 2 Choose Run As➛BIRT Application, as shown in Figure 19-9. Figure 19-9 Running a project as a BIRT application If prompted to save any unsaved resources, choose OK. 3 In Device Chooser, select the local browser device and choose OK, as shown in Figure 19-10. Figure 19-10 Selecting the default viewer The landing page of the BIRT application appears in a local browser. Edit the landing page file in BIRT Designer Professional to display links to files in the BIRT application, as shown in Figure 19-11. Figure 19-11 686 Displaying the BIRT application landing page Actuate BIRT Application Developer Guide Sharing applications To share a BIRT application you either publish a BIRT project to an iHub or archive it to send to another person as a file. BIRT applications contain all resources necessary to display BIRT dashboards and documents included in the application. When a BIRT application is published to an iHub server, other users can access the application and its contents using URL addresses. When a BIRT application is exported to an archive file, you can send it to another developer who loads the archive into their BIRT Designer Professional to edit and preview the application. How to publish a BIRT application To publish a project as a BIRT application to an iHub server, complete the following steps: 1 Select the BIRT project that you want to deploy as a BIRT application in Navigator, as shown in Figure 19-12. Figure 19-12 Selecting a BIRT project to publish as an application 2 Choose File➛Publish. 3 In Publish, select Publish Project if it is not already selected. 4 Select a server profile and choose Publish. Figure 19-13 shows the BIRT application named BIRT Project set to publish to the server profile Athena. Figure 19-13 Selecting a server profile to publish to Chapter 19, Deploying and sharing applications 687 5 After all items have been published, choose OK. Figure 19-14 shows that all files were successfully published. Figure 19-14 Verifying all items were published 6 Choose Close to return to BIRT Designer Professional. 7 Verify that the application is accessible by using a web browser to visit the URL of the application. For example, if the server name was Athena, then the URL to the application is the following: http://athena:8700/iportal/apps/BIRT Project/ For more information about URL access to BIRT application content, see “Accessing BIRT application content” in Chapter 1, “Planning a BIRT application.” How to export a BIRT application To archive a BIRT application, export the entire BIRT project that contains the BIRT application as an archive file. This retains the file structure and packages all files into a .zip archive file. 1 Select the BIRT project that contains the BIRT application in Navigator, as shown in Figure 19-15. Figure 19-15 Selecting a BIRT project to export 2 Choose File➛Export. 3 In Export, select General➛Archive File. Choose Next, as shown in Figure 19-16. 688 Actuate BIRT Application Developer Guide Figure 19-16 Selecting a method to export the BIRT project 4 Verify that the correct project is selected. Choose Browse. 5 In Export to archive file, select a file name and location for the project archive. Choose Save when you are finished. 6 Verify that the options are set for the file format and directory structure of the project archive. Choose Finish, as shown in Figure 19-17. Figure 19-17 Exporting the BIRT project as a .zip compressed file Chapter 19, Deploying and sharing applications 689 Sharing project files You can publish project files to locations on the iHub server such as a user folder or a folder for a specific department. You can also update selected files in a published BIRT application, such as dashboards, libraries, reports, and templates. How to publish a file to iHub To publish a file, such as a dashboard or report design, to an iHub server, complete the following steps: 1 Select the file in the BIRT project that you want to deploy in Navigator. Figure 19-18 shows the selection of a report design in the BIRT Project folder. Figure 19-18 Selecting a file to publish 2 Choose File➛Publish. 3 In Publish, select Publish Files if it is not already selected. 4 Select a server profile. If there is no appropriate profile in the iHub profile list, create a new profile by choosing Add. 5 Select Publish Files. 6 In Destination, type or browse for the location on the volume in which to publish the file, as shown in Figure 19-19. 7 Choose Publish. A window showing the file upload status appears. In Publishing, wait until the upload finishes, then choose OK, as shown in Figure 19-20. 8 In Publish, choose Close. 690 Actuate BIRT Application Developer Guide Figure 19-19 Selecting a server and location Figure 19-20 Confirming the report publishing Publishing a resource file to iHub BIRT dashboards and reports frequently use files with additional information to present report data to the users. A BIRT resource is any of the following items: ■ Static image that a BIRT report design uses ■ Report library ■ Properties file Chapter 19, Deploying and sharing applications 691 ■ Report template ■ Data object ■ CSS file ■ External JavaScript file ■ SWF file of a Flash object ■ Java event handler class packaged as a Java archive (JAR) file The location of resource files in the iHub’s volume depends on how the resources are used. Table 19-1 shows these locations. Table 19-1 Resource file locations Resource usage Publish method Location in iHub volume Used in a BIRT application Publish Project Same application folder Not used in a BIRT application Publish Resources Volume resource folder A BIRT application can only use resources in its own application folder. For example, a dashboard in a BIRT application cannot use data objects stored in the central resource folder of an iHub’s volume because that folder is outside the application folder. Files that are not in a BIRT application, such as reports and dashboards in a user’s home folder, use a single, shared resource folder in the volume. You can publish BIRT resources from the BIRT Designer Professional’s local resource folder to an iHub server. By default, the local resource folder is the current report project folder. If you use shared resources with other developers and the resource files for your reports are stored in a different folder, you can change the default Resource folder used in your project. Use the Window— Preferences—Actuate BIRT—Resource menu to set the resource folder. In the volume, the Resource folder is set to /Resources by default. How to publish a local resource to an iHub resource folder To publish a resource, such as a data object or report library, to an iHub server, complete the following steps: 1 Choose File➛Publish. 2 In Publish, select Publish Files if it is not already selected. 3 In Project, select the BIRT project where the local resources are located. 4 Select a server profile. If there is no appropriate profile in the iHub profile list, create a new profile by choosing Add. 5 Select Publish Resources. 692 Actuate BIRT Application Developer Guide 6 In Publish Resources, select the resources that you want to publish, as shown in Figure 19-21. Figure 19-21 Selecting a resource 7 Choose Publish. A window showing the file upload status appears. In Publishing, wait until the upload finishes, then choose OK, as shown in Figure 19-22. Figure 19-22 Confirming the resource publishing 8 In Publish, choose Close. Chapter 19, Deploying and sharing applications 693 Downloading files You can use published BIRT files such as dashboards, reports and data objects in BIRT applications by downloading these files from an iHub server. After downloading the file into your BIRT project, you can edit it using the tools of BIRT Designer Professional. If the file uses a data object, you must also download the data object into the BIRT application and put it in the same location in the BIRT application. For example, a dashboard gadget displays data from a data design file named Sales.datadesign. This file is located in the iHub’s volume, inside a folder named Resources. In the BIRT application, you make a folder named Resources and copy the Sales.datadesign file into that folder. Now that the gadget and data source files are in the correct locations, you can make dashboards in the BIRT application that use the gadget file. Resources are downloaded to the root of the BIRT application. You can change this location in the BIRT Designer Professional preferences. How to download a file from an iHub server To download a file, such as a dashboard gadget file, to an iHub server, complete the following steps: 1 In Navigator, select the BIRT project that you want to receive the dashboard gadget, as shown in Figure 19-23. Figure 19-23 Selecting a BIRT project to receive a file 2 Choose File➛Download. 3 Select a server profile. 4 Select Download file. 5 In Download Location, type or browse for the location in the BIRT project folder in which to download the file. 6 In the server tree, select the files on the volume to copy to the local download location. Figure 19-24 shows a dashboard gadget selected for download to the dashboard folder of a local BIRT project. 694 Actuate BIRT Application Developer Guide Figure 19-24 Selecting a file to download into a BIRT application 7 Choose Download. How to change the location of downloaded resource files 1 Choose Window➛Preferences➛Actuate BIRT➛Resource. 2 In Resource Folder, type the default location to store resource files. For example, change to /Resources to download all resources in the project to a folder named Resources. 3 Choose OK. Managing permissions You can set user permissions based on user roles to manage access to a BIRT application. These permissions are stored in the BIRTApplication.xml file in the BIRT application. The user roles are the BIRT iHub Visualization Platform user groups. Table 19-2 lists and describes all supported permissions and the task that each permission allows a user to perform. Chapter 19, Deploying and sharing applications 695 Table 19-2 Permission and allowed tasks for a BIRT application Permission Symbol Allowed task Delete D Delete the folder or file. Execute E Run a design, dashboard, or executable file. Only an administrator can set this privilege. The Execute privilege does not apply to folders or document files. Grant G Change privileges for a file or folder. An administrator has Grant privileges on all files and folders by default. Read R View and print a report. Privilege to view the contents of a folder. Requires the Visible permission. Secure read S View and print only restricted parts of a document. Visible V See a folder or a file in a list. Write W Modify a file or the contents of a folder. For information about how an administrator manages user privileges and permissions on a volume, see Managing Volumes and Users. Check with your iHub administrator for the user group names used on your iHub server and for the default permissions of the applications folder on the iHub volume. For example, if your iHub administrator has hidden the Application folder where all BIRT applications are stored, you must grant the Read permission to a user role for the BIRT application URL to function. After a BIRT application is published to an iHub server, you can change the permissions of each file in the BIRT application. Permissions are overwritten each time you publish a BIRT application. For example, after publishing an application to an iHub server, you remove the Read permissions on a BIRT data object so that users cannot download the data object file. Each time that you publish the BIRT application, you must again change the permissions on the iHub server. How to add permissions to a BIRT application 1 Using Navigator, right-click the BIRTApplication.xml file in the BIRT project that you want to deploy, as shown in Figure 19-25. Figure 19-25 696 Selecting the BIRT application file Actuate BIRT Application Developer Guide 2 Choose File➛Open. 3 In Permissions, choose Add, as shown in Figure 19-26. Figure 19-26 Adding a user group permission to a BIRT application 4 Type the name of a user role. Select the permissions to apply to the user role. In this example, the user role All is given the Read and the Execute permissions, as shown in Figure 19-27. Figure 19-27 Assigning permissions to a user group Choose OK. 5 To add additional permissions, return to step 3. 6 Choose File➛Save. The next time you publish this BIRT application to an iHub server, these permissions become active. Deploying Java classes used in BIRT reports A BIRT report uses scripts to implement custom functionality. For example, you can use scripts to create a scripted data set or to provide custom processing for a report element. When you deploy a BIRT report to a volume, you must provide Chapter 19, Deploying and sharing applications 697 iHub with access to the Java classes that the scripts reference. You package these classes as JAR files so an iHub Java factory process can recognize and process them. There are two ways to deploy Java classes: ■ Deploy the JAR files to the volume. This method supports creating specific implementations for each volume in iHub. This method of deployment requires packaging the Java classes as a JAR file and attaching the JAR file as a resource to the report design file. You treat a JAR file as a resource in the same way as a library or image. Using this method, you publish the JAR file to iHub every time you make a change in the Java classes. ■ Deploy the JAR files to the following iHub subdirectory: $ACTUATE_HOME\iHub\resources This method uses the same implementation for all volumes in iHub. Actuate does not recommend deploying JAR files to an iHub /resources folder because you must restart the iHub after deploying the JAR file. Another disadvantage of this deployment technique is that the JAR file, deployed in the iHub /resources directory, is shared across all volumes, which can cause conflicts if you need to have different implementations for different volumes. When using this method, you do not have to add the JAR file to the report design’s Resource property. iHub uses Java 1.6 compliance settings by default. A Java event handler deployed to iHub requires the same of lower level of Java compliance in the compiled class file. How to configure BIRT to use a compliance level of Java 1.6 in an event handler 1 Open the Java event handler in BIRT Designer Professional. 2 Choose Window➛Preferences. 3 In Preferences, in the navigation tree, expand Java and select Compiler. 4 In Compiler, in JDK Compliance, in compiler compliance level, select 1.6, as shown in Figure 19-28. Choose OK. 5 Recompile the event handler classes. How to configure BIRT reports and deploy a JAR file to a volume 1 Package the Java classes as a JAR file and copy the JAR file to the BIRT Designer Professional resource folder. 2 Open the report design in BIRT Designer Professional. 698 Actuate BIRT Application Developer Guide Figure 19-28 Setting the Java compiler compliance level 3 In Outline, select the root report design slot. Select the Resources property group in the Property Editor window. 4 In Resources, in JAR files, choose Add, and navigate through the Resource folder to select the JAR file, as shown in Figure 19-29. When the report executes, the engine searches for the required classes and methods only in this JAR file. How to deploy a JAR file to an iHub /resources folder 1 Copy the JAR file to the following iHub subdirectory: $ACTUATE_HOME\iHub\resources $ACTUATE_HOME is the folder where Actuate products install. 2 Publish the report to iHub, as described in “Sharing applications,” earlier in this chapter. 3 Restart iHub. 4 Run the report from BIRT iHub Visualization Platform. Chapter 19, Deploying and sharing applications 699 Figure 19-29 Add JAR file as a resource to a report Installing a custom JDBC driver In order to run a BIRT application in the iHub environment when the BIRT application uses a custom JDBC driver, you must install the JDBC driver in the following location: $ACTUATE_HOME\iHub\Jar\BIRT\platform\plugins \org.eclipse.birt.report.data.oda.jdbc_\drivers Installing custom ODA drivers and custom plug-ins BIRT Designer Professional loads plug-ins from the following folder: \BDPro\eclipse\plugins BIRT iHub and BIRT Visualization Platform load custom plug-ins from the following folder: $ACTUATE_HOME\iHub\MyClasses\eclipse\plugins 700 Actuate BIRT Application Developer Guide BIRT iHub and BIRT Visualization Platform load custom ODA drivers from the following folder: $ACTUATE_HOME\iHub\oda\eclipse\plugins Install all custom ODA drivers and custom plug-ins in the folder corresponding to your Actuate product If your application uses a different location to store custom plug-ins, you must set this location in a link file for each Actuate product. Actuate products use link files to locate the folder where the custom drivers or plug-ins are deployed. The name of the link files are customODA.link and customPlugins.link. Use the customODA.link file to store the path for custom ODA drivers, and use the customPlugins.link file for all plug-ins used by BIRT reports and the BIRT engine, such as custom emitters, or Flash object library plug-ins. For example, if you store custom plug-ins at C:\BIRT\MyPlugins\eclipse\plugins, then the contents of the customPlugins.link file is the following: path=C:/BIRT/MyPlugins Link files are typically stored in a \links subfolder of the Eclipse instance of the product. Create the links folder if it does not exist. For example, if BIRT Designer Professional for Windows is stored in the root of the C: drive, it looks for link files in the following location: C:\BDPro\eclipse\links The locations of the link files for each Actuate product are listed in Table 19-3. After adding the link file to your Actuate product, deploy the plug-ins to the new location described in the link file. Table 19-3 Locations to store .link files Product Paths to store .link files BIRT Designer Professional Windows \BDPro\eclipse\links BIRT Designer Professional Mac OS X \BRDPro\eclipse\links BIRT iHub $ACTUATE_HOME\iHub\Jar\BIRT\platform\links Chapter 19, Deploying and sharing applications 701 702 Actuate BIRT Application Developer Guide Chapter 20 Working with BIRT encryption in iHub Chapter 20 This chapter contains the following topics: ■ About BIRT encryption ■ About the BIRT default encryption plug-in ■ Creating a BIRT report that uses the default encryption ■ Deploying multiple encryption plug-ins ■ Deploying encryption plug-ins to iHub ■ Generating encryption keys ■ Creating a custom encryption plug-in ■ Using encryption API methods Chapter 20, Working with BIRT encr yption in iHub 701 About BIRT encryption BIRT provides an extension framework to support users registering their own encryption strategy with BIRT. The model implements the Java™ Cryptography Extension (JCE). The Java encryption extension framework provides multiple popular encryption algorithms, so the user can just specify the algorithm and key to have a high security level encryption. The default encryption extension plug-in supports customizing the encryption implementation by copying the BIRT default plug-in, and giving it different key and algorithm settings. JCE provides a framework and implementations for encryption, key generation and key agreement, and message authentication code (MAC) algorithms. Support for encryption includes symmetric, asymmetric, block, and stream ciphers. The software also supports secure streams and sealed objects. A conventional encryption scheme has the following five major parts: ■ Plaintext, the text to which an algorithm is applied. ■ Encryption algorithm, the mathematical operations to conduct substitutions on and transformations to the plaintext. A block cipher is an algorithm that operates on plaintext in groups of bits, called blocks. ■ Secret key, the input for the algorithm that dictates the encrypted outcome. ■ Ciphertext, the encrypted or scrambled content produced by applying the algorithm to the plaintext using the secret key. ■ Decryption algorithm, the encryption algorithm in reverse, using the ciphertext and the secret key to derive the plaintext content. About the BIRT default encryption plug-in BIRT’s default encryption algorithm is implemented as a plug-in named: com.actuate.birt.model.defaultsecurity_ Table 20-1 shows the location of this plug-in folder in the supported BIRT environments. Table 20-1 702 Locations of the default encryption plug-in folder Environment Font configuration file folder location BIRT Designer Professional $BDPro\eclipse\plugins iHub $iHub\modules\BIRTiHub\iHub\Jar\BIRT \platform\plugins Actuate BIRT Application Developer Guide About supported encryption algorithms Two different cryptographic methods, private-key and public-key encryptions, solve computer security problems. Private-key encryption is also known as symmetric encryption. In private-key encryption, the sender and receiver of information share a key that is used for both encryption and decryption. In public-key encryption, two different mathematically related keys, known as a key pair, are used to encrypt and decrypt data. Information encrypted using one key can only be decrypted by using the other member of the key pair. The BIRT default encryption plug-in supports the following algorithms within these two methods: ■ ■ Private-key encryption ■ DES is the Digital Encryption Standard as described in FIPS PUB 46-2 at http://www.itl.nist.gov/fipspubs/fip46-2.htm. The DES algorithm is the most widely used encryption algorithm in the world. This algorithm is the default encryption that BIRT uses. ■ DESede, triple DES encryption Triple-DES or DESede is an improvement over DES. This algorithm uses three DES keys: k1, k2, and k3. A message is encrypted using k1 first, then decrypted using k2, and encrypted again using k3. This technique is called DESencryptiondecryptionencryption. Two or three keys can be used in DESede. This algorithm increases security as the key length effectively increases from 56 to 112 or 168. Public-key encryption supports the RSA algorithm RSA uses both a public key and a private key. The public key can be known to everyone and is used for encrypting messages. Messages encrypted with the public key can only be decrypted using the private key. About the components of the BIRT default encryption plug-in The BIRT default encryption plug-in consists of the following main modules: ■ acdefaultsecurity.jar ■ encryption.properties file ■ META-INF/MANIFEST.MF ■ plugin.xml About acdefaultsecurity.jar This JAR file contains the encryption classes. The default encryption plug-in also provides key generator classes that can be used to create different encryption keys. Chapter 20, Working with BIRT encr yption in iHub 703 About encryption.properties This file specifies the encryption settings. BIRT loads the encryption type, encryption algorithm, and encryption keys from the encryption.properties file to do the encryption. The file contains pre-generated default keys for each of the supported algorithms. You define the following properties in the encryption.properties file: ■ Encryption type Type of algorithm. Specify one of the two values, symmetric encryption or public encryption. The default type is symmetric encryption. ■ Encryption algorithm The name of the algorithm. You must specify the correct encryption type for each algorithm. For the symmetric encryption type, BIRT supports DES and DESede. For public encryption type, BIRT supports RSA. ■ Encryption mode In cryptography, a block cipher algorithm operates on blocks of fixed length, which are typically 64 or 128 bits. Because messages can be of any length, and because encrypting the same plaintext with the same key always produces the same output, block ciphers support several modes of operation to provide confidentiality for messages of arbitrary length. Table 20-2 shows all supported modes. Table 20-2 ■ 704 Supported encryption modes Mode Description None No mode CBC Cipher Block Chaining Mode, as defined in the National Institute of Standards and Technology (NIST) Federal Information Processing Standard (FIPS) PUB 81, “DES Modes of Operation,” U.S. Department of Commerce, Dec 1980 CFB Cipher Feedback Mode, as defined in FIPS PUB 81 ECB Electronic Codebook Mode, as defined in FIPS PUB 81 OFB Output Feedback Mode, as defined in FIPS PUB 81 PCBC Propagating Cipher Block Chaining Encryption padding Because a block cipher works on units of a fixed size, but messages come in a variety of lengths, some modes, for example CBC, require that the final block be padded before encryption. Several padding schemes exist. The supported Actuate BIRT Application Developer Guide paddings are shown in Table 20-3. All padding settings are applicable to all algorithms. Table 20-3 ■ Supported encryption paddings Mode Description NoPadding No padding. OAEP Optimal Asymmetric Encryption Padding (OAEP) is a padding scheme that is often used with RSA encryption. PKCS5Padding The padding scheme described in RSA Laboratories, “PKCS #5: Password-Based Encryption Standard,” version 1.5, November 1993. This encryption padding is the default. SSL3Padding The padding scheme defined in the SSL Protocol Version 3.0, November 18, 1996, section 5.2.3.2. Encryption keys Actuate provides pre-generated keys for all algorithms. Listing 20-1 shows the default contents of encryption.properties. Listing 20-1 Default encryption.properties #message symmetric encryption , public encryption. type=symmetric encryption #private encryption: DES(default), DESede #public encryption: RSA algorithm=DES # NONE , CBC , CFB , ECB( default ) , OFB , PCBC mode=ECB # NoPadding , OAEP , PKCS5Padding( default ) , SSL3Padding padding=PKCS5Padding #For key , support default key value for algorithm #For DESede ,DES we only need to support private key #private key value of DESede algorithm : 20b0020… #private key value of DES algorithm: 527c2qI #for RSA algorithm , there is key pair. you should support private-public key pair #private key value of RSA algorithm: 30820… #public key value of RSA algorithm: 30819… Chapter 20, Working with BIRT encr yption in iHub 705 #private key symmetric-key=527c23… #public key public-key= About META-INF/MANIFEST.MF META-INF/MANIFEST.MF is a text file that is included inside a JAR to specify metadata about the file. Java’s default ClassLoader reads the attributes defined in MANIFEST.MF and appends the specified dependencies to its internal classpath. The encryption plug-in ID is the value of the Bundle-SymbolicName property in the manifest file for the encryption plug-in. You need to change this property when you deploy multiple instances of the default encryption plug-in, as described later in this chapter. Listing 20-2 shows the contents of the default MANIFEST.MF. Listing 20-2 Default MANIFEST.MF Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: Actuate Default Security Plug-in Bundle-SymbolicName: com.actuate.birt.model.defaultsecurity;singleton:=true Bundle-Version: Require-Bundle: org.eclipse.birt.report.model, org.eclipse.core.runtime,org.eclipse.birt.core; bundle-version="3.7.0" Export-Package: com.actuate.birt.model.defaultsecurity.api Bundle-ClassPath: acdefaultsecurity.jar Bundle-Vendor: Actuate Corporation Eclipse-LazyStart: true Bundle-Activator: com.actuate.birt.model.defaultsecurity.properties .SecurityPlugin Bundle-RequiredExecutionEnvironment: JavaSE-1.6 About plugin.xml plugin.xml is the plug-in descriptor file. This file describes the plug-in to the Eclipse platform. The platform reads this file and uses the information to populate and update, as necessary, the registry of information that configures the whole platform. The tag defines the root element of the plug-in descriptor file. The element within the element specifies the Eclipse extension point that this plug-in uses, org.eclipse.birt.report .model.encryptionHelper. This extension point requires a sub-element, . This element uses the following attributes: 706 Actuate BIRT Application Developer Guide ■ class The qualified name of the class that implements the interface IEncryptionHelper. The default class name is com.actuate.birt.model.defaultsecurity.api.DefaultEncryptionHelper. ■ extensionName The unique internal name of the extension. The default extension name is jce. ■ isDefault The field indicating whether this encryption extension is the default for all encryptable properties. This property is valid only in a BIRT Designer Professional environment. When an encryption plug-in sets the value of this attribute to true, BIRT Designer Professional uses this encryption method as the default to encrypt data. There is no default encryption mode in iHub and BIRT Visualization Platform. The encryption model that BIRT uses supports implementing and using several encryption algorithms. The default encryption plug-in is set as default using this isDefault attribute. If you implement several encryptionHelpers, set this attribute to true for only one of the implementations. If you implement multiple encryption algorithms and set isDefault to true to more than one instance, BIRT treats the first loaded encryption plug-in as the default algorithm. Listing 20-3 shows the contents of the default encryption plug-in’s plugin.xml. Listing 20-3 Default plugin.xml Creating a BIRT report that uses the default encryption This section describes an example that shows how the entire mechanism works. This example uses BIRT Designer Professional to create a report design. The report design connects to a MySQL Enterprise database server using the user, root, and password, root, as shown in Figure 20-1. Chapter 20, Working with BIRT encr yption in iHub 707 Figure 20-1 Data source properties for the encryption example The encryption model stores the encrypted value of the database password in the report design file. Along with the value, the model stores the encryptionID. In this way, it identifies the encryption mechanism used to encrypt the password, as shown in the element in the following code: com.mysql.jdbc.Driver jdbc:mysql://127.0.0.1:3306/classicmodels root 10e52… BIRT iHub uses the encryptionID attribute of the element to identify the algorithm to decrypt the password. After using the algorithm on the value of , BIRT iHub connects to the database and generates the report. 708 Actuate BIRT Application Developer Guide Deploying multiple encryption plug-ins In some cases, you need to use an encryption mechanism other than the Data Source Explorer default in your report application. For example, some applications need to create an encryption mechanism using the RSA algorithm that the default encryption plug-in supports. In this case, you must create an additional encryption plug-in instance. For use within BIRT Designer Professional, you can set this plug-in as the default encryption mechanism. If you change the default encryption mechanism, you must take care when you work with old report designs. For example, if you change an existing password field in the designer, the designer re-encrypts the password with the current default encryption algorithm regardless of the original algorithm that the field used. How to create a new instance of the default encryption plug-in 1 Make a copy of the default encryption plug-in: 1 Copy the folder: $ACTUATE_HOME\BRDPro\eclipse\plugins \com.actuate.birt.model.defaultsecurity_ 2 Paste the copied folder in the same folder: $ACTUATE_HOME\BRDPro\eclipse\plugins 3 Rename: $ACTUATE_HOME\BRDPro\eclipse\plugins\Copy of com.actuate.birt.model.defaultsecurity_ to a new name, such as: $ACTUATE_HOME\BRDPro\eclipse\plugins \com.actuate.birt.model.defaultsecurity__rsa 2 Modify the new plug-in’s manifest file: 1 Open: $ACTUATE_HOME\BRDPro\eclipse\plugins \com.actuate.birt.model.defaultsecurity__rsa \META-INF\MANIFEST.MF 2 Change: Bundle-SymbolicName: com.actuate.birt.model.defaultsecurity to: Bundle-SymbolicName: com.actuate.birt.model.defaultsecurity.rsa MANIFEST.MF now looks similar to the one in Listing 20-4. Chapter 20, Working with BIRT encr yption in iHub 709 Listing 20-4 Modified MANIFEST.MF for the new encryption plug-in Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: Actuate Default Security Plug-in Bundle-SymbolicName: com.actuate.birt.model.defaultsecurity.rsa;singleton:=true Bundle-Version: Require-Bundle: org.eclipse.birt.report.model, org.eclipse.core.runtime,org.eclipse.birt.core; bundle-version="3.7.0" Export-Package: com.actuate.birt.model.defaultsecurity.api Bundle-ClassPath: acdefaultsecurity.jar Bundle-Vendor: Actuate Corporation Eclipse-LazyStart: true Bundle-Activator: com.actuate.birt.model.defaultsecurity.properties .SecurityPlugin 3 Save and close MANIFEST.MF. 3 Modify the new plug-in’s descriptor file to be the default encryption plug-in: 1 Open: $ACTUATE_HOME\BRDPro\eclipse\plugins \com.actuate.birt.model.defaultsecurity__rsa \plugin.xml 2 Change: extensionName="jce" to: extensionName="rsa" plugin.xml now looks similar to the one in Listing 20-5. 3 Save and close plugin.xml. Listing 20-5 Modified plugin.xml for the new encryption plug-in "?> 710 Actuate BIRT Application Developer Guide 4 Modify the original plug-in’s descriptor file, so that it is no longer the default encryption plug-in: 1 Open: $ACTUATE_HOME\BRDPro\eclipse\plugins \com.actuate.birt.model.defaultsecurity_ \plugin.xml 2 Change: isDefault="true" to: isDefault="false" 3 Save and close plugin.xml. 5 Set the encryption type in the new plug-in to RSA: 1 Open: $ACTUATE_HOME\BRDPro\eclipse\plugins \com.actuate.birt.model.defaultsecurity__rsa \encryption.properties 2 Change the encryption type to public encryption: type=public encryption 3 Change the algorithm type to RSA: algorithm=RSA 4 Copy the pre-generated private and public keys for RSA to the symmetric-key and public-key properties. encryption.properties now looks similar to the one in Listing 20-6. 5 Save and close encryption.properties. Listing 20-6 Modified encryption.properties file for the new encryption plug-in #message symmetric encryption , public encryption type=public encryption #private encryption: DES(default), DESede #public encryption: RSA algorithm=RSA # NONE , CBC , CFB , ECB( default ) , OFB , PCBC mode=ECB #NoPadding , OAEP , PKCS5Padding( default ) , SSL3Padding padding=PKCS5Padding #For key , support default key value for algorithm Chapter 20, Working with BIRT encryption in iHub 711 #For DESede ,DES we only need to support private key #private key value of DESede algorithm : 20b0020e918.. #private key value of DES algorithm: 527c23ea... # RSA algorithm uses a key pair. You should support #private-public key pair #private key value of RSA algorithm: 308202760201003.... #public key value of RSA algorithm: 30819f300d0.... #private key symmetric-key=308202760.... #public key public-key=30819f300d0..... 6 To test the new default RSA encryption, open BIRT Designer Professional and create a new report design. Create a data source and type the password. 7 View the XML source of the report design file. Locate the data source definition code. The encryptionID is rsa, as shown in the following sample: com.mysql.jdbc.Driver jdbc:mysql://192.168.218.225:3306/classicmodels root 36582dc88..... 8 Create a data set and a simple report design. Preview the report to validate that BIRT connects successfully to the database server using the encrypted password. Before trying to connect to the data source the report engine decrypts the password stored in the report design using the default RSA encryption plug-in. Then the engine submits the decrypted value to the database server. Deploying encryption plug-ins to iHub If you deploy your report designs to BIRT iHub, you need to deploy the report and the new encryption plug-in to BIRT iHub. BIRT iHub loads all encryption 712 Actuate BIRT Application Developer Guide plug-ins at start up. During report execution, BIRT iHub reads the encryptionID property from the report design file and uses the corresponding encryption plug-in to decrypt the encrypted property. Every time you create reports using a new encryption plug-in, make sure you deploy the plug-in to BIRT iHub, otherwise the report execution on the server will fail. When using BIRT iHub, you do not need to deploy the encryption plug-ins to BIRT Visualization Platform. How to deploy a new encryption plug-in instance to BIRT iHub 1 Copy: $ACTUATE_HOME\BRDPro\eclipse\plugins \com.actuate.birt.model.defaultsecurity_2.3.2_rsa to: $ACTUATE_HOME\iHub2\Jar\BIRT\platform\plugins 2 Publish your report design to BIRT iHub. 3 Restart BIRT iHub to load the new encryption plug-in. 4 Log in to BIRT iHub using BIRT Visualization Platform and run the report. BIRT iHub now uses the new encryption plug-in to decrypt the password. Generating encryption keys The default encryption plug-in provides classes that can be used to generate different encryption keys. The classes names are SymmetricKeyGenerator and PublicKeyPairGenerator. SymmetricKeyGenerator generates private keys, which are also known as symmetric keys. PublicKeyPairGenerator generates public keys. Both classes require acdefaultsecurity.jar in the classpath. Both classes take two parameters, the encryption algorithm and the output file, where the generated encrypted key is written. The encryption algorithm is a required parameter. The output file is an optional parameter. If you do not provide the second parameter, the output file is named key.properties and is saved in the current folder. The encryption algorithm values are shown in Table 20-4. Table 20-4 Key-generation classes and parameters Encryption algorithm parameter Class name com.actuate.birt.model.defaultsecurity.api .keygenerator.SymmetricKeyGenerator des (continues) Chapter 20, Working with BIRT encr yption in iHub 713 Table 20-4 Key-generation classes and parameters (continued) Encryption algorithm parameter Class name com.actuate.birt.model.defaultsecurity.api .keygenerator.SymmetricKeyGenerator desede com.actuate.birt.model.defaultsecurity.api .keygenerator.PublicKeyPairGenerator rsa How to generate a symmetric encryption key Run the main function of SymmetricKeyGenerator. 1 To navigate to the default security folder, open a command prompt window and navigate to the default security plugin directory using a command similar to the following: cd C:\Program Files\BRDPro\eclipse\plugins \com.actuate.birt.model.defaultsecurity_ 2 To generate the key, as shown in Figure 20-2, type: java -cp acdefaultsecurity.jar com.actuate.birt.model.defaultsecurity.api.keygenerator .SymmetricKeyGenerator des Figure 20-2 Symmetric key generation 3 The generated key is saved in the file, key.properties. The content of the file looks like this one: #Key Generator #Fri Dec 20 12:03:03 PST 2013 symmetric-key=fbbf1f91028... 4 Copy the key from the generated key file to the encryption.properties file. How to generate a public key using RSA encryption Run the main function of PublicKeyPairGenerator. 1 To navigate to the default security folder, open a command prompt window and navigate to the default security plugin directory using a command similar to the following: 714 Actuate BIRT Application Developer Guide cd C:\Program Files\BRDPro\eclipse\plugins \com.actuate.birt.model.defaultsecurity_ 2 In the command prompt window, type: java -cp acdefaultsecurity.jar com.actuate.birt.model.defaultsecurity.api.keygenerator .PublicKeyPairGenerator rsa The class generates a pair of keys saved in the key.properties file: #Key Generator #Fri Dec 20 12:05:18 PST 2013 public-key=30819f300d06092a86... symmetric-key=3082027... 3 Copy the key from the generated key file to the encryption.properties file. Creating a custom encryption plug-in To create a custom encryption plug-in, you need to extend the following extension point: org.eclipse.birt.report.model.encryptionHelper The interface IEncryptionHelper defines two methods, as shown in the following code: public interface IEncryptionHelper { public String encrypt( String string ); public String decrypt( String string ); } You need to implement these methods and program your encryption and decryption logic there. To install the custom encryption plug-in, copy the plug-in to the product’s plugins folder, where the default plug-in resides. Change the isDefault property in plugin.xml to true. Change the isDefault properties of the rest of the encryption plug-ins to false. Using encryption API methods You can call the API methods in the default encryption plug-in when you have to set the encryptionID property, or encrypt data programmatically. The following list describes these methods and shows their signatures: Chapter 20, Working with BIRT encr yption in iHub 715 ■ IEncryptionHelper::encrypt encrypts the given string, and returns the encrypted string: String IEncryptionHelper::encrypt( String value ) ■ IEncryptionHelper::decrypt decrypts the given encrypted string, and returns the original string: public String IEncryptionHelper::decrypt( String string ) ■ MetaDataDictionary::getEncryptionHelper returns the encryption helper with the extension ID: public IEncryptionHelper MetaDataDictionary::getEncryptionHelper( String id ) ■ MetaDataDictionary::getEncryptionHelpers gets all the encryption helpers: public List MetaDataDictionary::getEncryptionHelpers( ) 716 Actuate BIRT Application Developer Guide Chapter 21 Configuring data source connections in iHub Chapter 21 This chapter contains the following topics: ■ About data source connection properties ■ Using a connection profile ■ Accessing BIRT report design and BIRT resource path in custom ODA plug-ins Chapter 21, Configuring data source connections in iHub 717 About data source connection properties Every BIRT data source object specifies the connection properties required to connect to an underlying data source. Typically, many report designs access the same data source. Rather than typing the same connection properties for each design, you can create a connection profile to reuse the same connection properties across multiple designs. Usually you change database connection properties used in the development environment when you publish the reports to BIRT iHub. To change the connection properties dynamically when you design or deploy your reports, you can use one of two approaches, connection configuration file or connection profile. The connection profile approach is the recommended method of managing database connections. The following sections describe these two approaches. Using a connection profile The connection profile includes information about the database driver, a user ID, password, port, host, and other properties related to the type of data source. BIRT supports using a connection profile when creating a data source in a report design. When a connection profile changes, the BIRT report picks up those changes. This behavior makes migration from a test to a production environment straightforward. You can use connection profiles for all data source types, except SQL Query Builder data sources. If you have to use connection profiles for this type of data source, you must define a unique connection profile in each report. Creating a connection profile There are two ways to create a connection profile in BIRT Designer Professional. You can create a connection profile in Data Explorer, when you create a data source, or in Data Source Explorer view. You use Data Source Explorer to modify, import and export connection profiles. Connection profiles are stored in text files called connection profile stores. Connection profile stores can contain multiple connection definitions for various ODA data sources. The default connection profile store is ServerProfiles.dat, located in the .metadata folder in your workspace. You can also define your own connection profile store, and choose an absolute or a relative file path to store it. It is a good practice to create and use your own profile store file, instead of the default store. Using the default store requires 718 Actuate BIRT Application Developer Guide using absolute file paths for a profile location and involves additional procedures of exporting a profile. Using the Data Source Explorer to create a connection profile limits the connection profile location definition to an absolute file path only, while Data Explorer allows a relative and absolute file path definition. When using a relative file path, the Resource folders in the designer and iHub are used as the base folders. At design time, the BIRT Resource folder points to either the project root or a folder on the file system set in BIRT Designer Preferences under Actuate BIRT—Resources. At run time, the BIRT Resource folder points to the Resource folder set for iHub. Like other BIRT resource files, you must deploy the connection profile store to the iHub when you deploy the report that uses it. By default, BIRT Designer deploys relative path connection profiles to the iHub Resource folder. The connection profile store file can be encrypted using BIRT secured encryption framework. The default extension for the connection profile is .acconnprofiles. This extension is tightly integrated with the default out-of-the-box encryption. How to create a connection profile using Data Explorer 1 In Data Explorer, right-click Data Sources, and choose New Data Source. 2 In New Data Source, choose Create from a connection profile in the profile store, as shown in Figure 21-1. Figure 21-1 Create a new data source 3 Choose Next. Connection Profile appears, as shown in Figure 21-2. Chapter 21, Configuring data source connections in iHub 719 Figure 21-2 Connection Profile 4 In Connection Profile Store, perform one of the following steps: ■ To use an existing profile store, choose Browse. 1 In Browse, narrow down your selection by choosing Relative Path or Absolute Path for the connection profile store. Relative Path lists all the connection profile stores in the Resource folder. Absolute Path opens a browser window to the file system. Selecting a connection profile store displays the connection profile store content in the text box below Use externalized properties in Connection Profile Store. 2 Select Use externalized properties in Connection Profile Store to maintain the link to the profile instance in the external profile store file. It is enabled by default. Disabling it removes the external reference link, and copies the properties from the selected profile to the data source local properties. 3 Deselect Use the default data source name, if you wish to specify a data source name different from the default. ■ To create a new connection profile store, choose New. Create a Connection Profile Store appears, as shown in Figure 21-3. Figure 21-3 720 Create a connection profile store Actuate BIRT Application Developer Guide 1 In Create a Connection Profile Store, select an existing profile from the list or choose New to create a new connection profile. New Connection Profile appears, as shown in Figure 21-4, and lists the data source types for which you can create connection profiles. Figure 21-4 New Connection Profile 2 Choose a data source type and specify a name for the new connection profile. In this example, as shown in Figure 21-4, Flat File Data Source is selected. 3 Choose Next. A new window for defining the data source properties appears. 4 Specify the required information to connect to the data source. For a flat file data source, as shown in Figure 21-5, you must enter: ❏ flat file home folder, or file URI ❏ flat file character set format ❏ flat file style ❏ file format details, such as Use first line as column name indicator, Use second line as data type indicator, and Use trailing null columns. Chapter 21, Configuring data source connections in iHub 721 Figure 21-5 Defining a folder for a flat file data source profile The connection properties are the same as the properties displayed by the data source wizard. 5 Select Test Connection to verify the connectivity. 6 Choose Finish. The new connection profile appears in the list of connection profiles, as shown in Figure 21-6. Figure 21-6 Selecting a connection profile 7 In Create a Connection Profile Store, select the connection profile, Products. 8 Specify a file name for the store file. 9 Choose Browse to select a location for the profile store, or choose the arrow icon next to Browse, and choose Relative Path or Absolute Path. By default, profile store files are saved in a relative file path. Try to use a relative path unless your implementation requires an absolute path. 722 Actuate BIRT Application Developer Guide The relative path selection brings up a window like the one in Figure 21-7. The default file extension is .acconnprofiles and the displayed location is the Resource folder in your workspace. Figure 21-7 Specifying a store file name 10 Select a folder in the suggested location and specify the file name, if you have not entered it in the previous step. Choose OK. 11 Deselect Encrypt file content if you wish not to encrypt. The option to encrypt is the default. 12 In Create a Connection Profile Store, choose OK. The selected relative path appears in Connection Profile Store. In this example, Report Designs/Products.acconnprofiles, as shown in Figure 21-8. Figure 21-8 Selecting the store path 13 Choose Next. 5 If you see a window such as the one shown in Figure 21-9, choose Test Connection. If the connection is successful, choose Finish to save the connection profile. Chapter 21, Configuring data source connections in iHub 723 Figure 21-9 Testing the connection How to create a connection profile from Data Source Explorer 1 Choose Window➛Show View➛Other. 2 In Show View, expand Data Management and select Data Source Explorer, then choose OK. Data Source Explorer lists the data source types for which you can create connection profiles, and any previously defined connection profiles, as shown in Figure 21-10. Figure 21-10 724 Data Source Explorer Actuate BIRT Application Developer Guide Database Connections supports creating profiles to connect to databases using drivers shipped with Actuate BIRT Designer Professional. These database drivers provide access to the graphical SQL query builder. Creating a database connection profile is equivalent to creating a data source by selecting JDBC Database Connection for Query Builder in the data source wizard. ODA Data Sources supports creating profiles to connect to all the other types of data sources. 3 Right-click the data source type for which to create a connection profile. Choose New. 4 Specify a name for the connection profile. Use a name that describes the data source, so that you or other report developers can identify it when selecting the profile later. 5 Specify the information to connect to the data source. The connection properties are the same as the properties displayed by the data source wizard. Figure 21-11 shows an example of connection properties for Amazon DynamoDB. Figure 21-11 Connection properties for Amazon DynamoDB 6 Choose Test Connection to verify the connection to the data source. 7 Choose Finish. The connection profile appears under the data source type in Data Source Explorer. Figure 21-12 shows a connection profile, ProductsDatabase-DynamoDB, under Amazon DynamoDB Data Source. Chapter 21, Configuring data source connections in iHub 725 Figure 21-12 Data Source Explorer displaying a connection profile for Amazon DynamoDB Managing a connection profile You can create connection profiles for different purposes. Data Source Explorer provides import and export functionality to support multiple connection profiles. This functionality supports creating and maintaining separate profiles with connection properties valid for different environments. Figure 21-13 shows Data Source Explorer, and the Import and Export buttons. Import Export Figure 21-13 Importing and exporting connection profiles Exporting connection profiles Connection profiles are exported as text files, either plain or encrypted. Use the exported feature to: 726 ■ Move reports from development to production environments. ■ Plan to create a new workspace or upgrade to a newer version. ■ Reuse existing connection profiles. ■ Share a common set of connection profiles across a workgroup. Actuate BIRT Application Developer Guide ■ Deploy a set of connection profiles to a server environment whose application can work directly with the exported file. How to export a connection profile 1 In Data Source Explorer, choose Export. 2 Select the connection profiles you want to export, as shown in Figure 21-14. Figure 21-14 Exporting a connection profile 3 Enter a fully qualified path to create a new file, or choose Browse to overwrite an existing file. Use the default .acconnprofiles extension if you plan to encrypt the connection profile and use the default out-of-the-box encryption mechanism for it. 4 Deselect Encrypt File Content if the connection profiles do not contain passwords or any other content that pose a security risk. 5 Choose OK. Importing connection profiles You might import a connection profile if you created connection profiles in a previous version of the product and want to reuse them in the current version, or want to share a common set of connection profiles across a workgroup. Importing connection profiles, as shown in Figure 21-15, involves a profile selection. You can overwrite an existing profile if you choose to. Figure 21-15 Importing a connection profile Chapter 21, Configuring data source connections in iHub 727 How to import a connection profile 1 In Data Source Explorer, choose Import. 2 Enter the fully qualified path to the connection profile file, or choose Browse. 3 Choose Overwrite Existing Connection Profiles with Same Names, if you wish. 4 Choose OK. The connection profile appears under its data source category. Editing connection profile properties You can use Data Source Explorer or Console Editor Application to edit connection profile properties. Console Editor Application works from a command line and is useful in environments where you do not have BIRT Designer Professional installed. Use this application for editing connection profile store files. How to edit connection profile properties 1 Open Data Source Explorer. 2 Expand the category for the connection profile that you want to edit. 3 Right-click the data source and select Properties. 4 Edit the connection profile properties as necessary. Figure 21-16 shows an example of the properties for a flat file data source. Figure 21-16 Modifying connection profile properties Editing connection profile store files using Console Editor Application You can also view and edit connection profile properties in connection profile store files using Console Editor Application, which is an application you can launch outside the Eclipse Workbench. Console Editor Application is a system console application to make minor changes to an exported connection profile, such as the file path to the JDBC driver JARs, a connection URL or an ODA data source file path. 728 Actuate BIRT Application Developer Guide When you copy an exported file to a server environment for deployment, you can use this editor tool to quickly adjust the connection profile properties without having to open Data Source Explorer in the Eclipse Workbench. The updates are saved in a separate file for all the connection profiles. If the connection profile is deployed on iHub, you must download the profile first, make the changes, and then upload it to iHub again. Before you can use Console Editor Application, you must install org.eclipse.datatools.connectivity.console.profile_.jar in your Eclipse environment, along with the other DTP plug-ins. The plug-in is installed with the BIRT Designer Professional installation. From within your Eclipse home directory, enter the command: eclipse[c] -nosplash -application org.eclipse.datatools.connectivity.console.profile. StorageFileEditor [ -? | -in | -out | -profile ] For Windows platforms, indicate eclipsec. For other platforms, use eclipse. The command line options are presented in Table 21-1. Table 21-1 Optional command line options Option Description -? Displays help. -in Enter the name of the connection profile storage file to view and/or change. -out Enter the name of the output file to save your changes. -profile Enter the name of a connection profile to view and/or change. If you do not specify a connection profile name, Console Editor steps through all the profiles found in the input file. If you do not specify an argument value, Console Editor prompts you for an input value. Deploying a connection profile Connection profiles that use relative paths are deployed the same way as report resources, and by default they are saved to the iHub Resource folder. For more details on how to publish resources to iHub, see “Publishing a resource file to iHub” in Chapter 19, “Deploying and sharing applications.” Chapter 21, Configuring data source connections in iHub 729 When deploying reports that use absolute connection profiles, you must deploy the connection profile to the correct folder in the file system on the iHub machine. For example, if a report uses a connection profile stored in folder C:\ConnProfile\MySQL.acconnprofiles, you must manually create the same folder C:\ConnProfile on the iHub machine and copy the MySQL.dat file there. Encrypting connection profile properties BIRT supports encrypting the connection profile properties by using the cipherProvider extension point. To define a new encryption method, you must extend org.eclipse.datatools.connectivity.cipherProvider extension point. To define a new encryption plug-in, you must define the file extension and its corresponding provider of javax.crypto.Cipher class for the encryption of connection profile store files. Listing 21-1 shows an example of such a definition. ■ fileExtension—The file extension of connection profile store files that shall be encrypted and decrypted using the cipher provider class specified in the class attribute. The out-of-the-box encryption implementation defines .acconnprofiles as a default extension. The fileExtension attribute value may include an optional dot (.) before the file extension, for example, you can define profiles or .profiles. A keyword default may be specified as an attribute value to match files with no file extension. ■ class—The concrete class that implements the org.eclipse.datatools .connectivity.security.ICipherProvider interface to provide the javax.crypto .Cipher instances for the encryption and decryption of connection profile store files. The custom class may optionally extend the org.eclipse.datatools .connectivity.security.CipherProviderBase base class, which reads a secret (symmetric) key specification from a bundled resource. The base implementation class of the org.eclipse.datatools.connectivity.security .ICipherProvider interface is org.eclipse.datatools.connectivity.security .CipherProviderBase. The class uses a default bundled encryption key as its javax.crypto.spec.SecretKeySpec. The example in Listing 21-1 registers org.company.connectivity.security .ProfileStoreCipherProvider as the provider for files with the extension .profile and for those with no file extension. Listing 21-1 Example of javax.crypto.Cipher extension 730 Actuate BIRT Application Developer Guide Listing 21-2 shows an example implementation of org.company.connectivity.security.ProfileStoreCipherProvider class. Listing 21-2 org.eclipse.datatools.connectivity.security.ICipherProvider interface implementation example import org.eclipse.datatools.connectivity.security.CipherProviderBase; import org.eclipse.datatools.connectivity.security.ICipherProvider; import org.osgi.framework.Bundle; public class ProfileStoreCipherProvider extends CipherProviderBase implements ICipherProvider { /* (non-Javadoc) * @see org.eclipse.datatools.connectivity.security.CipherProviderBase# getKeyResource() */ @Override protected URL getKeyResource() { Bundle bundle = Platform.getBundle( "org.company.connectivity.security" ); return bundle != null ? bundle.getResource( "cpkey" ) : //$NON-NLS-1$ super.getKeyResource(); } } Binding connection profile properties There are two connection profile properties, Connection Profile Store URL and Connection Profile Name, that can be bound to report parameters or expressions and updated when the report is generated. The next section shows how to bind a parameter to change Connection Profile Store URL. Chapter 21, Configuring data source connections in iHub 731 Binding the Connection Profile Store URL property The Connection Profile Store URL property is the path and name of the connection profile store file that contains the connection profile used in a report. The report developer can use the property binding feature in the BIRT data source editor to assign a dynamic file path or URL to Connection Profile Store URL property. This can be done at report run time without changing the report design itself. You can create multiple connection profile store files for different purposes and pass them to a report as parameters at run time. For example, you have two JDBC connection profiles to the same database using different user names and passwords. These profiles are stored in two separate profile store files. At run time, you can select the profile store you want to use to connect to the database. The Connection Profile Store URL property name is OdaConnProfileStorePath. You can also use the property binding feature to specify a JavaScript expression for the value of OdaConnProfileStorePath. This feature provides the flexibility to define a different root path for different file properties. For example, the JavaScript expression can include a variable to control the root path: config[ "birt.viewer.working.path" ].substring(0,2) + "../../data/ProfileStore.acconnprofiles" Alternatively, you can use a reportContext object to pass session information and build the path expression. Binding a connection profile name to a report parameter You can also externalize a connection profile name for a data source by binding it to a report parameter. The next example shows how to create a report design that uses a CSV file as a data source, using Actuate BIRT Designer Professional. At design time, the report design uses the CSV file in the folder, C:\ConnProfile\Testing. Typically, the design-time CSV file contains only a few records. In the production environment, the CSV file, which contains more records, is in the folder, C:\ConnProfile\Production. You create two connection profiles, one for the testing database and one for the production database, and pass the name of the connection profile as a parameter at run time. In this way, the report runs as expected in development and production environments. How to bind the Connection Profile Store URL property to a report parameter 1 In BIRT Designer Professional, create a new BIRT report. 2 In Data Sources, create a new data source and choose Create from a connection profile in the profile store. Choose Next. 3 In Connection Profile, choose New. 4 In Create a Connection Profile Store, select New. 732 Actuate BIRT Application Developer Guide 5 In New Connection Profile, choose Flat File Data Source and enter Products-testing as a profile name. 6 In Description, type Testing database. Choose Next. 7 In New Flat File Data Source Profile, choose Enter File URI. Choose Browse to select the testing database file, in this example, C:\ConnProfile\Testing\csvTestODA.csv. 8 Choose Test Connection to validate the connection, and select Finish. The Products-testing profile appears in the Create a Connection Profile Store list, as shown in Figure 21-17. Figure 21-17 Create a connection profile for testing 9 In Create a Connection Profile, choose New to create a connection profile for the production database. 10 In New Connection Profile, choose Flat File Data Source and enter Products-production as a connection profile name. 11 Choose Next. 12 In New Flat File Data Source Profile, enter the file URI: C:\ConnProfile\Production\csvTestODA.csv. 13 Select Test Connection to validate the connection. 14 Choose Finish. Products-production appears in Create a Connection Profile Store list. 15 In Select the connection profiles, select Products-testing and Products-production, as shown in Figure 21-18. Chapter 21, Configuring data source connections in iHub 733 Figure 21-18 Creating a relative path connection profile store 16 In Specify a file name, choose Browse. Create a Connection Profile store appears, showing Resources folder. 17 In Create a Connection Profile Store, choose the root project folder, ConnProfile, as shown in Figure 21-19. Figure 21-19 Specifying a store file name and location 18 Enter ProductsDB as a file name, and choose OK. 19 In Create a Connection Profile Store, choose OK. Select Connection Profile appears, as shown in Figure 21-20, prompting you to select a connection profile for the data source. 20 In Connection Profile, select the testing database connection profile, Products-testing, as shown in Figure 21-20. 21 Deselect Use the default data source name, and change the data source name to ProductsDB. 22 Choose Next. 734 Actuate BIRT Application Developer Guide Figure 21-20 Selecting a connection profile 23 Choose Finish. ProductsDB data source appears in Data Explorer. 24 In Data Explorer, create a new data set named Products from the ProductsDB data source. 25 In Select Columns, select all columns by choosing >>, and then choose Finish. 26 In Edit Data Set - Products, choose OK. 27 Add the Products data set to the layout and choose Run➛View Report ➛in Web Viewer. In the example, the report displays only six rows of data, as shown in Figure 21-21. Figure 21-21 Previewing the report with testing data 28 Select Layout, and create a new report parameter in Data Explorer. 29 Name the parameter ConnProfileName, as shown in Figure 21-22. 30 In Prompt text, enter: Select the connection profile name: 31 Choose OK to create the parameter. Chapter 21, Configuring data source connections in iHub 735 Figure 21-22 Creating a report parameter 32 In Data Explorer, double-click ProductsDB data source to open the properties. 33 Choose Property Binding, as shown in Figure 21-23, and enter the expression: params["ConnProfileName"].value Alternatively, you can select Fx to use Expression Builder to create the expression. Figure 21-23 Binding a connection profile name to a report parameter Choose OK. 736 Actuate BIRT Application Developer Guide 34 Choose Run➛View Report➛in Web Viewer. In Parameters, enter Products-Production to choose the production database as a data source. The report displays a large set of data, as shown in Figure 21-24. Figure 21-24 Previewing the report with the production data Accessing BIRT report design and BIRT resource path in custom ODA plug-ins ODA providers often need to obtain information about a resource path defined in ODA consumer applications. For example, if you develop an ODA flat file data source, you can implement an option to look up the data files in a path relative to a resource folder managed by its consumer. Such resource identifiers are needed in both design-time and run-time drivers. ODA consumer applications are able to specify: ■ The run-time resource identifiers and pass them to the ODA run-time driver in an application context map ■ The design-time resource identifiers in a DataSourceDesign, as defined in an ODA design session model Accessing resource identifiers in the run-time ODA driver For run time, the BIRT ODA run-time consumer passes its resource location information in the org.eclipse.datatools.connectivity.oda.util.ResourceIdentifiers Chapter 21, Configuring data source connections in iHub 737 instance in the appContext map. ODA run-time drivers can get the instance in any one of the setAppContext methods, such as IDriver.setAppContext: ■ To get the instance from the appContext map, pass the map key ResourceIdentifiers.ODA_APP_CONTEXT_KEY_CONSUMER_RESOURCE _IDS, defined by the class as a method argument. ■ To get the BIRT resource folder URI, call the getApplResourceBaseURI( ) method. ■ To get the URI of the associated report design file folder, call the getDesignResourceBaseURI( ) method. The URI is application-dependent and it can be absolute or relative. If your application maintains relative URLs, call the getDesignResourceURILocator.resolve( ) method to get the absolute URI. The code snippet on Listing 21-3 shows how to access the resource identifiers through the application context. Listing 21-3 Accessing resource identifiers at run time URI resourcePath = null; URI absolutePath = null; Object obj = this.appContext.get ( ResourceIdentifiers.ODA_APP_CONTEXT_KEY_CONSUMER_RESOURCE _IDS ); if ( obj != null ) { ResourceIdentifiers identifier = (ResourceIdentifiers)obj; if ( identifier.getDesignResourceBaseURI( ) != null ) { resourcePath = identifier.getDesignResourceBaseURI(); if ( ! resourcePath.isAbsolute() ) absolutePath = identifier.getDesignResourceURILocator().resolve( resourcePath ); else absolutePath = resourcePath; } } Accessing resource identifiers in the design ODA driver The resource identifiers are available to the custom ODA designer UI driver. The designer driver provides the user interface for the custom data source and data set. Typically, to implement a custom behavior, the data source UI driver extends the following class: 738 Actuate BIRT Application Developer Guide org.eclipse.datatools.connectivity.oda.design.ui.wizards .DataSourceWizardPage The DataSourceWizardPage class has an inherited method, getHostResourceIdentifiers( ), which provides access to the resource and report paths. The extended DataSourceWizardPage just needs to call the base method to get the ResourceIdentifiers for its path’s information. Similarly, if the custom driver implements a custom data source editor page, it extends: org.eclipse.datatools.connectivity.oda.design.ui.wizards .DataSourceEditorPage The DataSourceEditorPage class has an inherited method, getHostResourceIdentifiers( ). The extended class just needs to call the base class method to get the ResourceIdentifiers object for the two resource and report path base URIs. Related primary methods in the org.eclipse.datatools.connectivity .oda.design.ResourceIdentifiers class are: ■ getDesignResourceBaseURI( ); ■ getApplResourceBaseURI( ); Chapter 21, Configuring data source connections in iHub 739 740 Actuate BIRT Application Developer Guide Chapter 22 Using custom emitters in iHub Chapter 22 This chapter contains the following topics: ■ About custom emitters ■ Deploying custom emitters to iHub and BIRT Visualization Platform ■ Rendering in custom formats ■ Configuring the default export options for a BIRT report Chapter 22, Using custom emitters in iHub 741 About custom emitters In Actuate BIRT Designer Professional or Interactive Viewer, you can choose to render BIRT reports in several different formats, as shown in Figure 22-1. Figure 22-1 Rendering formats Actuate provides out-of-the-box report rendering for the following file formats: ■ DOC—Microsoft Word document ■ DOCX—Microsoft Word document, introduced in Windows 7 ■ HTML—HyperText Markup Language document, a standard format used for creating and publishing documents on the World Wide Web ■ PDF—Created by Adobe, a portable file format intended to facilitate document exchange, that also supports the ISO 14289-1 standard for Universal Accessibility ■ POSTSCRIPT—A page description language document for medium- to high-resolution printing devices ■ PPT—Microsoft PowerPoint document ■ PPTX—Microsoft PowerPoint document for Windows 7 ■ XHTML—Extensible Hypertext Markup Language document, the next generation of HTML, compliant with XML standards ■ XLS/XLSX—MS-Excel Document If you need to export your document to a format not directly supported by Actuate, such as CSV and XML, you need to develop a custom emitter. Actuate supports using custom emitters to export reports to custom formats. After a system administrator places custom emitters in the designated folder in BIRT Visualization Platform or iHub, and registers the emitters with iHub, he must restart the product. Users then are able to use the emitters as output formats when scheduling BIRT report jobs in iHub or exporting BIRT reports in BIRT 742 Actuate BIRT Application Developer Guide Visualization Platform. Custom emitters are also supported as e-mail attachment formats. iHub uses the custom emitter format type as a file extension for the output file when doing the conversion. When you develop custom emitters, always use the same name for a format type and an output file extension type. Actuate BIRT Visualization Platform for iHub displays the options of each emitter for the user to choose when exporting a report. The Integrating and Extending BIRT book, published by Addison-Wesley, provides detailed information about how to develop custom emitters in BIRT. Deploying custom emitters to iHub and BIRT Visualization Platform The custom emitters in BIRT are implemented as plug-ins and packaged as JAR files. To make them available to the Actuate products that support them, copy the emitters to the MyClasses folder. The MyClasses folder appears at different levels on different platforms and but it is always available at the product’s installation folder. For iHub the folder is at the following location: /BIRTiHub/iHub/MyClasses/eclipse /plugins When you install InformationConsole.war file to your own J2EE application server, the shared folder MyClasses is not available. In this case, custom emitter plug-ins should be copied to the following folder: /WEB-INF/platform/plugins Plug-ins depend on other plug-ins to function properly. It is a good practice to verify all required plug-ins are installed in the system. To get the list of all required plug-ins open MANIFEST.MF file of your custom plug-in, as shown in Listing 22-1. Depending on the way the plug-ins are developed, Import-Package or Require-Bundle entries declare plug-in dependencies on a package or bundle level. Listing 22-1 MANIFEST.MF Manifest-Version: 1.0 Require-Bundle: org.eclipse.birt.core;bundle-version="3.7.0", org.eclipse.birt.report.model;bundle-version="3.7.0", org.eclipse.birt.report.e ngine;bundle-version="3.7.0", org.eclipse.birt.data;bundle-version="3.7.0" Bundle-ActivationPolicy: lazy Bundle-Version: 1.0.0.201110121016 Bundle-Name: BIRT CSV Emitter Chapter 22, Using custom emitters in iHub 743 Bundle-Activator: org.eclipse.birt.report.engine.emitter.csv.CsvPlugin Bundle-ManifestVersion: 2 Import-Package: org.osgi.framework;version="1.3.0" Bundle-SymbolicName: org.eclipse.birt.report.engine.emitter.csv; Bundle-RequiredExecutionEnvironment: JavaSE-1.6 Every time you deploy a custom emitter you need to restart the product. This ensures the emitter JAR is added to the classpath and the product can discover the new rendering format. For iHub deployment you must execute an extra step to register the emitter with iHub. The following tools and products support custom emitters: ■ Actuate BIRT Designer Professional ■ Actuate BIRT Studio ■ BIRT Interactive Viewer for iHub ■ BIRT Visualization Platform for iHub ■ iHub Rendering in custom formats After deploying the custom emitter, you can see the new rendering formats displayed along with built-in emitters in the following places: ■ Preview report in Web Viewer in Actuate BIRT Designer ■ Output page of schedule job in BIRT Visualization Platform ■ Attachment notification page of schedule job in BIRT Visualization Platform ■ Export content in Actuate BIRT Viewer and Actuate BIRT Interactive Viewer The following examples show the deployment and usage of a custom CSV emitter. The CSV emitter renders a report as a comma-separated file. The JAR file name is org.eclipse.birt.report.engine.emitter.csv.jar. The custom format type is MyCSV. To test the emitter functionality with BIRT Visualization Platform, you schedule any BIRT report design or report document from the examples in the Documents/Applications/BIRT Sample App folder. The examples that follow use the report from the sample volume for an iHub: Documents/Applications/BIRT Sample App/CustomerList.rptdesign 744 Actuate BIRT Application Developer Guide How to deploy a custom emitter to iHub 1 Copy org.eclipse.birt.report.engine.emitter.csv.jar to: /BIRTiHub/iHub/MyClasses/eclipse /plugins 2 Register the emitter with iHub. 1 Open the following file: \BIRTiHub\iHub\etc \jfctsrvrconfig.xml JREM uses this configuration file at startup to load the registered emitters. 2 Navigate to the end of the file to find the following entry: The entry contains a list of emitter descriptions separated by a semicolon. The emitter description must have the format type and the emitter id separated by a colon. For example, the PDF emitter is described as: pdf:org.eclipse.birt.report.engine.emitter.pdf; 3 Add your emitter description to the beginning of the tag: MyCSV:org.eclipse.birt.report.engine.emitter.csv; The whole tag would look like this: MyCSV:org.eclipse.birt.report.engine.emitter.csv; html:org.eclipse.birt.report.engine.emitter.html; xhtml:com.actuate.birt.report.engine.emitter.xhtml; pdf:org.eclipse.birt.report.engine.emitter.pdf; postscript:org.eclipse.birt.report.engine.emitter.postscript; xls:com.actuate.birt.report.engine.emitter.xls; ppt:org.eclipse.birt.report.engine.emitter.ppt; pptx:com.actuate.birt.report.engine.emitter.pptx; doc:org.eclipse.birt.report.engine.emitter.word; docx:com.actuate.birt.report.engine.emitter.docx 3 Restart the iHub to make it load the new plug-in in its classpath: ■ Restart Actuate iHub from Start➛Settings➛Control Panel ➛Administrative Tools➛Services, as shown in Figure 22-2. Chapter 22, Using custom emitters in iHub 745 ■ If you use a separately deployed BIRT Visualization Platform, you must also restart the Web or Application Server. Figure 22-2 Services The following procedures show how to export a BIRT report to a custom format in different products. The procedures use an example format, CSV. How to deploy and use a custom emitter in Actuate BIRT Designer 1 Copy the emitter to: \eclipse\plugins 2 Reopen the designer. 3 Open a report design and choose Run➛View Report. The new CSV format appears in the list of formats, as shown in Figure 22-3. Figure 22-3 List of available formats in BIRT Designer How to export a BIRT report from iHub Schedule a BIRT report to run by choosing Save As on the Schedule page. The new CSV format appears in the document format list. You can also select to attach the output report to an e-mail notification, as shown in Figure 22-4. 746 Actuate BIRT Application Developer Guide Figure 22-4 Save As tab in the Schedule Jobs page in BIRT Visualization Platform How to export a BIRT report from Actuate BIRT Viewer or Actuate BIRT Interactive Viewer 1 Open a BIRT report in Actuate BIRT Viewer or Interactive Viewer. 2 Select Export Content from the viewer menu. The new CSV format shows up in Export Format, as shown in Figure 22-5. Figure 22-5 Export Content in Actuate BIRT Viewer Chapter 22, Using custom emitters in iHub 747 3 Choose OK. A file download window appears, as shown in Figure 22-6. You can choose to open or save the file. The default file name is Customer Order History.csv. Figure 22-6 File Download Configuring the default export options for a BIRT report You can export a BIRT report to various formats from the Web Viewer. These formats include docx, pptx, xls, xlsx, pdf, ps, doc, and ppt. You can configure the default export options by creating a RenderDefaults.cfg file that contains name-value pairs for the appropriate options. You must create a separate RenderDefaults.cfg file for each format. For example, when you export a BIRT report to XLSX, RenderDefaults.cfg can set Enable pivot table to false by default. Place RenderDefaults.cfg in the following locations: ■ For iHub, place RenderDefaults.cfg in: \Jar\BIRT\platform\plugins \com.actuate.birt.report.engine.emitter.config ._.jar When you create or modify RenderDefaults.cfg, you must restart iHub. ■ For BIRT Designer, place RenderDefaults.cfg in: \eclipse\plugins \com.actuate.birt.report.engine.emitter.config ._.jar The configuration file format should follow these rules: 748 ■ All settings should be entered in key = value format. ■ Key names are case-sensitive. ■ String and Boolean values are not case-sensitive. Actuate BIRT Application Developer Guide ■ The values true and false are acceptable for Boolean properties. ■ Any other value, different than true and false is interpreted as false. Listing 22-2 shows an example of RenderDefaults.cfg for a print stream emitter. Listing 22-2 # # # # # # # # # RenderDefaults.cfg for print stream emitter This file contains the default values to use when emitting print stream content. All settings are entered in 'key = value' format. Key names are case sensitive, but string and boolean values are not. The values 'true' and 'false' are acceptable for booleans. Any other value specified will be interpreted as false. Omitting any setting from this file causes the emitter to fall back to internal defaults. # The plex mode for the print job. # Valid values are Simplex, Duplex, and Tumble. # Default: Simplex xifRenderOption.plexMode = Simplex # The DPI to use for rendered pages. Valid values are 240,300,600, # and 1440. # Default: 240 afpRenderOption.pageDPI = 240 # Option to allow black and white images. # Default: True afpRenderOption.allowBlackAndWhiteImg = true # Option to allow single color images. # Default: True afpRenderOption.allowSingleColorImg = true # Option to allow grayscale images. # Default: True afpRenderOption.allowGrayscaleImg = true # Option to allow full color RBG images. # Default: True afpRenderOption.allowFullColorRGBImg = true # Option to allow full color CMYK images. # Default: True afpRenderOption.allowFullColorCMYKImg = true For information about creating a RenderDefaults.cfg file, see Using Visualization Platform. Chapter 22, Using custom emitters in iHub 749 750 Actuate BIRT Application Developer Guide Index Symbols ^ (caret) character 214 , (comma) character 213, 231 ; (semicolon) character 745 : (colon) character 745 ? (question mark) character 214 . (period) character decimal separators 213 pattern matching 214 .zip archive files 688 " (double quotation mark) character pattern matching and 214 [] (square brackets) characters 212 * (asterisk) character pattern matching 214 search expressions 214 / (forward slash) character 214 \ (backslash) character 61, 214 & (ampersand) character 61 % (percent) character 214 _ (underscore) character pattern matching 214 Numerics 3D charts 428 A absolute file paths 719 Access Control List Expression property data cubes 246, 247, 248 data objects 230, 241 data sets 241, 245 report elements 235, 238 report files 230 access control lists creating 230, 231 defining data security and 241, 250 defining page-level security and 231, 235, 238 propagating across report elements 235, 238 testing 240, 251 access restrictions 230, 231, 241 access rights 517, 518 access types getting 497, 506 setting 500, 509 accessing BIRT Interactive Crosstabs 580 chart builder 79 chart themes 179, 300 cross tab elements 581 dashboard editor 35 dashboard files 42 data 220, 718 Data Explorer 12 encryption plug-in 702 expression builder 213 external data sources 68 gadget builder 44 gadget files 43 Highcharts API 175 HTML buttons 281 HTML editor 684 Java classes 697 JavaScript API class libraries 322 reports 682 resources 737 script editor 137, 183 shared resources 204 SQL query builder 725 .acconnprofiles files 723 See also connection profile stores acdefaultsecurity.jar 703, 713 ACLs. See access control lists Action Details window 295 actions completing 389 performing 296 triggering 293 actions (interactive features) 138, 184 active tab (dashboards) 342 active tabs (dashboards) 346 Actual Page Number property 240 actuate class 322, 326 Index 751 Actuate JavaScript API 224 Actuate namespace 322 Actuate Viewer. See report viewer $ACTUATE_HOME variable 698 acviewer container 581 ad hoc parameters generating query output and 403 testing for 397, 407 ad hoc queries 403 Add Variables dialog 223 addAttribute function 638 addDimension function 313, 602 adding animated charts 174 chart elements 188 chart themes 178–181 chart titles 428 computed fields 212 cross tabs 601 custom report emitters 742 dashboard gadgets 37, 42, 44, 255 dashboard tabs 37 dashboards 34, 35, 41, 336 data cubes 311 data items 432 data selectors 56 data service components 369 data sets 14, 17 data sorters 316, 366, 662 expressions 212, 213 filter conditions 353, 628 filters 70, 296, 353 Flash movies 269 Flash objects 436, 440 Google gadgets 266 HTML buttons 216, 217, 281 HTML5 charts 175, 445 iHub profiles 205, 683, 690 informational messages 64 interactive charts 175, 184 interactive features 293, 294, 314, 528 label elements 471 maps 129 page breaks 89, 652, 655 parameter components 374 parameter groups 400, 411, 421 passwords 413 752 privilege filters 516 QR codes 121, 122 rendering options 554 report components 326 report elements 548 to libraries 202 to templates 196, 197, 199 Report Explorer components 487 report viewer components 524 resource folders 202 scroll panels 556 security IDs 230, 231 sort conditions 366, 662 standard charts 424 styles 202 tables 475 text elements 483 text file data sources 200 themes 196, 201–204 addLevel function 615 addMeasure function 313, 603 addMember function 621, 647 add-on properties 169 add-ons 167, 168 AddOns page (Format Gadget) 168 addPoint function 459, 460 addSeries function 446, 452 addTotal function 635, 666 administrators 696 Adobe Flash content. See Flash content advanced sort feature 563 afterDataSetFilled method 186 afterRendering method 187, 188, 189, 190 aggregate data adding dashboard gadgets and 88, 92, 97 creating 84 plotting values 77, 81 progressive viewing performance and 123 aggregate expressions creating 81 aggregate functions adding to cross tabs 92 adding to dashboard gadgets 81, 89, 97 charting data and 81 aggregation building cross tabs and 308, 315 building data cubes and 310 Actuate BIRT Application Developer Guide enabling or disabling 564 aggregation functions adding totals and 315 changing 642 getting 642, 670 setting 644, 671 alerts 221, 259, 263, 373 aligning text in gadgets 46, 170, 171 alphaNumericSorterSet array 362 ampersand (&) character 61 analyzing data 310, 580 anchor properties (gadgets) 161, 162 anchors (gadgets) 161, 162 animation (charts) 174, 176, 460 animation (gadgets) 149 Apache Shindig application 266 Apache Tomcat servers 746 appContext objects 738 application context maps 738 application programming interfaces (APIs) charts and 175, 181 Google gadgets and 268, 274 maps and 136, 140 web applications and 224 application servers 700, 743, 746 applications accessing BIRT resources for 692 adding interactive features to 50, 216, 224 archiving 688 building dashboards and 34 deploying 682 developing 224 displaying data and 310 downloading files for 694 editing landing page for 684 embedding web content and 62 encrypting data and 709 getting version information for 328 loading custom plug-ins for 700 logging out of 332 mobile devices and 121, 174 publishing 682, 687, 696 running 699, 737 sharing 687 testing 686 testing connections for 330 apply button gadgets 107 applyOptions function 456, 603 arc function 465 Arc Inner Radius property 159 Arc Outer Radius property 159 archiving BIRT applications 688 arcs (gadgets) 147, 159 area chart subtypes 71 area charts 453 See also charts adding 71 applying themes to 82 ascending sort order 366, 367, 664 asterisk (*) character pattern matching 214 search expressions 214 asymmetric encryption 705 asynchronous operations 296 attachments 743, 746 authenticate function actuate class 327 authentication logging in to web services and 327 authentication algorithms 702 authentication exceptions 333 authentication information requesting 520 unloading 332 authentication requests 333 AuthenticationException class 333 AuthenticationException objects 333 Auto Abbreviation property 154 Auto Adjust Tickmarks property 150 auto refresh (dashboards) 39, 46 auto suggest delays 380 auto suggest threshold values 403, 409 auto suggestion list controls 410 auto suggestion lists 381, 396 automatic linking (gadgets) 255 autosave feature 338, 342 Average function 81, 89, 92, 97 axes values changing appearance 187 displaying data as 80 axes values (charts) data points and 462 multiple series and 428 Index 753 axes values (charts) (continued) testing for 449, 453 axis labels (charts) 454 axis type values (cross tabs) 618 axis types (cross tabs) changing 315, 619 getting 617, 636 setting 618, 619, 637 B Background Color property 134, 148 background colors gadgets 148, 152 maps 134, 142 Background property 166 backslash (\) character 61, 214 bandwidth 400 bar chart gadgets 255, 256 bar chart subtypes 72 bar charts 453 See also charts adding 72 scripting 189, 190 bar stick stock chart subtypes 78 barcodes (QR code readers) 121 Base Color property 148 Base Width property 151 batch operations 503 beforeDataSetFilled method 186 beforeDrawAxis method 187 beforeDrawDataPoint method 187 beforeDrawSeries method 187, 189 beforeGeneration method 186, 187 beforeRendering method 187 BETWEEN operator 353, 628 BIRT 360 application 246, 250 BIRT design files. See report designs BIRT Designer 280 BIRT Designer Professional 311 applying security settings for 230 creating charts and 174, 179 creating connection profiles and 718 creating expressions and 212, 214 creating maps and 128, 136 creating themes and 201 deploying reports and 682 754 designing dashboards and 35, 40, 44 disabling default themes for 113, 119 encrypting data and 702, 709 formatting data and 112 integrating with iHub 682 link files for 700 QR codes and 121 rendering reports and 742, 744 testing security settings for 240, 250 viewing reports and 122 BIRT document files. See report documents BIRT reports See also reports BIRT resources 691 BIRT Studio designing dashboards and 246, 250 BIRT Viewer 744, 747 BIRT Web Viewer 744, 748 BizRDRptTemplates folder 205 block cipher algorithm 704 block ciphers 702, 704 bookmark names 360, 471, 483 bookmarks accessing cross tabs and 581, 591, 606, 657 adding Flash objects and 437, 531, 549 displaying report elements and 361, 535 displaying Reportlets and 534, 541 getting chart instance for 528, 548 getting chart names for 426 getting data item for 432, 531, 549 getting gadgets associated with 441, 533, 550 getting labels associated with 471, 533, 550 getting report content for 529, 531, 534 getting text element for 483, 534, 551 navigating through reports and 537 retrieving result sets and 359 returning table objects for 296, 476, 534, 550 returning viewer objects for 535 sending requests for 360, 361 Boolean expressions 353, 354, 628, 629 Border Color property gadgets 163 needle base 153 needles 152 thresholds 160 Actuate BIRT Application Developer Guide value indicators 164 Border property 163, 166 Border Thickness property 153 Border Width property 152, 163, 164 borders adding to gadgets 148, 149, 163 adding to maps 134 displaying gadget 46 enabling or disabling add-on 171 setting tooltip 166 bottom N filter feature 574 BOTTOM_N operator 353, 628 BOTTOM_PERCENT operator 353, 628 branding 178, 196 BrowserPanel class 546 bubble charts adding 73 Bulb Radius property 148 bullet gadgets 94, 97, 98, 154, 162, 164, 443 Bundle-SymbolicName property 706 button constants (navigation) 378 button elements 281, 378, 410 button events 216, 218, 219, 281 button names 217 buttons assigning values to 176 C calculated columns 564 calculations data cubes and 85 EasyScript expressions and 212 HTML buttons and 220 calculator gadget 266 calendar gadget 255, 266 calendar gadgets 98 callback functions 272 closing Interactive Crosstabs and 595 connecting to web services and 330 downloading parameters and 375 handling exceptions and 333, 335, 371 retrieving parameters and 376, 386 retrieving result sets and 364, 369, 528 callback parameter 327, 330 candlestick stock chart subtypes 78 Canvas Border Color property 134 canvas view (Google gadgets) 267 Caption property 134 caret (^) character 214 Cascade ACL option 235, 238 cascading ACLs 235, 238, 241 cascading parameter names 403, 409 cascading parameters changing 389 getting values 393 testing for 397 cascading selections 105, 106 cascading style sheets accessing custom 39 adding to Google gadgets 267 case sensitivity (EasyScript) 213 categories (templates) 206 category series selecting data for 80 category series (charts) drilling through 425 getting maximum value of 447 getting minimum value of 448 setting value range for 450 categoryData variable 296 CBC encryption mode 704 cells (empty) 604, 652, 654 Center X Coordinate property 148 Center X coordinate property 169 Center Y Coordinate property 148 Center Y coordinate property 169 CFB encryption mode 704 changeMeasureDirection function 315, 604 changes, undoing or redoing 575 changing aggregation functions 642 channel event names 273, 275 chart elements 188 chart subtype 430 chart themes 300 chart titles 425, 429 connection profiles 718, 728 connection properties 718 cross tabs 312, 314, 581 dashboard content 41 dashboard file names 36, 41 dashboard layouts 37, 41 data 565 Index 755 changing (continued) data cubes 312 data selector gadgets 56 data series 449 default encryption 709 expression builder preference 214 file paths 728 gadget types 567 HTML code 65 image size 225 Java classes 698 label elements 474 maps 142 parameters 374, 389, 400 passwords 709 report designs 586 report parameters 257, 264 reports 50, 566 resource folders 692 styles 196 text 138 text elements 573 themes 118, 177 user selection values 258, 263, 271, 275 channel names 273, 275 character patterns filter expressions 353, 354 characters adding QR codes and 122 displaying URLs and 61 JavaScript object notation and 180 chart annotations 191 chart areas 293 chart bookmarks 426, 528, 548 chart builder 293 adding interactive features and 176 creating charts and 175 formatting charts and 81 opening 79 Chart class 424 chart dimension constants 428 chart elements adding 424, 445 determining type 427 displaying 430 enabling interactive features for 175, 184 getting bookmarks for 528, 548 756 hiding 428 scripting and 188 setting size 429 chart event functions (HTML5 charts) 186 chart event handlers changing output formats and 183, 186 creating BIRT charts and 186 creating chart themes and 179 creating HTML5 charts and 182, 186 chart events 185 chart formatting attributes 179, 180 chart gadgets 443 adding to dashboards 34, 68 creating 69 filtering data for 70 linking to 254, 255, 256 chart IDs 426, 427 chart interactive features 293 chart legends 293 chart objects 424 event handlers and 188 getting 189 chart options 187 chart options objects 187 chart properties enabling or disabling 564 chart scripting examples 189, 190, 193 chart subtypes 430, 564 chart subtypes. See specific chart subtype chart theme builder 178, 179, 181 chart themes 300 applying 176, 177 creating 178–181 exporting formats to 179 overriding 176 selecting 82 setting options for 181 sharing 179, 183 chart titles 425, 426, 428, 429 formatting as auto 82 chart types 453 selecting 71 setting 175 CHART_DIMENSION_2D constant 428 CHART_DIMENSION_2D_WITH_DEPTH constant 428 Actuate BIRT Application Developer Guide CHART_SUBTYPE_PERCENTSTACKED constant 430 CHART_SUBTYPE_SIDEBYSIDE constant 430 CHART_SUBTYPE_STACKED constant 430 charting library 174, 180 charts accessing themes for 300 adding interactive features to 174, 175, 184, 293, 294 adding to dashboards 37, 68, 81, 129 adding to designs 174 aggregate data and 77, 81 changing output formats for 183, 186 changing subtype of 430 changing titles for 425, 429 clearing data filters for 425 comparing multiple series in 72, 73, 76 creating 424 displaying 430 displaying data in 68 displaying timelines in 71, 75, 84 drilling through 425, 426 drilling through values in 50, 80, 81 formatting values in 118 getting bookmark name for 426 getting HTML element for 426 getting page associated with 427 grouping data and 80 overlapping series in 71, 76 selecting data for 79 selecting subtypes for 564 selecting type 71 setting display properties for 82 setting filters for 429 setting number of dimensions for 428 setting title for 428 setting zoom levels for 83 showing high and low temperatures in 74, 78 showing percentages in 72, 73, 76 showing scientific or statistical data 78 stacking series in 71, 73, 76 submitting requests for 430 tracking financial data and 73, 75, 78 tracking scheduling information and 75 tracking stock values with 78, 255 chat applications 62 check box gadgets 99 check boxes 176, 410 Cipher Block Chaining (CBC) Mode 704 Cipher class 730 Cipher Feedback (CFB) Mode 704 cipherProvider extension point 730 CipherProviderBase class 730 ciphers 702, 704 ciphertext 702 circle function 466 class attribute 707 class libraries 322, 331 class property 730 class reference 322, 325, 583 classes accessing Java 697 building mashup pages and 281 changing 698 connecting to web applications and 322 deploying 698 developing with 581 encryption and 703, 707, 713, 730 HTML buttons and 225 ODA UI driver and 739 Classic Models demo database building data objects and 10 connecting to 12 retrieving data from 14, 17 viewing tables in 14 classpaths 706, 713, 744 clearFilters function Chart class 425 FlashObject class 436 Gadget class 440 Table class 476 XTabAnalyzer class 604 clearing data selections 256 click events 219 Client Script option 183 ClientChart class 445 ClientChart objects 445 ClientOption class 452 ClientOption objects 452 ClientPoint class 456 ClientSeries class 459 client-side error constants 385, 494 Index 757 client-side errors 371, 626 client-side scripts 140, 183, 186, 216 clipping rectangles 467 clipRect function 467 closing values (charts) 78 closing values (gadgets) 163 code adding chart interactive features and 295 adding chart themes and 179, 180, 181 adding Google gadgets and 266, 268 adding HTML buttons and 218, 219 adding HTML5 charts and 184, 186, 187, 188 adding interactive maps and 138, 140 changing HTML 65 changing user selection values and 257, 263, 271, 275 creating QR codes and 121 customizing report emitters and 745 displaying cross tabs and 313, 317, 580 displaying embedded HTML 62 displaying user selection values and 261 enabling user interface options and 319 hiding user interface options and 319 linking to dashboard gadgets and 257, 263, 275 linking to Google gadgets and 273, 275 registering event handlers and 312 retrieving gadget content and 259 running 281 code templates 219 collapse/expand feature 565 colon (:) character 745 Color property borders 148 lines 169 regions (gadgets) 156 regions (maps) 136 text 166 threshold areas 160 value indicators 165 colors add-on objects 169, 170 gadget regions 156 gadget threshold areas 160 gadget tick marks 157, 158 gadgets 148, 153, 163 758 maps 130, 134, 135 needles 152 column bars (dashboards) 38 column chart subtypes 73 column charts 73 column editing feature 565 column headings 308 column index values accessing result sets and 365 displaying cross tabs and 607 getting 365, 476, 558 column layouts (gadgets) 37, 38, 43 column mirror starting level getting 651 setting 604, 650, 654 column name parameter 296 column names displaying charts and 296 displaying parameters and 403, 417, 420, 553 filtering data and 355, 356 getting list of 360, 364 running queries and 409 sorting data and 366, 367 column types parameter definitions and 403, 410 parameter value objects and 417, 420 COLUMN_AXIS_TYPE constant 618 columnMirrorStartingLevel parameter 604, 650 columnPageBreakInterval parameter 650 columns adding to cross tabs 651 changing data in 565 creating expressions for 212 filtering values in 425 getting 476, 607 hiding 119–120, 479 matching top or bottom values in 353 moving 569 reordering 482, 571 resizing 38, 565 retrieving data values in 365, 403 retrieving index values for 365, 476, 558 retrieving result sets and 361, 365 selecting 558 setting page breaks on 652, 654, 655 Actuate BIRT Application Developer Guide showing calculated values in 564, 645 showing summary data in 315 showing table 481 sorting on 366, 367 combination charts 174 combo box gadgets 99, 103, 104, 107 comma (,) character 213, 231 command line editor 728 comma-separated values files 200 comments (templates) 198 commit function 586 component names (reports) 331 computed columns 212, 643, 645 computed measures 643, 645 configuration files exporting reports and 748 loading custom emitters and 745 configurations accessing text file data and 200 running BIRT reports and 698 specifying default template category and 207 Connect Missing Data property 148 connection exceptions 335 connection parameters 329 Connection Profile dialog 720 Connection Profile Name property 731 connection profile names 732 Connection Profile Store URL property 731, 732 connection profile stores creating 718, 720, 732 deploying 719 editing 728 encrypting and decrypting 719, 723, 730 selecting 720 connection profiles binding to reports 731, 732 changing 718, 728 creating 718, 719, 724, 726 deploying 729 encrypting 730 exporting 718, 726 externalizing names 732 iHub servers 683, 690 importing 718, 727 naming 725 setting for specific volumes 205 connection properties changing 718 reusing 718 ConnectionException class 335 ConnectionException objects 335 connections accessing data and 718 accessing databases and 725 accessing sample database and 12 authenticating users and 327 closing 332 displaying dashboards and 343 handling errors for 335 iHub servers and 682 loading JavaScript classes and 281 logging in to web applications and 369 opening 329 testing 330, 725 Connector Line Color property 134 Console Editor Application 728 Console Editor command line options 729 Constants class 385, 494 content components 358 content panels (viewer) 546, 556, 560, 561 content variable 582 context menus 574 context objects 732, 738 control type UI values 394 control types 404, 410 controls (HTML buttons) 281 convert function 386 convertDate function 387 ConvertUtility class 386 Copy Library to Shared Resource Folder command 203 copying access rights 518 chart themes 179 dashboard tabs 41 Information Console directory structures 309 libraries 203 privileges 206 report emitter plug-in files 743 copyright statements 199 Count Distinct function 92 Index 759 Count function 81, 89, 92, 97 counting pages in files 498 pages in reports 535, 589 Create Connection Profile Store dialog 721, 722 Create Template Report Item command 199 creating access control lists 230, 231 aggregate expressions 81 animated charts 174 auto suggestion lists 381 chart gadgets 69 chart themes 178–181 computed fields 212 connection profile stores 718, 720, 732 connection profiles 718, 719, 724, 726 cross tab ga