Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Introduction to Embedding Applications

Embeddeding 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

Overview

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.

See Creating an Embedded Vaadin Application Tutorial for a detailed example.

Importing an Embeddable Application

To embed the exported application in a page:

  • Add webcomponent-loader.js polyfill script to your page, for example <script type="text/javascript"src="YOUR_EMBEDDED_APPLICATION_URI/VAADIN/build/webcomponentsjs/webcomponents-loader.js"></script>

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

    • While the example above uses the polyfill provided with Vaadin, you can use any CDN (such as unpkg.com).

  • 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.

    • As before, YOUR_EMBEDDED_APPLICATION_URI is the URI at which you deploy your exported 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.

For more on embedded applications, see:

4BE256E8-62E7-4742-B18F-FCB238A797A2