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 your data set to enhance the user experience by providing tailored filtering capabilities.

Prerequisites

1. Install a supported version of Java.

   Note

   Check the compatibility matrix for supported JDKs, databases, and environments. See JVM Configuration for recommended JVM settings.

2. 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.120-ga120

Sign in to Liferay at http://localhost:8080. Use the email address [e-mail] 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.

Note

To deploy your client extension to Liferay SaaS, use the Liferay Cloud Command-Line Tool to run lcp deploy.

Tip

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

Beta Feature

Important

Currently, this feature is behind a beta feature flag (LPS-164563).

Start by setting up the environment:

1. Enable the LPS-164563 beta feature flag.

2. Create a site using the Minium template.

   This populates the database with products to be displayed in the data set.

   

3. 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

   

4. Click on the Products data set to start editing it.

   Alternatively, click Actions () next to the data set and select Edit ().

5. Select the Visualization Modes tab.

6. Click Add () and select the catalogId, id, and name fields.

   This adds the three fields to the table visualization mode displayed in the data set.

   

7. Select the Filters tab.

8. 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

   

   Tip

   To 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 to a content page:

1. Create a new page or Start editing one.

2. In the Fragments and Widgets menu on the left, search for Data Set under fragments. Drag and drop the fragment in your editing area.

3. Click on your fragment. In the General tab on your right, there is a field where you can select a Data Set. Click Add () and select the Products data set.

   

4. Publish the page.

Navigate to the page to test the filter:

1. Next to the page’s name, click Actions () and select View ().

2. Click Filter and select the Filter by Name option under the search bar.

3. 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 actions and customize your data set even further.

Related Topics

• Integrating External Applications
• Client Extensions UI Reference
• Managing Data Sets
• Data Set Filters