Creating a Basic Custom Element¶
Available Liferay 7.4+
Custom elements are a type of client extension that use Liferay’s front-end infrastructure to register external, remote applications with the Liferay platform and render them as widgets.
Custom elements or IFrames being deployed in the same way as other types of client extensions is a beta feature in Liferay 7.4. This tutorial uses a different way to deploy custom element remote applications, and it is still the recommended approach until a future update.
Here you’ll create a basic remote application using Liferay’s
create_remote_app.sh script. After the application is generated, you’ll compile its code and host its
.css files. Once hosted, you’ll copy each file’s URLs and use them to create a custom element. Finally, you can deploy the application to site pages as a widget.
Custom element client extensions are agnostic regarding how applications are built, packaged, and hosted. This tutorial only offers a convenient way to create a sample custom element application.
Run this command to generate the React application’s code:
curl -Ls https://github.com/liferay/liferay-portal/raw/master/tools/create_remote_app.sh | bash -s h5v7-remote-app react
This calls the script with two arguments: a custom HTML element name (
When finished running, the script automatically creates a new React application which includes these elements in a folder named
h5v7-remote-app ├── node_modules ├── README.md ├── package.json ├── public │ └── index.html ├── src │ ├── common │ │ ├── services │ │ │ └── liferay │ │ │ ├── api.js │ │ │ └── liferay.js │ │ └── styles │ │ ├── hello-world.scss │ │ ├── index.scss │ │ └── variables.scss │ ├── index.js │ └── routes │ ├── hello-bar │ │ ├── components │ │ └── pages │ │ └── HelloBar.js │ ├── hello-foo │ │ ├── components │ │ └── pages │ │ └── HelloFoo.js │ └── hello-world │ ├── components │ └── pages │ └── HelloWorld.js └── yarn.lock
index.js file includes two customizations necessary for using the application as a Liferay custom element remote application.
WebComponent: On line 21, the application is declared a
WebComponentso it can connect to Liferay’s framework.
ELEMENT_ID: On line 30,
ELEMENT_IDis set to
h5v7-remote-app, instead of the conventional
<div id="root" />. This is because a remote application’s HTML Element Name must match the application’s
<div id="root" />does not work for this purpose.
Understanding the React Routes¶
The generated code includes three routes:
hello-bar. Routes are alternative sets of code that you can use when running an application. See Using Routes with Custom Elements for a basic example.
Building the React Application¶
create_remote_app.sh, navigate to the new
h5v7-remote-app folder and build the application:
This command creates an optimized production build, which includes the
.css files necessary for running the application.
Before proceeding, confirm the code has compiled successfully and take note of the application’s
Creating an optimized production build... Compiled successfully. File sizes after gzip: 43.51 kB build/static/js/main.114dde4a.js 121 B build/static/css/main.9877909d.css
These files must be hosted in a location accessible to Liferay. They can be hosted on a remote server or a data storage system optimized for serving static resources. For demonstration purposes, this example uploads them to Liferay’s Document Library and hosts them using WebDAV URLs.
Unique file names are generated for every build. When testing your custom applications, remember to update your
.css files after builds.
Hosting the Application Files¶
For demonstration purposes this tutorial hosts the application’s static resources in Liferay’s Document Library. In a production environment, you should host the application’s files on a server optimized for hosting static resources.
Start a new Liferay DXP instance by running
docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u29
Sign in to Liferay at http://localhost:8080 using the email address firstname.lastname@example.org and the password test. When prompted, change the password to learn.
Then, follow these steps:
Open the Site Menu (), expand Content & Data, and go to Documents and Media.
Click the Add button () and select Multiple Files Upload.
Drag and drop the
.cssfiles into the upload area.
Alternatively, use Select Files to upload them.
This adds the files to the Document Library and assigns them unique URLs, which you’ll use to create the remote application.
To view each file’s URL, click the Info icon () and select a file. Copy each file’s WebDAV URL and save them for use in the next step.
Registering the Application with Liferay¶
Open the Global Menu (), click the Applications tab, and go to Remote Apps.
Click the Add button ().
Enter these values:
HTML Element Name
WebDAV URL for the
WebDAV URL for the
Portlet Category Name
Once saved, Liferay creates a widget named H5V7-Remote-App, which you can deploy to site pages like other page widgets. This widget appears under the selected Portlet Category Name.