Using a Frontend Data Set Filter Client Extension
Liferay DXP 2024.Q2+/Portal 7.4 GA120+
Frontend data set filter client extensions define JavaScript functions for creating customizable filter interfaces. Add these extensions to data set views to enhance the user experience by providing tailored filtering capabilities.
Prerequisites
-
Install Java (JDK 8 or JDK 11).
NoteCheck the compatibility matrix for supported JDKs, databases, and environments. See JVM Configuration for recommended JVM settings.
-
Download and unzip the sample workspace:
curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip
unzip com.liferay.sample.workspace-latest.zip
Now you have the tools to deploy your first custom filter via a client extension.
Examine and Modify the Custom Filter
The frontend data set filter client extension is in the sample workspace’s client-extensions/liferay-sample-fds-filter/
folder. It’s defined in the client-extension.yaml
file:
liferay-sample-fds-filter:
name: Liferay Sample FDS Filter
type: fdsFilter
url: index.*.js
The client extension has the ID liferay-sample-fds-filter
and contains the key configurations for a Custom Element client extension, including the type
and the url
properties that define the JavaScript resource file’s location.
It also contains the assemble
block:
assemble:
- from: build/static
into: static
This specifies that everything in the build/static
folder should be included as a static resource in the built client extension .zip
file. The JavaScript files in a client extension are used as static resources in Liferay.
Understand the Code
The src/index.ts
file defines three main JavaScript functions that provide a customizable filter interface: descriptionBuilder
, htmlElementBuilder
, and oDataQueryBuilder
, which are responsible for describing the filter’s state, rendering the filter’s UI, and building the OData query respectively.
The descriptionBuilder()
function takes the filter’s internal state (selectedData
) and returns it as a human-readable string. Here, it returns the OData query string entered by the user.
function descriptionBuilder(selectedData: FilterData): string {
return selectedData;
}
The htmlElementBuilder()
function renders the UI shown to the user when configuring the filter. It creates an input field for the OData query string, a submit button, and attaches an event handler to the button to update the filter’s state using the setFilter
callback.
It creates a div
element, assigns it the class name dropdown-item
, appends the input field and button to this div, and then returns the div.
const div = document.createElement('div');
div.className = 'dropdown-item';
div.appendChild(input);
div.appendChild(button);
return div;
The oDataQueryBuilder()
function takes the filter’s internal state (selectedData
) and returns it as the OData query string for filtering the data set.
function oDataQueryBuilder(selectedData: FilterData): string {
return selectedData;
}
Then, an object fdsFilter
is created that implements the FDSFilter
interface, incorporating the three main functions defined above. And this object is exported as the default export of the module.
const fdsFilter: FDSFilter<FilterData> = {
descriptionBuilder,
htmlElementBuilder,
oDataQueryBuilder,
};
export default fdsFilter;
Now, deploy the client extension.
Deploy the Custom Element Client Extension to Liferay
Start a new Liferay instance by running
docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.112-ga112
Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.
Once Liferay starts, run this command from the client extension’s folder in the sample workspace:
../../gradlew clean deploy -Ddeploy.docker.container.id=$(docker ps -lq)
This builds your client extension and deploys the zip to Liferay’s deploy/
folder.
To deploy your client extension to Liferay SaaS, use the Liferay Cloud Command-Line Tool to run lcp deploy
.
To deploy all client extensions in the workspace simultaneously, run the command from the client-extensions/
folder.
Confirm the deployment in your Liferay instance’s console:
STARTED liferaysamplecustomelement1_7.4.13
Now that your client extension is deployed, check if the filter is working properly.
Add the Custom Filter to a Data Set View
Currently, this feature is behind a beta feature flag (LPS-164563).
Start by setting up the environment:
-
Enable the
LPS-164563
beta feature flag. -
Create a site using the
Minium
template.This populates the database with products to be displayed in the data set view.
Create the data set and the data set view:
-
Create a Data Set using these settings:
Field Content Name Products
REST Application /headless-commerce-admin-catalog/v1.0
REST Schema Product
REST Endpoint /v1.0/products
-
Create a Data Set View, name it
Products Data Set View
, and click Save. -
Click on the Products Data Set View to start editing it.
Alternatively, click Actions (
) next to the view and select Edit (
).
-
Select the Visualization Modes tab.
-
Click Add (
) and select the
catalogId
,id
, andname
fields.This adds the three fields to the table visualization mode displayed in the data set view.
-
Select the Filters tab.
-
Click Add (
) and select Client Extension. Fill in the information using these settings:
Field Content Name Filter by Name
Filter By name
Client Extension Liferay Sample FDS Filter
TipTo ensure the filter works across different “Filter By” fields, the frontend data set filter client extension should be coded to handle various field names dynamically. Since the selected field in “Filter By” is accessible from the code, the filter can be applied generically, eliminating the need to create separate client extensions for each field.
Add the data set view to a content page:
-
Create a new page or Start editing one.
-
In the Fragments and Widgets menu on the left, search for Data Set under fragments. Drag and drop the fragment in your editing area.
-
Click on your fragment. In the General tab on your right, there is a field where you can select a Data Set View. Click Add (
) and select the Products Data Set View.
-
Publish the page.
Navigate to the page to test the filter:
-
Next to the page’s name, click Actions (
) and select View (
).
-
Click Filter and select the Filter by Name option under the search bar.
-
Select the search field, type in
name eq 'Piston'
, and click Submit.The table displays only the products named Piston.
You have successfully deployed and used a frontend data set filter client extension in Liferay. Next, try using data set view actions and customize your data set even further.