Overview of Embedding Applications
In addition to running Vaadin as an application in a web page, you can embed it in a web page which could be part of some other application. Embedding applications is an alternative to writing monolithic frontends for your applications.
Embedded applications are also known 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. The difference is that the embedded application has backend 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 is embedded and export it: Write and declare a server-side component in a specific way, using a custom element tag name; and 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 aren’t 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 is 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 use to identify it on the host application. — Configure properties in the constructor using theaddProperty()
method. — Implement theconfigureInstance()
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, 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 by 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
|
Generated Tag Name Represents a Web Component
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 the wrapper’s shadow root and isn’t available outside it. Hence, its styles don’t leak to the page, and global page styles don’t affect the styles of the embedded component.
|
The embeddable applications can also be used inside React views in Hilla applications, see Use Custom Flow Components In Hilla
Using External Embeddable Applications
If you use an embedded application that you develop in your own web application on the same domain, the preceding information is enough to make it work. However, the situation is different if you are developing an embeddable application to be deployed to a domain that differs from the domain of the main/embedding application. In this case, there is a cross-site cookies issue.
Like other servlet applications, Vaadin applications use cookies to track the HTTP session by default. For some cases, cross-site cookies can’t be used for embedding. In these cases, SSL session tracking mode can be used to get the embedded application to work.
To make embedded applications work, configure the server on which you are going to deploy the embeddable application to use HTTPS/SSL
. The procedure for doing this is specific to each web server, so it’s out of the scope of this tutorial. Check the documentation of the server that you use. Then 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);
}
}
Lastly, use HTTPS
protocol for links to your embeddable application. This means that the main/embedding application should use links with a format such as https://YOUR_DOMAIN:443/VAADIN/web-component/my-component.js
. Use a similar pattern for other links.
Note
|
Session tracking mode switch is needed only in production. You probably don’t need to perform these steps during application development. In your tests, you normally use localhost as a local domain. Hence, there aren’t any issues with plain cookies session tracking mode. The session tracking mode switch is required only in production.
|
You can use a web.xml
file and read session context initialization parameters from there in SessionTrackingModeListener
code to switch the session tracking mode conditionally. You use the init
parameter in web.xml
to set one value for development mode, and another for production mode.
Topics
- Tutorial
- Creating a basic embedded application with Vaadin Flow.
- Application Properties
- How to set properties of embedded applications.
- Theming
- How to theme an embedded application.
- Configuring Push
- How to configure push in an embedded application.
- Security
- How to use an embedded application’s properties to secure it.
- Preserve on Refresh
- How to preserve content when an embedded application is refreshed.
- Limitations
- List of limitations in embedded applications.