ScreenFacet

LIVE DEMO

ScreenFacet is a facet that provides an ability to pre-configure screen opening and passing parameters. Declarative definition of the screen replaces existing ScreenBuilders.screen() method.

Component’s XML-name: screen.

Attributes

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.
- NEW_WINDOW - open a screen in the new tab of the main window.
- ROOT - opens a screen as main.

You can also bind ScreenFacet to action or button. In those cases, the screen will open when action is fires or button clicks. To aware ScreenFacet with action or button, use the following attributes:

onAction

<window xmlns="http://jmix.io/schema/ui/window"
        caption="msg://screenFacetScreen.caption">
    <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>
    <layout>
    </layout>
</window>

onButton

<window xmlns="http://jmix.io/schema/ui/window"
        caption="msg://screenFacetScreen.caption">
    <facets>
        <screen id="buttonScreenFacet"
                openMode="NEW_TAB"
                screenClass="ui.ex1.screen.entity.customer.CustomerBrowse"
                onButton="openNewTabBtn"/>
    </facets>
    <layout>
            <button id="openNewTabBtn"
                    caption="Open a screen in new tab"
                    width="100%"/>
    </layout>
</window>

You can also open screen configured with ScreenFacet using the show() method:

@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 ScreenFacet properties element. This element represents a list of properties that will be injected into the opened screen via public setters.

For example, lets pass Integer value for num property from ScreenFacetScreen to AnotherScreen.

@UiController("sample_AnotherScreen")
@UiDescriptor("another-screen.xml")
public class AnotherScreen extends Screen {
    @Autowired
    private Label<Integer> label; (1)

    @WindowParam(name = "num", required = true)
    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 need to define value and name 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

See AfterCloseEvent.

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

AfterShowEvent

See AfterShowEvent.

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

OptionsProvider

To pass parameters ScreenFacet has options provider.

@Install(to = "propScreenFacet", subject = "optionsProvider")
private ScreenOptions propScreenFacetOptionsProvider() {
    return new MapScreenOptions(new HashMap<String, Object>() {
        {
            put("num", 55);
        }
    });
}

Programmatic usage: call the setOptionsProvider() component 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