Multiple Interacting Parameters

In this project we look at how to create two parameters on a BIRT report which interact with each other. The example we use is a list of customers from which the user can select one or many non-contiguous ranges of customers to report on, but we have added a check box to the parameter screen, which, if checked, will run the report for all customers.

2010

Paul Bappoo Paul@BirtReporting.com

http://www.BirtReporting.com

September 2010

CONTENTS

How To Contact The Author ........................................................................................................................... 4

Introduction .................................................................................................................................................... 5

The Basic Report ............................................................................................................................................. 6

The Report Parameters .................................................................................................................................. 8

The Magic ..................................................................................................................................................... 11

Running the Report ...................................................................................................................................... 13

More Information ......................................................................................................................................... 15

Paul Bappoo – Multiple Interacting Parameters

© COPYRIGHT 2009 by Paul Bappoo, all rights reserved.

This guide is furnished under license and may be used or copied only in accordance with the terms of such license. The content of this

guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by the

author. The author assumes no responsibility or liability for any errors or inaccuracies that may appear in this guide.

Except as permitted by such license, no part of this publication may be reproduced, stored in a retrieval system or transmitted, in any form

or by any means, electronic, mechanical, recording or otherwise, without the prior written permission of the author.

All product and company names are trademarks or registered trademarks of their respective holders.

HOW TO CONTACT THE AUTHOR

Email: Paul@BirtReporting.com

Web Site: http://www.BirtReporting.com

Paul Bappoo is the author of BIRT for Beginners (which is available in paperback from BIRTReporting.com,

Amazon and Barnes and Noble amongst others) and has been an international technical software

consultant and involved with computers for over 30 years. Paul has an interest in BIRT reporting,

enterprise application integration, automated software testing, computer based training and enterprise

system implementation. Paul runs the BIRT User Group UK and is a member of the BIRT-Exchange Advisory

Council. He would be delighted to hear from you with your tips, tricks and stories about your usage of

BIRT. If you have a question, a need for training or consulting or great tip to share with the community

then drop him a line.

INTRODUCTION

A reader of BIRTReporting.com came up with a great question this week.

He needed to create a set of parameters on a BIRT report that allowed the user to select

from a list of customers. The selection had to allow for just a single customer to be

selected, or for a range or multiple, non-contiguous ranges or customers to be selected.

Plus he wanted to allow the user to click a single check box to select all customers if

required.

This is a fairly common scenario so I set to work figuring out how it could be achieved

and present the result to you in this “Do try it at home” mini-project.

The rptdesign file is included in the download, was written in BIRT 2.5.1 and runs over

the Classic Models database, so you should be able to run the example quite easily.

Here’s a screen shot of the parameter screen showing multiple ranges selected and the

“Select All” tick box:

Submit a Tip

As you become more familiar with BIRT please submit a tip that you think other users will

find useful. Just email your tip to Paul@BIRTReporting.com it doesn’t matter how simple

your tip is send it anyway, we are pleased to receive all suggestions.

THE BASIC REPORT

Start by creating a basic listing report over the customers table of Classic Models. Your

report should look something like this:

Now add a second data set which provides a full list of all customer numbers and

names. We are going to use this to provide out list of customers for the parameter

screen.

You will recall from my previous tutorials that you would usually enter a report parameter

placeholder using a question mark into the SQL query for your main report. In this case

we are not going to do that, since we are going to amend the query string to apply the

filter later on.

Your report design should look something like this:

Notice how the main data set “CustomersAllFields” shows the list of all the fields from

the customers table. This is the dataset that is used to return data to the report and the

smaller dataset “CustomerNumberAndName” is the one that we will use to present the

list of customers to the user.

The reason for having two data sets is that, if one data set is filtered by a parameter, it

wont return any data until the parameter has been entered, so you cant use it to present

a list of parameter values to the user at run time, because they haven’t selected a

parameter value yet and the list would be empty! Actually that is not strictly true in this

case, because as you will see we only add the filter to the SQL query after the

parameters are selected, but it is a good design principle to stick to for most cases.

Also, notice how we are using two fields in the “CustomerNumberAndName” dataset.

This is so that we can show the user a list of easily recognisable customer names in the

select list, but then use the associated customer number in our code, where we build the

query filter. This is important when dealing with text data, such as customer names since

text fields can contain certain characters like single quotes, which can cause us

problems when building SQL statements out of them. It is far easier to use the numeric

customer ID in the query building phase.

THE REPORT PARAMETERS

Now add two parameters to your report, called Customer and All Customers.

Here is the detail for the customer parameter:

You can see that it is of type “list box”, it is dynamic and it uses the

CustomerNumberAndName data set to provide the list of values to the user. It also

allows the user to see the CUSTOMERNAME values by the selection we made in the

“Select display text” field and it returns the CUSTOMERNUMBER to the query due to the

selection in the “Select value column” field.

Here is the setup for the AllCustomers parameter. This is a check box, that returns a

Boolean value. The prompt text has been set to “Select All Customers”.

THE MAGIC

The magic in this report is performed in a small piece of Javascript that we add to the

beforeOpen event of the main report data set.

Select the data set, in our case CustomersAllFields and click on the script tab at the

bottom of the main design window. Then ensure that the beforeOpen event is selected in

the Script drop down.

Next copy in the following script:

//Get the report parameters

ParamCustomer = reportContext.getParameterValue("Customer");

ParamAllCustomers = reportContext.getParameterValue("AllCustomers");

//Generate comma seperated list of customers

CustomerList ="";

i = 0

for (i; i<ParamCustomer.length; i++)

{

CustomerList += ParamCustomer[i] + ","

};

//Remove final comma

CustomerList=CustomerList.substring(0,CustomerList.length-1);

//If all customers was not selected then add the customer list to the

query

if (ParamAllCustomers==false)

{

this.queryText += " WHERE Customernumber IN (" + CustomerList +")";

}

You can see here that we first pick up the report parameters from the user entry, using the getParameterValue function. So the ParamCustomer variable will contain the list of customer numbers that the user selected and the ParamAllCustomers will contain a true or false depending on if the user selected the check box. Actually the ParamCustomer variable contains a pointer to an internal BIRT object, which contains our list of customers and our task is to extract the customer numbers, join them up into a valid WHERE clause and apply this to our SQL query, but only if the user did not check the All Customers check box. First we generate a comma separated list of customers by running a for loop over the ParamCustomer object. We set the CustomerList variable to blank and initialise a counter i to zero. The for loop increments i while i is less than the length (i.e. the number of entries) of ParamCustomer. For each ParamCustomer entry we add the value (followed by a comma) to the CustomerList. This give us a list of customer numbers like this: 112,145,231,245, We then need to strip off the final comma so we can use the list in our SQL WHERE clause.

Finally we check that the user has not selected the all customers check box and if not, we add the WHERE clause containing our list of customer numbers to our initial SQL statement from the data set.

RUNNING THE REPORT

When the report is executed, the parameter entry screen is displayed as follows:

The user can use CTRL and/or SHIFT to make multiple non-contiguous selections from

the list of customers and the report returns details for just the selected customers.

If the user selects the check box, then the additional SQL WHERE clause is not applied

and the report displays all customers, regardless of selections in the customer list box.

MORE INFORMATION

This book, written by Paul Bappoo, the founder of the BIRT User Group UK presents an overview of the open source BIRT tools and the commercial enhancements available from Actuate, including...

Eclipse BIRT Designer

Actuate BIRT Designer

iServer Express

Interactive BIRT viewer

Actuate BIRT Studio

BIRT Spreadsheet Designer

With walkthrough tutorials of the main features, including screenshots, from installation through data selection to formatting reports and fully graphical Flash charting this book will have you creating your own reports from scratch in only a couple of hours.

If you are too busy to spend days learning software and want tangible results fast then BIRT For Beginners is for you.

When you buy the book you will automatically get access to the readers section of this web site which includes BIRT report request forms that you can distribute to your end users, extra chapters in PDF format and an ever growing library of reports, tutorials, reviews, tips & tricks.

Buy the book and get free membership of BIRT Reporting and the BIRT User Group UK

at:

http://www.BIRTReporting.com

Please feel free to share this address with your colleagues and inspire them to use BIRT

to create great looking reports.

I look forward to your feedback so please feel free to send me an email and let me know

how you get on with BIRT, provide feedback on this guide, share your tips and tricks, or

request help for specific problems. I can’t guarantee to personally solve everyone’s

problems but there are some great BIRT related forums out there and you can find a

growing list of links and resources on my site.