Using Routes with Custom Elements¶
Available Liferay 7.4+
Custom elements are a type of client extension that use Liferay’s front-end infrastructure to register external applications with the Liferay platform and render them as widgets. For applications that include multiple routes (e.g., React Router, you can define remote application properties to determine which routes are used for a widget at runtime. These properties can be set for an application via the Remote Apps menu in Liferay or the widget’s configuration options once deployed.
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.
In this tutorial, you’ll create a basic React application using Liferay’s
create_remote_app.sh script, which generates a sample app with three routes:
hello-bar. After compiling the application and hosting its
.css files, you’ll register the application with Liferay and deploy it as a page widget. Finally, you’ll configure it to use each of the alternative routes.
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 with basic routing.
Creating, Building, and Hosting the React Application¶
Start a new Liferay DXP 7.4+ container. You can continue to the next steps while the container starts.
docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u29
Run this command in a separate terminal to generate the React application.
curl -Ls https://github.com/liferay/liferay-portal/raw/master/tools/create_remote_app.sh | bash -s j1v3-remote-app react
Verify the application was created successfully.
The script should create a new React application called
j1v3-remote-appthat includes the following elements:
j1v3-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 │ │ └── pages │ │ └── HelloBar.js │ ├── hello-foo │ │ └── pages │ │ └── HelloFoo.js │ └── hello-world │ └── pages │ └── HelloWorld.js └── yarn.lock
Navigate to the new
j1v3-remote-appfolder and build the application.
Verify the build succeeded 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
Sign in to Liferay at
<http://localhost:8080>using the email address email@example.com and the password test. When prompted, change the password to learn.
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.
This adds the files to the Liferay Document Library and assigns them unique WebDAV URLs, which you’ll use to create the remote application.
This tutorial hosts the application’s static resources in Liferay’s Document Library for demonstration purposes. In a production environment, you should host the application’s files on a server optimized for hosting static resources.
To view each file’s URL, click the Info icon () and select one of the files at a time. Copy each file’s WebDAV URL and save them for use in the next step.
Registering and Deploying the Application¶
Open the Global Menu (), click on 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 J1V3-Remote-App, which you can deploy to Site Pages like any other Page widget. It appears under the selected Portlet Category Name.
Since J1V3-Remote-App is instanceable, you can add many of them to a page, each with its own independent configuration. For this tutorial, add the widget to a page twice.
The auto-generated app includes three routes:
hello-bar. By default the application uses the
hello-world route. However, you can use remote application properties to configure it to use an alternate route. You can set these properties via the Remote Apps menu or a widget’s configuration options.
Defining a Route Property via Widget Configuration¶
Edit the Page containing the J1V3-Remote-App widgets.
Click the Options button () for one of the widgets and select Configuration.
route=hello-barinto the Properties field.
Verify the configured widget uses the
hello-barroute, while the other widget still uses the
Analyzing the Route Code¶
index.js file creates the
WebComponent class, which extends the
HTMLElement interface. This class implements the interface’s
connectedCallback() function, which calls
App as a parameter. When
App is called, it checks for any defined
"route" attribute and compares that value with the available routes. If it matches either
hello-bar, then it returns and renders the corresponding route. Otherwise, it returns and renders
Each of the routes is imported into the
index.js file from the
routes ├── hello-bar │ └── pages │ └── HelloBar.js ├── hello-foo │ └── pages │ └── HelloFoo.js └── hello-world └── pages └── HelloWorld.js
import React from 'react'; const HelloWorld = () => ( <div className="hello-world"> <h1>Hello World</h1> </div> ); export default HelloWorld;
import React from 'react'; const HelloFoo = () => ( <div className="hello-foo"> <h1>Hello Foo</h1> </div> ); export default HelloFoo;
import React from 'react'; const HelloBar = () => ( <div className="hello-bar"> <h1>Hello Bar</h1> </div> ); export default HelloBar;