> Markdown version of [Migration example](https://vaadin.com/docs/v14/flow/upgrading/v8/8-migration-example). Section index: [llms.txt](https://vaadin.com/docs/v14/flow/llms.txt)

# Migration example - Bookstore Starter

This document shows an example of migration from a Vaadin 8 app to Vaadin 14. The migration process is done step-by-step and can be seen through the history of its [GitHub repository](https://github.com/vaadin/bookstore-starter-flow). The idea is to keep the application compilable in order to be able to see the result of migrating steps.

## <a id="step-1-initial-vaadin-flow-configuration"></a>Step 1 - Initial Vaadin Flow configuration

### <a id="maven"></a>Maven

First of all, required maven dependency must be added to pom.xml. The Vaadin 8 dependencies, except `vaadin-themes`, are kept for now and will be eliminated after the whole application is migrated. The only Vaadin platform dependency is the following:

```xml
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.vaadin</groupId>
      <artifactId>vaadin-bom</artifactId>
      <type>pom</type>
      <scope>import</scope>
      <version>${vaadin.version}</version>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
     <groupId>com.vaadin</groupId>
     <artifactId>vaadin-core</artifactId>
  </dependency>
</dependencies>
```

Starting from Vaadin 14, the `vaadin-maven-plugin` should be configured for development time to make sure that all the needed resources are available for the development of the project. While it is not mandatory to have the plugin configured for all projects, it is needed for this migration so that necessary files are generated:

```xml
<build>
  <plugins>
    <plugin>
      <groupId>com.vaadin</groupId>
      <artifactId>vaadin-maven-plugin</artifactId>
      <version>${vaadin.version}</version>
      <executions>
        <execution>
          <goals>
            <goal>prepare-frontend</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
```

In this document, migrating custom components and extensions are not covered. So, the widgetset module that includes the following extensions is removed.

- `AttributeExtension`

- `ResetButtonForTextField`

### <a id="ui-class-and-servlet-configuration"></a>UI class and Servlet configuration

- Both `UI` class and Servlet configuration are optional in Vaadin Flow. However, we can keep them to leverage them in some cases e.g. controlling user access.

- Since the components are different, the DOM structure has changed. The new components are based on web components and a new theme. Thus the theming is discussed later.

- In Vaadin Flow the locale is set automatically based on user preferred locale. So, `setLocale` can be removed.

- Best practice for setting page title is using `PageTitle` annotation on each view. So, `getPage().setTitle` is removed from `MyUI::init`.

- All packages names in Vaadin Flow start with `com.vaadin.flow`. One way to correct them is to remove all `import` statements starting by `com.vaadin` and reimport Vaadin Flow classes. For example some equivalent classes in Vaadin Flow are:

- `com.vaadin.ui.UI` → `com.vaadin.flow.component.UI`

- `com.vaadin.server.VaadinRequest` → `com.vaadin.flow.server.VaadinRequest`

- `com.vaadin.ui.TextField` → `com.vaadin.flow.component.textfield.TextField`

- `com.vaadin.ui.VerticalLayout` → `com.vaadin.flow.component.orderedlayout.VerticalLayout`

### <a id="test-page"></a>Test page

In order to verify that Vaadin Flow setup has been done correctly, a simple `HelloWorldPage` like the following can be added.

```java
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H1;
import com.vaadin.flow.router.PageTitle;
import com.vaadin.flow.router.Route;

@Route("")
@PageTitle("My")
public class HelloWorldPage extends Div {
   public HelloWorldPage() {
       this.add(new H1("Hello World!"));
   }
}
```

`@Route("")` shows that root path should be routed to this page. After running the application by `mvn jetty:run`, the “Hello World!” message can be seen in the browser by entering this address: <http://127.0.0.1:8080>.

## <a id="step-2-access-control-and-login-screen"></a>Step 2 - Access Control and Login Screen

### <a id="vaadinservletconfiguration-and-ui-class"></a>VaadinServletConfiguration and UI class

In Vaadin Flow, defining a Servlet class is optional. So, we don’t have to create an extended class of `VaadinServlet`, unless we need to change some configuration. Having a `UI` class is optional too and this class can be removed as well because the `UI` class is created by the framework. However, we may have some tasks assigned to our `UI` class e.g. controlling access. In this example access control is moved to a more suitable place which is described in the following section.

### <a id="access-control"></a>Access Control

`BeforeEnter` event of `UI` class is a good place to control access and there is another event named `UIInit` in `VaadinService` class that is fired whenever a `UI` is created. In order to leverage these events, we can create a class extended from [VaadinServiceInitListener](https://vaadin.com/docs/v14/flow/advanced/tutorial-service-init-listener) and add required code in `serviceInit` method. The result looks like the following piece of code:

```java
public class BookstoreInitListener implements VaadinServiceInitListener {
   @Override
   public void serviceInit(ServiceInitEvent initEvent) {
       initEvent.getSource().addUIInitListener(uiInitEvent -> {
           uiInitEvent.getUI().addBeforeEnterListener(enterEvent -> {
               // Controlling access can be done here.
           });
       });
   }
}
```

`MyUI` class had an instance of `BasicAccessControl` and other classes used it via its accessor; now after `MyUI` class is eliminated, there must be another provider for `AccessControl` implementation. The selected solution here is using a factory class (`AccessControlFactory`).

`CurrentUser` class is also needed to change because it is used in `BasicAccessControl` class. We need to apply new packages names of Flow that start with `com.vaadin.flow`. The same should be done in the next steps of migration.

### <a id="loginscreen"></a>LoginScreen

This is the first `UI` screen migrated to 14. The following items describe what needs to be done in the migration process:

- Instead of `CssLayout` another equivalent component must be used e.g. `FlexLayout` or a simple `Div`.

- Equivalent of `addComponent` method is `add` method.

- `setWidth` method in Flow has only one `String` parameter that includes both measurement unit and width as a number e.g. “15em” or “310px”.

- `Route` annotation determines the URL associated with this screen.

- Predefined style changes to components in 14 are referred to "theme variants", and those change the `theme` attribute of the components instead of the `className`. So, `addStyleName(String)` can be replaced with `addThemeVariants(…​)`. The available theme variants for components are showcased in the component demos. Changes in theming from V8 to Vaadin platform is described [here](https://vaadin.com/docs/v14/flow/upgrading/v8/6-theming.md).

- New `FormLayout` has a method named `addFormItem` takes a component as a parameter and in addition to adding it to the form, it adds a label beside the component as well.

- Instead of `Button::setClickShortcut` the API is now `Button::addClickShortcut;`.

Some other changes that have been done are not related to Vaadin framework migration process; however, it is a good idea to do such refactorings at the same time as migration.

## <a id="step-3-menu-mainscreen-and-aboutview"></a>Step 3 - Menu, MainScreen and AboutView

### <a id="menu"></a>Menu

As explained before, instead of `CssLayout`, `FlexLayout` is used.

`Navigator` class is removed in Flow and this is one of many changes in routing and navigation since version 8. So, `navigator` field is removed from `Menu`. In `addView` method it can be seen that navigation is done by `RouterLink` component.

At this stage, a pretty look is not aimed for. It will be made nicer in later steps.

### <a id="mainscreen"></a>MainScreen

In Vaadin 8 version there is a `CssLayout` that acts as a view container and navigation between different views is done inside the `CssLayout`. In Vaadin Flow, parent layouts can be defined using a newly introduced `RouterLayout` interface. Since `MainScreen` is used as a layout for other views, it must implement `RouterLayout` interface.

### <a id="aboutview"></a>AboutView

Layout of views can be specified in `Route` annotation like this `@Route(value = "About", layout = MainScreen.class)`. We don’t need the `HelloWorldPage` anymore, so it is removed and since it’s good to have a route to root path, `RouteAlias` annotation is used to add a secondary path for `AboutView`.

Another thing worth mentioning here is that in Vaadin platform, a component named `Icon` is added and can be created by calling `create` method of `VaadinIcon` enum.

[Here](https://github.com/vaadin/bookstore-starter-flow/commit/f017602f668527d26f02f1cd2ef862f474ba033b) is the link to see the changes in step 3.

## <a id="step-4-product-grid"></a>Step 4 - Product Grid

### <a id="dataprovider"></a>DataProvider

In Vaadin platform, when `DataProvider::fetch` method is overridden, `query.getOffset()` and `query.getLimit()` must be used to fetch a specific chunk of data. If they are not used it shows that the returned data is incorrect and unexpected. To avoid such mistakes in implemented code, Vaadin platform throws an `IllegalStateException` to show us what is wrong. So, `ProductDataProvider::fetch` is fixed in order to use specified offset and limit. The data provider documentation for Vaadin platform can be found [here](https://vaadin.com/docs/v14/flow/binding-data/tutorial-flow-data-provider).

### <a id="productgrid"></a>ProductGrid

The following items briefly describe some of the changes in `ProductGrid`.

- There is no `HtmlRenderer` in Vaadin platform and it must be replaced by other renderers such as `TemplateRenderer` or `ComponentRenderer`. In this migration, `TemplateRenderer` is used. More info and guidance about all kinds of renderers can be found in "Using Renderers" section of [Grid document](https://vaadin.com/docs/v14/flow/components/tutorial-flow-grid#using-renderers-in-columns). In `TemplateRenderer`, apart from HTML markup, Polymer data binding notation can also be used. In `ProductGrid`, there are three TemplateRenderers:

  - Price and StockCount columns leverage `TemplateRenderer` to align their text to the right.

  - Availability column template uses a Vaadin component named `iron-icon` to show a circle colored based on availability value. In order to set different styles to the circle, three CSS classes with equivalent names to three values of availability (`Available`, `Coming` and `Discontinued`) are defined in a CSS file (grid.css). Also, the dependency of the grid on the CSS file is defined by adding `CssImport` annotation to `ProductGrid` class.

- `Grid.Column::setCaption` method is renamed to `setHeader`.

- `setFlexGrow` method is called for each column to set grow ratios of them.

### <a id="samplecrudview"></a>SampleCrudView

This is the page that includes `ProductGrid` and `ProductForm` and since `ProductForm` is going to be migrated in the next step, the parts of the code related to it are commented. Like in the other views, a `Route` annotation is added here with the "Inventory" value. Also, as this view is the main view of the project, the route to the root path, the `RouteAlias` annotation, should be moved here. Other changes in `SampleCrudView` are the following items.

- `getElement().getThemeList()::add` is used to add a theme variant to a component. An improved API for this has been released in V12.

- In Vaadin 8, to get the parameters passed via the URL, `View` interface must be implemented and the `enter` method must be overridden. In Vaadin platform, there is an interface named `HasUrlParameter` that does the job. It is generic, so parameters are safely converted to the given types. More information about URL parameters can be found [here](https://vaadin.com/docs/flow/routing/tutorial-router-url-parameters.html).

- Instead of using `HorizontalLayout::setExpandRatio`, `HorizontalLayout::expand` method is used.

[Here](https://github.com/vaadin/bookstore-starter-flow/commit/d628f29b81df8a94dacec72556a19f2d7f0ff019) is the link to see the changes in step four.

## <a id="step-5-product-form"></a>Step 5 - Product Form

Since after this step, all Java code is migrated to Vaadin platform, it is time to remove Vaadin 8 dependencies. Besides, keeping both versions may cause some conflicts in their dependencies e.g. `jsoup`. So, `vaadin-server` and `vaadin-push` are removed from pom.xml. Other changes in this step are as follows.

### <a id="productform-design"></a>ProductForm Design

The following items are some of the changes from Vaadin 8 to Vaadin platform in design files.

- In Vaadin 8, Vaadin Designer uses HTML markups to store designed views and they are stored in files with html extension. However, the tags that are used by Vaadin Designer are not standard HTML tags. So, these html files cannot be correctly shown and rendered by browsers. While in Vaadin platform, Polymer template is used to define views and Vaadin Designer also uses it to store designed views.

- Prefix of the Vaadin components names is changed from `v` to `vaadin`.

- For customizing the look and feel of the components using the provided theme variants, the variants are applied with the `theme` attribute, instead of the `style-name` (class name). E.g.

Vaadin 8 version:

```html
<v-button style-name="primary" _id="save">Save</v-button>
```

Vaadin platform version:

```html
<vaadin-button theme="primary" id="save">Save</vaadin-button>
```

### <a id="productform-java-class"></a>ProductForm Java Class

`ProductFormDesign` class is removed and its content is moved to `ProductForm` class. Actually, this is the recommended pattern in Vaadin platform and it is also supported by Vaadin Designer. In Vaadin 8, Vaadin Designer keeps two classes, a superclass for designer generated code and an inherited class for the code implemented by the developer. The following items are some of the changes in `ProductForm`.

- `JsModule` and Tag annotations are the required annotations to connect `ProductForm` class to its design file, ProductFormDesign.html. And unlike Vaadin 8, reading the design file is done automatically and there is no need to call `Design.read`.

- `Id` annotation is used to connect fields to their equivalents in the associated polymer template.

- In `ComboBox`, `setEmptySelectionAllowed` method is renamed to `setAllowCustomValue`.

### <a id="errorview"></a>ErrorView

Router Exception Handling in Vaadin Flow is described [here](https://vaadin.com/docs/v14/flow/routing/tutorial-routing-exception-handling.md). Applications can have different views for catching different exceptions. For example, `ErrorView` catches `NotFoundException` that is thrown when something goes wrong while resolving navigation routes. And unlike Vaadin 8, there is no need to register `ErrorView` in a `navigator` or something like that. It is automatically detected and is used by Flow.

### <a id="samplecrudlogic"></a>SampleCrudLogic

Apart from some cleaning, a small change that is worth mentioning is the change in how the URL of the browser is updated. In Vaadin 8, `page.setUriFragment` is called and the new URL must be constructed and passed as a parameter. While in Vaadin Flow, it is done more elegantly; `navigate` method of `UI` class is called and the view parameter is passed as a parameter to `navigate` method.

## <a id="step-6-production-mode"></a>Step 6 - Production Mode

In Vaadin 14 the production mode is recommended to be enabled by is adding a profile to `pom.xml`. All old V8 related production build configuration can be removed. The following code shows the required configuration for enabling a production build in 14 when running the command `mvn package -Pproduction`:

```xml
<profiles>
  <profile>
    <!-- Production mode is activated using -Pproduction -->
    <id>production</id>
    <properties>
      <vaadin.productionMode>true</vaadin.productionMode>
    </properties>

    <dependencies>
      <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>flow-server-production-mode</artifactId>
      </dependency>
    </dependencies>

    <build>
      <plugins>
        <plugin>
          <groupId>com.vaadin</groupId>
          <artifactId>vaadin-maven-plugin</artifactId>
          <executions>
            <execution>
              <goals>
                <goal>build-frontend</goal>
              </goals>
              <phase>compile</phase>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>
```

For further details on production mode in 14, you can read [here](https://vaadin.com/docs/flow/production/tutorial-production-mode-basic.html).

## <a id="step-7-theming-the-application"></a>Step 7 - Theming the application

There is currently no example on migrating from an existing Vaadin 7 or 8 theme to Vaadin 14 Lumo theme. The component set is different, so the styling cannot be applied out-of-the-box to newer versions.

Thus it is recommended to switch to using the new Lumo theme, and customizing the look and feel on top of that. For more information, check the [Themes and Styling](https://vaadin.com/docs/v14/flow/styling/overview.md) documentation.

`CF6DE862-2AA8-4360-8309-3026912744DE`
