View Methods

In this section, we describe some methods of view controller base classes that can be invoked or overridden in the application code.

Methods of All Views

  • close() - requests closing the view with the passed StandardOutcome enum value or a CloseAction object.

    @Subscribe("discardButton")
    public void onDiscardButtonClick(ClickEvent<Button> event) {
        close(StandardOutcome.DISCARD);
    }

    The parameter value is propagated to the BeforeCloseEvent and AfterCloseEvent, so the information about the reason why the view was closed can be obtained in the listeners.

  • closeWithDefaultAction() - requests closing the view with StandardOutcome.CLOSE.

  • setPreventBrowserTabClosing() - sets whether this view should prevent the browser tab from closing accidentally if the jmix.ui.view.prevent-browser-tab-closing property is set to true (which is false by default). Enabled by default for detail views.

  • getViewData() - returns the ViewData object that serves as a registry for all data components defined in the view XML descriptor. You can use its loadAll() method to trigger all data loaders of the view:

    @Subscribe
    public void onReady(final ReadyEvent event) {
        getViewData().loadAll();
    }
  • getViewAttributes() - returns the ViewAttributes object that serves as a storage of named values. Uses VaadinSession as a store. For example, a detail view uses ViewAttributes to store the read-only state and locked status and revert these settings if a view is refreshed.

  • getPageTitle() - returns the title of a view. By default, returns localized value defined in a view descriptor. Can be overridden to provide the title dynamically, for example:

    @Override
    public String getPageTitle() {
        User user = getEditedEntity();
        return entityStates.isNew(user)
                ? messageBundle.getMessage("newUserTitle")
                : messageBundle.formatMessage("editUserTitle", metadataTools.getInstanceName(user));
    
    }
  • beforeLeave() - a callback that is executed before the navigation to another view is performed. Part of Vaadin’s navigation lifecycle.

    • The event allows the navigation to be postponed, canceled, or changed to a different destination.

    • Is not executed when a view is opened in a dialog mode.

    • Must not be overridden without calling super() method as it executes framework related code.

  • beforeEnter() - a callback that is executed before navigating to a view. Part of Vaadin’s navigation lifecycle.

    • Can be used to obtain the Location object and enables changing the navigation target to go to a different destination from the original one.

    • Is not executed when a view is opened in a dialog mode.

    • Must not be overridden without calling super() method as it executes framework related code.

  • afterNavigation() - a callback that is executed after navigation has been completed. Part of Vaadin’s navigation lifecycle.

    • Can be used to obtain the Location object.

    • Is not executed when a view is opened in a dialog mode.

    • Must not be overridden without calling super() method as it executes framework related code.

Methods of StandardListView

  • closeWithDiscard() - requests closing the view with StandardOutcome.DISCARD.

  • getLookupComponent() / findLookupComponent() - returns a component to be used for getting a value returned from this lookup view. By default, returns a component with an id specified by the @LookupComponent annotation.

  • setSelectionValidator() - sets a predicate that tests if selected items can be processed by SelectionHandler.

  • setSelectionHandler() - sets a callback that handles selected items. By default, adds items to a collection container if a lookup view is opened for a dataGrid component or sets a single value if a lookup view is opened for a field, for example entityPicker.

    DialogWindow<View<?>> dialog = dialogWindows.lookup(ProjectDetailView.this, User.class) (1)
            .withSelectHandler(users -> { (2)
                for (User user : users) {
                    ProjectParticipant projectParticipant = dataManager.create(ProjectParticipant.class);
                    projectParticipant.setUser(user);
                    projectParticipant.setProject(getEditedEntity());
                    projectParticipant.setRole(projectRole);
                    participantsDc.getMutableItems().add(projectParticipant);
                }
            })
            .build();
    
    View<?> view = dialog.getView();
    if (view instanceof MultiSelectLookupView multiSelectLookupView) { (3)
        multiSelectLookupView.setLookupComponentMultiSelect(true);
    }
    
    dialog.open();
    1 Create a lookup view builder not bound to any UI component.
    2 Define selection handler for the lookup view.
    3 Check if actual lookup view supports multiple selection.

Methods of StandardDetailView

  • getEditedEntity() - when the view is shown, returns an instance of the entity being edited. It’s the instance that is set in the data container specified in the @EditedEntityContainer annotation.

    In the InitEvent listener, this method returns null. In the BeforeShowEvent listener, this method returns the instance passed to the view for editing (later in the view opening process the entity is reloaded and a different instance is set to the data container).

The following methods can be used to close the detail screen:

  • closeWithSave() - validates and saves changes, then closes the view with StandardOutcome.SAVE. You can call this method from a custom event listener or add the built-in detail_saveClose action to the view.

  • closeWithDiscard() - ignores any unsaved changes and closes the view with StandardOutcome.DISCARD. You can call this method from a custom event listener or add the built-in detail_discard action to the view.

If the view is closed using close(StandardOutcome.CLOSE) or closeWithDefaultAction() and has unsaved changes in its DataContext, a dialog with a corresponding message will be displayed before the view is closed. You can adjust the notification type using the jmix.ui.view.use-save-confirmation application property. If you use the closeWithDiscard() or close(StandardOutcome.DISCARD) methods, unsaved changes are ignored without any message.

  • hasUnsavedChanges() - returns true if the view has unsaved changes. The default implementations checks if there are removed or modified entities in the DataContext. If only new entities have been registered as modified in the DataContext, checks whether they have been modified since the view was opened. You can override this method to provide additional checks or skip checking altogether and just return false.

  • save() - validates and saves changes without closing the view. You can call this method from a custom event listener or add the built-in detail_save action to the view. Also, you can override the save() method to perform some operations after the data has been saved, for example:

    @Override
    public OperationResult save() {
        return super.save()     (1)
                .then(() -> {
                    // ...      (2)
                });
    }
    1 Call super method to execute the default logic.
    2 You can perform actions after the data has been saved.
  • setReloadSaved(boolean) - sets whether edited entity should be reloaded after the closeWithSave() method is invoked. The default value is false.

    This method is invoked by the framework with true value when the view is opened in the dialog mode, to return the saved entity instance from the opened view. If you don’t need to reload the saved entity in dialog mode, invoke setReloadSaved(false) in a ReadyEvent listener.

  • setShowSaveNotification(boolean) - sets whether a notification should be shown in case of a successful save. The default value is true.

  • setShowValidationErrors(boolean) - sets whether to indicate about errors after components validation using the showValidationErrors() method. The default value is true.

  • setCrossFieldValidationEnabled(boolean) - sets whether cross-field validation should be performed before saving changes. It uses UiCrossFieldChecks constraint group to validate the entity instance. The default value is true.

  • getLockStatus() - Returns pessimistic lock status of the currently edited entity instance. Possible variants:

    • LockStatus.NOT_SUPPORTED - if the entity does not support pessimistic locking.

    • LockStatus.LOCKED - if the entity instance is successfully locked.

    • LockStatus.FAILED - if the lock failed because the entity is already locked by someone else.