Brad Tilton

4 minute read

In this week’s UI Builder Bytes, we’re going to take a closer look at the list components: List and List - Simple. These list components are among the more popular components in UI Builder, and I’ve seen similar questions a few times on the Now Experience community and in the sndevs slack around them. They’re questions that I also had when I first started working with UI Builder and the list components.

Right now, the two main questions I’m seeing around lists are how to do dynamic list filtering and how to refresh a list automatically from a script.

List Components

In the Quebec release, there are two different list components.

  1. The List component gives you a full-featured Now Experience styled list that you may be familiar with from agent workspace. This list has all the things you’d expect from a fully-featured list like filtering, exporting, pagination, show matching, etc., and has a TON of properties that control which of those things you want to show. The list component is something you would definitely use in a workspace with fulfillers.

    screenshot of list

  2. The List - Simple is more of a barebones version of the list component that is basically just showing a list of data that you can click into without filters, pagination, etc. I think this type of component is more suited to a portal where someone is consuming information and may just need to click into a list item for more details.

    screenshot of list - simple

List Filtering

The filter in the list components works as you would expect from any filter in ServiceNow. You click Edit filter in the list component properties and get a modal with a filter against whatever table you’ve configured in the table property on the component.

screenshot of list filter

The issue that I’ve run into is: what if you want something more dynamic like Active is true AND Parent is equal to a page parameter or client state parameter? The first time I saw this, I expected it to work like flow designer where I could use some data pills inside the filter. It’s still possible to make it dynamic, but instead, you need to provide that component’s filter property with an encoded query. You can do that either by binding a client state parameter or something else representing an encoded query to the filter property, or by using a script in the filter property to produce an encoded query. In the video below, I’ll show the second approach.

The script we used in this video was:

function evaluateProperty({api}) {
  return 'active=true^category=' + api.state.category;

List Refreshing

The other thing that I’ve run into is refreshing a list component programmatically instead of having to click the refresh button on the list component itself. The main use case I’ve seen for this is when you’ve created a record that goes in this list somewhere else on the page and you want to automatically refresh the list so it shows up. Basically, what you need to do is bind a client state parameter to the refresh property on the list component, and then set that parameter from a client script.

I’ll show that method in the video below:

The important line of code from this video is: api.setState('listRefreshed', {timestamp:})

More Resources

Make sure to check out the previous posts in this UI Builder series, and stay tuned for more posts.

Have a UI Builder topic you’d like me to hit in a future post? Let me know on Twitter, LinkedIn, or slack (@btilton).