5.5.8.2. Main Window Layout

The mechanism described below allows you to design the application main window layout with CUBA Generic UI technology by creating an XML-descriptor and Java controller, and using UI components and data sources.

The main window is defined by a specific screen with mainWindow identifier. Its controller should be derived from the AbstractMainWindow class.

The following special components may be used in the main window in addition to the standard UI components:

  • AppMenu - main application menu.

  • FoldersPane - application and search folders panel.

  • AppWorkArea - work area, the required component for opening screens in the THIS_TAB, NEW_TAB and NEW_WINDOW modes.

  • UserIndicator - the field which displays the name of the current user, as well as enables selecting substituted users, if any.

    The setUserNameFormatter() method allows you to represent the user’s name in a format different from the User instance name:

    userIndicator.setUserNameFormatter(value -> value.getName() + " - [" + value.getEmail() + "]");
    userIndicator

  • NewWindowButton - the button which opens a new main window in a separate browser tab.

  • LogoutButton - the application logout button.

  • TimeZoneIndicator - the label displaying the current user’s time zone.

  • FtsField - the full text search field.

In order to define the special components, add the xmlns:main namespace to the screen:

<window xmlns="http://schemas.haulmont.com/cuba/window.xsd"
        xmlns:main="http://schemas.haulmont.com/cuba/mainwindow.xsd"
        class="com.company.sample.gui.MainWindow">
    <layout>
    </layout>
</window>

The AppWorkArea component is designed to show application screens. If the cuba.web.appWindowMode application property is TABBED (default), the work area shows a TabSheet with open screens. Otherwise a single open screen is shown. The cuba.web.mainTabSheetMode and cuba.web.managedMainTabSheetMode application properties define how the tabs content is handled when the tabs are switched. When no screens are opened, the work area shows components defined in the initialLayout internal element:

<main:workArea id="workArea" width="100%" height="100%">
    <main:initialLayout spacing="true" margin="true">
        <!-- content shown when there are no open screens -->
    </main:initialLayout>
</main:workArea>

The initial screen layout (initialLayout) is removed from AppWorkArea when the first application screen is opened, and added back when all screens are closed. You can add AppWorkArea.StateChangeListener to handle changing the work area between the initial layout and application screens. Such listener can, for example, refresh the initial layout data.

The platform provides 2 standard main window implementations. XML descriptor of the default main window with horizontal menu on top is available in /com/haulmont/cuba/web/app/mainwindow/mainwindow.xml, its corresponding controller class is AppMainWindow. Another available template contains the vertical side menu.

The standard implementation can be extended in the project, like any other application screen. Example of an extending screen:

<window xmlns="http://schemas.haulmont.com/cuba/window.xsd"
        xmlns:ext="http://schemas.haulmont.com/cuba/window-ext.xsd"
        extends="com/haulmont/cuba/web/app/mainwindow/mainwindow.xml"
        class="com.haulmont.cuba.web.app.mainwindow.AppMainWindow">
    <layout>
        <vbox ext:index="0">
            <label value="This is my main window!" stylename="h2"/>
        </vbox>
    </layout>
</window>

This screen should be registered in web-screens.xml file with the mainWindow identifier.

The easiest way to extend the main screen is provided by CUBA Studio: click New on the GENERIC UI tab of the navigation panel and choose the template for the new main screen in the Generic UI templates visual designer. The new ext-mainwindow.xml file will be created in the Web module and automatically registered in web-screens.xml.

CUBA Platform provides 2 standard main window layout templates: with horizontal menu and with the side menu. The standard main window implementation may be fully replaced with a custom one. For example:

<window xmlns="http://schemas.haulmont.com/cuba/window.xsd"
        xmlns:main="http://schemas.haulmont.com/cuba/mainwindow.xsd"
        class="com.company.sample.gui.MainWindow">
    <layout expand="middlePanel">
        <hbox margin="true"
              stylename="gray"
              width="100%">
            <label align="MIDDLE_CENTER"
                   value="Header"/>
        </hbox>
        <main:menu width="100%"/>
        <split id="middlePanel"
               orientation="horizontal"
               pos="80"
               width="100%">
            <main:workArea id="workArea"
                           height="100%"
                           width="100%">
                <main:initialLayout stylename="red">
                    <label align="MIDDLE_CENTER"
                           value="Work Area (Initial Layout)"/>
                </main:initialLayout>
            </main:workArea>
            <main:foldersPane height="100%"
                              stylename="blue"
                              width="100%"/>
        </split>
        <hbox margin="true"
              stylename="gray"
              width="100%">
            <label align="MIDDLE_CENTER"
                   value="Footer"/>
        </hbox>
    </layout>
</window>

The resulting main window is shown below:

main window 1

The same main window with an open screen:

main window 2

The cuba.web.showBreadCrumbs application property allows you to hide the navigation panel (breadcrumbs) above the opened screen.