Overview of Embedding Applications

Embedding applications is an alternative to writing monolithic frontends for your applications.

Embedded applications are also know as micro frontends. They are isolated and self-contained pieces of code that can be maintained by different teams, using different frameworks. A simple example is an embedded calendar in a web page: the calendar functionality is isolated and has no relation to the logic of the main application.

Embedding an application is similar to adding a client-side widget to a page, except the embedded application has back-end logic and is a real application in its own right.

Embedding Applications in Vaadin

Vaadin allows you to embed applications using web components and provides the WebComponentExporter class for this purpose.

These are the basic steps to creating an embedded application:

  • Create the application that will be embedded and export it:

    • Write and declare a server-side component in a specific way, using a custom element tag name.

    • Create an exporter for the component by extending the WebComponentExporter class.

  • Embed and use the application in your host (embedding) page.

    • Make your page aware of the application by adding an element with a matching custom tag.

The embedded application behaves like a standard Vaadin component, regardless of any other content on the page, except that certain features are not available. See Embedded Application Limitations for more.

Creating an Embedded Application

To create an embedded application, you need to export a component as an embeddable application:

  • Create the component (MyComponent) that will be used as the embedded application. You can create a new component or use an existing one. This component (application) has no relation to the host application.

  • Create an exporter for the component, by extending the WebComponentExporter<MyComponent> class.

    • Implement its constructor providing the tag name that you will use to identify it on the host application.

    • Configure properties in the constructor using the addProperty method.

    • Implement the configureInstance method, if you need additional initialization of the exported component (for example, add a listener to the original component).

  • Deploy your embeddable application.

Importing an Embeddable Application

To embed the exported application in a page:

  • Import the web component URL resource of the embedded application, for example <script type='module' src='YOUR_EMBEDDED_APPLICATION_URI/web-component/my-component.js'></script>.

    • The application is imported using the path "web-component/my-component.js", where "web-component" is the base path for embeddable applications, and "my-component.js" is the custom-tag-name.js.

    • YOUR_EMBEDDED_APPLICATION_URI is the URI at which you deploy your exported application. This depends on how and where you deploy the application.

  • Use the embedded web component in your HTML code using the tag name you assigned to the embedded application, for example <my-component></my-component>`.

    • The tag name, "my-component", is used to identify the embedded application.

    • The element my-component is used in your HTML page content. This can be a static HTML file or content generated by any framework, for example a plain servlet, JSP, and more.

Note
The generated custom-tag-name ("my-component" in the example) element is a web component which wraps the original MyComponent HTML representation element. This element is inside wrapper’s shadow root and it’s not available outside it. So its styles don’t leak to the page and global page styles don’t affect the styles of the embedded component.

Using an external Embeddable Application

If you use an embedded application which you develop in your own web application on the same domain then the information above is enough to make it work. However if you are developing an embeddable application that will be deployed to a domain which differs from the domain of the main/embedding application then there is a cross-site cookies issue. Like other Servlet applications Vaadin applications use cookies to track HTTP session by default. For some cases cross-site cookies may not be used for embedding. In these cases SSL session tracking mode can be used to get the embedded application to work. Here are the necessary steps to make embedded application work:

  • Configure the server where you are going to deploy the embeddable application to use HTTPS/SSL. This is quite specific for every web server so it’s out of the scope of this tutorial: check the documentation of the server which you use.

  • Configure the embeddable application to use SSL session tracking mode.

@WebListener
public class SessionTrackingModeListener implements ServletContextListener {

    @Override
    public void contextDestroyed(ServletContextEvent event) {
    }

    @Override
    public void contextInitialized(ServletContextEvent event) {
        ServletContext context = event.getServletContext();
        EnumSet<SessionTrackingMode> modes = EnumSet
                .of(SessionTrackingMode.SSL);

        context.setSessionTrackingModes(modes);
    }

}
  • Use HTTPS protocol for links to your embeddable application. It means that the main/embedding application should use links like https://your_domain:443/VAADIN/web-component/my-component.js (same pattern for other links).

Note
You don’t need to do these steps during the application development most likely: in your tests you normally use localhost as a local domain. So there will be no any issues with plain cookies session tracking mode. Session tracking mode switch is required only in production.

You may use web.xml file and read session context init parameters from there in SessionTrackingModeListener code to switch the session tracking mode conditionally (based on init parameter value in web.xml: one value for dev mode, another for production mode).

For more on embedded applications, see: