Routing and Navigation

Routing and navigation are core concepts for any web application or site. In Vaadin Flow this has been completely reinvented. In Vaadin 8 and 7 Navigator only supported single-level navigation, had limited support for parameters and did not support HTML5 History API until Vaadin 8.2.

Router is the new navigation API provided by Vaadin Flow. This document only outlines the core concept and how it differs from the old Navigator. To get the best picture on the capabilities of the new Router, you should visit the Router documentation.

The Router API allows building robust and complex application structures with hierarchies, error handling and view access control by using lifecycle events.

The routes are configured declaratively on each navigation target and are the same for the entire application, unlike in V8 where configuration was made for each UI instance separately:

Java

  1. @Route(value = "company", layout = MainLayout.class)
  2. public class CompanyView extends Composite<Div> {
  3.      // Implementation omitted
  4. }

Thus, when migrating from using Navigator, any View from Vaadin 8 can be migrated to Vaadin Flow by removing the registration from the now optional UI class and instead applying the @Route annotation the class. Note that there is no View interface in Vaadin Flow, but instead the class must be a Component!

To receive an event when the user navigates to or from a view, make it implement one of BeforeEnterObserver, BeforeLeaveObserver or AfterNavigationObserver interfaces instead of the enter and beforeLeave methods from View in Vaadin 8. BeforeLeaveEvent.postpone() can be used to postpone or cancel navigation to achieve the same results as selectively calling ViewBeforeLeaveEvent.navigate() in Vaadin 8.

Instead of manually constructing URLs and using ViewChangeEvent.getParameters() to find parameter values, you can use UI.navigate(NavigationTargetClass.class) and have your view implement the HasUrlParameter interface.

The ViewDisplay concept is replaced in Vaadin Flow with the RouterLayout interface, but now it is possible to have nested hierarchies, by using the @ParentLayout annotation to set one RouterLayout class as the parent of another.

There is no ViewProvider in Vaadin Flow as it is not needed.

With the HTML5 History API, it is possible to have deep-linking and use proper navigation state and parameters for the navigation targets. Flow supports optional parameters. It is not anymore possible to use the fragment style (#!) navigation state from V8 as the fragment is not intended to be used on the server side at all, but just be a browser feature for navigation inside a page.

It is very much recommended to take a look at the router documentation to get full understanding on how to structure your Vaadin Flow application.