Report Parameters and Field Formatters

External Report Parameters

External parameters are passed from the outside when running a report and can be used as conditions in datasets. All external parameters become fields for each report band, so you can use them directly in the template as dataset fields. If any dataset contains field with the same name, it overrides the external parameter in the corresponding band and the report uses the dataset field value.

External parameters can be passed by the invoking code when running a report through API. Also, the report generator can show a dialog to enter parameters when a user runs the report. In the latter case you should describe the external parameters in the Parameters and Formats tab of the report editor.

The form for defining a parameter is shown below:

report parameter
Figure 1. External Report Parameters

Input Parameters Properties

In the Properties tab, you can define parameter properties:

  • Caption – parameter name, as it will appear in the parameter input form when running the report.

  • Parameter alias – parameter alias used to access it in datasets.

  • Parameter type – parameter type.

  • Hidden – flag that defines whether the request for parameter should be hidden from users.

  • Required parameter? – flag determining if the parameter is mandatory.

  • Default value – defines the parameter value that will be used by default if no other value is selected by the user.

The parameter type can be primitive types of String, Number, Boolean or temporal types, besides, you can choose Enumeration, Entity or List of entities as a parameter type. Based on different type selected, additional fields are required:

If the Entity or List of entities parameter type is selected:

  • Entity – entity to use as parameter.

  • Entity selection screen – optional screen identifier, which will be used to select entity instances. If the screen is not specified, selection will be made from a special screen generic for all entities.

If the Enumeration parameter type is selected:

  • Enumeration – enumeration to use as parameter.

If the temporal parameter type is selected (Date, Time or Date and time):

  • Default date(time) is current – flag defines whether the current timestamp will be used as the default parameter value.

Input Parameters Localization

In the Localization tab, you can define the parameter name for different locales. In order to do this, you should enter the locale_name = parameter_name pairs, for example:

ru = Книга

Input Parameters Transformation

In the Transformation tab, you can apply a Groovy script to the parameter before using it in the report.

A Groovy script should return a new parameter value. The following variables are passed into the script:

  • params – parameters map is available by alias params.

  • paramValue – Current parameter value is available in the script by the paramValue.

  • dataManager – an object of the DataManager type that provides CRUD functionality.

  • metadata – an object of the Metadata type that provides access to the application metadata.

  • applicationContext – an object of the org.springframework.context.ApplicationContext type that provides access to managed beans.

For example:

return "%" + paramValue + "%"

You can also use predefined transformations that add wildcards for text (String) parameters:

  • Starts with,

  • Ends with,

  • Contains.

report parameter transformation
Figure 2. Input parameters transformation

In the Validation tab, you can define a Groovy script with some conditions for the parameter validation, see the details below.

Input Parameters Validation

You can validate an input parameter and/or define the cross-parameter validation.

  1. You can enable validation of each parameter in the Validation tab of the parameter editor by checking the Validate checkbox. The validation logic is specified by a Groovy script. The script should check the parameter value and call the invalid() method if the value is not valid. This method will show the user an alert with the given message about the report validation errors.

    The following variables are passed into the script:

    • value – the parameter value entered by the user.

    • applicationContext – an object of the org.springframework.context.ApplicationContext type that provides access to managed beans.

    • currentAuthentication – an object of the io.jmix.core.security.CurrentAuthentication type associated with the currently authenticated user.

    • dataManager – an object of the DataManager type that provides CRUD functionality.

    • metadata – an object of the Metadata type that provides access to the application metadata.

    • invalid – groovy closure which effectively fails validation if called from inside the script.

      report parameter validation
      Figure 3. Input parameters validation

  2. Cross-parameter validation can be enabled by checking the Validate checkbox in the Cross parameters validation section of the Parameters and Formats tab. The validation logic is specified by a Groovy script. The script should check whether or not parameter values make sense in relation to each other and call the invalid() method if they do not. This method will show the user an alert with the given message about the report validation errors.

    In addition to the variables listed above, the params variable is passed into the script to access the external report parameters map.

    cross parameter validation
    Figure 4. Cross-parameter validation

Field Value Formats

You can specify the formatting for any field output by the report in the Parameters and Formats tab of the report editor. Below is the form to add a format:

report formatter
Figure 5. Field Value Formats

  • Value name – report field name with the band prefix, for example, Book.year.

  • Format string – field format. For number values specify the format according to the java.text.DecimalFormat rules, for dates – java.text.SimpleDateFormat.

  • Groovy script checkbox – allow specifying a Groovy script to format the parameter. Using the value alias, the current parameter value is passed to the script, which can be formatted or converted to the desired format. A Groovy script should return the new value as a string.

With the help of formats, it is possible to insert images and HTML blocks into the document.

  • In order to insert an image, specify the image URL as the field value, and the format string must be as follows: ${image:<Width>x<Height>}, for example, ${image:200x300}.

    To work with the FileRef, use the ${imageFileId:WxH} value formatter that accepts a FileRef instance or a URI of a file as a string.

  • In order to insert an HTML block, you should return an HTML markup in the field, and select ${html} as the format string. In the output value, you may omit top-level tags up to <body> inclusive. If necessary, all missing top-level tags will be added automatically. All blocks should be encoded with UTF-8. CSS and the style attribute are not supported.

You can specify your own custom formats as well. To do this, type the new value in the field without opening the dropdown and press Enter. You can also choose any format from the dropdown, edit its name in the field and press Enter. Custom format will be saved in both cases.