UI Builder - Client state parameters, Client Scripts, and Events

#UI Builder , #Quebec Release , #Now Experience , #UI Builder Bytes

Brad Tilton

5 minute read

So far in our Now Experience UI Builder series we’ve looked at creating pages, adding components to pages, using data sources to return data from the platform, and then binding that data to our components. As we continue this week we’re going to take a look at client state parameters, client scripts, and events. These are the tools that are going to allow the components on our UI Builder pages to communicate and share data with each other and ultimately make these pages more powerful.

Client State Parameters

Client state parameters let you define a client state or piece of data, then bind that data to a component property. If you think of a UI Builder page as just a large web component, client state parameters let you manage the state of your page. If you’re not as familiar with web components you can think of client state parameters as page variables. You define them and then you can set their value from one place and use that value in another place on your page. In the demo video below I’ll use a client state parameter called todo_filter to store an encoded query that I use as the query for my simple list component when displaying open or completed todos.

Client Scripts

Client scripts in UI Builder allow you to run some client-side javascript based on an event. You can use scripts to do the following:

  • Get available data, manipulate the data, and store it in the client state.
  • Access data resource results.
  • Execute data resource operations.
  • Dispatch events.

From a client script, you have access to the page properties, client state parameters, data resources, and the payload and name of the event handled by the client script. One of the cool things about client scripts in UI Builder is that you can bind a client script to any event fired on your page through an event handler.

Client scripts use the new Now Code Editor which will show suggestions at the insertion point for class names, function names, object names, and variable names. This is really helpful as you’re exploring client scripting in UI Builder. One other thing that has been helpful to me has been logging some of the input params to the console, especially the event, so that I know the contents of the payload.

    console.log(JSON.stringify(event,null,4));

In the demo video below we’ll use the following piece of code to grab the state property from the payload of the event and use that to set a new encoded query value on our todo_filter client state parameter.

    function handler({api, event, helpers, imports}) {
        const filterState = event.payload.state;
        api.setState('todo_filter', 'userDYNAMIC90d1921e5f510100a9ad2572f2b477fe^state=' + filterState);
    }

Events and Handlers

Events are a pretty big topic, and the docs page explores them in-depth, so I won’t duplicate too much here. Basically, events allow you to add actions to your page, and there are three basic types of events:

  • Component events - most components have a set of events they will fire based on some sort of interaction with the component. An example could be a list loading or button clicked. Events and payloads are the way that components can interact with other components on your page.
  • Data resources - data resources generally have events that notify you about the progress of the data fetch, like when the data is returned to the page.
  • Page events - Pages have default events like when the page is loaded, and you can also create handled events on the page that can be called from other places.

Event handlers are how you map an event to some sort of action. You can add one or more event handlers to an event so that when the event is fired you can run a client script, set a client state parameter, navigate somewhere, open a modal, and more.

We’ve worked with events a bit already in this series, but in the following video, we’ll do even more.

Putting it all together

In this video, the goal is to add a Show completed todos and Show open todos that will change the filter on the simple list to show todos based on their state. A lot happens in the video so I’ve added the steps I took and a flow that shows how everything ties together.

Steps:

  1. Create the client state parameter.
  2. Bind the value of the client state parameter to the filter property on the todos list.
  3. Create a page event called Filter Todo.
  4. Create a client script that grabs the payload of the Filter Todo event and sets a new value to the client state parameter.
  5. Link the page event to the client script with an event handler.
  6. Create a button for Show completed todos and link it to the handled page event with an event handler.
  7. Create a button for Show open todos and link it to the handled page event with an event handler.
  8. Test

Here is an extremely professional diagram of how this all links together.

demo flow diagram

More Resources

Make sure to check out the previous posts in this UI Builder series, and stay tuned for more posts every Wednesday through mid-March.

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

Comments