loginForm

LIVE DEMO

A form for entering authentication credentials.

  • XML element: loginForm

  • Java class: JmixLoginForm

Basics

Basic loginForm includes username and password fields and a button that the user clicks to attempt logging in. The form can also include optional elements such as a locales combobox, "Remember me" checkbox and "Forgot password" button.

login form

Labels and Messages

Include the form element to specify the form’s title, input field labels, and button text.

Values in the form can be strings of text or keys in the message bundle. 
<loginForm>
    <form title="Welcome"
          username="Username or email"
          password="Password"
          rememberMe="Remember me"
          submit="Log in"
          forgotPassword="Forgot password"/>
    <errorMessage title="Login failed"
                  message="Check that you have entered the correct username and password and try again"/>
    <additionalInformation message="Additional information"/>
</loginForm>

The example above also adds an optional errorMessage element to display a message when login fails and an additionalInformation element to provide relevant details about the login process.

Optional Elements

Show or hide optional elements such as a locales combobox, "Remember me" checkbox and "Forgot password" button by using the appropriate attributes:

<loginForm localesVisible="true"
           rememberMeVisible="true"
           forgotPasswordButtonVisible="true">
    //...
</loginForm>

Authentication

The standard login view will include the necessary logic for authenticating the user with the application:

@ViewComponent
private JmixLoginForm login; (1)

@Subscribe("login")
public void onLogin(final LoginEvent event) {
    try {
        loginViewSupport.authenticate(
                AuthDetails.of(event.getUsername(), event.getPassword())
                        .withLocale(login.getSelectedLocale()) (2)
                        .withRememberMe(login.isRememberMe()) (3)
        );
    } catch (final BadCredentialsException | DisabledException | LockedException | AccessDeniedException e) {
        log.info("Login failed", e);
        event.getSource().setError(true);
    }
}
1 Inject the loginForm to access it by id in the controller class.
2 Applies the selected locale for the application.
3 Checks whether to remember the user between sessions based on the checkbox value.

Exceptions Handling

To help users identify login issues, extend the default logic to include informative messages for each exception type:

@Subscribe("login")
public void onLogin(final AbstractLogin.LoginEvent event) {
    try {
        loginViewSupport.authenticate(
                AuthDetails.of(event.getUsername(), event.getPassword())
                        .withLocale(login.getSelectedLocale())
                        .withRememberMe(login.isRememberMe())
        );
    }
    catch (final BadCredentialsException | DisabledException | LockedException | AccessDeniedException e) {
        if (e instanceof LockedException) {
            JmixLoginI18n loginI18n = createLoginI18n();
            loginI18n.getErrorMessage().setMessage(e.getMessage()); (1)
            login.setI18n(loginI18n);
        } else {
            login.setI18n(createLoginI18n());
        }

        log.warn("Login failed for user '{}': {}", event.getUsername(), e.toString()); (2)
        event.getSource().setError(true);
    }
}
1 Displays the error message for a login failure based on the exception, specifically a LockedException, which indicates that the account is temporarily locked.
2 Logs a warning message indicating that a login attempt failed for a specific user.

Locale

The login form can include a combobox that allows the user to select their preferred locale. To make the preferred option available, you need to set up the locale in your application. Once an additional locale is set up, it will appear in the list.

login form locales

Whenever the user selects a new locale from the list, the LocaleChangedEvent is fired. By creating a handler for this event, you can ensure that the login form messages will update immediately without requiring a page reload. This is how it is done on the standard login view:

@Override
public void localeChange(final LocaleChangeEvent event) {
    UI.getCurrent().getPage().setTitle(messageBundle.getMessage("LoginView.title"));

    final JmixLoginI18n loginI18n = JmixLoginI18n.createDefault();

    final JmixLoginI18n.JmixForm form = new JmixLoginI18n.JmixForm();
    form.setTitle(messageBundle.getMessage("loginForm.headerTitle"));
    form.setUsername(messageBundle.getMessage("loginForm.username"));
    form.setPassword(messageBundle.getMessage("loginForm.password"));
    form.setSubmit(messageBundle.getMessage("loginForm.submit"));
    form.setForgotPassword(messageBundle.getMessage("loginForm.forgotPassword"));
    form.setRememberMe(messageBundle.getMessage("loginForm.rememberMe"));
    loginI18n.setForm(form);

    final LoginI18n.ErrorMessage errorMessage = new LoginI18n.ErrorMessage();
    errorMessage.setTitle(messageBundle.getMessage("loginForm.errorTitle"));
    errorMessage.setMessage(messageBundle.getMessage("loginForm.badCredentials"));
    loginI18n.setErrorMessage(errorMessage);

    login.setI18n(loginI18n);
}

Styling the Login View

LIVE DEMO

You can use CSS styles to enhance the appearance and layout of the login view in your application. One way to improve the view is by adding a background image. This image will visually confirm to the user that they are logging into the right app.

Attributes

id - alignSelf - classNames - colspan - css - enabled - forgotPasswordButtonVisible - localesVisible - rememberMeVisible - visible

forgotPasswordButtonVisible

Sets the visibility of the Forgot password button.

localesVisible

Sets the visibility of the locales combobox.

rememberMeVisible

Sets the visibility of the Remember me checkbox.

Handlers

AttachEvent - DetachEvent - ForgotPasswordEvent - LocaleChangedEvent - LoginEvent - RememberMeChangedEvent - localeItemLabelGenerator

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the Code → Generate menu (Alt+Insert / Cmd+N).

ForgotPasswordEvent

ForgotPasswordEvent is sent when the Forgot password button is clicked. Add a handler to this event to provide users with password recovery instructions.

LocaleChangedEvent

LocaleChangedEvent is sent when a different locale is selected. A handler for this event may be used to update labels and messages in the form to be of selected locale.

LoginEvent

LoginEvent is sent whe the user attempts to log in.

RememberMeChangedEvent

RememberMeChangedEvent is sent when the state of the Remember me checkbox changes.

localeItemLabelGenerator

Customizes names for locales in the list. For example, instead of using the full language name for each locale, you can use a three-letter uppercase abbreviation.

@Install(to = "login", subject = "localeItemLabelGenerator")
private String loginLocaleItemLabelGenerator(final Locale locale) {
    return locale.getISO3Language().toUpperCase();
}

Elements

additionalInformation - form - errorMessage

See Also

See Vaadin Docs for more information.