Understanding Custom Element Client Extensions

Custom element client extensions use Liferay’s frontend infrastructure to register external, remote applications with the Liferay platform and render them as widgets. Modern Liferay pages often use a combination of out-of-the-box widgets and custom element client extensions that adhere to Web Components standards. For users building pages, Liferay obfuscates this distinction and presents custom elements alongside widgets in a single palette of options. While this provides a better user experience, it’s important to understand that custom element client extensions and widgets are handled differently when rendering pages.

Unlike widgets, client extensions live and run outside of the Liferay portal container. The principal benefit of this decoupling for custom elements is that they become technology agnostic, so you can build the client extension with whatever technology, language, framework, or version you choose without any constraints from Liferay. In practice, this means that it’s possible to build a page that uses Java to render one component, React to render another, and different technologies for a third, fourth, or fifth component. With this capability, you can build external custom element applications without the need for Liferay-specific expertise.

Architecture of Custom Element Applications

Custom element applications comprise three main components: the Liferay server, the Liferay host page, and the server where the external application code is stored. Together, these components work to render the application directly in your browser.

Custom element client extensions embed external application code within a dedicated <custom-element> HTML tag that enables full integration with the host page. Each custom element entry specifies an HTML element name, URLs for required JavaScript and CSS files, and any properties that are applied to the application at runtime. When you add a custom element to a page, Liferay inserts the associated JavaScript and CSS files into the page using <script> and <link> tags. The JavaScript defines and initializes the application, while the CSS styles it.

Once rendered, the custom element application is fully integrated with the Liferay host page. This means it can use Liferay’s public JavaScript API and leverage the host page’s existing style classes. However, you can control how the application interacts with the host page by configuring the custom element’s structure and styling. For instance, you can use a shadow DOM to isolate the custom element’s styles from those of the host page.

Because custom element client extensions are implementations of Web Components standards, you can do more than just treat them like widgets. Web Components allow you to define your own custom HTML tags that tell the browser what to do when it encounters the custom element in the markup. As long as your client extension is deployed, registered, and working correctly, you can freely reference its HTML tag anywhere in your code, whether that is a fragment, a widget template, or even a JSP (Jakarta Server Page), and the browser will interpret the custom element inline. This model is extremely flexible because it enables you to configure the presentation of a custom element with additional markup and styling even if you don’t have access to the client extension code.

Anatomy of Custom Element Client Extensions

As with any client extension project in Liferay, the client-extension.yaml file defines the structure, resources, and configurations needed to deploy and manage the extension. The assemble block tells the processor where to find the resources that should be included in the deployable archive and where to place the artifacts once the build process is complete.

assemble:
    - from: build/static
      into: static

The extension definition block contains the core configurations for the client extension. Below is an example definition block for one of the custom element client extensions in the Liferay Sample Workspace, followed by a table of the properties and their descriptions.

liferay-sample-custom-element-2:
    cssURLs:
        - css/main.*.css
    friendlyURLMapping: liferay-sample-custom-element-2
    htmlElementName: liferay-sample-custom-element-2
    instanceable: false
    name: Liferay Sample Custom Element 2
    portletCategoryName: category.client-extensions
    type: customElement
    urls:
        - js/main.*.js
    useESM: true

Registration and Management Options

There are two mechanisms for registering and managing custom elements with Liferay. The first method is the standard deployment approach that is common to all client extension types. This is the the recommended best practice approach we will use throughout the course. Registering and managing custom elements with client extension deployment eliminates error-prone manual processes and enables you to leverage CI/CD and GitOps workflows.

That said, there may be times when you want to use the second mechanism: manual registration via UI. To manually register a new custom element client extension, open the Global Menu (ICON), navigate to the Control Panel tab, click Client Extensions, then Add (ICON), and select Add Custom Element.

As you can see, many of the form fields align with the property names in the client-extension.yaml file. Custom elements registered manually through the UI can have their properties updated in the UI. Custom elements registered through deployment will show up in the UI, but they can only be updated with follow-up deployments.

Manual registration is mainly useful for troubleshooting or one-off testing scenarios. Client extension deployment is the recommended mechanism for registering and managing custom elements.

Conclusion

Custom element client extensions are a technology-agnostic method of integrating external web applications with Liferay pages, right alongside out-of-the-box functionality like widgets. Clarity plans to use custom elements to implement a micro frontend for their ticketing app. Next, you’ll take a closer look at the code to understand how custom element client extensions retrieve and display data.