Eclipse BIRT Report Object Model (ROM)

ScalarParameter Element

Element Overview

Defines a simple single-value parameter.

Details

Display Name: ScalarParameter
Since: 1.0
XML Element: scalar-parameter
Extends: Parameter
Extendable: Yes
Abstract: No
Name Space: Parameters
Name Requirement: Required
Allows User Properties: Yes
Has Style: No

Property Summary

alignment
How the items should appear in the UI. Choices are auto (default), left, center or right.
boundDataColumns
Bindings the data set column and expressions with the property values..
concealValue
Hides the user�s entry by displaying asterisks or similar characters. Often used for passwords.
controlType
The suggested type of UI control to use when displaying the parameter.
dataSetName
The name of the data set to execute to obtain a selection list dynamically.
dataType
The data type for the parameter.
defaultValue
The default value of the parameter.
distinct
fixedOrder
Whether to display the list sorted in unsorted (fixed) order.
format
Formatting pattern for showing the parameter in the UI.
isRequired
labelExpr
An expression on the data row to return the display value for each choice in a dynamic list.
listLimit
List limitation number.
mustMatch
If true, then the value that the user provides must match one of the values in the static or dynamic selection list.
paramType
promptText
The prompt text displayed when user input the parameter value.
promptTextID
selectionList
Defines a selection list for the parameter: static list of values from which the user can choose.
sortBy
sortDirection
valueExpr
An expression on the data set row to return the value of each choice in a dynamic list.
valueType
Type of the parameter

Inherited Properties

comments, customXml, displayName, displayNameID, eventHandlerClass, extends, helpText, helpTextID, hidden, name, propertyMasks, userProperties, viewAction

Inherited Methods

validate

Description

This element defines a single-value parameter. Scalar parameters can have selection lists.

Scalar parameters can provide a selection list. The list can be static (defined by the selectionList property) or dynamic (defined by the dataSet, valueExpr and labelExpr properties.) The user can be required to select a value from the list, or can enter a value not in the list (as controlled by the mustMatch property).

BIRT uses the following rules to determine the selection list:

Property Detail

alignment Property

How the items should appear in the UI. Choices are auto (default), left, center or right.

Details

Type: choice (scalarParamAlign)
Since: 1.0
Required: No
Display Name: Alignment
JavaScript Type:
Default Value: auto
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
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.

Description

How the items should appear in the UI. Choices are auto (default), left, center or right.


boundDataColumns Property

Bindings the data set column and expressions with the property values..

Details

Type: List of ComputedColumn Structures
Since: 2.1
Required: No
Display Name: Bound data columns
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

Property values of a scalar parameter can bind to a data set column through bound data columns' names. If a data set column or expression are not bound in the data columns, the exeuction of the expression fails.

See Also

 


concealValue Property

Hides the user�s entry by displaying asterisks or similar characters. Often used for passwords.

Details

Type: boolean
Since: 1.0
Required: No
Display Name: Conceal value
JavaScript Type:
Default Value: false
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

This property hides the user�s entry by displaying asterisks or similar characters. Often used for passwords. The default is to show the entry in plain text.

See Also

hidden Property


controlType Property

The suggested type of UI control to use when displaying the parameter.

Details

Type: choice (paramControl)
Since: 1.0
Required: No
Display Name: Control type
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
text-box Text Box text-box The user can type in the value.
list-box Combo/List Box list-box 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.
radio-button Radio Button radio-button Only allowed for a fixed set of choices.
check-box Check Box check-box Only for Boolean values

Description

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

The list-box control is rendered in the UI depending on the value of the mustMatch property. If mustMatch is true, then the user much choose a value from the list, and the control is rendered as a UI list box. However, if mustMatch is false, then 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.

See Also

mustMatch property


dataSetName Property

The name of the data set to execute to obtain a selection list dynamically.

Details

Type: DataSet Reference
Since: 2.0
Required: No
Display Name: DataSet Name
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Dynamic list

Description

The name of the data set to execute to obtain the 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 can be done by BIRT (if the fixedOrder property is false.)

The data set must return a column that contains the choice values. It may also contain a column that returns the labels for the values. All other columns are ignored. The choice is that passed to the report when run. The optional display value is shown to the user 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 Property

The data type for the parameter.

Details

Type: choice (paramType)
Since: 1.0
Required: No
Display Name: Data type
JavaScript Type:
Default Value: string
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
string String string Arbitrary Unicode text.
float Float float A scientific amount using the usual floating point notation.
decimal Decimal decimal Any type of number including currency. Fixed decimal, arbitrary precision.
dateTime DateTime dateTime A date, time or combination of date and time.
boolean Boolean boolean A simple true/false value.
integer Integer integer
any Any any
date Date date
time Time time

Description

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. And, the parameter can require that the user select one of the choices.

See Also

selectionList property

defaultValue property


defaultValue Property

The default value of the parameter.

Details

Type: literalString
Since: 1.0
Required: No
Display Name: Default value
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

The default value for the parameter. The default value can be an expression, but cannot reference any other parameters.


distinct Property

Details

Type: boolean
Since: 2.2
Required: No
Display Name: Distinct
JavaScript Type:
Default Value: true
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

fixedOrder Property

Whether to display the list sorted in unsorted (fixed) order.

Details

Type: boolean
Since: 1.0
Required: No
Display Name: Fixed order
JavaScript Type:
Default Value: true
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Selection list

Description

Whether to display the values in the order defined in the list, or whether to resort 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.

See Also

selectionList property

dynamicList property


format Property

Formatting pattern for showing the parameter in the UI.

Details

Type: ParameterFormatValue Structure
Since: 1.0
Required: No
Display Name: Format
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Hidden
Property Sheet Group: Top

Description

Formatting instructions for the parameter value within the parameter UI. For UIs that are able to show formatted parameter values, provides a BIRT format used to display the value. The format is dropped, and the unformatted value presented, when the user edits the parameter value.

Formatting instructions for the parameter value within the parameter UI. By default the UI should use the following rules:

The format string must be one of the valid BIRT format strings (see the Style element for a list.) The format is used by the UI to display the value after the user moves away from a field. For example, to format a number as a dollar amount.


isRequired Property

Details

Type: boolean
Since: 2.2
Required: No
Display Name: Is required
JavaScript Type:
Default Value: true
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

labelExpr Property

An expression on the data row to return the display value for each choice in a dynamic list.

Details

Type: expression
Context:
Expression Type: string
Since: 2.0
Required: No
Display Name: Label expression
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Dynamic list

Description

An expression on the data row from the dynamic list data set that returns the prompt for the choice. If omitted, then BIRT uses the value as the label.

See Also

 


listLimit Property

List limitation number.

Details

Type: integer
Since: 2.0
Required: No
Display Name: List limit
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

Value for the list limitation number. If the limitation is provided, only the top-n choices will be available in the parameter request dialog.


mustMatch Property

If true, then the value that the user provides must match one of the values in the static or dynamic selection list.

Details

Type: boolean
Since: 1.0
Required: No
Display Name: Must match
JavaScript Type:
Default Value: true
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Selection list

Description

If true, then 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. Ignored if the property does not have a selection list.


paramType Property

Details

Type: choice (scalarParamType)
Since: 2.2
Required: No
Display Name: Scalar parameter type
JavaScript Type:
Default Value: simple
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
simple Simple simple
multi-value Multi Value multi-value
ad-hoc Ad-hoc ad-hoc


promptText Property

The prompt text displayed when user input the parameter value.

Details

Type: string
Since: 2.0
Required: No
Display Name: Prompt text
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Description

The text that will be displayed to the user when he/she is prompt for the parameter value.


promptTextID Property

Details

Type: resourceKey
Since: 2.1
Required: No
Display Name: Prompt text key
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: Yes
Property Sheet Visibility: Visible
Property Sheet Group: Top

selectionList Property

Defines a selection list for the parameter: static list of values from which the user can choose.

Details

Type: List of SelectionChoice Structures
Since: 1.0
Required: No
Display Name: Selection list
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Hidden
Property Sheet Group: Selection list

Description

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

The items in the list are of the type given by the parameter data type.

See Also

mustMatch property

fixedOrder property

controlType property


sortBy Property

Details

Type: choice (paramSortValues)
Since: 2.2
Required: No
Display Name: Sort by
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
value Value value
label Display Text label


sortDirection Property

Details

Type: choice (sortDirection)
Since: 2.2
Required: No
Display Name: Sort direction
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
asc Ascending asc
desc Descending desc


valueExpr Property

An expression on the data set row to return the value of each choice in a dynamic list.

Details

Type: expression
Context:
Expression Type: any
Since: 2.0
Required: No
Display Name: Value expression
JavaScript Type:
Default Value: None
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Dynamic list

Description

An expression on the data row from the dynamic list data set that returns the value for the choice. If omitted, then BIRT uses the first column.


valueType Property

Type of the parameter

Details

Type: choice (paramValueType)
Since: 2.0
Required: No
Display Name: Value type
JavaScript Type:
Default Value: static
Inherited: Yes
Runtime Settable: No
Property Sheet Visibility: Visible
Property Sheet Group: Top

Choices

NameDisplay Name ValueDescription
static Static static
dynamic Dynamic dynamic

Description

Type of the parameter, can be static or dynamic