Client Extensions UI Reference
Liferay’s widget client extensions (custom element and iframe) register applications with Liferay, adding them as widgets to site pages. Additionally, you can style your pages without deploying a new theme by creating styling client extensions.
To add and manage these extensions,
Open the Global Menu (
) and navigate to Applications tab → Client Extensions.Click Add (
) on the right side.Choose your client extension type.
Frontend Client Extension Properties
Set these properties in the client-extension.yaml file of any frontend client extension:
| Name | Data Type | Default Value | Description |
|---|---|---|---|
baseURL |
String | Derived from site URL | The base path from which all of the client extension’s defined resources are served. |
description |
String | The client extension’s description. | |
name |
String | The client extension’s name (as it appears in the UI). A name is required for frontend client extensions. | |
sourceCodeURL |
URL | https://www.liferay.com | The address to the client extension’s source repository. |
typeSettings |
String[] | [] | A list of strings that are processed with Liferay’s UnicodeProperties syntax. Type-specific client extension properties are copied automatically into this when the client extension is built. |
See Configuring Client Extensions in client-extension.yaml for more information.
Export/Import Frontend Client Extensions Configured From the UI
Liferay DXP 2024.Q1+/Portal 7.4 GA112+
This feature is currently behind a release feature flag (LPS-182184). Read Release Feature Flags for more information.
You can Export/Import frontend client extensions that were configured from the UI while maintaining the external reference code and references created when the client extension was used in a page.
This export and import method is only available to client extensions configured from the UI.
To export a frontend client extension,
Open the Global Menu (
), navigate to the Applications tab, and select Client Extensions under Custom Apps.Click Actions (
) next to the client extension you want to export and select Export as JSON.
The client extension is exported in JSON format and it’s downloaded automatically onto your machine.
To import a frontend client extension,
In the Client Extensions application under Custom Apps, click Options (
) next to the Global Menu and select Import.Select the JSON file containing the client extension and click Import.
The client extension is imported, and it appears in the client extensions list.
Widget Client Extensions
The custom element and iframe client extensions use Liferay’s frontend infrastructure to register JavaScript applications and render them as page widgets.
When creating or editing a widget extension, the following fields are available depending on the selected type of client extension.
| Field | Description |
|---|---|
| Name | The display name used for the client extension entry and its widget. Required. |
| Description | A description for the client extension entry. |
| Source Code URL | A URL to the external extension’s source code for convenience. |
| URL (IFrame) | Specify the URL to be rendered in the iframe. The entry’s widget renders the application in an <iframe> element that points to the client extension’s URL. |
Styling Client Extensions
The CSS, JavaScript, theme CSS, and theme favicon client extensions make the design implementation experience in Liferay smooth, scalable and efficient.
These client extensions enable extending the default look and feel and behavior of your sites without the need for theme editing and redeployment. You can instead add styling and JavaScript client extensions directly to pages in a scalable way by using an external source of design for page building, without needing to modify the underlying theme for this purpose.
When creating or editing a styling extension, the following fields are available depending on the selected type of client extension.
| Field | Description |
|---|---|
| Name | The display name used for the client extension entry. Required. |
| Description | A description for the client extension entry. |
| Source Code URL | A URL to the external extension’s source code for convenience. |
| CSS URL (CSS) | A URL to where the CSS application is hosted. This CSS is appended to theme.css. Required. |
| JavaScript URL (JS) | A URL to where the JavaScript application is hosted. This JavaScript is appended to main.js. Required. |
| Main CSS URL (Theme CSS) | A URL to where the main CSS file is hosted. This CSS replaces main.css. |
| Clay CSS URL (Theme CSS) | A URL to where the clay CSS file is hosted. This CSS replaces clay.css. |
| URL (Theme Favicon) | A URL to where the favicon is hosted. This favicon replaces the one from the theme. Required. |
Documents and Media is not recommended to host design resources to be used for Client Extensions. Permissions can be confusing, and users could eventually manipulate or delete these resources. Also, Documents and Media is not able to provide the correct MIME type for CSS resources.
Once the client extensions are created, they can be applied so that pages are able to read their contained styles. For more information on how to use the client extension on a page, see Customizing Liferay’s Look and Feel, choose the client extension type you desire, and follow the steps to apply or override it on a page.