Using Screen Parameters in Loaders

It is often required to load data in a screen depending on parameters passed to that screen. Below is an example of a browse screen which accepts a parameter and uses it to filter the loaded data.

Suppose we have two entities: Country and City. The City entity has country attribute which is a reference to Country. The cities browser accepts a country instance and shows cities only of this country.

First, consider the cities screen XML descriptor. It’s loader contains a query with a parameter:

<collection id="citiesDc"
    <loader id="citiesDl">
            <![CDATA[select e from demo_City e where e.country = :country]]>

The cities screen controller contains a public setter for the parameter and uses the parameter in BeforeShowEvent handler. Notice that the screen has no @LoadDataBeforeShow annotation, because loading is triggered explicitly:

public class CityBrowse extends StandardLookup<City> {

    private CollectionLoader<City> citiesDl;

    private Country country;

    public void setCountry(Country country) {
        this.country = country;

    private void onBeforeShow(BeforeShowEvent event) {
        if (country == null)
            throw new IllegalStateException("country parameter is null");
        citiesDl.setParameter("country", country);

The cities screen can be opened from another screen passing a country as follows:

private ScreenBuilders screenBuilders;

private void showCitiesOfCountry(Country country) {
    CityBrowse cityBrowse = screenBuilders.screen(this)