Actuate BIRT Application Developer Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 828
| Download | |
| Open PDF In Browser | View 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 theelement, shown in the following example: 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: Data Source C:\ UTF-8 YES 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 asor
. 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
DEFAULT TEXT
The above text changes according to the current
selection of the gadgets it is linked to.
]]>
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
"?>
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 gadgets 90
cross tabs 311, 601
dashboard gadgets 129
dashboards 34, 35, 41, 336
data cubes 311
data selection gadgets 56, 58, 101
data service components 369
data sets 14, 17
data sorters 316, 366, 662
data sources 718, 732
EasyScript expressions 212, 213
encryption keys 703, 713, 714
encryption plug-ins 715, 730
filter conditions 353, 628
filters 70, 296, 353
Flash gadgets 440
Flash objects 436
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 web pages 224
label elements 471
libraries 201
maps 129
mobile device applications 121, 174
parameter components 374
parameter gadgets 58
760
parameter groups 400, 411, 421
passwords 413
privilege filters 516
report designs 309
report explorer 487
report templates 198–199
Reportlet gadgets 52
reports 713
resource folders 202
result sets 364
scroll panels 556
sort conditions 366, 662
standard charts 424
styles 202
table gadgets 86
tables 475
template categories 206
text elements 483
text file data sources 200
themes 196, 201–204
viewer components 524
web-based applications 322
credentials
external users 327
credentials parameter 327
cross tab bookmarks 581, 591, 606, 657
cross tab elements 312, 580, 581, 609
cross tab filter objects 628
cross tab gadgets 84, 90, 91, 93, 587, 594
cross tab layout view 674
cross tab objects 581, 601
cross tab report elements 581, 601
cross tab Reportlets 597
cross tabs
accessing 580
adding dimensions to 313, 602, 615
adding measures to 313, 603, 642
adding to reports 85
changing 312, 314, 581
creating 311, 601
displaying 308, 312, 580, 657
drilling through 317, 605, 621
enabling interactive features for 314
filtering data in 604, 612, 628
getting bookmarks for 591, 606
getting columns in 607
getting empty cell values for 652
Actuate BIRT Application Developer Guide
getting level values in 649
getting measure direction for 653
getting page breaks for 652, 653
getting rows in 608
handling errors for 625
handling events for 312, 592, 624
hiding detail data in 319, 609
loading 580
pivoting elements in 315, 609
removing default themes 118
removing dimensions from 313, 609
removing measures from 610
removing summary data in 316
rendering 599
reordering elements in 315, 610, 611
retrieving data for 311, 314, 607, 608
selecting elements in 624
setting display options for 603, 650
setting empty cell values in 604, 654
setting level values for 649
setting measure direction for 655
setting page breaks for 654, 655, 656
sorting data in 316, 612, 662
submitting changes to 613
switching measure direction in 604
updating 317
viewing detail data in 613
viewing summary data in 315, 635, 666,
670
Crosstab Builder 91
Crosstab class 312, 601
Crosstab objects 581, 601
crosstab variable 582
cryptographic methods 703
CSS code 62
CSS position attribute 589, 596
CSS styles 39, 267
CSV custom emitter 744
CSV file data sources 200
CSV files 732
CSV formats 742
cube view 675
cubes
analyzing data and 310
changing 312
creating 311
loading 580
cubes. See data cubes
currency values
adding to gadgets 154
Current Selections command 256
current selections gadget option 105
custom drivers 699, 700
custom emitter descriptions 745
custom emitter IDs 745
custom emitters
deploying 743
developing 743
loading 700
rendering reports and 742
testing 744
custom plug-ins 700, 715, 743
customizing
auto suggestion lists 381
encryption plug-in 702, 715, 730
HTML buttons 225–227
HTML5 charts 176, 178
maps 140, 141, 142
reports 697
styles 201, 202
URL parameters 327
user interfaces 562, 674
customODA.link file 700
customPlugins.link file 700
cylinder gadgets 94, 98, 146, 443
D
Dash Gap property 170
Dash Length property 170
dashboard applications. See dashboards
Dashboard class 336
dashboard components 331
dashboard definitions 337, 340, 346
dashboard editor 35, 36
dashboard event constants 347
dashboard files 36, 41, 42, 50
dashboard layouts 35, 37, 41
dashboard metadata 340
dashboard names 338, 342
dashboard objects 336
dashboard page fragment (HTML) 342
dashboard tab names 346, 349, 351
dashboard tab objects 351
Index
761
dashboard tab toolbar 344
dashboard tab type constants 351
dashboard tabs
adding 37
constructing 351
determining gadget specific 350
formatting 39
getting active 346
getting array of 346
getting names 349, 351, 352
getting type 351
importing dashboards and 41
renaming 37
setting as active 342
dashboard templates 338, 344
DASHBOARD_MAX constant 543
DASHBOARD_NORMAL constant 543
DashboardDefinition class 346
dashboards
adding tabs to 351
changing content 41
changing gadgets in 348
changing layouts for 37, 41
changing user selection values on 258,
263, 271, 275
clearing data selections on 256
clearing values on 105
closing 339
controlling access to 241
creating 34, 35, 41, 336
deploying 35, 41, 42
designing 35, 37, 46
determining status of 592
displaying data on 40, 43, 50, 68, 84
displaying external content on 35, 39, 50,
60
displaying Google gadgets on 63, 266, 268,
272, 275
displaying text on 64
downloading 337
filtering values on 105
getting active tab for 338, 346
getting content for 340
getting tabs in 346
handling events for 340, 347, 348
linking to gadgets on 254, 255, 256, 258,
271
762
linking to values on 64, 80, 88, 92, 96
opening 42, 46
optimizing 46
plotting data for 68, 71, 79, 81
publishing 690
refreshing gadgets on 263
renaming 36, 41
saving 36, 41, 338, 339, 341
selecting unique values for 98
setting active tab for 341, 342
setting auto save delay for 342
setting size of 343, 344
setting viewing mode for 543
setting web service connection for 343
showing personal 345
showing tab toolbar in 344
submitting requests for 344
testing content 46
testing data security for 250
updating content 39, 52
viewing cross tabs and 587
viewing gadgets and 350, 594
data
See also values
accessing 220, 718
aggregating. See aggregation
analyzing 310, 580
changing 565
controlling access to 230, 241
displaying 216, 650
downloading 358
encrypting 707, 709, 715
hiding 201, 216, 319, 434, 609
including in templates 196, 200
plotting 68, 79
prompting for 400, 419, 422
refreshing 39
returning from web services 369
returning subsets of 364
selecting 558
submitting requests for 359
summarizing 308
updating 398
viewing as tasks 75
viewing external 60
viewing trends in 68
Data Analytics module 582
Actuate BIRT Application Developer Guide
Data Analytics viewer 595
Data Analyzer
enabling or disabling 566
data analyzer component 331
data cubes
building charts and 80, 81
building cross tabs and 92
calculations and 85
controlling access to 241, 246–249
linking to gadgets and 256
returning unique values in 98
selecting aggregate values in 92, 97
data elements
adding 432
creating 309
getting 549
Data Explorer 718, 719
accessing 12
adding data sets to 14, 17
adding data sources to 12
data extraction operations 566
data fields 308
data fields. See data set fields
data filters. See filters
data hierarchies (cubes) 311, 312, 315
data item IDs 433
data item objects 432
data items 241, 432, 433, 434
data models
aggregating values in 85, 89, 92, 97
creating charts and 80
creating cross tabs and 92
returning unique values in 98
data object files 68, 241
data object stores 103
data objects 10
building dashboards and 40, 259
controlling access to 230, 241, 244
downloading 694
linking to gadgets and 256
linking to values in 80, 88, 92, 96
retrieving data from 200
selecting 104
data point arrays 462
data point options 456, 459
data points
changing appearance 187
data points (charts) 456, 459
data ranges. See range of values
data repositories
displaying content 487
data repository access rights 517, 518
data repository file paths 338
data repository type constants 523
data repository types 521, 523
data rows
setting page breaks for 89
data security 230, 250
data selection gadget types 98, 104
data selection gadgets
accessing messages from 258
adding 58, 101
displaying parameters in 54, 56
enabling interactive filtering and 70, 98
formatting 103
linking to 70, 256, 271, 272, 275
retrieving values for 102
See also data selector gadgets
Data Selector Gadget Wizard 56, 57, 102, 104
data selector gadgets 35, 56
data series
See also charts
comparing multiple 72, 73, 76
displaying percentage of whole 72, 73, 76
displaying relationship between 78
displaying relationship to whole 72, 73,
75, 77
enabling user interactions for 185
grouping data for 80
overlapping multiple 71, 76
plotting side-by-side 72, 73
setting appearance 187
showing high and low values 78
showing open and close values 78
stacking multiple 71, 73, 76
data series (charts)
adding 446, 452, 459
changing 449
deleting 449, 460
displaying values 293
drilling through 425, 426
getting number of run-time 447
getting values for 447, 448
managing 459
Index
763
data series (charts) (continued)
removing 461
replacing 461
setting values for 450, 451
setting visibility of 449, 454, 462
data series names 296
data series objects 459, 460
data service class 280, 369
data service components 331
data service objects 369
data services 369
data set field names 212
data set fields
adding to expressions 214
hiding 245
linking dashboard gadgets and 256
restricting access to 245
selecting 106
data sets
adding to templates 196, 200
aggregating values in 89, 97
calculations and 85
controlling access to 230, 241, 244
creating 14, 17
displaying needle values and 149
displaying query output for 16
hiding 201
linking to gadgets and 256
progressive viewing performance and 122
retrieving 200
returning unique values in 98
selecting 200
Data Source Explorer 718, 724, 726, 728
data source objects 718
data sources
accessing data in 718
accessing external 68
creating 718, 732
creating templates and 200
linking dashboard gadgets and 254, 255
progressive viewing performance and 122
setting up CSV flies as 200
testing connections to 725
data stores. See data object stores
data types
computed columns 643, 645
parameter definitions 403, 404, 410
764
report parameters 418, 421
data version gadgets 99, 103, 104
data visualization gadgets 58, 68
Database Connections folder (BIRT
Designer) 725
database drivers 725
database schemas 14
DataExtraction operations 566
DataItem class 432
dataObject class 221
DataService class 280, 369
DataSourceEditorPage class 739
data-sources element 200
DataSourceWizardPage class 739
date values 353, 387
as literals 213
building Google gadgets and 274
formatting 103
date-and-time formats (gadgets) 103
decimal separators 213
decimal values
adding to gadgets 154
rounding 212
decrypt method 716
decryption 708, 713, 716, 730
decryption algorithms 702
decryption keys 703
default animation state 176
default encryption 707, 709
default encryption algorithm 707
default encryption extension 707
default encryption keys 704
default export options 748
default expression builder 214
default iHub server URL 328
default parameters 327
default report parameters 257
default request options 328
default security api packages 713
default state (UI elements) 176
Default Syntax property 214
default template category 204
default themes 118, 119
default values
assigning to parameters 55
downloading 376
formatting interactive charts and 176
Actuate BIRT Application Developer Guide
getting 405
setting 411
default view (Google gadgets) 267, 268
default web service URL 328
DEFAULT_REPORT_TEMPLATE_
CATEGORY_NAME parameter 207
DefaultEncryptionHelper class 707
delays 380
delete privileges 696
deleting
authentication information 332
chart elements 188
data groups 479
data series 449, 460, 461
dimensions 313, 609
duplicate values 460
event handlers 312, 379, 592
measures 610
summary data 316
theme libraries 113, 119
dependencies 743
deploying
applications 682
connection profile stores 719
connection profiles 729
dashboards 35, 41, 42
encryption plug-in 706, 709, 712, 713
JAR files 698
Java classes 698
report designs 712
report emitter plug-in 743
reports 697, 730
Deployment Kit 333
DES encryption 703, 704
des encryption parameter 713
descending sort order 366, 367, 664
Description property 199
DESede encryption 703, 704
desede encryption parameter 714
design files 50
getting URIs for 738
naming 540, 541, 597
designer ODA driver 738
designing
chart themes 178
dashboards 35, 37, 46, 250
report templates 196, 198
reports 122, 238
designs
accessing data sources for 718
adding charts to 174
changing connection properties for 718
changing default encryption for 709
committing changes to 586
creating 309
creating data sources in 718
defining chart themes in 179
deploying 712
enabling page-level security in 238
generating 707
publishing 690
saving 571
saving viewer content as 538
viewing in dashboards 50
destroy function
ClientPoint class 457
ClientSeries class 460
HTML5Chart Renderer class 467
detail data 319, 481, 609, 613
developers 692
developing
Flash content 62
Google gadgets 266, 274, 275
HTML buttons 219–225
HTML5 chart themes 178, 179, 180, 181
HTML5 charts 175, 182, 186
mobile device applications 121, 174
report emitters 742, 743
reports 682
web applications 224, 322
deviation 74, 89
dial values (gadgets) 148
dialog boxes
displaying cross tabs and 580
exporting data and 543
loading 280, 331
printing reports and 544
viewing result sets and 543
Dialog class 280
dialog components 331
dialog event constants 547
dials (meter gadgets) 98
difference charts 74
Dimension class 312, 315, 615
Index
765
dimension index values 315, 611, 618, 620
dimension names 616, 618
dimension objects 615
dimensions
access restrictions and 247, 248
adding levels to 615, 619, 638, 641
adding to cross tabs 313, 602, 615
changing axis type 315, 611, 619
creating data cubes and 310
drilling through 317, 605, 621
expanding or collapsing members in 317,
613
filtering 630, 632, 633
generating summary values for 315
getting level values in 649
getting levels 617, 631
hiding detail data in 319, 609
naming 618
removing 313, 609
reordering 315, 610
setting axis type for 618, 619
setting index values for 618, 620
sorting values 662, 663, 664
viewing charts and 428
DIRECTION_HORIZONTAL value 650, 653,
655
DIRECTION_VERTICAL value 650, 653, 655
directories
copying 309
directory paths
changing 728
connection profile stores 718
connection profiles 732
defining root 732
getting 739
link files 700
ODA data sources 737
ODA drivers 700
text file data sources 200
disableIV function 526
Display Name property 199
display names
parameter definitions 404, 405, 410, 411
parameter values 390, 418, 421
report templates and 199
Display parameter as new selector setting 56
Display property 120, 136
766
displaying
aggregate values 308
columns 481
cross tabs 308, 312, 580, 657
dashboard gadgets 35
data 216, 650
data cubes 310, 675
data items 434
data series 449, 454, 462
database schemas 14
external content 50, 60
Flash content 62
Flash objects 436, 439, 444
folders 492
HTML5 charts 463
image files 63
Interactive Crosstabs features 318
label elements 473, 533
libraries 204
output formats 746
page number elements 239
parameter groups 382
plug-ins 743
QR barcodes 121, 122
report designs 50
report documents 50
report elements 50, 198, 202
report items 568
report parameters 54, 108, 264, 374, 400
report templates 204
Reportlets 534
reports 122, 682
source code 62
standard charts 430
summary data 315, 635, 666, 670
table elements 481
table of contents 560, 561, 573
tables 296, 475
temporary messages 269
text 484, 485, 534
threshold values 158, 160
toolbars 573, 675
tooltips 572
URLs 60
user selections 254, 261, 271, 275
video files 65
displayname variable 404
Actuate BIRT Application Developer Guide
Distinct Count function 81, 89, 97
div tag 580
DOC formats 742
document files 50
getting names 377
naming 383, 540, 541, 597
document output formats (Word) 527
documentation xiii, 466
documents
changing 50
displaying 50, 682
printing 682
running Interactive Crosstabs and 580
saving 538, 571
selecting parameters for 58
DOCX formats 742
double quotation mark (") character
pattern matching and 214
doughnut charts 75
download result set dialog 543
downloadDashboard function 337
downloading
dashboards 337
data 358
data objects 694
predefined chart themes 179
report files 694, 748
report parameters 375, 376
reports 358, 527
result sets 369, 528, 543
downloadParameters function 375
downloadParameterValues function 376
downloadReport function 527
downloadResultSet function
DataService class 369
Viewer class 527
drawing elements (Highcharts) 465
drill function 317, 604
drillDown function 605
drillDownCategory function 425
drillDownSeries function 425
Driller class 621
Driller objects 317, 621
drilling 317
drill-through functionality 50
drillUp function 605
drillUpCategory function 425
drillUpSeries function 426
drivers
adding ODA resource identifiers to 737,
738
installing custom 699, 700
retrieving data and 725
running BIRT applications and 699
driving_directions gadget 266
Drop Shadow property 134
drop shadows 134, 164
duplicate values 81, 460
duplication suppression feature 572
dynamic data 266
dynamic filter parameters
converting values 386
defining 412
getting column names for 403, 417
getting column type for 403, 417
dynamic filter queries 403
dynamic filters 397
E
EasyScript 314
EasyScript expression builder 213, 214
EasyScript expressions 212, 214, 231
ECB encryption mode 704
Eclipse platform 706
Edit base URL option 139
Edit Data Set dialog
creating queries and 15
editing data sets and 15
Edit Script dialog 259
editable report elements 197, 199, 200
editMeasure function 314, 606
Electronic Codebook (ECB) Mode 704
e-mail 743, 746
embedTemplate function 337
emitters
loading 700
empty cells 604, 652, 654
emptyCellValue parameter 604, 650
Enable Data Security property 250
Enable Gradient Legend property 136
enableAdvancedSort function 563
enableAggregation function 564
enableCalculatedColumn function 564
Index
767
enableChartProperty function 564
enableChartSubType function 564
enableCollapseExpand function 565
enableColumnEdit function 565
enableColumnResize function 565
enableContentMargin function 565
enableCrosstabView function 674
enableCubeView function 675
enableDataAnalyzer function 566
enableDataExtraction function 566
enableEditReport function 566
enableExportReport function 566
enableFacebookComments function 567
enableFilter function 567
enableFilterSummaryView function 675
enableFlashGadgetType function 567
enableFormat function 567
enableGroupEdit function 568
enableHideShowItems function 568
enableHighlight function 568
enableHoverHighlight function 568
enableIV function 528
enableLaunchViewer function 569
enableLinkToThisPage function 569
enableMainMenu function 569
enableMoveColumn function 569
enablePageBreak function 570
enablePageBreak parameter 650
enablePageNavigation function 570
enableParameterPage function 570
enablePrint function 570
enableReorderColumns function 571
enableRowResize function 571
enableSaveDesign function 571
enableSaveDocument function 571
enableShowToolTip function 572
enableSort function 572
enableSuppressDuplicate function 572
enableSwitchView function 572
enableTextEdit function 573
enableTOC function 573
enableToolBar function
Viewer.UIOptions class 573
XTabAnalyzer.UIOptions class 675
enableToolbarContextMenu function 574
enableToolbarHelp function 574, 676
enableToolbarSave function 676
768
enableToolbarSaveDesign function 676
enableToolbarSaveDocument function 677
enableTopBottomNFilter function 574
enableUndoRedo function 575
encrypt method 716
encrypted-property tag 708
encryption
BIRT reports 702, 707, 716
changing default 709
connection profile properties 730
encryption algorithm parameters 713
Encryption algorithm property 704
encryption algorithm type 711
encryption algorithms 702, 703, 704, 707
encryption API methods 715
encryption classes 703
encryption extensions 707
encryption IDs 708
encryption keys
accessing pre-generated 705
cryptographic methods and 702, 703
generating 703, 713, 714
loading 704
reading 730
Encryption keys property 705
Encryption mode property 704
Encryption padding property 704
encryption paddings 704
encryption plug-in
accessing 702
customizing 702, 715, 730
deploying 706, 709, 712, 713
generating encryption keys and 713
installing 715
instantiating 709
overview 703
RSA encryption algorithms and 709
setting default 707
supported algorithms for 703
encryption plug-in IDs 706
encryption properties file 704, 705
encryption settings 704, 723
encryption type 704, 711
Encryption type property 704
encryptionHelper extension point 706, 707,
715
Actuate BIRT Application Developer Guide
encryptionHelper tag 706
encryptionID property 713, 715
Encyclopedia volumes
connecting to 205
deploying reports to 697
publishing Java classes to 698
publishing report designs to 690
publishing templates to 205
securing 230
sharing resources and 692
End Angle property 147, 148, 170
End Color property 153, 170
End Label property 136
End Value property 156, 160
End X coordinate property 170
End Y coordinate property 170
enterprise applications 216
enterprise repository type 523
Entities Border Color property 134
Entities Fill Color property 134
environments 726
EQ operator 296, 353, 628
ERR_CLIENT constant
parameter class 385
ReportExplorer class 494
ERR_CLIENT exception type
actuate.Exception class 371
ViewerException class 576
XTabAnalyzer.Exception class 625
ERR_SERVER constant
parameter class 385
ReportExplorer class 494
ERR_SERVER exception type
actuate.Exception class 371
ViewerException class 576
XTabAnalyzer.Exception class 625
ERR_USAGE constant
parameter class 385
ReportExplorer class 494
ERR_USAGE exception type
actuate.Exception class 371
ViewerException class 576
XTabAnalyzer.Exception class 625
error callback functions 333, 335, 370
error codes 372, 626
error constants 385, 494
error descriptions 371, 625
error messages
Interactive Crosstabs 626
uncategorized exceptions 372
viewer 577
errorCallback parameter 328, 330
errors
web service requests and 328, 330
event functions 281
event handlers
accessing data and 220
calculating values and 223
creating HTML buttons and 219–225, 281
creating interactive charts and 295
creating maps and 137–144
creating QR codes and 121
designing reports and 280
displaying cross tabs and 312, 592, 624
displaying dashboards and 340, 347, 348
displaying parameters and 379
displaying reports and 547
exceptions and 371
filtering data and 224, 225
navigating repository content and 489, 495
registering 379, 592
removing 312, 379, 592
responding to user interactions and 183,
184
selecting report elements and 558
writing multiple 220
event objects 259
EventConstants class
Dashboard class 347
Parameter class 389
ReportExplorer class 495
Viewer class 547
XTabAnalyzer class 624
events
adding to HTML buttons 281
displaying user selection values and 258,
261, 263
HTML buttons 216, 218, 219
HTML5 charts 183, 185, 186
interactive charts and 293
linking Google gadgets and 272, 275
running Interactive Crosstabs and 312
running JavaScript API scripts and 280
updating gadget content and 258
Index
769
events (continued)
user interactions and 184
evt variable 296
example event handlers (charts) 189, 190, 193
Excel formats 527, 742, 748
Excel functions 212
Excel spreadsheets 554
Exception class 312, 371, 625
exception classes 333, 335, 576
exception objects 371
exception types
constructing exception objects and 371
getting 372, 627
testing for 372, 627
exceptions
authentication and 333
connections and 335
cross tabs and 312, 624, 625
report parameters and 389
viewer and 547, 576
execute privileges 696
explodePieSlice function 453
Explorer view 682
Export Content command 747
export options (default) 748
export report dialog 543
exporting
BIRT projects 688
chart formatting attributes 179
connection profiles 718, 726
map locations 132
reports 742, 747, 748
exporting reports 527, 543, 566
expression builder
accessing 213
creating expressions and 214
setting scripting preferences for 214
Expression Syntax command 214
expressions
See also JavaScript expressions
access control lists and 231
aggregating data values and 314
aggregation and 81
binding connection profiles to 731, 732
calculating data values and 212
computing cross tab values and 314, 643,
645
770
creating 212
creating EasyScript 314
filtering data and 353, 628
HTML buttons and 217
literal values in 213
validating 214
variables and 223
writing EasyScript 212, 213
extension names 707
extension points 706
extension tag 706
extensionName attribute 707
external content 35, 139
external user credentials 327
externalizing
connections 732
extras gadgets 35, 60
F
Facebook comments 567
Facebook comments panel 544
failed connections 335
failed requests 333
FALSE operator 353, 628
feature maps 575, 677
feature names (Google gadgets) 268
features 560, 562, 674
features (Google gadgets) 268, 269, 270
fetch direction (FileSearch) 507, 511
fetch handles
file searches 508, 511
folder items 514, 515
fetch size (FileSearch) 508, 511
field names 212
fields 308
adding to expressions 214
hiding 245
linking dashboard gadgets and 256
restricting access to 245
selecting 106
file access types
getting 497, 506
setting 500, 509
File class 496
file dependencies 743
getting 507
Actuate BIRT Application Developer Guide
searching for 511
file descriptions 497, 500
file IDs 497, 500, 507, 510
file lists 503
file name extensions 497
connection profile stores 723
output files 743
file names 743
getting 377, 498, 509, 534
saving report designs and 538
saving report documents and 538
setting 501, 513
viewing reports and 540, 541
File objects 496
file owners
getting 498, 508
setting 501, 512
file search objects 489, 491, 505
file size 498, 501
file system interface 487
file types 171
getting extensions 497
setting 500
FileCondition class 503
fileExtension property 730
files
accessing external data sources and 68
controlling access to 230, 241
counting pages in 498
deploying custom plug-ins and 700
deploying Java classes and 698
downloading 748
importing dashboard 41
navigating through 487
referencing 496
searching 505
selecting specific version 103
setting number of pages in 501
uploading to HTML buttons 225
viewing external 50, 60, 63
FileSearch class 505
FileSearch objects 489, 491, 505
Fill Background Color property 152
Fill Color property 148, 152, 154, 170
Fill Gradient property 154
fill patterns (gadgets) 154, 170, 171
Filter class 353, 628
filter conditions
adding 353, 628
getting operator in 631
getting values of 356, 632
matching character patterns and 353, 354
setting operator in 356, 633
setting values for 357, 633
filter expressions 353, 628
creating 212
filter objects 296, 353, 628
filter operators 353, 355, 356, 628
Filter page (Data Selector) 102
Filter page (Table Builder) 87
filter strings 503
filter summary view 675
filtering
file lists 503, 509, 512
filters
adding gadgets and 440, 442
adding table elements and 476, 480
clearing 436, 476
creating 296, 353
determining if dynamic 397
displaying charts and 295, 425, 429
displaying cross tabs and 604, 612, 628
displaying Flash objects and 436, 438
enabling or disabling 567, 574
getting column names for 355
getting type for 630
HTML buttons and 216, 224
linked gadgets and 255, 256
progressive viewing performance and 123
retrieving data and 98, 353
selecting cascading values and 105
setting column names for 356
setting level names for 632, 633
submitting requests and 360, 362
financial data 73, 75, 78
Firefox browsers 296, 371
First function 81, 89, 92, 97
Flash charts 427, 438, 443
Flash content 62, 269
Flash feature (Google gadgets) 269
Flash object elements 438
Flash object library plug-ins 700
Flash objects 436, 437, 531, 549
FlashObject class 436
Index
771
flat file data sources 721, 732, 737
floating gadgets 43
focus 539
folder labels 492
folder lists 515
folder names 488
FolderItems class 514
folders
accessing encryption plug-in in 702
accessing ODA data sources and 737
changing resource 692, 695
controlling access to 230
copying custom emitters to 743
creating resource 202
deploying connection profiles and 730
deploying JAR files to 698
displaying 492
getting names 488
getting URIs for 738
installing custom drivers and 699, 700
installing custom plug-ins and 700
naming 490
navigating through 487
publishing BIRT resources and 692
storing connection profile stores in 719
viewing library files in 204
Font Color property 134
Font Faces property 134
font properties (gadgets) 166
Font property 166, 170
Font Size property 134, 170
fonts 382
footers
adding page numbers to 239
Force Trailing Zeros property 154
forceSoftRestart function 586
Format Chart page
interactive charts and 176
Format Chart Theme page 179
format editing feature 567
Format Gadget page 146
Format Map page 132, 141
Format Number property 134
Format Number Scale property 134
Format Numbers property 154
Format page (Chart Builder) 69
Format page (Data Selector) 102
772
Format page (Table Builder) 87
formats
downloading reports and 527
localizing data and 353
formatting
cross tab gadgets 93
dashboard tabs 39
data selection gadgets 103
data version gadgets 104
gadgets 45, 46, 118, 146
HTML5 charts 176, 179, 180, 187
maps 132
measurement gadgets 97
numbers 103, 134, 154
reports 112
selector group gadgets 107
tabular gadgets 89
formatting options 46
forward slash (/) character 214
Fraction Digits property 134, 154
freeform grid (gadgets) 43
freeform layouts (gadgets) 37, 43
function names 213
functions
See also methods
Actuate JavaScript API 280, 325
aggregating data and 81, 89, 92, 97
calculating data values and 212, 214
customizing maps and 140, 141
Interactive Crosstabs JavaScript API 580
linking Google gadgets and 272
Fusion Charts API 136, 140
FusionCharts library 136
G
g function 467
gadget builder 43, 44, 96
Gadget class 440
gadget elements 440, 550
gadget files 694
gadget IDs 587
gadget names 349
gadget objects 440
gadget properties
add-ons 169
anchors 161, 162
Actuate BIRT Application Developer Guide
fonts 166
general 146, 147
needle base 152, 153
needles 150, 151
number formatting 154
padding and margins 166
pivot 152, 153
plot 162, 163
regions 155, 156
scale 149, 150
thresholds 158, 159
tick marks 156, 157
tooltips 165
value indicators 164
gadget script objects 348
gadget templates 43
gadget titles 149
gadget type change control 567
gadget types 34, 57, 60, 129, 443
GADGET_TYPE_BULLET constant 443
GADGET_TYPE_CYLINDER constant 443
GADGET_TYPE_LINEARGAUGE
constant 443
GADGET_TYPE_METER constant 443
GADGET_TYPE_SPARK constant 443
GADGET_TYPE_THERMOMETER
constant 443
gadgets
See also Flash gadgets; Google gadgets;
HTML gadgets
adding custom objects to 167
adding report parameters to 264
adding styles to 149
adding to dashboards 37, 42, 44, 255, 340
adjusting column size for 38
adjusting spacing in 166
aligning text in 46, 170, 171
analyzing data and 68
changing 348, 567
creating 129
disabling or enabling animation for 149
disabling values in 149, 152, 158, 160, 164
displaying 444
displaying data in 128, 150, 154, 155, 161
displaying external images in 63
displaying threshold values in 159, 160
displaying user selections in 104, 254, 261,
271, 275
filtering 440, 442
formatting 45, 46, 118, 146
getting instance of 441, 533
getting title of 349
getting type 349
hiding 442
interfacing with Google 268, 271, 275
laying out 37
linking to 254, 255, 256, 258, 271
moving 43
naming 46
refreshing 263
resizing 37, 44, 46
retrieving bookmarks for 441
retrieving values for 259
rotating add-on objects in 170
saving 43
scaling images in 170
selecting data sources for 35, 40, 58
selecting external files for 60
selecting parameters and 56
selecting type 57
setting parameter values in 53, 55
setting size 443
showing tick marks on 149, 157
specifying type 443
tilting 149
updating report items and 52
updating user selections on 258
viewing 35
GadgetScript class 348
Gantt charts 75
garbage collection 378
gauge (meter gadgets) 148, 149
general properties (gadgets) 146, 147
general properties (HTML buttons) 225
general properties (maps) 132, 133
generating
BIRT reports 742
encryption keys 703, 713, 714
HTML5 charts 174
maps 136
QR codes 121
query output 403, 409, 420
report components 326
Index
773
generating (continued)
report designs 707
Reportlets 280
reports 122, 682
geographical data 128
getAccessRights function 517
getAccessType function 497, 506
getActiveTab function 338
getAggregationFunction function 642, 670
getApplResourceBaseURI method 738
getAttributes function 638
getAutoSuggestThreshold function 403
getAxisType function 616, 636
getBookmark function
Chart class 426
Crosstab class 606
DataItem class 432
FlashObject class 437
Gadget class 441
Label class 471
Request class 360
Table class 476
TextItem class 483
getCascadingParentName function 403
getCascadingParentValues function 393
getCategoryCount function 446
getChart function 528
getChartByBookmark function 548
getChartHeight function 446
getChartWidth function 446
getChildData function 394
getClientChart function 426
getClientHeight function 529
getClientOptions function 447
getClientWidth function 529
getColumn function 476, 607
getColumnIndex function 558
getColumnMirrorStartingLevel function 651
getColumnName function
Filter class 355
ParameterDefinition class 403
ParameterValue class 417
Sorter class 366
getColumnNames function 364
getColumnPageBreakInterval function 652
getColumns function 360
getColumnType function 403, 417
774
getCondition function 506
getConditionArray function 506
getContentByBookmark function 529
getContentByPageRange function 530
getContentMargin function 530
getContentPanel function 560
getControlType function 394, 404
getCore function 447
getCore method 189
getCountLimit function 507
getCrosstabByBookmark function 657
getCurrentDisplayName function 404
getCurrentPageContent function
Viewer class 531
XTabAnalyzer class 587
getCurrentPageNum function 531, 587
getCurrentReportParameters function 349
getCurrentReportParameters method 264
getCurrentValue function 394
getDashboardName function 338
getData function 433, 607
getDataItem function 531
getDataItemByBookmark function 549
getDataType function
Measure class 643
ParameterDefinition class 404
ParameterValue class 418
getDefaultActiveTab function 346
getDefaultIportalUrl function 328
getDefaultRequestOptions function 328
getDefaultValue function 394, 405
getDefaultValueIsNull function 405
getDependentFileId function 507
getDependentFileName function 507
getDescription function
actuate.Exception class 371
ReportExplorer.File class 497
XTabAnalyzer.Exception class 625
getDesignResourceBaseURI method 738
getDimension function 622
getDimensionName function 616
getDisplayName function 405, 418
getElement function 576, 626
getEmptyCellValue function 652
getEnablePageBreak function 652
getEncryptionHelper method 716
getEncryptionHelpers method 716
Actuate BIRT Application Developer Guide
getErrCode function 372, 626
getErrorMessage function 577
getExpression function 643
getFeatureMap function 575, 677
getFetchDirection function 507
getFetchHandle function 508, 514
getFetchSize function 508
getField function 503
getFileType function 497
getFilters function 360
getFilterType function 630
getFlashObject function 531
getFlashObjectByBookmark function 549
getFolderName function 488
getGadget function 533
getGadgetByBookmark function 550
getGadgetId function 587
getGadgetName function 349
getGadgetTitle function 349
getGadgetType function 349
getGrantedRoleId function 517
getGrantedRoleName function 517
getGrantedUserId function 517
getGrantedUserName function 518
getGroup function 405, 418
getHeight function 533, 588
getHelpText function 395, 406
getHostResourceIdentifiers method 739
getHtmlDom function
Chart class 426
Crosstab class 607
DataItem class 433
FlashObject class 437
Gadget class 441
Label class 471
Table class 477
TextItem class 484
getId function 497
getIncludeHiddenObject function 508
getIndex function 616, 639, 643
getInstanceId function
Chart class 427
DataItem class 433
FlashObject class 437
Gadget class 441
Label class 472
Table class 477
TextItem class 484
getIportalUrl function 333
getIServerUrl function 520
getItemList function 514
getKey function 662
getLabel function 472, 533
getLabelByBookmark function 550
getLatestVersionOnly function 488
getLayout function 376
getLeft function 588
getLevelAttributeName function 630
getLevelName function
Filter class 631
Level class 639
MemberValue class 648
Sorter class 663
SubTotal class 667
getLevels function 617
getLocale function 521
getLocation function 667
getMatch function 503
getMaxRows function 360
getMeasureDirection function 653
getMeasureIndex function 671
getMeasureName function 644
getMember function 663
getMembers function 622, 648
getMessage function 372, 626
getMouseScrollingEnabled function 556
getName function
File class 498
LevelAttribute class 641
NameValuePair class 390
ParameterDefinition class 406
ParameterValue class 418, 552, 659
Tab class 351
getNameValueList function 395
getNewAxisType function 617
getNewIndex function 617, 644
getOperator function 355, 631
getOperatorList function 406
getOptions function 554
getOwner function 498, 508
getPageContent function
Chart class 427
Crosstab class 608
DataItem class 433
Index
775
getPageContent function (continued)
FlashObject class 438
Gadget class 442
Label class 472
Table class 477
TextItem class 484
getPageCount function 498
getPanInOutEnabled function 557
getParameterGroupNames function 376
getParameterMap function 387
getParameterName function 395
getParameterValues function 388, 588
getParentData function 395
getPickList function 396
getPosition function 406, 419, 588
getPrivilegeFilter function 509
getPromptParameter function 419
getPromptText function 396
getReportletBookmark function 534
getReportName function 377, 534
getRepositoryType function 521
getRequestOptions function 333
getRequiredFileId function 509
getRequiredFileName function 509
getResultDef function 488
getRow function 478, 608
getRowMirrorStartingLevel function 653
getRowPageBreakInterval function 653
getSearch function 489
getSelectedElement function 558
getSelectNameValueList function 407
getSelectValueList function 407
getSeriesCount function 447
getShowToc function 560
getSize function 498
getSorters function 361
getStartRow function 361
getSuggestionList function 396
getTable function 534
getTableByBookmark function 296, 550
getTabName function 349
getTabs function 346
getTabTitle function 350
getTabType function 351
getTemplate function 338
getText function 485, 534
getTextByBookmark function 551
776
getTextContent function 358
getTimeStamp function 499
getTitle function 352
getTop function 589
getTotalCount function 515
getTotalPageCount function 535, 589
getTotals function 636, 667
getTransientDocumentName function 377
getType function
Chart class 427
Crosstab class 609
DataItem class 434
Exception class 372, 627
FlashObject class 438
Gadget class 442
GrandTotal class 636
Label class 473
SubTotal class 668
Table class 478
TextItem class 485
getUIConfig function 535
getUIOptions function 535, 589
getUrl function 335
getUserId function 334
getUserPermissions function 499
getValue function
MemberValue class 648
NameValuePair class 391
ParameterValue class 419, 552, 660
ResultSet class 365
getValueIsNull function 419, 553, 660
getValues function 356, 631
getVersion function 328, 499
getVersionName function 499
getViewer function
actuate class 296, 329
Viewer class 535
XTabAnalyzer class 590
getViewerId function 551, 657
getVolume function 521
getVolumeProfile function 521
getWidth function 537, 590
getXAxisMax function 447
getXAxisMin function 448
getXTabBookmark function 590
getXTabIid function 591
getYAxisMax function 448
Actuate BIRT Application Developer Guide
getYAxisMin function 448
glass styles (charts) 176
global constants 385, 494
global variables 263
Google Gadget API 268
Google Gadget API reference 269
Google Gadget Developer’s Guide 268
Google gadget features 268, 269, 270
Google gadget views 267
Google gadgets 62, 63, 266, 271
Google maps 272
gotoBookmark function 537
gotoPage function 537
Gradient Legend Color property 136
Gradient property 170
grand totals 315, 635
GrandTotal class 315, 635
grant privileges 696
grantedRoleId value 517, 518
grantedRoleName value 517, 518
grantedUserId value 517, 519
grantedUserName value 518, 519
graphical query builder 725
graphics elements 468
graphs. See charts
gray check marks 176
GREATER_THAN operator 353, 628
GREATER_THAN_OR_EQUAL
operator 353, 628
group editing feature 568
groupBy function 478
grouping data
charts and 80
legend items and 80
grouping data rows 281, 478
groups
removing in tables 479
H
handleColorRange method 141
handleData method 141
handleEntityDef method 141
handleMap method 141
handleMarkers method 141
headers
displaying gadget 46
headers (HTML) 281
Height property
gadgets 146, 148
HTML buttons 225
help 64, 198, 199, 574, 676
help text 395, 406, 412
hidden files 508, 512
hide function
Chart class 428
ClientSeries class 460
DataItem class 434
FlashObject class 438
Gadget class 442
Label class 473
Table class 479
TextItem class 485
hide/show item feature 568
hideColumn function 479
hideDetail function 319, 479, 609
hideNavBar function 377
hideParameterGroup function 377
hideParameterNames function 378
hiding
chart elements 428
columns 119–120, 479
data 201, 216, 319, 434, 609
data set fields 245
Flash objects 438, 442
HTML buttons 216
HTML5 charts 460
Interactive Crosstabs features 318
label elements 473
navigation bars 377
region labels 156
report parameters 377, 378, 407, 412
table of contents 561
tables 242, 479
text items 485
Highchart renderer objects 190
Highcharts API 175, 181, 186
Highcharts charting library 174, 180
Highcharts class 464
Highcharts documentation 466
Highcharts drawing elements 465
Highcharts objects 447, 464
Highcharts point class 456
Highcharts point configurations 462
Index
777
Highcharts renderer objects 465, 467, 470
highlight properties (maps) 135, 136
highlighting 568
HOME property 201
horizontal bar charts 72
Horizontal property 170
Hover Effect Color property 134
hover highlight feature 568
HTML Button dialog 217, 227
HTML button elements 217
HTML button names 217
HTML buttons 281
accessing report elements and 224
adding 216, 217
calculating data values and 221
changing values for 227
creating event handlers for 219–225
customizing 225–227
displaying data and 220, 221, 224, 274
filtering data and 216, 224
hiding 216
linking to reports and 216
renaming 227
resizing 227
setting size of 225
testing 218, 225
HTML code 470
adding to landing pages 684
displaying web content and 266, 269
editing 65
embedding on dashboards 60, 62
playing video files and 66
HTML content 39, 60, 267
HTML editor 684
HTML elements
adding Flash objects to 437, 441
adding table elements to 477
adding text elements to 472, 484
creating cross tabs and 580, 607
displaying charts and 426
displaying data and 433, 524
displaying Interactive Crosstabs and 581,
584
displaying parameters and 374
HTML formats 527, 742
HTML forms 374, 382
HTML gadgets 60, 263
778
HTML landing page 684
HTML text editor 64
HTML5 chart scripting examples 189, 190,
193
HTML5 charts
adding animation feature to 460
adding data series to 446, 452, 459
adding to designs 174
applying themes to 177–181, 301
changing data series in 449
changing output formats for 183
changing themes for 177
converting BIRT charts to 186
creating 175
customizing 176, 178
disabling animation for 176
displaying 463
drawing functions for 465
enabling interactivity for 184–186
formatting 176, 179, 180, 187
getting number of run-time series in 447
getting options for 447
getting series values for 447, 448
getting size of 446, 447
getting specific instance of 426
hiding 460
instantiating 445
labeling axes values 454
pivoting axes values in 453
redrawing 449, 461, 462
removing data points in 457
removing duplicate values for 460
removing series from 449, 460, 461
rendering 174, 461
replacing data series in 461
resizing drawing area for 470
selecting data points in 457
selecting series for 461
setting data point properties for 456
setting options for 452
setting properties for 174
setting series values for 450, 451
setting series visibility in 462
setting title of 450, 454
setting type 453
updating data points in 458
viewing data series in 449, 454
Actuate BIRT Application Developer Guide
writing event handlers for 182, 186
HTML5 technology 174
HTTP sessions
running Interactive Crosstabs and 624
hyperlinks
adding to charts 80
adding to gadgets 64, 88, 92, 96
adding to maps 139–140
enabling or disabling 569
I
i character in search expressions 214
ICipherProvider interface 730
IEncryptionHelper interface 707, 715, 716
iHub profile property 205
iHub security model 230
iHub server URLs
getting 328, 520
setting 522
iHub servers
accessing files on 696
adding Google gadgets and 268
changing connection profile stores on 729
creating profiles for 205, 683, 690
deploying connection profiles to 730
deploying custom emitters to 743
deploying Java classes to 698
deploying report designs to 712
deploying reports to 697
downloading files from 694
encrypting data and 707, 708
exporting reports and 748
getting URLs for 328, 520
installing custom plug-ins to 700
managing connections to 682
publishing applications to 682
publishing JAR files to 698
publishing project files to 690
publishing resource files to 691, 692
publishing shared resources to 719
publishing templates to 205
rendering reports for 742, 743, 744
restarting 745
running BIRT reports and 699
setting URLs for 522
storing connection profile stores on 719
iHub System 682
image elements 468
displaying QR codes and 121
image file types 63, 171
image files
accessing external 63
publishing 204
image function 468
image gadgets 63
Image property 225
images
adding to charts 190
adding to gadgets 167, 171
adding to HTML buttons 225
formatting gadget 148, 149
resizing 225
scaling 170
setting transparency 171
template thumbnails and 199, 204
import gadgets 255, 271, 272, 274, 275
importing
connection profiles 718, 726, 727
dashboard files 41
IN operator 353, 629
Include Name in Labels property 134
Include Value in Labels property 134
includeHiddenObject value 512
inclusive range operators 353, 354
index values
accessing result sets and 365
changing axis type and 315, 611
creating total objects and 316
displaying cross tabs and 607, 608
displaying tables and 478
getting column 365, 476, 558
getting data row 361
getting level 639
getting measure 643, 644, 671
incrementing 620
setting data row 362, 363
setting dimension 618, 620
setting level 639
setting measure 645, 646, 672
setting parameter position and 414
index.html file 684
indexes 617, 620
Index
779
Information Console
deploying custom emitters for 743
encrypting data and 702, 707, 713
managing reports and 682
rendering reports for 742, 743, 744
restarting application server for 746
running reports and 746
Information Console URL 333
Information Console web application
copying directory structures for 309
informational messages 64
informational text 198
InformationConsole.war file 743
inherited ACLs 241
initialize function 329
Inner Radius property 147, 148, 170
input 400
input parameters
callback functions and 364
generic objects as 386
installation
Console Editor Application 729
custom plug-ins 700, 715, 743
JDBC drivers 699
ODA drivers 700
interactive chart event handlers 184
interactive charts 174, 175, 184
Interactive Crosstabs
accessing 580
building user interface for 318
changing CSS position attribute for 596
closing 595
determining status of 591, 592
displaying cross tabs and 309, 311, 312,
584, 657
displaying data cubes and 675
displaying specific object in 590
enabling driller for 317, 621
enabling filter summary view 675
getting content for 587, 657
getting CSS position attribute for 589
getting current instance 591
getting feature map for 677
getting ID for 657
getting margins for 588, 589
getting parameters for 659
getting size 588, 590
780
getting UI options for 589
handling errors for 625
handling events for 312, 624
hiding features of 319
initializing 581
instantiating 580, 584
integrating with Interactive Viewer 591,
595, 599
loading 580
resizing 593, 594, 599
restarting 586
restoring initial state 593
rolling back changes to 594
saving documents 676, 677
sessions timing out and 624
setting display options for 603, 650
setting margins for 595, 598
setting UI options for 598, 674
submitting requests for 581, 600
Interactive Crosstabs API 580
Interactive Crosstabs API class reference 583
Interactive Crosstabs API classes 581
Interactive Crosstabs API error constants 625
Interactive Crosstabs API event
constants 624
Interactive Crosstabs objects 584
Interactive Crosstabs tool 85, 93
Interactive Crosstabs toolbars
enabling or disabling 675
help feature for 676
save design feature for 676
save document feature for 677
save feature for 676
Interactive Crosstabs viewer 580, 584, 590
Interactive Crosstabs viewer ID 657
interactive features 293, 314, 528
interactive maps 137, 138, 140
Interactive mode (Data Analytics) 595
Interactive mode (Interactive Crosstabs) 592
interactive reports 216, 224
Interactive Viewer 120, 742, 744, 747
disabling 526
enabling 528
integrating crosstab analyzer with 591,
595, 599
interactive viewing status 538
interactivity editor 295
Actuate BIRT Application Developer Guide
internal ACLs 238
Internet Explorer 261, 296
Invoke Script action 185, 296
iportal URL 328, 333
iportal web service connection 369
iPortalURL parameter 327, 329
iportalURL variable 327, 330
IS_MULTISHEET constant 554
isActive function 591
isAdHoc function 397, 407
isAscending function 367, 663
isAutoSaveEnabled function 338
isCascadingParameter function 397
isChartWithAxes function 449, 453
isConnected function 330
isDashboard function 592
isDefault attribute 707
isDefault property 715
isDynamicFilter function 397
isEnabled function 671
iserverURL parameter 522
iserverURL variable 327, 330
isExceptionType function 372, 627
isHidden function 407
isInitialized function 331
isInteractive function 538, 592
isMultiList function 398
isPassword function 408
isRequired function 398, 408
isSavingNeeded function 339
isUsingPersonalDashboard function 339
isViewParameter function 408, 420
isViewParameter value 413
ivMode parameter 595
J
J2EE application servers 700, 743
.jar files
deploying Java classes and 698
deploying to iHub 698
publishing 698
running reports and 698
JAR files
Console Editor Application and 729
generating encryption keys and 713
report emitters and 743, 744
Java classes
accessing 697
changing 698
deploying 698
encryption and 703, 707, 713, 730
HTML buttons and 225
ODA UI driver and 739
Java Cryptography Extension 702
JavaScript API
designing cross tabs and 580, 582
designing reports and 280
developing with 322
JavaScript API class libraries 322, 331
JavaScript API class reference 322, 325, 583
JavaScript API classes 281, 322, 581
JavaScript API function reference 325
JavaScript API functions
Interactive Crosstabs 580
report designs 280
JavaScript API usage error constants 385, 494
JavaScript API usage errors 371, 626
JavaScript APIs 224, 268
JavaScript chart theme builder 181
JavaScript code
accessing HTML components and 62
adding Google gadgets and 266, 267, 268
adding interactive maps and 138, 140
adding report parameters and 264
changing user selection values and 257,
263, 271, 275
creating chart themes and 178, 180, 181
displaying URLs and 61
displaying user selection values and 261
executing from HTML buttons 216
linking to dashboard gadgets and 257,
263, 275
linking to Google gadgets and 273, 275
retrieving gadget content and 259
JavaScript code templates 219
JavaScript console 261
JavaScript debugger 261
JavaScript event handlers
building HTML5 charts and 182, 186
building maps and 137–144
JavaScript expression builder 213
JavaScript expressions
adding to reports 212, 213
Index
781
JavaScript expressions (continued)
binding connection profiles to 732
converting to EasyScript 214
creating access control lists and 231
HTML buttons and 217
syntax for 180
JavaScript functions
customizing maps and 140, 141
JavaScript object notation syntax 180
JavaScript objects 259, 261, 263
JDBC data sources
connecting to 732
JDBC drivers 699
jfctsrvrconfig.xml 745
jobs 746
joined data sets 241
K
key generator classes 703
key pairs (encryption) 703
key.properties file 713
keyboard events 219
L
Label class 471
label elements 471, 533, 550
Label objects 471
Label property 156, 160, 170
labels
enabling or disabling map 134
hiding region 156
labels (report explorer) 492
landing page 684
Last function 81, 89, 92, 97
launch viewer feature 569
layout type constants (parameters) 376, 382
LAYOUT_COLLAPSIBLE event 385
LAYOUT_GROUP event 385
LAYOUT_NONE constant 385
layouts
designing dashboards and 35, 37, 41
Legend Caption property 134
Legend Position property 134
legends
adding to maps 134, 135, 142
generating 187
782
grouping data for 80
legends (chart) 293
Length property 160
LESS_THAN operator 353, 629
LESS_THAN_OR_EQUAL operator 353, 629
level attribute names 641
level attribute objects 641
level attributes 638
Level class 312, 638
level index values 639
level names
getting 631, 639, 648, 667
setting 633, 640, 649, 668
level objects 638
LevelAttribute class 641
libraries
accessing default themes in 118
associating with templates 202
copying chart themes to 179
determining if initialized 331
loading JavaScript API class 322
removing from BIRT Designer 113, 119
rendering HTML5 charts and 174
rendering maps and 136
sharing chart themes and 179
Library command 201
library files 52, 204
library gadgets (reports) 52, 53
LIKE operator 353, 629
line chart subtypes 76
line charts 75, 453
See also charts
adding 75
Line Color property 163
Line Style property 160
Line Width property 163
linear gauge gadgets 443
adding pointers to 98
adding regions to 97, 155
displaying data and 95, 96
scaling 149
setting threshold values for 158
link channel names 273, 275
Link command 255
link files 700
linking dashboard gadgets 254, 255, 256, 258,
271
Actuate BIRT Application Developer Guide
linking Google gadgets 271, 272, 274, 275
linking to
data selection gadgets 70
external content 139
import gadgets 255, 271, 273, 274, 275
links 121, 255, 720
See also hyperlinks
list boxes 410
interactive charts and 176
list controls 410
list gadgets
adding 100
data version gadgets and 104
maps and 254, 255, 273
multiple data objects and 256
user selections and 107, 271
listing reports 19, 27
lists
enabling page-level security for 235
filtering file 503
searching 503
selecting repository contents and 487
setting items for folder 515
literal strings 540
literal values 213
load function
actuate class 331
loading
class libraries 322
cross tabs 580
data cubes 580
dialog boxes 280, 331
Interactive Crosstabs 580
JavaScript API library 322
report components 326, 331
report viewers 280
locales
converting parameters for 387
creating date expressions and 213
formatting data for 353
getting current 521
selecting templates for 198, 204
setting 522
showing data for 384
location entities (maps) 130, 134, 135
location entity names 130, 134
logout function 332
M
MAC algorithms 702
main menu 569
Major Tick Marks Color property 157
Major Tick Marks Height property 157
Major Tick Marks Width property 157
Major Tickmarks Count property 150
Management Console
rendering reports for 744
manifest files 706, 743
map builder 136
map keys (application context) 738
map legends 134, 135, 142
map library 136
map objects 142
map properties
general 132, 133
highlights 135, 136
map rules 212
maps
adding hyperlinks to 139–140
adding interactive features to 137, 138, 140
configuring options for 142
creating 129
customizing 140, 141, 142
displaying data in 128, 130
formatting 132
generating reports from 255
previewing changes to 142
rendering platform for 136
user selection values and 272, 273
validating data for 131
writing event handlers for 137–144
margin properties (gadgets) 166
margin properties (HTML buttons) 226, 227
margins
enabling or disabling 565
getting Interactive Crosstabs 588, 589
getting viewer 530
setting Interactive Crosstabs 595, 598
setting viewer 539
Margins property 166
Marker Color property 160
marker lines (charts) 293
mashup page 281
master detail reports 123
Index
783
Master Page tab 239
master pages
displaying page numbers on 239
MATCH operator 354, 629
Max function 81, 89, 92, 97
Max property 136
Maximum Label property 158
Maximum Value property 149, 150
maximum values 149
Measure class 312, 315, 642
measure index values
adding totals and 316
changing axis type and 315
getting 643, 644, 671
setting 645, 646, 672
measure names 314, 644, 646
measure objects 642
measureDirection parameter 603, 650
measureExpression variable 314
measurement gadget types 94
measurement gadgets 94, 96, 97, 129
measureName variable 314
measures
adding to cross tabs 313, 603, 642
changing direction of 315, 604
changing order of 315, 611
deleting 610
editing 314, 606
entering expressions for 645
filtering data in 633
generating summary values for 315
getting aggregate functions for 642
getting data type of 643
getting direction for 653
getting expressions for 643
getting index for 643, 644, 671
getting level values in 649
getting names 644
limiting access to 247
naming 646
retrieving 314
setting aggregate function for 644
setting data type of 645
setting direction of 603, 655
setting index values for 645, 646, 672
sorting values 662
viewing data cubes and 310
784
Median function 89, 92
Member Access Control List Expression
property 248
member value objects 647, 648
members (cross tabs)
defining values for 647
drilling through 621, 623
getting level names for 648
sorting values 663, 664
MemberValue class 647
memory 400
menus
enabling or disabling 569, 574
message authentication code algorithms 702
message boxes 221
messages 703, 704
Google gadgets and 269
templates and 198
metadata 706
creating dashboards and 340
MetaDataDictionary class 716
META-INF/MANIFEST.MF file 706
meter gadgets 443
adding objects to 168
adding pointers to 98
adding regions to 97
customizing 147, 151, 152
displaying data and 95, 96
methods 715
See also functions
HTML buttons and 225
HTML5 chart events 186
Metrics Management 50
Min function 81, 89, 93, 97
Min property 136
minimessage feature (Google gadgets) 269
Minimum Label property 158
Minimum Value property 149, 150
minimum values 149
Minor Tick Marks Color property 158
Minor Tick Marks Height property 158
Minor Tick Marks Width property 158
Minor Tickmarks Count property 150
mirror column starting level
getting 651
setting 604, 650, 654
Actuate BIRT Application Developer Guide
mirror row starting level
getting 653
setting 604, 650, 655
missing data points 148
mobile devices 121, 122, 174
Mode function 89, 93
mouse events 219
mouse scrolling 556, 557
move columns feature 569
movies 269
See also Google gadgets
moving
dashboard gadgets 43
multi-clue parameters 386
multidimensional data structures 310
multilevel dimensions 315
multi-list UI elements 398
multiple encryption algorithms 707
multi-select parameters 412
multisheet render option 554
MyClasses folder 743
MySQL databases 707
N
Name property 170
names
applying styles and 201
changing channel event 273, 275
creating maps and location 130, 134
namespace 322
nameValueArray variable 386
NameValuePair class 390
naming
chart themes 179
connection profiles 725
dashboard files 36, 41
dashboard tabs 37
editable report items 199
folders 490
gadget regions 156
gadgets 46
HTML buttons 217
non-editable report items 199
plug-in extensions 707
projects 10
report designs 540, 541, 597
report documents 383, 540, 541, 597
report elements 198
report files 501, 513
report templates 199
variables 223
NAV_FIRST constant 385, 494
NAV_LAST constant 385, 494
NAV_NEXT constant 385, 494
NAV_PREV constant 385, 494
navigate function 378
navigation bars 377
navigation buttons 378
navigation constants 385, 494
navigation feature (page) 570
navigation links 385, 494
needle base (gadgets) 152
needle base properties (gadgets) 152, 153
needle properties (gadgets) 150, 151
needle shapes (gadgets) 152
needle size (gadgets) 152
needles (gadgets) 148, 149, 150, 152
needles (linear gauges) 98
needles (maps) 135
nested tables 123
New Connection Profile dialog 721
New Dashboard dialog 35
New Data Set wizard
accessing sample database and 14
New Data Source dialog 719
New Data Source wizard
accessing sample database and 13
New Library wizard 202
New Parameter Gadget dialog 59
New Project command 10, 12, 19, 20, 21, 22,
23, 24, 26, 28, 35, 37, 39, 40, 41, 43, 44, 46, 52,
53, 55, 56, 58
New Project dialog 10, 12, 20
New Report Gadget dialog 56
New Report Item Theme dialog 179, 181
New Report Project dialog 10
New Server Profile command 28, 683
New Server Profile dialog 28, 683
New Style command 202
New Style wizard 202
New Template wizard 199
New Theme wizard 202
next function 365
Index
785
NON_DASHBOARD constant 543
non-editable report elements 198, 199
NoPadding mode (encryption) 705
NOT_BETWEEN operator 354, 629
NOT_EQ operator 354, 629
NOT_IN operator 354, 629
NOT_LIKE operator 354, 629
NOT_MATCH operator 354, 629
NOT_NULL operator 354, 629
notifications 746
NULL operator 354, 629
null values
assigning to parameters 411, 423, 553, 661
authentication and 327
getting 405, 419, 553
subtotals and 612
testing for 354, 629, 660
number formatting properties (gadgets) 103,
154
Number Prefix property 134
Number Suffix property 134
numbering report pages 239
numeric values
abbreviating 134, 154
adding to gadgets 149, 154
adding to maps 130, 134
aggregating. See aggregation
as literals 213
displaying text with 154
filtering 353
formatting 103, 134, 154
plotting sets of 73, 78
rounding 212
O
OAEP encryption mode 705
object names 170
object types 559, 576
objects 702
as input parameters 386
customizing 167
inspecting JavaScript 261, 263
retrieving gadget content and 259
selecting viewer content and 558, 590
ODA connection profiles 718, 732
ODA consumer applications 737
786
ODA data sets 738
ODA data source editor pages 739
ODA data source wizard pages 739
ODA data sources 737, 738
ODA Data Sources folder (BIRT
Designer) 725
ODA drivers 700
adding resource identifiers to 738
ODA providers 737
ODA user interfaces 738
ODA_APP_CONTEXT_KEY_CONSUMER_
RESOURCE_IDS key 738
OdaConnProfileStorePath property 732
OFB encryption mode 704
ON_CHANGE_COMPLETED constant 389
ON_CHANGED constant 389
ON_CONTENT_CHANGED constant 547,
624
ON_CONTENT_SELECTED constant 547,
624
ON_CONTENT_SELECTED event 558
ON_DIALOG_OK constant 547
ON_EXCEPTION constant
Dashboard class 347
Parameter class 389
ReportExplorer class 495
Viewer class 547
XTabAnalyzer class 624
ON_EXCEPTION event 576
ON_SELECTION_CHANGED constant 389,
495
ON_SELECTOR_GADGET_CHANGED
event 272
ON_SESSION_TIMEOUT constant
Dashboard class 347
Parameter class 389
ReportExplorer class 495
Viewer class 547
XTabAnalyzer class 624
onblur events 219
onChange events 258
onChange method 258
onclick events 219
ondblclick events 219
onEventChange method 273
onfocus events 219
onkeydown events 219
Actuate BIRT Application Developer Guide
onkeypress events 219
onkeyup events 219
online documentation xiii
online help 64
onmousedown events 219
onmousemove events 219
onmouseover events 219
onmouseup events 219
onUnload function
Dashboard class 339
Parameter class 378
ReportExplorer class 489
opening
chart builder 79
connections 329
dashboard editor 35
dashboard files 42, 46
Data Explorer 12
EasyScript expression builder 213
gadget builder 44
gadget files 43
HTML editor 684
JavaScript expression builder 213
report files 230
reports 540, 541
script editor 137, 183
opening values (charts) 78
opening values (gadgets) 164
operations
processing 296
operator lists 406
operators (filter expressions) 353, 355, 356,
628
Optimal Asymmetric Encryption
Padding 705
Options class 650
options objects (Highcharts) 187
Outer Radius property 147, 148, 170
Outline view (BIRT Report Designer) 202
output 704
testing data security and 250
testing page-level security and 240
Output Feedback (OFB) Mode 704
output files 713, 743
output formats
export operations and 742, 747, 748
exporting reports and 527
HTML buttons and 216
HTML5 charts and 183, 186
report emitters and 743
reports 742, 744
viewing 746
overlapping gadgets 37
overlapping regions (gadgets) 98
overlay chart subtypes 71, 76
P
packaging Java classes 698
padding properties (gadgets) 166
padding properties (HTML buttons) 226, 227
Padding Title property 166
Padding Value property 166
page break editing feature 570
page break intervals 652, 653, 654
page break status 652
page breaks 89, 652, 655
access control lists and 238
adding 89
page components
accessing report elements in 548
adding Flash objects to 438, 442
adding tables to 477, 481
adding text elements to 472, 484
creating cross tabs and 587, 608, 657
displaying charts and 427, 429, 460
displaying data and 434
getting content from 531, 587
getting current number for 531
getting Flash objects in 549, 550
linking to 569
navigating to specific 385, 494, 537, 570
page content objects 548, 657
page counts
files 498, 501
reports 535, 589
page headers and footers
adding page numbers to 239
page navigation constants 385, 494
page navigation feature 570
page number elements 239
page numbers 239, 531
page position (viewer) 537
page ranges 527, 530
Index
787
PageContent class 548, 657
page-level security
described 230
disabling 239
displaying reports and 231–232, 238
enabling 230, 235, 238, 239
testing 240
page-level security examples 235, 237
pages
counting file 498
counting report 535, 589
Parameter class 374, 385
parameter components 331, 374
parameter control type UI values 394
parameter control types 404, 410
parameter convert utility class 386
parameter definition names 406
parameter definition objects 375, 392, 400
parameter definitions
creating 400
displaying parameters and 390, 416
entering passwords and 408, 413
getting auto suggest threshold for 403
getting column names for 403
getting control type for 404
getting data type for 404
getting default values for 405
getting display names for 404, 405
getting help text for 406
getting name-value pair for 407
getting operator list for 406
getting required parameters for 408
getting values for 407
naming 414
selecting report parameters and 407, 414
setting auto suggest threshold for 409
setting column names for 409
setting column type for 409
setting control type for 410
setting data type for 410
setting display names for 410, 411
setting help text for 412
setting multiple values for 412
setting name-value pairs for 414
setting required parameters for 413
specifying data type returned by 403
specifying default values for 411
788
storing position of 406, 414
Parameter Display Settings page 56
parameter events 379
parameter gadgets 58, 108
parameter global constants 385
parameter group names 376, 382
parameter groups
creating 400, 411, 421
displaying 382
expanding 381
hiding parameters in 377
returning 405, 418
parameter index values 414
parameter layout type constants 376
parameter lists
changing values in 389
defining name-value pairs for 390, 414
getting auto suggest threshold for 403
getting name-value pair for 407
getting parameter position in 419
setting auto suggest delays for 380
setting auto suggest threshold for 409
setting column names for 420, 553
setting column type for 420
setting fetch size of 381
setting length of 381
setting parameter position in 422
parameter maps 387
parameter names
getting cascading 403
getting for specific value 418, 552
getting from cross tabs 659
getting from data objects 395
setting 409, 422, 660
parameter objects 374, 378, 383
parameter page components 331
parameter pages
changing 378
displaying parameter definitions and 411
displaying parameters and 374, 385, 400
enabling 570
getting group names for 376
getting layout type for 376
hiding navigation bar for 377
loading 331
navigating through 378, 385
rendering content for 374, 380
Actuate BIRT Application Developer Guide
setting fonts for 382
setting layout of 382
parameter panels 544
parameter value objects 416, 552, 659
ParameterData class 392
ParameterDefinition class 400
ParameterDefinition objects 375, 392, 400
parameters
accessing result sets and 364
adding to HTML containers 374
adding to viewer component 386
authenticating web services and 327
binding connection profiles to 731, 732
changing default 257, 264
converting values 386
creating dashboards and 53, 56, 58
customizing 327
determining type 397, 407, 408
displaying tables and 296
filtering data and 353
generating encryption keys and 713
generating query output and 409, 420
getting cross tab 588
getting custom URL 522
getting viewer 552, 553
handling events for 379, 389
initializing HTTP sessions and 329
linking to web services 383
localizing 384
performing garbage collection for 378
prompting for input and 400, 419, 422
retrieving data and 392
retrieving external content and 61
returning Interactive Crosstabs 659
running report documents and 58
running reports and 377, 540
submitting requests for 384, 416
Parameters class 280
ParameterValue class 416, 552, 659
ParameterValue objects 388
paramValues variable 388
parent parameters 403
parentname variable 403
password parameter 327
passwords
changing 709
encrypting 413
encrypting and decrypting 708
getting 408
JDBC data sources 732
path commands (SVG) 469
path function 468
paths
changing 728
connection profile stores 718
connection profiles 732
dashboard templates 338, 344
defining root 732
getting 739
link files 700
ODA data sources 737
ODA drivers 700
Report Explorer 492
text file data sources 200
pattern operators 353, 354
Pattern property 154
PCBC encryption mode 704
PDF formats 527, 742
PDF report emitter 745
percent (%) character 214
percent stacked chart subtypes 72, 73, 76
performance 400
displaying reports and 53, 122
performance gadgets 50
period (.) character
as decimal separator 213
pattern matching 214
period bars (gadgets) 163
Period Bars Color property 163
Period Bars Length property 163
personal dashboards 339, 345
pie chart sectors 453
pie charts 453
adding 77
pivot function 315, 609
pivot properties (gadgets) 152, 153
pivot tables 86
pivotChart function 453
pixel values (viewer) 530
PKCS5Padding encryption mode 705
plaintext component (encryption) 702
playing video files 66
plot properties (gadgets) 162, 163
plug-in dependencies 743
Index
789
plug-in descriptor files 706
plug-in extension names 707
plug-in extension points 706
plugin tag 706
plugin.xml 706
plug-ins
customizing report emitters and 743
deploying 709, 712, 713, 743
editing connection profiles and 729
encrypting reports and 702
getting deployment location for 700
installing custom 700, 715, 743
viewing required 743
ports 62
Position Above property 158
Position Below property 158
Position Left property 158
Position Right property 158
PostScript formats 527, 742
PowerPoint documents 742
PowerPoint formats 527
PPT formats 742
PPTX formats 742
predefined chart themes 177, 179
predefined styles 201, 202
Prefix property 154
Preset Scheme property 148
Preview Type page (chart theme builder) 179
previewing
HTML button functionality 225
HTML5 charts 179
maps 142
query output 16
reports 280
print dialog 544
printing 682, 742
reports 544, 570
private files 497, 500
private-key encryptions 703, 713
privilege filter objects 516
privilege filters
creating 516
getting 509
setting 512
PrivilegeFilter class 516
privileges 35, 206, 230, 695, 696
assigning to users or groups 502
790
getting user 499
profiles (volume) 521, 523
ProfileStoreCipherProvider class 730
programmers 692
programming interfaces. See application
programming interfaces
progressive viewing 122–123
project files
publishing 690
project types 10, 12, 20
projects
downloading files for 694
exporting 688
naming 10
opening dashboard files and 36
running 686
sharing BIRT applications and 687
prompt text 396
prompts 400, 419, 422
Propagating Cipher Block Chaining (PCBC)
Mode 704
properties
chart theme builder 179
chart themes 176, 179, 181
charting applications and 564
encrypting 730
encryption 704, 706, 707
gadgets 146
HTML buttons 225
HTML5 charts 174
maps 132
report parameters 387
report template 199
styles
applying 201
setting 202
.properties files 204
public encryption type 704, 711
public keys 713, 714
public-key encryption 703
PublicKeyPairGenerator class 713
PublicPairGenerator class 714
Publish dialog 29, 687, 690, 692
publish subscribe framework 270
publish subscribe framework API 274
See also pubsub feature (Google gadgets)
Publish Templates dialog 205
Actuate BIRT Application Developer Guide
Publish Templates to iHub command 205
publisher objects 260, 261
publishing
BIRT applications 682, 687, 696
JAR files 698
project files 690
report files 690, 694
resources 691, 692, 719
templates 204–206
pubsub feature (Google gadgets) 268, 270,
271, 275
Q
QR code generator 121
QR code readers 121
QR codes 121, 122
qrreport.rptdesign 121
queries
building data cubes and 310
previewing result sets for 16
retrieving data with 15
running ad hoc 403
running dynamic filter 403
setting column names for 409
setting column types for 409, 420
query builder data sources 718
query builders 725
Query page 14
question mark (?) character 214
Quick Response (QR) codes 121, 122
R
radar chart subtypes 77
radar charts 77
radio button gadgets 100, 104
radio buttons 410
interactive charts and 176
Radius property
circle gadgets 170
dashboard gadgets (general) 146, 148
gadget threshold markers 160
range of values
adding gadgets and 97, 149
creating maps and 135, 136
read privileges 696
read-only parameters 383
Rear Extension property 152
rect function 469
rectangles 467, 469
redirection 61
redo feature 575
redraw function 449, 460
referencing
report files 496
refresh settings 39
refreshing data 39
refreshing gadgets 263
region names 156
region properties 155, 156
Region property 156
regions (gadgets) 97, 155
registerEventHandler function
Dashboard class 339
Parameter class 379
ReportExplorer class 489
XTabAnalyzer class 312, 592
relational databases
See also databases
relative file paths 719
remove function 457, 461
removeDimension function 313, 609
removeEventHandler function
Dashboard class 340
Parameter class 379
ReportExplorer class 489
XTabAnalyzer class 312, 592
removeGroup function 479
removeMeasure function 610
removeSeries function 449
renaming
dashboard tabs 37
dashboards 36, 41
HTML buttons 227
renaming themes 202
render function 461
render options 554
render options map 554
renderContent function 340, 380
RenderDefaults.cfg 748, 749
Renderer class 465
Renderer objects 465, 467, 470
renderer objects (Highchart) 190
Index
791
rendering
cross tabs 599
dashboard content 340
HTML5 charts 461
parameter components 374, 380
reports 280
rendering formats 744
rendering reports 742, 744
RenderOptions class 554
reorderDimension function 315, 610
reorderMeasure function 315, 611
report classes 324
report content objects 358
report context objects 732
report design files 50
getting URIs for 738
naming 540, 541, 597
Report Design perspective 196, 198
report design save feature 571
report designs
accessing data sources for 718
adding charts to 174
changing connection properties for 718
changing default encryption for 709
committing changes to 586
creating 309
creating data sources in 718
defining chart themes in 179
deploying 712
enabling page-level security in 238
generating 707
publishing 690
saving 198, 571
saving viewer content as 538
viewing in dashboards 50
report document files 50
getting names 377
naming 383, 540, 541, 597
report document save feature 571
report documents
changing 50
displaying 50, 682
exporting 742
printing 682
running Interactive Crosstabs and 580
saving 538, 571
selecting parameters for 58
792
report element IDs 433
report element types 559
report elements
adding 548
adding QR codes and 121
adding to libraries 202
adding to templates 196, 197, 199
applying styles to 202
changing default themes for 119
displaying 50, 198
displaying charts and 424, 445, 464
displaying data and 434
displaying text and 471, 483
embedding in web pages 224
getting bookmarks for 531, 535
getting from viewer 531
getting type 559
handling events for 280
handling exceptions for 576, 626
naming 198, 199
retrieving result sets and 359
selecting 558
setting bookmarks for 361
setting page-level security for 235, 238
submitting requests for 473, 486
report emitter descriptions 745
report emitter IDs 745
report emitters
deploying 743
developing 743
loading 700
rendering reports and 742
testing 744
report engine
accessing classes for 698
report engine plug-in 700
report files 230, 694
downloading 748
getting names 377, 498, 534
searching for 505
selecting 487
report gadgets 34, 50, 54, 58, 260, 264, 349
report items
adding to dashboards 52
adding to templates 199
displaying 568
report library files 52, 204
Actuate BIRT Application Developer Guide
report library gadgets 52, 53
report parameters
assigning data types to 410, 421
binding connection profiles to 731, 732
changing 374, 389, 400
determining if required 398, 408
displaying 54, 108, 264
downloading 375, 376
getting control type for 394
getting data type of 404, 418
getting display names for 418
getting file names for 377
getting values for 349, 419
hiding 377, 378, 407, 412
naming 660
prompting for 419
retrieving 383
selecting 56, 381, 396, 407, 414
setting default values for 55
setting display names for 421
setting properties for 387
setting values for 416, 552, 661
specifying as read-only 383
specifying default values for 411
specifying multiple values for 412
specifying null values for 423, 553, 661
specifying required 413
testing for null values in 660
viewing 374, 400
Report Studio
creating text file data sources for 200
report template categories in 204, 206
report template categories 206
Report Template dialog 197
report template files 198, 199, 337
report templates
accessing resources for 204
adding report elements to 196, 197, 199
adding themes to 196, 201–204
associating libraries with 202
changing styles in 196
creating 198–199
designing reports and 197
excluding data sets in 201
localizing 198, 204
naming 199
providing data with 200
providing descriptions for 199
providing images for 199
publishing 204–206
setting properties for 199
specifying default category for 206
specifying editable report elements for 199
specifying non-editable report elements
for 199
viewing 204
report titles 535
report viewer
getting current 224
ReportContent class 358
ReportContent objects 358
reportContext objects 732
ReportExplorer class 487
ReportExplorer components
getting file descriptions for 497
getting files for 497, 498, 499
getting folders for 488
getting latest items 488
getting results definitions for 488
getting timestamps for 499
getting user information for 516
handling events for 489, 495
instantiating 487
loading 331
retrieving data for 491
searching for items for 489, 491, 503, 505
setting container for 490
setting file descriptions for 500
setting file names for 501
setting file types for 500
setting file version for 502
setting folder names for 490
setting folder paths for 492
setting items displayed in 492
setting labels for 492
setting latest version flag for 490
setting results definitions for 491
setting target service URL for 491
setting timestamps for 502
submitting requests for 492
viewing report items and 487
ReportExplorer event constants 495
ReportExplorer global constants 494
Index
793
Reportlet gadgets 349
adding parameters to 58, 260, 264
adding to dashboards 52
displaying data and 50
displaying parameters in 54
displaying report items in 46, 52
Reportlets
generating 280
getting bookmarks for 534
setting bookmarks for 541
setting document mode for 597
reports
accessing data for 220
adding data items to 432
adding Flash objects to 436
adding interactive features to 50, 216, 224
adding QR codes to 121
changing 566
changing connection properties for 718
changing default themes for 118
counting pages in 535, 589
creating 713
customizing 697
deploying 697, 730
designing 122, 238
developing 682
displaying 122, 682
downloading 358, 527
embedding in web pages 224
enabling page-level security for 235–240
exporting 527, 543, 566, 742, 747, 748
formatting 112
generating 122, 682, 742
getting name of transient 377
getting parameters for 374
getting user information for 516
getting version of 499
hiding content in 120
hiding data in 434
including in templates 196
linking to 121, 216
navigating through 537, 546, 570
opening 540, 541
previewing 280
printing 544, 570
reloading 547
rendering 280, 742, 744
794
restricting access to 230, 231
retrieving content from bookmarks 529
retrieving data from 369
retrieving parameters from 377, 383
retrieving specific pages 527, 530, 531, 537
running 682, 746
selecting content in 547, 558
setting locale for 522
setting page breaks for 570
setting parameters for 540
setting version information for 502
standardizing 196
structuring 197
suppressing duplicate values in 572
testing data security for 250
testing page-level security for 240
viewing data in 216
viewing hidden elements in 439
viewing page numbers in 239, 240
viewing table of contents for 560, 561, 573
repositories
displaying content 487
repository access rights 517, 518
repository file paths 338
repository types 521, 523
REPOSITORY_ENCYCLOPEDIA
constant 523
REPOSITORY_STANDALONE constant 523
Request class 359
request objects 359
RequestOptions class 520
RequestOptions objects 333, 520
requestOptions parameter 327, 329
requests
adding filters to 362
adding Flash objects and 439, 444
adding sorters to 362
authenticating 520
displaying charts and 430
displaying cross tabs and 581
displaying dashboards and 344
displaying reports and 544
displaying tables and 481
downloading result sets and 528
failing 333
getting bookmarks for 360
getting options for 328
Actuate BIRT Application Developer Guide
retrieving data and 359, 434
retrieving parameters and 384, 416
retrieving report elements and 473, 486
running Interactive Crosstabs and 600
required parameters 398, 408, 413
requiredFileId value 509, 512
requiredFileName value 509, 513
reset function 593
resetting driller objects 317
resizeTo function 593
resizing
columns 38, 565
dashboard gadgets 37, 44, 46
HTML buttons 227
images 225
Interactive Crosstabs 593, 594, 599
rows 571
viewers 344, 529, 533, 542
resolve method 738
resource files
downloading 694, 695
publishing 691, 692
setting location of 692, 695
resource folder
deploying JAR files to 698
publishing BIRT resources and 692, 695
publishing templates and 202
resource folder URIs 738
resource identifiers 737, 738
resource paths 737, 739
ResourceIdentifiers class 739
ResourceIdentifiers objects 737
resources
accessing 204, 737
BIRT environments and 691
deploying JAR files and 698
publishing 719
thumbnail images and 199
result set objects 364, 528
result sets
accessing data in 364
creating 364
downloading 369, 528, 543
getting content in 365
incrementing data rows for 365
previewing data in 16
referencing 364
retrieving data for 359, 364, 369
sorting values in 362, 366
ResultSet class 364
ResultSet objects 364, 528
role IDs 517, 518
role names 231, 517, 518
roles 230, 695
rollback function 594
Rotation Angle property 170
Rotation property 154, 170
ROUND function 212
round function 212
rounded corners (gadgets) 171
rounding 212
Row Access Control List Expression
property 243
row headings 308
row index values
getting 361
retrieving table data and 478, 608
setting 362, 363
row mirror starting level
getting 653
setting 604, 650, 655
ROW_AXIS_TYPE constant 618
rowMirrorStartingLevel parameter 604, 650
rowPageBreakInterval parameter 650
rows
adding to cross tabs 608, 653
adding to tables 478
controlling access to 243
creating tables and 87
getting first 361
getting index values for 361
getting last 361
getting number of 243
grouping 281, 478
iterating through 365
resizing 571
retrieving result sets and 362, 365
retrieving specific sets of 296, 354
setting index values for 362
setting page breaks for 89, 655
setting page breaks on 653, 656
viewing summary data in 315
.rpttemplate files 198
Index
795
RSA algorithms 703, 704, 709
RSA encryption 711, 714
RSA encryption padding 705
rsa encryption parameter 714
rules
accessing data and 241
EasyScript expressions and map 212
running
applications 699, 737
BIRT projects 686
Interactive Crosstabs 580
JavaScript API library 322
reports 682, 746
run-time parameters 408
S
sample event handlers (charts) 189, 190, 193
sample report document 581
save function 341
saveReportDesign function 538
saveReportDocument function 538
saving
connection profile stores 722
connection profiles 729
dashboard gadgets 43
dashboards 36, 41, 338, 339, 341
encryption keys 714
iHub profiles 29, 683
report designs 198, 571
report documents 538, 571
viewer content 538
Scalable Vector Graphics 542, 598
Scalable Vector Graphics elements 465, 466,
468
Scale Image property 170
scale properties (gadgets) 149, 150
scatter charts 453
See also charts
adding 78
scripting 193
scheduling information 75
scheduling report jobs 746
schemas
databases and 14
scientific data 78
scorecards 50
796
script editor
adding HTML buttons and 219
adding HTML5 charts and 175
handling chart events and 183, 184
interactive features and 138
opening 137, 183
rendering maps and 136, 137
script tag 322
scripting 280
scripts
adding report parameters and 264
BIRT designers and 280
building charts and 182
building maps and 137, 140, 141, 142
building reports and 697
changing user selections and 263, 271, 275
displaying Flash content and 62
linking dashboard gadgets and 257, 263,
275
linking Google gadgets and 273, 275
retrieving gadget content and 259
writing client-side 183, 186
writing server-side 186
scroll bars 546
scroll bars (gadgets) 46
scroll controls 556
scroll panels 556
scrolling 556, 560
ScrollPanel class 556
sealed objects 702
search conditions
getting 506
retrieving files and 503
setting 510
specifying multiple 510
search operations
assigning FileSearch objects to 491
comparing field values and 503
getting FileSearch objects for 489
searching
files 505
list items 503
secret keys 702, 730
sectors (charts) 75, 77
secure read privileges 696
security
accessing data and 241
Actuate BIRT Application Developer Guide
accessing reports and 230, 712
connecting to data sources and 730
disabling or enabling 250
implementing 230, 241
setting on data cubes 246–249
setting on data sets 241–246
testing 240, 250
Security command 235, 239
Security dialog 239, 240, 250
security IDs
adding 230, 231
cascading 238
testing 240, 251
security model (iHub) 230
security role names 231
security roles 230, 695
security rules 241
security types 230
Select Data dialog 201
select function 457, 461
SelectedContent class 558
selection lists 396
selector gadgets. See data selector gadgets
selector group gadgets 100, 105, 106, 107
semicolon (;) character 745
sending e-mail attachments 743
series
See also charts
comparing multiple 72, 73, 76
displaying percentage of whole 72, 73, 76
displaying relationship between 78
displaying relationship to whole 72, 73,
75, 77
enabling user interactions for 185
grouping data for 80
overlapping multiple 71, 76
plotting side-by-side 72, 73
setting appearance 187
showing high and low values 78
showing open and close values 78
stacking multiple 71, 73, 76
series (charts)
adding 446, 452, 459
changing 449
deleting 449, 460
displaying values 293
drilling through 425, 426
getting number of run-time 447
getting values for 447, 448
managing 459
removing 461
replacing 461
setting values for 450, 451
setting visibility of 449, 454, 462
series names 296
series objects 459, 460
server error constants 385, 494
server errors 371, 625
Server Explorer 28, 682, 683
server URLs
getting 328, 520
setting 522
ServerProfiles.dat file 718
servers 743, 746
See also iHub servers
installing custom ODA resources to 700
server-side scripts 140, 186
session information 732
Set Template Property page 199
setAccessRights function 518
setAccessType function 500, 509
setActiveTab function 342
setAggregationFunction function 644, 671
setAppContext method 738
setAscending function 367, 664
setAutoSaveDelay function 342
setAutoSuggestDelay function 380
setAutoSuggestFetchSize function 381
setAutoSuggestListSize function 381
setAutoSuggestThreshold function 409
setAxisType function 618, 637
setBookmark function 361
setCascadingParentName function 409
setChartTitle function 428
setChartType function 453
setChildData function 398
setColumnMirrorStartingLevel function 654
setColumnName function
Data.Filter class 356
Data.Sorter class 367
ParameterDefinition class 409
ParameterValue class 420, 553
setColumnPageBreakInterval function 654
setColumns function 361
Index
797
setColumnType function 409, 420
setCondition function 510
setConditionArray function 510
setContainer function 342, 490
setContentMarg function 539
setContentPanel function 561
setControlType function 410
setCountLimit function 510
setCurrentDisplayName function 410
setCurrentValue function 398
setCustomParameter function 522
setDashboardName function 342
setData function 461
setDataType function
Measure class 645
ParameterDefinition class 410
ParameterValue class 420
setDefaultValue function 411
setDefaultValueIsNull function 411
setDependentFileId function 510
setDependentFileName function 511
setDescription function 500
setDimension function 428, 622
setDimensionName function 618
setDisplayName function 411, 421
setEmptyCellValue function 654
setEnabled function 672
setEnablePageBreak function 655
setExpandedGroups function 381
setExpression function 314, 645
setFetchDirection function 511
setFetchHandle function 511, 515
setFetchSize function 511
setField function 504
setFileType function 500
setFilters function
Chart class 429
Crosstab class 612
FlashObject class 438
Gadget class 442
Request class 361
Table class 480
setFilterType function 632
setFocus function 539
setFolderName function 490
setFont function 382
setGadgetId function 594
798
setGadgetType function 443
setGrantedRoleId function 518
setGrantedRoleName function 518
setGrantedUserId function 519
setGrantedUserName function 519
setGroup function 411, 421
setGroupContainer function 382
setHeight function
Dashboard class 343
Viewer class 539
XTabAnalyzer class 594
setHelpText function 412
setId function 500
setIncludeHiddenObject function 512
setIndex function
Dimension class 618
Level class 639
Measure class 645
setIsAdHoc function 412
setIServerUrl function 522
setIsHidden function 412
setIsMultiSelectControl function 412
setIsPassword function 413
setIsRequired function 413
setIsViewParameter function 413, 421
setItemList function 515
setIVMode function 595
setKey function 664
setLatestVersionOnly function 490
setLayout function 382
setLeft function 595
setLevelAttributeName function 632
setLevelName function
Filter class 633
Level class 640
MemberValue class 649
Sorter class 664
SubTotal class 668
setLevels function 619
setLocale function 522
setLocation function 668
setMatch function 504
setMaxRows function 362
setMeasureDirection function 655
setMeasureIndex function 672
setMeasureName function 646
setMember function 664
Actuate BIRT Application Developer Guide
setMembers function 623
setMouseScrollingEnabled function 557
setName function
File class 501
LevelAttribute class 641
NameValuePair class 391
ParameterDefinition class 414
ParameterValue class 422, 660
setNewAxisType function 619
setNewIndex function 620, 646
setOnClosed function 595
setOperator function 356, 633
setOption function 554
setOwner function 501, 512
setPageCount function 501
setPageNum function 596
setPanInOutEnabled function 557
setParameters function 539
setParameterValues function
Viewer class 540
XTabAnalyzer class 596
setParentData function 399
setPosition function
ParameterDefinition class 414
ParameterValue class 422
XTabAnalyzer class 596
setPrivilegeFilter function 512
setPromptParameter function 422
setReadOnly function 383
setReportDocument function
Viewer class 540
setReportletBookmark function 541
setReportletDocumentMode function 597
setReportName function
Parameter class 383
Viewer class 541
XTabAnalyzer class 580, 597
setRepositoryType function 523
setRequiredFileId function 512
setRequiredFileName function 513
setResultDef function 491
setRowMirrorStartingLevel function 655
setRowPageBreakInterval function 656
setSearch function 491
setSelectNameValueList function 414
setSelectValueList function 414
setSeriesVisible function 449, 454
setService function
Dashboard class 343
Parameter class 383
ReportExplorer class 491
Viewer class 541
XTabAnalyzer class 597
setShowDisplayType function 384
setShowToc function 561
setSize function
Chart class 429
Dashboard class 343
File class 501
Gadget class 443
HTML5Chart Renderer class 470
Viewer class 542
setSorters function
Crosstab class 316, 612
Request class 362
Table class 480
setStartingFolder function 492
setStartRow function 362
setSubType function 430
setSupportSVG function 542, 598
setTemplate function 344
setTimeStamp function 502
setTitle function 450, 454
setTop function 598
setTotalCount function 515
setTotals function
Crosstab class 612
GrandTotal class 637
SubTotal class 669
setUIOptions function
Viewer class 542
XTabAnalyzer class 598
setUseDescriptionAsLabel function 492
setUserPermissions function 502
setValue function
NameValuePair class 391
ParameterValue class 422
viewer.ParameterValue class 553
XTabAnalyzer.MemberValue class 649
XTabAnalyzer.ParameterValue class 661
setValueIsNull function
ParameterValue class 423, 661
viewer class 553
Index
799
setValues function
ClientChart class 450
Data.Filter class 357
XTabAnalyzer.Filter class 633
setVersion function 502
setVersionName function 502
setViewingMode function 543
setVisible function 462
setVolume function 523
setVolumeProfile function 523
setWebService function 399
setWidth function
Dashboard class 344
Viewer class 543
XTabAnalyzer class 599
setXAxisRange function 450
setXAxisTitle function 454
setXTabBookmark function 599
setXTabIid function 599
setYAxisRange function 451
setYAxisTitle function 454
shadows
dashboard gadgets 164
maps 134
shadows. See drop shadows
Shape property 152, 162
shapes (add-ons) 167
shapes (charts) 190
shared icon (dashboards) 41
shared resources 204, 692
Shindig application 266
Short Name in Tool Tip property 134
Show as Dashed property 170
Show as Dot property 163
Show as Zone property 160
Show Border property
add-on objects 171
gadgets 148, 154
maps 134
meter thresholds 160
value indicators 165
Show Close Value property 163
Show Dial Values property 148
Show Entity Tool Tip property 134
show function
Chart class 430
ClientSeries class 463
800
DataItem class 434
FlashObject class 439
Gadget class 444
Label class 473
Table class 480
TextItem class 485
Show High and Low Values property 163
Show Labels property 134, 156
Show Legend property 134
Show Limits Value property 158
Show Marker property 160
Show Needle On property 148
Show Needle Value property 149
Show Open Value property 164
Show Period Bars property 164
Show Round Corners property 171
Show Shadow property 164
Show Threshold property 160
Show Tick Marks property 158
Show Tick Values property 158
Show Tooltip property 166
Show Value Inside property 160
Show Value Label property 164
Show Value on Top property 160
Show Value property 149, 152, 160
showColumn function 481
showDetail function
Crosstab class 319, 613
Table class 481
showDownloadReportDialog function 543
showDownloadResultSetDialog function 543
showFacebookCommentPanel function 544
showFoldersOnly function 492
showParameterPanel function 544
showPrintDialog function 544
showTabNavigation function 344
showToc flag 560, 561
showTocPanel function 544
side-by-side chart subtypes 72
Sides property 171
Size property
add-ons 171
anchors 162
fonts 166
needle base 154
needles 152
threshold markers 160
Actuate BIRT Application Developer Guide
slider gadgets 101
SOAP message error descriptions 371, 625
SOAP messages
binding to web service operations 399
sort conditions 366, 662
sort feature 563, 572
sort keys 662, 664
sort order
setting 366, 367, 664
testing for 367, 663
Sorter class 316, 366, 662
sorter object arrays 362, 612
sorter objects 316, 362, 366, 662
sorters
creating 316, 366, 662
getting column names for 366
sending requests for 361, 362
setting column names for 367
setting sort order for 367, 664
sorting data and 316
specifying specific tables for 480
testing sort order for 367, 663
sorting data 316, 362
by groups 123
HTML buttons and 216
source 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
displaying embedded HTML 62
displaying user selection values and 261
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
space characters 61
spark gadgets 443
sparkline gadgets 95, 96, 161, 162, 166
spider radar charts 77
SQL query builder 725
SQL statements
See also queries
validating 16
square brackets ([]) characters 212
SSL3Padding encryption mode 705
stacked chart subtypes 71, 73, 76
Standard Deviation function 89, 93
Start Angle property 147, 149, 171
Start Color property 154, 171
Start Label property 136
Start Value property 156, 160
Start X Coordinate property 149
Start X coordinate property 171
Start Y Coordinate property 149
Start Y coordinate property 171
static text
creating HTML buttons and 216
statistical data 78
stock chart gadgets 255
stock chart subtypes 78
stock charts 78
adding 78
stocks, tracking value of 255
string pattern operators 353, 354
strings
filtering files and 503
formatting values 103
running reports and 540
style properties
chart themes 179
interactive charts 176
Style property 149
style sheets
accessing custom 39
adding to Google gadgets 267
styles
applying 118
creating 202
designing themes and 196, 201, 202
Index
801
submit function
actions and 296
Chart class 430
Crosstab class 613
Dashboard class 344
DataItem class 434
FlashObject class 439
Gadget class 444
Label class 473
Parameter class 384
ReportExplorer class 492
Table class 481
TextItem class 485
Viewer class 544
XTabAnalyzer class 600
subscribe method 271, 273
Sub-Title property 149
SubTotal class 315, 666
subtotals 315, 612, 666, 669
Suffix property 154
Sum function 81, 89, 93, 97
summary data
adding 308, 310, 315
deleting 316
generating 81
generating grand totals and 315, 635
generating subtotals and 315, 612, 666
getting aggregate function for 670
getting level names for 667
getting location name for 667
getting type names for 668
setting aggregation function for 671
setting level names for 668
setting location of 668
summary tables 123
summary values
See also aggregation
SVG elements 465, 466, 468
SVG flag 542, 598
SVG path commands 469
swapColumns function 482
switch view feature 572
symmetric encryption 703, 704
symmetric encryption keys 713, 714
symmetric encryption types 704
SymmetricKeyGenerator class 713, 714
802
T
Tab class 351
tab objects 351
tab type constants 351
table bookmarks 296, 476
Table Builder 87
Table class 475
table elements 475
placing in templates 200
table gadgets
adding 34, 86
displaying data in 84, 87
formatting 89
linking to data selection gadgets 87
setting display options for 87
table headers 281
table names 476, 477
table objects 475
table of contents (reports)
displaying 560, 561
enabling or disabling 573
table of contents panel 544
tables
adding page breaks to 652, 655
creating reports and 123
displaying 296, 475
displaying data in 84, 86
enabling page-level security for 235, 237
filtering data in 295, 476, 480
formatting 118
getting columns in 476
getting instance ID of 477
getting number of rows in 243
getting rows for 478
grouping rows in 281, 478
hiding 242, 479
hiding columns in 479
hiding columns or rows in 119
hiding data in 479
linking to data in 88
removing groups from 479
reordering columns in 482, 569, 571
resizing columns in 565
resizing rows in 571
retrieving 296, 534, 550
showing columns in 481
Actuate BIRT Application Developer Guide
showing groups in 481
submitting requests for 481
suppressing duplicate values in 572
tabs feature (Google gadgets) 270
tabs. See dashboard tabs
tabular data formats 85
target service URL 491, 541
temperature data 74, 78
template categories 206
Template Category property 206
template files 198, 199, 337
Template Image property 199
Template page 199
template paths 344
templates
accessing resources for 204
adding report elements to 196, 197, 199
adding themes to 196, 201–204
associating libraries with 202
building dashboards and 43
changing styles in 196
creating 198–199
designing reports and 197
excluding data sets in 201
localizing 198, 204
naming 199
providing data with 200
providing descriptions for 199
providing images for 199
publishing 204–206
setting properties for 199
specifying default category for 206
specifying editable report elements for 199
specifying non-editable report elements
for 199
viewing 204
temporary messages 269
testing
BIRT applications 686
connection profiles 722
connections 330, 725
data security 250
HTML buttons 218, 225
page-level security 240
report emitters 744
scripts 280
security IDs 240, 251
text
adding QR codes and 121
adding to charts 190
adding to dashboards 64
adding to gadgets 154, 166, 167
adding to HTML buttons 217, 225
adding to maps 134
adding to numeric values 154
creating tooltips and 138
displaying 534
getting from downloaded content 358
getting from text elements 485
getting label 472
HTML buttons appearing as 216
localizing 204
providing informational 198
setting color of 166
wrapping 171
text alignment (gadgets) 46, 170, 171
text boxes 152, 171
text editing feature 573
text elements 483, 485, 551
text file data sources 200
text files 718, 726
building maps and 132
text function 470
text gadgets 64
text graphic elements 470
text item objects 483
text items 483, 484, 485
text objects 534
Text Wrap property 171
TextBox Background Color property 171
TextBox Border Color property 171
TextItem class 483
theme builder (charts) 178, 179, 181
theme names 179
Theme property 119, 177
themes
creating 196, 201–204
dashboard charts 82
HTML5 charts 176, 177, 179
renaming 202
standardizing reports and 118, 119
updating 196
Themes list 202
ThemesReportItems3.rptlibrary 118, 179
Index
803
thermometer gadgets 96, 98, 443
Thickness property 171
thisGadget objects 260, 264
3D charts 428
Threshold Line property 161
threshold markers (gadgets) 160
threshold properties (gadgets) 158, 159
Threshold property 160
threshold values (gadgets) 158
Threshold Zone property 161
thumbnail images (templates) 199, 204
tick marks (gadgets) 149, 156
tick properties (gadgets) 156, 157
tick values (gadgets) 157
Ticks Inside property 158
time dimensions (cubes) 311
time range selector 84
time stamps
getting 499
setting 502
time values 353
formatting 103
plotting 71, 75, 84
timeline sliders 84
Title property 149
titles
charts 425, 426, 428, 429
formatting chart 82
reports 535
Tomcat servers 746
toolbar help feature 574
toolbar save feature 676
toolbars
disabling 675
Interactive Crosstabs 675
viewers 573
toolbars (gadgets) 46, 50
tooltip properties (gadgets) 165
Tooltip property 152, 161, 171
tooltips 293, 572
chart series 184
chart themes 180
gadget add-ons 171
gadgets 152, 161, 165
maps 134, 138
top N filter feature 574
Top Width property 152
804
TOP_N operator 354, 629
TOP_PERCENT operator 354, 629
Total class 315, 670
total objects 316, 668, 670
Total Page element 240
totals
adding grand totals and 635, 637
adding to subtotals 612, 666, 669
enabling or disabling 671, 672
getting 636, 668
returning axis type for 636
returning index values for 671
returning type 637
setting axis type for 637
setting index values for 672
threshold values and 158
viewing in charts 293
viewing in cross tabs 315, 670
trailing zeros 154
transient files
getting names 377
Transparent property 171
trends 68
triple-DES encryption 703
TRUE operator 354, 629
truncated images 225
Turn Off All Animations property 149
Turn Off Default Animations property 149
tutorials
building dashboards 19–26
building data objects 10–19
deploying the BIRT application 27–30
U
UI configuration objects 535, 560
UI elements 398
UIConfig class 560
UIOptions class
Viewer 562
XTabAnalyzer 318, 674
uncategorized exceptions 371
underscore (_) character
pattern matching 214
undo feature 575
unique values 98
update function 458
Actuate BIRT Application Developer Guide
updating
connection profiles 718, 729, 731
cross tabs 317
dashboard gadgets 52
dashboards 39
data 398
Java classes 698
themes 196
user selections 258, 272
uploading image files 225
URIs 738, 739
URL parameters
authentication requests and 327, 383
returning custom parameters in 522
URL property 171
URLs
accessing JavaScript library and 322
accessing web services and 597
connection profile stores 732
displaying 60
external image files and 63
external web content and 60, 63, 64
getting 328, 335, 520
Google Gadget API reference 269
Google Gadget Developer’s Guide 268
Google gadget files 266
Highcharts documentation 180
image files 171
map event handlers and 139
retrieving parameters and 383
returning default web service 328
returning failed requests for 333
returning from exception objects 333
setting server 522
setting target service 491, 541
storing 121
testing connections for 330
video files and 65
usage error constants 385, 494
usage errors 371, 626
UsageInBRS property 201
Use Glass Style property 176
Use Hover Effect property 134
Use Library command 203
Use Library dialog 203, 204
usePersonalDashboard function 345
user credentials 327
user groups 241, 696
user IDs
authentication and 327, 334
privilege filters and 517, 519
user information 516
user interface configuration objects 535, 560
user interface elements 398
user interface options
enabling 562
getting 535, 589
hiding 319
setting Interactive Crosstabs 598, 674
setting viewer 542
user interfaces 738
browsing repository contents and 487
enabling or disabling Interactive Crosstabs
viewer 318
user names 230
connection profiles and 732
filtering privileges and 518, 519
userID parameter 327
userid variable 327, 330
users
assigning privileges 35, 230, 695, 696
assigning roles 230
obtaining security information for 241
providing tooltips for 199
restricting access to 230, 231, 241
user-selection values
changing 258, 263, 271, 275
displaying 254, 261, 271
organizing 104
setting default parameters for 53
updating 258, 272
V
Validate Data page 131
validating expressions 214
value indicator (gadgets) 163, 164
value indicator properties (gadgets) 164
value parameter 296
Value property (gadgets) 152
value series
selecting data for 80
value series (charts)
getting maximum values 448
Index
805
value series (charts) (continued)
getting minimum values 448
interactive features and 293
setting value range for 451
three-dimensional charts and 428
Value Textbox X Co-ordinate property 152
Value Textbox Y Co-ordinate property 152
valueData variable 296
valueIsNull value 419, 553
values
See also data
abbreviating numeric 134, 154
aggregating. See aggregation
averaging 81
cascading 105, 106
changing HTML button 227
changing parameter 389, 400
changing user selection 258, 263, 271, 275
converting 386
counting 81
creating tooltips for 199
disabling gadget 149, 152, 158, 160, 164
disabling or enabling location 134
displaying first or last 81, 161
displaying highest or lowest 74, 78, 81,
150, 158, 161, 163
displaying open or close 78, 163
displaying small sets of 77
downloading parameters and 376
filtering cross tabs and 628
filtering locale-specific data and 353
filtering top or bottom 574
generating summary 315
getting default 405
getting empty cell 652
getting level 649
getting list of 407
getting parameter 419, 552, 553, 588
getting series 447, 448
matching set of 353, 354
matching top or bottom 353
plotting over time 71, 75, 84
plotting percentages to whole 72, 73, 76
plotting relationship to whole 72, 73, 75,
77, 78
prompting for 400, 419, 422
removing duplicate 460
806
returning specific 365, 433
returning sum of 81
returning unique 98
rounding 212
selecting 412
selecting multiple 87, 92, 106, 107
selecting non-adjacent 100
setting default 55, 411
setting display names for 390
setting empty cell 604, 654
setting level 649
setting parameter 416, 552, 661
setting series 450
showing deviation among 74, 89
showing differences between 89
showing most frequently occurring 89
specifying null 423, 553, 661
suppressing duplicate 572
testing for null 354, 629, 660
tracking stock 255
updating user selection 258, 272
viewing as bubbles 73
viewing threshold 158, 160
viewing user selection 254, 261, 271, 272
Values Inside property 158
valueSeriesName variable 296
variables
accessing event handler 221
HTML buttons and 221, 223
linking to dashboard gadgets and 257
naming 223
unloading JavaScript 378, 489
writing user selection values to 263
Variables page 223
Variance function 89, 93
vector graphics elements 465, 466, 468
Vector Markup Language graphics
elements 465, 468, 469
version gadgets. See data version gadgets
version information 499, 502
version names 502
Version property 206
versioning options 206
Vertical property 171
video files 65
video gadgets 65
view parameter 268
Actuate BIRT Application Developer Guide
view parameters
setting 413
View Report with Data Security
command 250
View Report with Page Security
command 240
Viewer class 280, 524
viewer classes 325
viewer components 331, 524
viewer event constants 547
viewer IDs 551, 657
viewer objects 524, 590
viewer variable 582
ViewerException class 576
viewers
accessing report content for 528
adding interactive features to 293
building user interface for 487
determining status of 538
disabling 526
displaying charts in 296, 528, 548
displaying reports in 524
enabling interactive features for 528, 560,
562
getting browser size for 529
getting content for 528, 529, 530, 531
getting file names for 534
getting margins for 530
getting size 533, 537
getting specific instance 329, 535
getting UI options for 535
handling events for 547
handling exceptions for 576
launching 569
loading 280
reloading 544
resizing 344, 529, 533, 542
saving contents 538
scrolling in 546, 556, 560
selecting content in 558
sessions timing out and 624
setting focus for 539
setting margins for 539
setting size 539, 542, 543
setting UI options for 542
showing main menu in 569
showing toolbar help in 574
showing toolbars in 573
submitting requests for 544
switching views 572
viewing
aggregate values 308
columns 481
cross tabs 308, 312, 580, 657
dashboard gadgets 35
data 216, 650
data cubes 310, 675
data items 434
data series 449, 454, 462
database schemas 14
external content 50, 60
Flash content 62
Flash objects 436, 439, 444
folders 492
HTML5 charts 463
image files 63
Interactive Crosstabs features 318
label elements 473, 533
libraries 204
output formats 746
page number elements 239
parameter groups 382
plug-ins 743
QR barcodes 121, 122
report designs 50
report documents 50
report elements 50, 198, 202
report items 568
report parameters 54, 108, 264, 374, 400
report templates 204
Reportlets 534
reports 122, 682
source code 62
standard charts 430
summary data 315, 635, 666, 670
table elements 481
table of contents 560, 561, 573
tables 296, 475
temporary messages 269
text 484, 485, 534
threshold values 158, 160
toolbars 573, 675
tooltips 572
URLs 60
Index
807
viewing (continued)
user selections 254, 261, 271, 275
video files 65
Viewing Angle property 149
viewing mode (dashboards) 543
viewing mode constants 543
viewing restrictions 238
views (Google gadgets) 267
views, switching 572
view-time parameters 408, 420, 421
Visibilities property 162
Visibility property
table columns 120
Visible Page Number property 240
visible privileges 696
visual report elements 196
visualization gadgets. See data visualization
gadgets
VML graphics elements 465, 468, 469
volume file paths 338
volume profiles 521, 523
volume variable 327, 330
volumes
getting specific 521
setting profiles for 523
specifying 523
W
war files 700
web applications 60, 174
customizing content for 322
web browser content panels 546
web browser exceptions 371
web browser windows 529
web browsers 261
getting exception descriptions for 371
rendering output for 465
viewer events and 296
web page redirection 61
web pages
accessing class libraries for 322
adding interactive features to 314
adding report components to 326
displaying content from 60, 63
displaying cross tabs in 580
displaying reports as 331, 524
808
embedding reports in 224
enabling SVG support for 542, 598
retrieving data for 358
web service connections 369
web services
closing connections to 332
displaying dashboards and 343
getting default URL for 328
linking parameters to 383
opening connections for 329
sending SOAP messages over 399
setting URLs for 491, 541, 597
web sites 60
Web Viewer (BIRT) 744, 748
Width property
gadget borders 149
gadgets 161, 165
HTML buttons 225
Windows systems 729
wmode parameter 62
Word document output formats 527
Word documents 742
workgroup repository type 523
worksheets 554
world map 255
wrapping text 171
write privileges 696
X
x-axis labels (charts) 454
x-axis values (charts)
adding interactive features to 293
returning maximum value for 447
returning minimum value for 448
setting data points for 462
setting range for 450
x-axis values. See axes values
XHTML formats 742
XLS formats 742
XLSX formats 742
XML documents 742
XML files 200
XML formats 742
XTabAnalyzer class 312, 580, 584
xtabAnalyzer components 331
XTabAnalyzer event constants 624
Actuate BIRT Application Developer Guide
XTabAnalyzer exception objects 625
Y
y-axis labels (charts) 454
y-axis values (charts)
adding interactive features to 293
converting chart dimensions and 428
returning maximum value for 448
returning minimum value for 448
setting data points for 462
setting value range for 451
y-axis values. See axes values
Z
z order 168
zoom settings (charts) 83
zooming 557
ZXing QR code generator 121
Index
809
810
Actuate BIRT Application Developer Guide
Source Exif Data:
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
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : Yes XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:08:04 Format : application/pdf Creator : Actuate Corporation Title : Actuate BIRT Application Developer Guide Create Date : 2014:12:01 18:08:04Z Creator Tool : FrameMaker 11.0.2 Modify Date : 2014:12:01 18:08:04Z Web Statement : www.actuate.com Producer : Acrobat Distiller 9.5.5 (Windows) Copyright : 1995-2013 by Actuate Corporation. All rights reserved. Printed in the United States of America Copyright Status : Copyrighted Document ID : uuid:80f6fc4c-2739-4863-b200-d0c4c48b7056 Instance ID : uuid:e64802e3-8749-42b7-93fa-b028edc4d5c8 Page Layout : SinglePage Page Mode : UseOutlines Page Count : 828 Author : Actuate CorporationEXIF Metadata provided by EXIF.tools