Embedding Applications in Compatibility and Production Mode

Compatibility Mode

When embedding applications in compatibility mode, the following differences to development mode need to be taken into account:

• The "webcomponents-loader.js" polyfill library is required to import web components using HTML import.

• The web component URL resource is imported via HTML import.

  Example: Importing a web component in compatibility mode.

  HTML

  <script type='text/javascript' src='/frontend/bower_components/webcomponentsjs/webcomponents-loader.js'></script>
  <link rel='import' href='/vaadin/web-component/login-form.html'>

• When implementing VaadinServlet, you will need to add more urlPatterns than in npm mode:

  Java

  @WebServlet(urlPatterns = {"/vaadin/*", "/VAADIN/*", "/frontend/*"})
  public class CompatibilityVaadinServlet extends VaadinServlet {
  }

  • Add /VAADIN/* to the urlPatterns in both development *and* production modes.

    • We need to handle Vaadin client and other static resources under /VAADIN for the embedded application.

  • In development mode, add /frontend/* to the urlPatterns.

    • We need to handle WebJar resource URIs: we use various Vaadin components in the server-side web component and this requires a frontend URI handler.

• If you follow the examples given in Creating an Embedded Vaadin Application Tutorial, you need to make sure that the embedded application has access to /frontend-* static folders. If your http servlet is mapped to /*, it will swallow the static resource requests.

The rest of the embedding process is the same.

Production Mode

Embedding applications in production mode is similar to development mode in that it requires these two steps:

1. Package the application for production in the normal way.

2. Import the packaged application onto the target page.

However, in production mode the second step differs slightly from in development mode. The reason is that the "webcomponents-loader.js" polyfill library is located in a different folder, which depends on the user’s browser. This library provides support for browsers that do not have native support for rel="import on a link element.

To avoid using the boilerplate line in production mode, you should use a script tag, instead of a link element for the web component.

Example Using the <script> tag for a web component in production mode.

HTML

<script type='text/javascript'
        src='/vaadin/web-component/login-form.html'>
</script>

In production mode, the generated login-form.html content is simply JavaScript code that adds a proper polyfill library together with the required imports.