Understanding Remote App Types¶
Remote Apps use Liferay’s front-end infrastructure to register external applications and render them as Page widgets. When creating a remote app entry, you can select between the IFrame and Custom Element types. This determines how the external application is registered with Liferay DXP and rendered in Site Pages.
Both types of Remote Apps are integrated into Pages as a widget during the render Page life cycle. When you create the entry, Liferay generates and adds the widget to the OSGi service registry. If desired, you can set additional properties at the entry or widget level to configure how both IFrame and Custom Element applications are rendered.
However, IFrame and Custom Element applications are hosted and rendered differently. They also have different levels of access to Liferay services and runtime data.
The Custom Element type offers greater integration with the Liferay platform and supports more complex scenarios.
Using the IFrame Type¶
The IFrame type renders external applications into a separate
<iframe> element and allows for limited interaction with the host page using Liferay’s client SDK API. The architecture for IFrame applications includes three main parts: the Liferay server, the Liferay host Page, and the external server hosting your application.
Each IFrame entry stores an IFrame URL that links to an application, typically served from an external server. As a result, the application must provide an HTML document including markup, scripts, styles, and (optionally) the client SDK.
When you add the remote app’s widget to a Page, Liferay uses the entry’s URL to render an
<iframe> tag populated with the external application’s content. If the entry or widget instance includes properties, they are passed to the application as additional URL attributes (
<iframe (+properties)/>) so the app can access them programmatically.
IFrame apps must be deployed to a server so they can assemble their own markup and send it to the browser to fill the widget’s
<iframe> element. By contrast, Custom Element apps don’t require a server to produce any markup. They only require the application’s code is available via URLs, since the browser is responsible for running the necessary logic via the app’s widget and JS code.
By default, all browsers impose the ‘same-origin’ policy for IFrame applications to prevent information flow between a host page and its external applications. Liferay provides a client SDK script to allow limited communication between IFrame elements and a Liferay Page. It works by implementing a communication protocol with the Page via the
postMessage() API. To use this script, it must be included in the application’s markup.
When an IFrame app uses the client SDK, the Liferay Page receives instructions to perform certain actions on behalf of the application as the current logged-in user. This includes making service calls to the DXP server and access state details (e.g., opening a toast in the host Page, calling headless APIs, running GraphQL queries, accessing style properties).
Using the Custom Element Type¶
The Custom Element type renders external application code into a separate HTML
<custom-element> and provides full integration with the Liferay host Page. The architecture for Custom Element applications includes three main parts: the Liferay server, the Liferay host Page, and the server storing your application’s code. Liferay uses these files to create the application in a browser.
The remote application’s code must declare the custom element and provide an HTML element name matching the name in the remote app entry. For this reason, it must use an IIFE to ensure the custom element declaration runs in the browser as soon as the app code is loaded.
When the remote app’s widget is added to a Page, it renders the application markup by first generating a tag with the provided HTML element name and then executing the logic defined in the element’s code. If the entry or widget instance includes properties, they are added to the generated custom element markup (
When multiple instances of the Custom Element widget are added to a page, Liferay only includes the application’s URLs once.