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

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

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 View

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

    Create a site based on the Minium template.

Create the data set and the data set view:

  1. Create a Data Set using these settings:

    FieldContent
    NameProducts
    REST Application/headless-commerce-admin-catalog/v1.0
    REST SchemaProduct
    REST Endpoint/v1.0/products

    Create a data set to display products.

  2. Create a Data Set View, name it Products Data Set View, and click Save.

  3. Click on the Products Data Set View to start editing it.

    Alternatively, click Actions (Actions menu) next to the view and select Edit (Edit).

  4. Select the Visualization Modes tab.

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

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

    Add the catalogId, id, and name fields to the table visualization mode.

  6. Select the Filters tab.

  7. Click Add (Add icon) and select Client Extension. Fill in the information using these settings:

    FieldContent
    NameFilter by Name
    Filter Byname
    Client ExtensionLiferay Sample FDS Filter

    Add the Liferay Sample FDS Filter client extension to the data set view.

    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 view 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 View. Click Add (Add icon) and select the Products Data Set View.

    Select the Products Data Set View and display it using the Data Set fragment.

  4. Publish the page.

Navigate to the page to test the filter:

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

  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.

    Use OData queries to filter products by name.

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.

Capabilities

Product

Contact Us

Connect

Powered by Liferay
© 2024 Liferay Inc. All Rights Reserved • Privacy Policy