Using a Frontend Data Set Cell Renderer Client Extension

Liferay 7.4+

You can use Frontend Data Set (FDS) cell renderer client extensions to customize the display for your data set. Use this type to process information in your data sets with a separately deployed function for the display. Start with a client extension from the sample workspace.

Prerequisites

Install a supported version of Java.

Note

Check 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 Frontend Data Set cell renderer client extension.

Examine and Modify the Client Extension

The FDS cell renderer client extension is in the sample workspace’s client-extensions/liferay-sample-fds-cell-renderer/ folder. It’s defined in the client-extension.yaml file:

liferay-sample-fds-cell-renderer:
    name: Liferay Sample Frontend Data Set Cell Renderer
    type: fdsCellRenderer
    url: index.*.js

The client extension has the ID liferay-sample-fds-cell-renderer and contains the key configurations for a Frontend Data Set cell renderer client extension, including the type and a URL where the exported renderer is located on deployment. See the YAML configuration reference for more information on the available properties.

It also contains the assemble block:

assemble:
    - from: build/static
      into: static

This specifies that every file created in the build/static/ folder should be included as a static resource in the built client extension .zip file. The included tsconfig.json and webpack.config.js files include boilerplate configurations to build JavaScript from the entry point src/index.ts into the build/static/ folder for the client extension.

The index.ts file contains this JavaScript code:

const fdsCellRenderer: FDSTableCellHTMLElementBuilder = ({value}) => {
    const element = document.createElement('div');

    element.innerHTML = value === 'Green' ? '🍏' : value.toString();

    return element;
};

export default fdsCellRenderer;

This defines a function fdsCellRenderer that retrieves the data set cell’s data (value) and sets its innerHTML property depending on the value: either the existing value used as a string, or a green apple icon (🍏) if the value is Green. Then it exports the function for use as a client extension.

On the line before the innerHTML property is set, add this code to shorten any value with Joseph to the nickname Joe:

if (value === 'Joseph')
{
    value = 'Joe';
}

Now deploy the client extension.

Deploy the Data Set Cell Renderer

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

The command used to deploy your client extension changes if you use a self-hosted instance outside of Docker, Liferay PaaS, or Liferay SaaS. See Deploying to Your Liferay Instance for more information.

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 liferaysamplefdscellrenderer_7.4.13 [1459]

Now that your custom data set cell renderer is deployed, create and populate a data set to use it.

Create a Data Set of Users

Note

Currently, the Frontend Data Set cell renderer client extension is behind a beta feature flag. You must enable the feature flag before you can use it.

Create a data set that uses your client extension to render cells.

In your running Liferay instance, navigate to the Applications Menu () → Control Panel → Data Sets.
Click Add () to add a new data set.
Fill in the New Data Set form with these values:
- Name: User Data Set
- REST Application: /headless-admin-user/v1.0
- REST Schema: UserAccount
- REST Endpoint: /v1.0/user-accounts
Click Save.
Click the User Data Set to start editing it.

Alternatively, click Actions () next to the data set entry and select Edit.
Click the Visualization Modes tab.
With the Table view selected, click Add ().
Select the emailAddress, familyName, and givenName fields and click Save.

The givenName and familyName fields represent the user’s first and last name, respectively.
On the familyName row, click Actions () → Edit.
From the Renderer drop-down menu, select Liferay Sample Frontend Data Set Cell Renderer.
Click Save.
On the givenName row, click Actions () → Edit.
From the Renderer drop-down menu, select Liferay Sample Frontend Data Set Cell Renderer.
Click Save.
Click the Details tab and click Save to confirm the changes.

Now your data set uses your new client extension to render users’ first and last names.

Display the Data Set on a Page

Next, add a user for the data set to display.

Navigate to the Applications Menu () → Control Panel → Users and Organizations.
Click Add ().
Fill in the user form’s required fields with these values:
- Screen Name: josephgreen
- Email Address: josephgreen@liferay.com
- First Name: Joseph
- Last Name: Green
Click Save.
Navigate to a blank page on any site.
Click Edit () at the top of the page.
From the Fragments and Widgets menu on the left, scroll down to the Content Display section and drag a Data Set fragment onto the page.
Click on the Data Set fragment.
Click Add () beside the Data Set field in the configuration menu on the right.
Select User Data Set as the data set.
Click Save.

The data set fragment updates to display your data set of users. The first and last name for the new user, Joseph Green, display using values altered by your data set cell renderer code (the nickname “Joe” and the green apple icon, 🍏).

Joseph Green's first and last names display differently because of your JavaScript processing the data.

Next Steps

You have successfully used a Frontend Data Set cell renderer client extension in Liferay. Next, learn about other types of frontend client extensions.