**This page describes all the available parameter properties that can be included in JRXML source to help Aperte Reports generate Vaadin forms.**
These parameters are read from a compiled source and later transformed into appropriate widgets. The values selected by users are send back to the reports engine.
## Jasper parameter syntax ##
Let us have a look at a single report parameter. Below you can see an example of a parameter that would display a select box populated with a list of report names fetched from database (notice the **`jdbc/aperte-reports`** query prefix):
```
```
After uploading a report with parameters configured in such a way a user can invoke the report generation form. This form is constructed according to the properties of each parameter and shown to the user. The output JasperPrint is then filled with the values from these inputs.
Each parameter has an input class attribute. It should be ALWAYS configured as `java.lang.String`, since all the types from form are serialized to strings.
In next section the possible parameters are described in detail.
## Parameter properties ##
A JRXML parameter can be linked with a number of properties. The values of the parameters are always passed as strings. The properties recognized by Aperte Reports are listed below:
* ### input\_type ###
The input type (i.e. SELECT) which is transformed into a Vaadin field. The details of the input types are described in next section.
Example:
```
```
#### Available input types: ####
| **text** | Displays fillable single-row text field.|
|:---------|:----------------------------------------|
| **date** | Displays a date field.|
| **textarea** | Displays a multiline text area.|
| **select** | Displays a select box.|
| **multiselect** | Displays a select box that allows multiple selection.|
| **radiobuttons** | Displays a group of radio buttons. Only one value can be selected.|
| **checkboxes** | Displays a group of check boxes. Multiple values can be selected.|
| **checkbox** | Displays a single check box.|
| **special\_control** | Displays a special control rendered and maintained by an external script code.|
| **filter** | Displays a filtering select. Should be used together with a filtered select. Values from filters are used only to filter other fields and are NOT passed to JRXML.|
| **filtered\_select** | Displays a base select that is an object to filtering selects. The value from this input is crucial in a complete filtering group scope.|
* ### dict\_query ###
A database query to retrieve a dictionary for fields offering selections.
Typically a query consists of a JNDI resource name (i.e. `jdbc/aperte-reports`), semicolon separator and the SQL query. The results of the query are translated into object according the following manner:
1. the first and the second columns are the code (id) and description (visible for users)
1. rest of the columns can be used with multilevel filters (described below)
Format:
```
{datasource};{SQL}
```
Example:
```
```
* ### dict\_item\_list ###
A static list of dictionary items. Each item is a pair of a key and a value separated by a colon. The values are separated from themselves by a semicolon.
Format:
```
{value passed to the report}:{label of the value};{value2}:{label2};{value3}:{label3};...
```
Example:
```
```
* ### width ###
Specifies the width of a Vaadin component using CSS syntax. The value should contain the size unit used (i.e. pixels).
Example:
```
```
* ### maxchars ###
Specifies the maximum number of characters the input component can handle. This value should be an **integer**.
Example:
```
```
* ### required ###
Specifies whether the field should be required to fill by the user. A boolean type of value (**true** or **false**).
Format:
```
true|false
```
Example:
```
```
* ### required\_error ###
Specifies the resource bundle error message key. The message is shown to user when the required parameter has not been filled. Should be used together with **required** property.
Message replacements:
If the error message (given either directly or in bundle) contains '%s' it will be replaced with field name.
Format:
```
{error message key in resource bundle(recommended)}|{error message}
```
Default:
```
form.required.error
```
Example:
```
```
* ### regexp ###
Adds a [regexp validator](http://regexpal.com/) for the generated Vaadin field.
Example:
```
```
* ### regexp\_error ###
Specifies the resource bundle error message key. The message is shown to user when the regexp validator rejects the value of the field. Should be used together with **regexp** property.
Message replacements:
If the error message (given either directly or in bundle) contains '%s' it will be replaced with field name and next '%s' will be replaced with regexp value.
Format:
```
{error message key in resource bundle(recommended)}|{error message}
```
Default:
```
form.errors.regexp
```
Example:
```
```
* ### order ###
Describes the order of the field in a Vaadin form. The higher the value the later the field is positioned in the form.
Default:
```
1000
```
Example:
```
```
* ### label ###
The caption of the Vaadin field, displayed on its' let.
Example:
```
```
* ### filter\_group ###
Name of a filtering group. This should be used together with a filtering input type. It is used to connect appropriate filters with filtered\_select.
Example:
```
```
Example use of filters and filtering groups:
```
```
* ### level ###
The number that indicates a filtering level of a filtering input type. The higher the level the earlier the filter appears, therefore the more general it should be. It also defines the column from dict\_query from which the data should be taken as `level+2`.
Example:
```
```
* ### multiple\_choice ###
Indicates whether a select input should allow multiselect. A boolean type (**true** or **false**). May also be used with filtered\_select.
Format:
```
true|false
```
Default:
```
false
```
Example:
```
```
* ### select\_all ###
Indicates whether a select input should be accompanied with a "select all" checkbox that selects/deselects all available items. May also be used with filtered\_select.
Format:
```
true|false
```
Default:
```
false
```
Example:
```
```
* ### script\_language ###
Specifies the script language used for a special control code. Its libraries must be available in classpath.
Example:
```
```
* ### special\_control\_code ###
The special control code invoked by a **`javax.script.ScriptEngine`** instance.
This code should create a Vaadin component and add it to the container passed as a parameter.
Should be used together with **script\_language** property and other special properties.
Function signature:
```
void specialControl(FieldContainer container, List data, String width,
String maxchars, Boolean required, String requiredError,
String regexp, String regexpError, String caption)
```
Adding field to layout should be done calling `FieldContainer.setFieldComponent(com.vaadin.ui.Component component);`
Example:
```
```
* ### special\_validation\_code ###
The special validation code that creates a Vaadin field Validator.
Should be used together with **script\_language** property.
Function signature:
```
com.vaadin.data.Validator specialValidator(FieldContainer container, String errorMessage)
```
`specialValidator()` should return object implementing `com.vaadin.data.Validator` which will be later applied to the field (there is no need to add inside the script).
Example:
```
```
* ### special\_validation\_error ###
Validation error message that is passed to the function creating a special Validator. Since this error message is used by custom validator, any format of the error message may be used.
Should be used together with **special\_validation\_code** property.
Example:
```
```
* ### special\_data\_query\_code ###
The special code that retrieves dictionary items using a custom script language. Useful when dictionary cannot be simple fetched using SQL.
Should be used together with **script\_language** property.
Function signature:
```
void specialQuery(DictionaryItemsWrapper items, String dataQuery);
```
Adding data items is done calling `DictionaryItemsWrapper.addItem(String[] dataRow)`. Order of data cells has to be the same as in regular **data\_query**.
Example:
```
```
## Report datasource parameter ##
This parameter specifies a datasource of the report fields used by Jasper.
See an example below:
```
```