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