blob: fd1816e5a7659544c03c297a42b15dd9e9092ef2 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 transitional//EN">
<title>BIRT FAQ</title>
<link rel="stylesheet" href="../style/compose.css" type="text/css"/>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<p class="head">BIRT FAQ</p>
<p class="subhead">Report Parameters</p>
<h2>Q: How can my user enter information to be passed to the report?</div> </h2>
BIRT provides <i>report parameters</i> for this task. The report UI will prompt
the user
to enter the parameter values; the values will be available within the report
where they can be displayed, passed to a query, used in expressions, etc.
Report parameters provide the following properties: Allow null value, Allow
blank values. What are they for? What is the difference?</h2>
Databases support a null value. If the user wants to find null values, then he
must enter a special value that can be interpreted as null. For numbers &amp; dates
this is no problem; BIRT simply interprets an empty entry as a null value. For
strings, however, there is an ambiguity. Should an empty string mean an empty
string or a null string? (They are different: empty string means: &quot;I know the
value, and that value is an empty string&quot;, while null means &quot;I don't know the
<p>Now, the properties. Allow blank says whether a string can take a blank value.
(For example, you've got a report about divisions, and the user must enter a
division code.) Allow null says whether to allow a null value (blank entry) for
numbers and dates.
Further, the UI for a string parameter will have some way to indicate that the
user wants a null value (instead of empty string). The allow null property says
whether to display this additional bit of UI (and hence allow the user to submit
a null value.)
<p>The value rule is: populate the UI with the default value (which can be null or
blank.) Let the user enter a value. Then check if the value the user entered (or
left from the default) meets the rules. If the value is null or blank when the
parameter does not allow it, then a runtime error occurs.
<h2>Report parameter provide a Hidden property. Does this it from the parameter
prompt dialog? Why would I want to hide a report parameter?</h2>
You would hide a report parameter if your application will set it via code. For
example, a web app might show a report for your account. The account number is a
hidden parameter; the application code sets it based on your login: the report
won't allow you to type in someone else's account code.<p>
<h2>What does the report parameter Format property do?</h2>
This allows parameter UIs to format the parameter value within the UI. For
example, suppose your report has a parameter for a dollar amount. When you first
see the page that contains a dollar amount, you'd see:</p>
<pre class="code-block">Find Orders Over: [ $10,000.00]</pre>
You'd click in the field and you'd see:</p>
<pre class="code-block">Find Orders Over: [10000.00| ]</pre>
Where the vertical bar represents the insert caret. Next, you type in a different value:<p>
<pre class="code-block">Find Orders Over: [1234.56| ]</pre>
You click elsewhere and the value becomes:</p>
<pre class="code-block">Find Orders Over: [ $1,234.56]</pre>
This kind of formatting can't be done with a plain HTML page (such as that used
by the BIRT web app), so the format property is not used, at present, by the
BIRT parameter entry UI.<p>
We've found that many people misunderstood the format to be the input
format. In actual fact, the parameter format is entirely for displaying
parameter values in parameter UI, and does not in any way specify what the user
should type.<h1>Parameter API</h1>
<h2>Q: Is there an API for this?</h2>
Yes, BIRT provides an API for working with parameters. BIRT also provides a
a default UI that prompts the user for parameter values.
<h2>Q: Can my application provide some of the values?</h2>
In some cases, parameter values can be provided by the application based on its
current state. For example, provide the transaction history for the current
customer account. The application knows the current account, so it just needs
to ask for the history parameters.
No problem. Because BIRT is an "embedded" reporting solution, it assumes
that the application will pass in any needed context information. You'd create
a custom parameter UI that asks only for the "extra" parameters.