Birt required / facultative parameters
- Parameters dialog automatically displayed or not?
- Report parameters default values are very important in the reportlet engine
- 'All values' feature in list parameters
- Portlet preferences
Why the parameters dialog is almost never automatically displayed?
If you already tried your own reports with the reportlet, you probably noticed it is not keeping asking you the required parameters with a popup dialog. All has been done in the reportlet so that the popup parameters dialog will almost never have to be displayed automatically. Imagine you aggregate 4 reportlet windows on a unique page, it would not be very user-friendly if each of them keep displaying its parameters when the page is refreshed. A few rules are applied to decide if the popup parameters dialog must be displayed or not:
- No default value is set up for this parameter in your report design
- No value has already been set for this parameter in preferences mode
- No value is found in user session (if the report has already been run in current session, parameters values are persistent even after a page refresh)
This behavior is very different from Eclipse WebViewer and Birt designer, which always display a parameters dialog when at least a report parameter is required.
Birt Default values & 'All values' items
In Eclipse designer, It is possible to set each report parameter as required or facultative. Have a look on this screen:
The first list relates to a required combobox parameter, the second to a facultative one. You can notice when a such parameter is not required, a specific "All values" item is added at the end of the list.
The value returned by this item is:
- The value of a specific custom property '_allvalues' if it is defined for this report parameter (see screenshot below)
- else the BIRT default value of the report parameter if it is defined
- else an empty string/null value
In Eclipse designer we should declare this user property '_allvalues' as a string , even if the parameter has an integer type. If we declare it as integer BIRT might introduce some decimal separator ("0.0" instead of "0" for example) which could cause troubles.
For example, from final v1.0 the " interactive-table " demo report has been updated like this:
- "Country" parameter has now a BIRT default value "USA" and a custom property "_allvalues" set to "all"
- "Year" parameter has now a BIRT default value "2010" and a custom property "_allvalues" set to "-1"
- The other parameters are unchanged, so their "All values" item still use their respective BIRT default value
In this example, both "all" and "-1" values are processed by the dataset query so that they return all rows .
How to handle "All values" item with a specific value in your SQL queries?
Note from v0.9.4 it is possible to use a "Null" defaut value (let it blank in Birt designer), whatever the datatype is. With our example, the query would be:
You may wonder why a constant value has not been chosen instead of default values: a such constant can't be used because a parameter may be an integer, a text, a date, etc. Of course we could arbitrarily utilize a constant for each datatype (-9999999 for numbers, an empty string for texts, 9999-01-01 for dates etc.) , or even "Null", but it would probably be too much intrusive: for example, you may have existing stored procedures, web service datasources etc which already work with specific values, therefore it seems to be a better option to let each project manage its own fictive codes for each parameter.
Report parameters in portlet preferences
If you set report parameters in "preferences" mode, as shown in the screen below, these parameters values are stored as portlet preferences in your portal database. From a user point of view, the report will run by default with these stored values, instead of BIRT default values. Here is a summary of the priority order used by the reportlet to select which value to apply when running a report:
values set by users > values in session > values in preferences > default values in BIRT report design
26 October 2015
14 October 2015
08 October 2015
10 September 2015
07 April 2015
01 April 2015
01 April 2015
23 March 2015
23 March 2015
02 December 2014