3.5.1.6. Root Screens

A root screen is a Generic UI screen which is displayed directly in the web browser tab. There are two types of such screens: login screen and main screen. Among other components, any root screen can contain the WorkArea component which enables opening other application screens in the inner tabs. If the root screen doesn’t contain WorkArea, application screens can be opened only in DIALOG mode.

Login screen

Login screen is displayed before a user logs in. You can customize the login screen by extending the one provided by the framework or by creating completely new screen from scratch.

In order to extend the existing screen, use Login screen template in Studio screen creation wizard. As a result, Studio will create a screen extending the standard login screen. This screen will be used instead of the standard one because it will have the same login identifier in the @UiController annotation.

If you want to create a new login screen from scratch, use Blank screen template. The source code of a minimalistic login screen may look as follows:

my-login-screen.xml 
<window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd"
        caption="Login"
        messagesPack="com.company.sample.web">
    <layout>
        <label value="Hello World"/>
        <button id="loginBtn" caption="Login"/>
    </layout>
</window>
MyLoginScreen.java 
package com.company.sample.web;

import com.haulmont.cuba.gui.Route;
import com.haulmont.cuba.gui.components.Button;
import com.haulmont.cuba.gui.screen.*;
import com.haulmont.cuba.security.auth.LoginPasswordCredentials;
import com.haulmont.cuba.web.App;

@UiController("myLogin")
@UiDescriptor("my-login-screen.xml")
@Route(path = "login", root = true)
public class MyLoginScreen extends Screen {

    @Subscribe("loginBtn")
    private void onLoginBtnClick(Button.ClickEvent event) {
        App.getInstance().getConnection().login(
                new LoginPasswordCredentials("admin", "admin"));
    }
}

In order to use this login screen instead of the default one, set its id to the cuba.web.loginScreenId property in web-app.properties file:

cuba.web.loginScreenId = myLogin

You could as well give your screen the default login id and don’t change this property.

Main screen

Main screen is the root application screen displayed when the user is logged in. By default, the framework provides the main screen with a side menu.

Studio has a number of templates for creating a customized main screen. All of them use the same MainScreen base class for controllers.

  • Main screen with side menu creates an extension of the standard main screen with the main id. The main screen with side menu, by default, allows you to expand and collapse the side menu using the Collapse button located in the lower-left corner.

    The behavior of the side menu can be customized using SCSS variables (you can change these variables in the visual editor after creating a theme extension or a custom theme):

    • $cuba-sidemenu-layout-collapse-enabled enables or disables the side menu collapse mode. The default value is true.

    • $cuba-sidemenu-layout-collapsed-width specifies the width of the collapsed side menu.

    • $cuba-sidemenu-layout-expanded-width specifies the width of the expanded side menu.

    • $cuba-sidemenu-layout-collapse-animation-time specifies the time for the side menu to collapse and expand in seconds.

      When the $cuba-sidemenu-layout-collapse-enabled variable is set to false, the Collapse button is hidden, and the side menu is expanded.

  • Main screen with responsive side menu creates a similar screen, but the side menu is responsive and collapses on narrow displays. The screen will have an own generated id which must be registered in web-app.properties:

    cuba.web.mainScreenId = respSideMenuMainScreen

  • Main screen with top menu creates a screen with top menu bar and ability to show folders panel on the left. The screen will have an own generated id which must be registered in web-app.properties:

    cuba.web.mainScreenId = topMenuMainScreen

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

  • SideMenu – application menu in the form of the vertical tree.

  • AppMenu – application menu bar.

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

  • FoldersPane – a panel for application and search folders.

  • 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 screen in a separate browser tab.

  • UserActionsButton – if the session is not authenticated, shows the link to the login screen. Otherwise, shows the menu with the link to the user settings screen and logout action.

    You can install LoginHandler or LogoutHandler in the main screen controller to implement your custom logic:

    @Install(to = "userActionsButton", subject = "loginHandler")
private void loginHandler(UserActionsButton.LoginHandlerContext ctx) {
    // do custom logic
}

@Install(to = "userActionsButton", subject = "logoutHandler")
private void logoutHandler(UserActionsButton.LogoutHandlerContext ctx) {
    // do custom logic
}

  • LogoutButton – the application logout button.

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

  • FtsField – the full text search field.

The following application properties may affect the main screen: