-
Notifications
You must be signed in to change notification settings - Fork 4
ReportParameters
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.
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):
<parameter name="r_title" class="java.lang.String">
<property name="input_type" value="select"/>
<property name="label" value="Report title"/>
<property name="dict_query"
value="jdbc/aperte-reports;
SELECT DISTINCT id, reportname FROM ar_configuration"/>
<defaultValueExpression>
<![CDATA["Pick a report"]]>
</defaultValueExpression>
</parameter>
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.
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:
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:
<property name="input_type" value="select"/>
| 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. |
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:
<property name="dict_query"
value="jdbc/aperte-reports; SELECT DISTINCT id, reportname FROM vries_configuration"/>
<property name="dict_query"
value="jdbc/aperte-reports; SELECT id, description, filename, reportname FROM vries_configuration"/>
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:
<property name="dict_item_list"
value="id_chart:Show chart;id_table:Show table;id_projects:Show projects"/>
Specifies the width of a Vaadin component using CSS syntax. The value should contain the size unit used (i.e. pixels).
Example:
<property name="width" value="300px"/>
Specifies the maximum number of characters the input component can handle. This value should be an integer.
Example:
<property name="maxchars" value="30"/>
Specifies whether the field should be required to fill by the user. A boolean type of value (true or false).
Format:
true|false
Example:
<property name="required" value="true"/>
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:
<property name="required_error" value="form.required.error"/>
<property name="required_error" value="Field named '%s' is required"/>
Adds a regexp validator for the generated Vaadin field.
Example:
<property name="regexp" value="[A-Z].*"/>
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:
<property name="regexp_error" value="form.errors.must_be_upper_case"/>
<property name="regexp_error" value="Field '%s' has to match '%s'"/>
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:
<property name="order" value="1"/>
The caption of the Vaadin field, displayed on its' let.
Example:
<property name="label" value="Pick a report from list"/>
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:
<property name="filter_group" value="projects_group"/>
Example use of filters and filtering groups:
<parameter name="filter_2" class="java.lang.String">
<property name="level" value="2"/>
<property name="input_type" value="filter"/>
<property name="label" value="Filter report name"/>
<property name="filter_group" value="filtering_group"/>
</parameter>
<parameter name="filter_1" class="java.lang.String">
<property name="level" value="1"/>
<property name="input_type" value="filter"/>
<property name="label" value="Filter file name"/>
<property name="filter_group" value="filtering_group"/>
</parameter>
<parameter name="filtered_value" class="java.lang.String">
<property name="level" value="0"/>
<property name="input_type" value="filtered_select"/>
<property name="label" value="Report"/>
<property name="filter_group" value="filtering_group"/>
<property name="select_all" value="true"/>
<property name="dict_query" value="jdbc/aperte-reports;SELECT id, description, filename, reportname FROM vries_report_template"/>
<property name="multiple_choice" value="true"/>
</parameter>
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:
<property name="level" value="1"/>
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:
<property name="multiple_choice" value="true"/>
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:
<property name="select_all" value="true"/>
Specifies the script language used for a special control code. Its libraries must be available in classpath.
Example:
<property name="script_language" value="jruby"/>
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:
<property name="special_control_code" value="
def specialControl(container, data, width, maxchars, required, requiredError, regexp, regexpError, caption);
container.setFieldComponent(com.vaadin.ui.DateField.new(caption));
end;"/>
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:
<property name="special_validation_code" value="
class SpecialValidator;
include com.vaadin.data.Validator;
attr_accessor :error_message;
def isValid(value);
value.nil? || value.size % 5 == 0;
end ;
def validate(value);
if !isValid(value);
raise InvalidValueException.new(@error_message);
end;
end;
def initialize(message);
@error_message = message;
end;
end;
def specialValidator(container, errorMessage);
SpecialValidator.new errorMessage;
end;"/>
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:
<property name="special_validation_error" value="The field validation failed"/>
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:
<property name="special_data_query_code" value="
def specialQuery(items, dataQuery);
items.addItem(['true','aktywne']);
items.addItem(['false','nieaktywne']);
end;"/>
This parameter specifies a datasource of the report fields used by Jasper. See an example below:
<parameter name="datasource" class="java.lang.String">
<parameterDescription><![CDATA[java:comp/env/jdbc/aperte-reports_production]]</parameterDescription>
</parameter>