ScreenFacet

LIVE DEMO

ScreenFacet gives you an alternative way to open related screens and pass parameters to them. Instead of using the ScreenBuilders.screen() method in the screen controller, you can configure ScreenFacet in the XML descriptor with the help of Studio visual designer.

Component’s XML-name: screen.

Basics

In the example below, the uiex1_Customer.browse screen will be opened as a dialog when openDialogAction is executed:

<actions>
    <action id="openDialogAction"
            caption="Open a screen as modal dialog"/>
</actions>
<facets>
    <screen id="actionScreenFacet"
            openMode="DIALOG"
            screenId="uiex1_Customer.browse"
            onAction="openDialogAction">
    </screen>
</facets>

ScreenFacet is defined in the facets element of the screen XML descriptor and has the following attributes:

  • screenId - specifies the id of the screen to open.

  • screenClass - specifies the Java class of the screen controller to open.

  • openMode - defines the screen open mode. There are the following possible values:

    • NEW_TAB - opens a screen in the new tab of the main window. This is the default value.

    • THIS_TAB - opens a screen on top of the current tab screens stack.

    • DIALOG - opens a screen as a modal dialog.

    • ROOT - opens a screen as main.

You can bind ScreenFacet to a button or an action to open the screen on the button click or execution of the action.

  • onAction - defines id of an action which should trigger the screen opening.

  • onButton - defines id of a button which should trigger the screen opening.

Also, you can use the ScreenFacet.show() method to open the screen:

@Autowired
private ScreenFacet<Screen> screenFacet;

@Subscribe("btn")
public void onBtnClick(Button.ClickEvent event) {
    screenFacet.show();
}

Passing Parameters

To pass parameters to the screen, use the properties element. This element defines a list of properties that will be injected into the opened screen via public setters.

For example, let’s pass an integer value to the num property of AnotherScreen from ScreenFacetScreen.

@UiController("sample_AnotherScreen")
@UiDescriptor("another-screen.xml")
public class AnotherScreen extends Screen {

    @Autowired
    private Label<Integer> label; (1)

    private Integer num;

    public void setNum(Integer num) { (2)
        this.num = num;
    }

    @Subscribe
    public void onAfterShow(AfterShowEvent event) { (3)
        label.setValue(num);
    }
}
1 Set label to display received value.
2 Define setter to assign the transmitted value.
3 Assign the accepted value to the label.

In the ScreenFacetScreen XML descriptor, we define name and value attributes of the property element:

<window xmlns="http://jmix.io/schema/ui/window"
        caption="msg://screenFacetScreen.caption">
    <facets>
        <screen id="propScreenFacet"
                screenId="sample_AnotherScreen"
                openMode="DIALOG"
                onButton="propBtn">
           <properties>
                <property name="num" value="55"/>
            </properties>
        </screen>
    </facets>
    <layout>
            <button id="propBtn"
                    caption="Pass params"
                    width="100%"/>
    </layout>
</window>

Events and Handlers

To generate a handler stub in Jmix Studio, select the facet in the screen descriptor XML or in the Jmix UI hierarchy panel and use the Handlers tab of the Jmix UI inspector panel.

Alternatively, you can use the Generate Handler button in the top panel of the screen controller.

AfterCloseEvent

AfterCloseEvent is sent after the screen configured by the facet is closed. See AfterCloseEvent for details.

To register the event handler programmatically, use the addAfterCloseEventListener() method.

AfterShowEvent

AfterShowEvent is sent after the screen configured by the facet is shown. See AfterShowEvent for details.

To register the event handler programmatically, use the addAfterShowEventListener() method.

OptionsProvider

The OptionsProvider delegate method allows you to configure screen parameters programmatically, for example:

@Install(to = "propScreenFacet", subject = "optionsProvider")
private ScreenOptions propScreenFacetOptionsProvider() {
    return new MapScreenOptions(ParamsMap.of("num", 55));
}

To register the options provider programmatically, use the setOptionsProvider() method.

ScreenConfigurer

It is a handler that accepts the screen and can initialize it before opening. Use the configurer if you need to provide parameters to the opened screen through public setters. The preferred way to set the configurer is using a controller method annotated with @Install, for example:

@Install(to = "screenFacetC", subject = "screenConfigurer")
protected void screenFacetCScreenConfigurer(CustomerBrowse customerBrowse) {
    customerBrowse.setSomeParameter(55);
}

To register the screen configurer programmatically, use the setScreenConfigurer(Consumer<S> screenConfigurer) method.

All XML Attributes

You can view and edit attributes applicable to the facet using the Jmix UI inspector panel of the Studio’s Screen Designer.

id - onAction - onButton - openMode - screenClass - screenId