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 screen open mode. There are the following possible values:
- NEW_TAB - open a screen in the new tab of the main window. This is the default value.
- THIS_TAB - open a screen on top of the current tab screens stack.
- DIALOG - open 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"/>
    </layout>
</window>

Events and Handlers

To generate a handler stub in Jmix Studio, select the facet in the screen descriptor XML or in the Component Hierarchy panel and use the Handlers tab of the Component 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.

Programmatic registration of the event handler: use the addAfterCloseEventListener() method.

AfterShowEvent

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

Programmatic registration of the event handler: 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));
}

Programmatic usage: call the setOptionsProvider() method.

All XML Attributes

You can view and edit attributes applicable to the facet using the Component Inspector panel of the Studio’s Screen Designer.

id - onAction - onButton - openMode - screenClass - screenId