com.holonplatform.vaadin.navigator

Interface ViewNavigator

All Superinterfaces:

Serializable

All Known Subinterfaces:

SpringViewNavigator, ViewNavigatorAdapter

All Known Implementing Classes:

DefaultSpringViewNavigator, DefaultViewNavigator

public interface ViewNavigator
extends Serializable

Navigator to manage application UI View configuration and display. Extends the features and the behaviour of a standard Vaadin Navigator component.

View parameters will be automatically injected in View instance using ViewParameter annotated fields.
Supported parameter value types are:

• String
• Numbers
• Boolean
• Enum (ordinal value must be used for enum values serialization)
• Date using date format pattern ViewParameter.DEFAULT_DATE_PATTERN
• LocalDate using date format pattern ISO local date (yyyy-MM-dd)
• LocalTime using date format pattern ISO local time (HH:mm:ss)
• LocalDateTime using date format pattern ISO local date/time ('yyyy-MM-ddTHH:mm:ss')

This navigator provides the navigateTo(String, Map) method to trigger navigation using a Map of parameters name and values instead of a fully serialized navigation state string.

A navigateInWindow method is provided to display a View using a Window instead of the navigator default ViewDisplay component.

View display lifecycle can be intercepted by the view instance itself, using OnShow and OnLeave annotated methods. This methods must be public and provide zero or only one parameter of ViewNavigator.ViewNavigatorChangeEvent or default ViewChangeListener.ViewChangeEvent type. The OnShow annotated method will be called when the View is displayed in application interface, the OnLeave annotated methods will be called when the View is about to be deactivated to be replaced by another view in the navigation flow.

This navigator is expected to keep a history of the navigation states of the navigation flow, allowing to navigate back in navigation history using navigateBack() method.

If correctly configured in concrete subclasses, navigateToDefault() allow to navigate to a predefined default View (something like a homepage View).

Sub-view are supported, i.e. View instances intended to be displayed in a parent View which must implement SubViewContainer interface and take care of sub view instances display in application UI. Sub view are declared using SubViewOf annotation on View classes.

Since:

5.0.0

See Also:

DefaultViewNavigator

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ViewNavigator.Builder Builder to create ViewNavigator instances
static interface	ViewNavigator.NavigationBuilder Builder to create navigation calls using view name and parameters
static interface	ViewNavigator.NavigatorBuilder<B extends ViewNavigator.NavigatorBuilder<B>> Base ViewNavigator builder
static class	ViewNavigator.ViewNavigationException Exception related to View navigation errors.
static interface	ViewNavigator.ViewNavigatorChangeEvent View change event.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONTEXT_KEY Default Context resource reference
static String	VIEW_URI_SCHEME URI scheme which represents a navigation to a View.

Method Summary

Modifier and Type	Method and Description
com.vaadin.shared.Registration	addViewChangeListener(com.vaadin.navigator.ViewChangeListener listener) Listen to changes of the active view
static ViewNavigator.Builder	builder() Builder to create ViewNavigator instance in fluent-style mode
static Optional<ViewNavigator>	getCurrent() Get the current ViewNavigator, if available as Context resource or from current UI.
com.vaadin.navigator.View	getCurrentView() Get current (active) view in navigator.
String	getCurrentViewName() Get current (active) view name in navigator
String	getDefaultViewName() Get default view name
boolean	navigateBack() Navigates back to previous View, if any.
default com.vaadin.ui.Window	navigateInWindow(String viewName) Navigate to the View identified by given viewName using the same behaviour of navigateTo(String, Map) but rendering the View contents in an application Window, using default Window configuration.
default com.vaadin.ui.Window	navigateInWindow(String viewName, Consumer<ViewWindowConfigurator> windowConfiguration) Navigate to the View identified by given viewName using the same behaviour of navigateTo(String, Map) but rendering the View contents in an application Window, using optional windowConfiguration to setup Window features.
com.vaadin.ui.Window	navigateInWindow(String viewName, Consumer<ViewWindowConfigurator> windowConfiguration, Map<String,Object> parameters) Navigate to the View identified by given viewName using the same behaviour of navigateTo(String, Map) but rendering the View contents in an application Window, using optional windowConfiguration to setup Window features.
default com.vaadin.ui.Window	navigateInWindow(String viewName, Map<String,Object> parameters) Navigate to the View identified by given viewName using the same behaviour of navigateTo(String, Map) but rendering the View contents in an application Window, using default Window configuration.
default void	navigateTo(String viewName) Navigates to the View identified by given viewName.
void	navigateTo(String viewName, Map<String,Object> parameters) Navigates to the View identified by given viewName using given parameters, if any, and linking them to View fields using ViewParameter annotated view class fields.
void	navigateToDefault() Navigates to the default View
void	navigateToState(String navigationState) Navigates to a view and initialize the view with given parameters.
static ViewNavigator	require() Requires the current ViewNavigator.
void	runAfterLeaveConfirmation(com.vaadin.navigator.ViewLeaveAction action) Triggers View.beforeLeave(ViewBeforeLeaveEvent) for the current view with the given action.
default ViewNavigator.NavigationBuilder	toView(String viewName) Get a ViewNavigator.NavigationBuilder to create a navigation declaration to navigate to given viewName using parameters.

Field Detail

CONTEXT_KEY

static final String CONTEXT_KEY

Default Context resource reference

VIEW_URI_SCHEME

static final String VIEW_URI_SCHEME

URI scheme which represents a navigation to a View.

See Also:

Constant Field Values

Method Detail

navigateToState

void navigateToState(String navigationState)

Navigates to a view and initialize the view with given parameters.

The navigationState string consists of a view name optionally followed by a slash and a parameters part that is passed as-is to the view. ViewProviders are used to find and create the correct type of view.

If multiple providers return a matching view, the view with the longest name is selected. This way, e.g. hierarchies of subviews can be registered like "admin/", "admin/users", "admin/settings" and the longest match is used.

If the view being deactivated indicates it wants a confirmation for the navigation operation, the user is asked for the confirmation.

Registered ViewChangeListeners are called upon successful view change.

Parameters:

navigationState - View name and parameters

navigateTo

void navigateTo(String viewName,
                Map<String,Object> parameters)
         throws ViewNavigator.ViewNavigationException

Navigates to the View identified by given viewName using given parameters, if any, and linking them to View fields using ViewParameter annotated view class fields.

If the view being deactivated indicates it wants a confirmation for the navigation operation, the user is asked for the confirmation.

Registered ViewChangeListeners are called upon successful view change.

Parameters:

viewName - View name

parameters - Optional view parameters

Throws:

ViewNavigator.ViewNavigationException - View with given name cannot be found or other view handling error

navigateTo

default void navigateTo(String viewName)
                 throws ViewNavigator.ViewNavigationException

Navigates to the View identified by given viewName.

If the view being deactivated indicates it wants a confirmation for the navigation operation, the user is asked for the confirmation.

Registered ViewChangeListeners are called upon successful view change.

Parameters:

viewName - View name

Throws:

ViewNavigator.ViewNavigationException - View with given name cannot be found or other view handling error

navigateInWindow

com.vaadin.ui.Window navigateInWindow(String viewName,
                                      Consumer<ViewWindowConfigurator> windowConfiguration,
                                      Map<String,Object> parameters)
                               throws ViewNavigator.ViewNavigationException

Navigate to the View identified by given viewName using the same behaviour of navigateTo(String, Map) but rendering the View contents in an application Window, using optional windowConfiguration to setup Window features.

Parameters:

viewName - View name

windowConfiguration - View window configurator to setup the view Window

parameters - Optional view parameters

Returns:

The UI Window in which the View is displayed

Throws:

ViewNavigator.ViewNavigationException - View with given name cannot be found or other view handling error

navigateInWindow

default com.vaadin.ui.Window navigateInWindow(String viewName,
                                              Map<String,Object> parameters)
                                       throws ViewNavigator.ViewNavigationException

Navigate to the View identified by given viewName using the same behaviour of navigateTo(String, Map) but rendering the View contents in an application Window, using default Window configuration.

Parameters:

viewName - View name

parameters - Optional view parameters

Returns:

The UI Window in which the View is displayed

Throws:

ViewNavigator.ViewNavigationException - View with given name cannot be found or other view handling error

navigateInWindow

default com.vaadin.ui.Window navigateInWindow(String viewName,
                                              Consumer<ViewWindowConfigurator> windowConfiguration)
                                       throws ViewNavigator.ViewNavigationException

Navigate to the View identified by given viewName using the same behaviour of navigateTo(String, Map) but rendering the View contents in an application Window, using optional windowConfiguration to setup Window features.

Parameters:

viewName - View name

windowConfiguration - View window configurator to setup the view Window

Returns:

The UI Window in which the View is displayed

Throws:

ViewNavigator.ViewNavigationException - View with given name cannot be found or other view handling error

navigateInWindow

default com.vaadin.ui.Window navigateInWindow(String viewName)
                                       throws ViewNavigator.ViewNavigationException

Navigate to the View identified by given viewName using the same behaviour of navigateTo(String, Map) but rendering the View contents in an application Window, using default Window configuration.

Parameters:

viewName - View name

Returns:

The UI Window in which the View is displayed

Throws:

ViewNavigator.ViewNavigationException - View with given name cannot be found or other view handling error

navigateBack

boolean navigateBack()
              throws ViewNavigator.ViewNavigationException

Navigates back to previous View, if any. In no previous View is available and a default view is defined, navigator will navigate to the default view.

Returns:

true if a previous view in navigation history, or the default view, was available and back navigation succeeded

Throws:

ViewNavigator.ViewNavigationException - View handling error

navigateToDefault

void navigateToDefault()
                throws ViewNavigator.ViewNavigationException

Navigates to the default View

Throws:

ViewNavigator.ViewNavigationException - If no default View is available or other view handling error

runAfterLeaveConfirmation

void runAfterLeaveConfirmation(com.vaadin.navigator.ViewLeaveAction action)

Triggers View.beforeLeave(ViewBeforeLeaveEvent) for the current view with the given action.

This method can be called from application code when you want to e.g. show a confirmation dialog before perfoming an action which is not a navigation but which would cause the view to be hidden, e.g. logging out.

Note that this method will not trigger any ViewChangeListeners as it does not navigate to a new view.

Parameters:

action - the action to execute when the view confirms it is ok to leave

toView

default ViewNavigator.NavigationBuilder toView(String viewName)

Get a ViewNavigator.NavigationBuilder to create a navigation declaration to navigate to given viewName using parameters.

Parameters:

viewName - View name (not null)

Returns:

NavigationBuilder

getDefaultViewName

String getDefaultViewName()

Get default view name

Returns:

Default view name, or null if not defined

getCurrentViewName

String getCurrentViewName()

Get current (active) view name in navigator

Returns:

Current view name, or null if no view is currently active in navigator

getCurrentView

com.vaadin.navigator.View getCurrentView()

Get current (active) view in navigator.

Note that this methods returns always the current top-level View in navigator: this means that sub-view instances will be never returned. To obtain current sub-view check if returned View is a SubViewContainer instance and than call SubViewContainer.getCurrentView() method.

Returns:

Current view, or null if no view is currently active in navigator

addViewChangeListener

com.vaadin.shared.Registration addViewChangeListener(com.vaadin.navigator.ViewChangeListener listener)

Listen to changes of the active view

Parameters:

listener - Listener to invoke during a view change

Returns:

the listener Registration

getCurrent

static Optional<ViewNavigator> getCurrent()

Get the current ViewNavigator, if available as Context resource or from current UI.

Returns:

Current ViewNavigator, or an empty Optinal if not available

require

static ViewNavigator require()

Requires the current ViewNavigator. If not available using getCurrent(), an IllegalStateException is thrown.

Returns:

Current ViewNavigator

Throws:

IllegalStateException - ViewNavigator is not available as a Context resource of from current UI

builder

static ViewNavigator.Builder builder()

Builder to create ViewNavigator instance in fluent-style mode

Returns:

ViewNavigatorBuilder