Expert Insights Hub

Overview:

Liferay 7.4 offers a powerful system for extending its functionality with front-end client extensions. This allows developers to embed custom JavaScript, CSS, and external frameworks (like React, Angular, or Vue.js) directly into the Liferay portal. By leveraging this system, you can create dynamic, interactive user interfaces while maintaining the core capabilities of Liferay, such as user authentication and data security.

In this blog, we will explore how to create a front-end client extension in Liferay 7.4 using React. By converting a React app into a custom web component, we can seamlessly integrate it into the Liferay portal. This enables the development of interactive UIs for Liferay users while utilizing React's powerful ecosystem.

Prerequisite:

• JDK 11
• Liferay Server: liferay-dxp-tomcat-2024.q4.0
• Liferay Developer Studio:  3.9.7.202207131011-ga8
• Node.js
• React JS

What is a Frontend Client Extension in Liferay?

A frontend client extension in Liferay allows developers to add custom functionality to Liferay's frontend without modifying the core platform. These extensions can be used to: 

• Add custom JavaScript and CSS.
• Integrate with external libraries or frameworks.
• Build reusable components, such as widgets or portlets, that can be embedded in different parts of a Liferay site.
• Extend Liferay's default UI and behavior.

In Liferay 7.4, the frontend client extension system allows you to register custom web components (like React or Angular components) and easily integrate them into the portal.

Key Features of Frontend Client Extensions in Liferay 7.4:

1. Framework Agnostic

• Supports modern front-end frameworks like React, Angular, Vue.js, or even plain JavaScript, giving developers flexibility to use their preferred technologies. 

2. Seamless Integration with Liferay

• Easily integrates custom front-end components into Liferay’s environment, allowing for smooth interaction with Liferay services, APIs, and theme styles.

3. Modular Architecture

• Encourages a modular approach to development, allowing for reusable, independent components that can be deployed and maintained separately.

4. Shadow DOM Support

• Provides Shadow DOM encapsulation for CSS and JavaScript, ensuring style and behavior isolation from Liferay’s global environment. This prevents conflicts with other portal elements.

5. Single Page Application (SPA) Compatibility

• Fully compatible with Liferay’s SPA navigation system, enabling fast, smooth transitions between pages without full reloads.

6. Deployment via Liferay Workspace

• Simplifies deployment using Liferay Workspace and the Blade CLI, streamlining the build and deployment process for front-end developers.

7. Customization and Extensibility

• Offers the ability to customize and extend Liferay’s default behavior and UI through custom elements, widgets, and portlets.

8. Access to Liferay APIs and Services

• Provides easy access to Liferay’s REST APIs, OAuth2 services, and ThemeDisplay objects, enabling dynamic, data-driven applications.

9. Automatic Resource Loading

• Automatically handles loading of JavaScript and CSS resources, optimizing performance and reducing manual configuration.

Types of Frontend Client Extensions

• JavaScript: Include custom JavaScript code for specific functionalities.
• CSS: Add custom CSS styles to specific pages or the entire platform.
• Theme CSS: Modify the existing Liferay theme by adding custom CSS styles.
• Theme Favicon: Change the favicon displayed in the browser tab.
• Custom Element: Register and integrate external applications as widgets within Liferay.
• IFrame: Embed external content within a dedicated frame on a Liferay page.

Steps to implement a front-end client extension in Liferay 7.4:

1. Create a Workspace Project:

• Open Liferay Developer Studio and start the server.
• Navigate to File → New → Liferay Workspace Project
• Provide a project name (e.g., global-workspace) and click Finish.

2. Install Node.js:

• Ensure Node.js is installed on your system.
• You can download it from nodejs.org.

3. Create a Client Extension Folder:

• Inside the workspace, create a new folder named client-extension.

4. Create a React App in the Client Extension Folder:

• Open your terminal and navigate to the client-extension folder.
• Run the following command to create a new React app inside this folder: Command: npx create-react-app my-react-app.

5. Update index.js:

• The WebComponent class extends the HTMLElement class to manage the lifecycle of the custom React element, ensuring correct mounting and unmounting for improved performance.

6. Update index.html:

• Modify index.html to register the React custom element. This ensures that when the browser encounters <employee-management-react-custom-element>, it renders the React application.

7. Create the client-extension.yaml File:

• At the root of your React app, create client-extension.yaml. This file configures how Liferay loads the custom element:
  
  

a. Assemble Section
This section defines how static assets (like CSS, JS, and images) are packaged for deployment. 

• from: build/static
  Specifies the source directory where static files are generated, typically from a React build (npm run build). 

• into: static
  Indicates the destination directory where these files will be placed in the final build output.

b. Custom Element Configuration (my-react-custom-element1)

• cssURLs: 
  css/main.*.css: Points to the main CSS file generated during the React build. The asterisk (*) is a wildcard matching hashed filenames like main.a1b2c3.css for cache busting. 

• friendlyURLMapping: my-react-custom-element1
  Defines a user-friendly URL slug for accessing the custom element, useful in platforms like Liferay for direct navigation. 

• htmlElementName: my-react-custom-element1
  Specifies the name of the custom HTML tag used to embed this component in your HTML. 

• instanceable: false
  Indicates that the custom element cannot be added multiple times on the same page. Setting it to true would allow multiple instances. 

• name: My React Custom Element1
  The display name of the custom element in the admin interface (e.g., Liferay Control Panel). 

• portletCategoryName: category.client-extensions 
  Specifies the category under which this custom element will be listed in the admin panel. Here, it's under Client Extensions. 

• type: customElement
  Indicates that this extension is a Custom Element (Web Component). 

• urls:
  js/main.*.js: Points to the main JavaScript bundle generated by the React build. The wildcard (*) handles hashed file names for cache management. 

• useESM: true
  Instructs the system to use ES Modules (ESM), a modern JavaScript module format that enhances performance and compatibility with modern browsers. 

 8. Test Headless API:

• Open a browser and navigate to: http://localhost:8080/o/api/ 
• Click on the REST APPLICATION tab. 
• Click on employee-rest/v1.0 to view and test the API. 
• You can follow our blog for a detailed guide on creating headless APIs. Read more here.

9. Create a Test.js file: 

• Navigate to the src folder inside your React app: 
• Create a new folder named utils inside src. 
• Inside the utils folder, create a new file named test.js. 

10. Create API Functions in test.js:
Inside src/utils/test.js, create API functions:

a.  addObject(object): Adds a new employee via POST.

b. getEmployees(): Fetch All Employees

c. deleteEmployee(employeeId): Deletes an employee via DELETE.

d. updateEmployee(employeeData): Updates an employee via PUT.

11. Create Individual CRUD Components

• AddStudent.js: Create the AddEmployee.js component to handle adding new employees.
  
  
  
  
  
  
   
• EmployeeList.js: This component displays the employee list and includes the logic to delete employees from the list.
  
  
  
  
  
  
   
• UpdateEmployee.js: Create the UpdateEmployee.js component to update existing employee records.
  
  
  
  
  
  
  
  

12. Build the Client Extension 

• Delete the node_modules folder from the React app. 
• Open Gradle Task Executor in Liferay Developer Studio. 
• Navigate to Client-Extension -> employee-management-app. 
• Under the Build section, click on Build to execute the build task. 
• After a successful build, a zip file employee-management-app.zip i will be generated in the dist directory.
  
  

13. Deploy the Client Extension 

• Open Gradle Task Executor in Liferay Developer Studio. 
• Navigate to Client-Extension -> employee-management-app. 
• Under the Build section, click on Deploy to execute the deployment task. 
• After deployment, the client extension will be available on the Liferay server. You can confirm that it has been properly configured from the workspace.