Previous TopicNext Topic


ScalarParameter

The ScalarParameter element defines a simple single-value parameter. A scalar parameter can provide a selection list. The list can be static, defined by the selectionList property, or it can be dynamic, defined by the dataSet and labelExpr properties. You can select a value from the list or enter a value not in the list, as controlled by the mustMatch property.

BIRT uses the following rules to determine the selection list:

Extends

DesignElement->ReportElement->Parameter

Property summary

Inherited properties

comments, customXml, extends, name, userProperties

Inherited method

validate

Slot summary

None

Method summary

None

ScalarParameter properties

The following sections describe the ScalarParameter properties.

alignment

How the items should appear in the user interface. The following table itemizes the choices for this property.

Name
Display name
Value
Description
auto
Auto
auto
Numbers are left-aligned, all others are right-aligned.
left
Left
left
Values are left-aligned.
center
Center
center
Values are centered.
right
Right
right
Values are right-aligned.

allowBlank

A boolean value that determines whether to allow a blank value for string parameters. The default value for this property is true, allow a blank value. This property is ignored for parameters of type other than string.

allowNull

A boolean value that determines whether the value of the parameter can be null. The default is false, in which case the user must enter a value for the parameter if no default is provided.

concealValue

A boolean value that determines whether to hide the user's entry by displaying asterisks or similar characters. Often used for passwords. This property hides the user's entry by displaying asterisks or similar characters. The default is to show the entry in plain text.

controlType

The suggested type of UI control to use when displaying the parameter. The default depends on the parameter properties:

B IRT renders the list-box control in the UI depending on the value of the mustMatch property. If mustMatch is true, the user much choose a value from the list and the control is rendered as a UI list box. If mustMatch is false, the user can chose an item from the list or type in a different value, and the control is rendered as a UI combo box.

The following table itemizes the choices for this property.

Name
Display name
Value
Description
textbox
TextBox
textbox
The user can enter a value.
listbox
Combo ListBox
listbox
Requires a list of choices: static or dynamic. Shown as a list box if set of choices are fixed, combo-box if set of choices is open.
radiobutton
Radio Button
radiobutton
Only allowed for a fixed set of choices.
checkbox
Check Box
checkbox
Only for Boolean values

dataSetName

The name of the data set to execute to dynamically obtain a selection list. This element defines or references a query that defines a dynamic selection list for the parameter. The data set can reference other parameters, but only those that appear in the design before this parameter. Sorting can be done by the data set if the fixedOrder property is true. Or it can be done by BIRT if the fixedOrder property is false.

The data set must return a column that contains the choice values. It can also contain a column that returns the labels for the values. All other columns are ignored. The choice is passed to the report at run time. The optional display value is displayed in the UI. For example, the display values might be Residential, Commercial, and Government while the corresponding parameter values are R, C, and G.

dataType

The data type for the parameter. The data type controls how the Requester formats, parses and validates the parameter. Every type can optionally provide a choice list. The parameter can require that the user select one of the choices.

The following table itemizes the choices for this property.

Name
Display name
Value
Description
string
String
string
Arbitrary Unicode text.
float
Float
float
An amount using the usual floating point notation.
decimal
Decimal
decimal
Any type of number including currency. Fixed decimal, arbitrary precision.
dateTime
Date Time
dateTime
A date, time or combination of date and time.
boolean
Boolean
boolean
A simple true or false value.

defaultValue

The default value of the parameter. The default value can be an expression, but cannot refer to any other parameters.

fixedOrder

A boolean value that determines whether to display the values in the order defined in the list, or to re-sort the list lexicographically based on the actual translated values. The default is true, and the selections are displayed in the order in which they are defined.

format

Formatting instructions for the parameter value within the parameter user interface. For user interfaces that are able to show formatted parameter values, this property provides a format. When the user edits the parameter value, the format is dropped, and the unformatted value presented.

By default, the UI should use the following rules:

Type
Rule
Text
No formatting
Number
Default locale formatting
Float
Default locale formatting
Date and time
Default locale formatting

The format string must be one of the valid BIRT format strings. The format is used by the UI to display the value after the user leaves the field.

labelExpr

An expression on the data row to return the display value for each choice in a dynamic list. If omitted, BIRT uses the value as the label.

listLimit

The maximum number of parameters that can appear in a parameter display list

mustMatch

If true, the value that the user provides must match one of the values in the list. If false, then the values in the list are a reference. The use can enter additional values as well. This property is ignored if the element does not have a selection list.

promptText

The text displayed when prompting the user for a parameter value

selectionList

Defines a selection list for the parameter. The selection list is a static list of values from which the user can choose. The parameter selection list provides a developer-defined list of choices. Every choice has two parts: a choice and a label. The label can be externalized and appears in the UI. The choice is the value passed to the report. For example, labels may be Open and Closed, while the values are 0 and 1.

valueExpr

An expression on the data set row to return the value of each choice in a dynamic list. If omitted, BIRT uses the first column.

valueType

The type of the parameter, either static or dynamic


(c) Copyright Actuate Corporation 2006

Previous TopicNext Topic