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`
  - `Number`s
  - `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

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    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 `ViewChangeListener`s 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 `ViewChangeListener`s 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 `ViewChangeListener`s 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 `ViewChangeListener`s 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

Copyright © 2019 The Holon Platform. All rights reserved.