Brad Tilton

4 minute read

This week in our UI Builder Bytes series we’re going to take a closer look at client scripting. We did touch on and do a quick demo around client scripting in the UI Builder - Client state parameters, Client Scripts, and Events post, but I wanted to look at it a little deeper and call out some of the more common methods and properties you might need to use.

How to trigger a client script

In order to trigger a client script you’ll need to add an event handler to an event in UI Builder that triggers your client script. That could be any number of things like a page ready event, button click event, list load event, and more. You’ll just need to find an event, click to add an event handler and find your client script in the list. This is one reason that your client script name should be informative and easily identifiable.

Client Script Includes

As a long-time ServiceNow developer when I hear the term script include I automatically think “server-side reusable script”, but in UI Builder only half of that is true. Client Script Includes [sys_ux_client_script_include] in UI Builder are reusable client-side scripts that can be called from any client script. As you scale your Now Experience UI Builder pages I think these client script includes will come in handy, and you should treat scripting in UI Builder like anywhere else on the platform where you make your scripts modular and reusable.

We’ll look at how you call these script includes in the next section.

Common Methods and Properties

Most of the client scripting methods and properties are documented in the developer site API documentation, but I want to call out some of the more common methods and properties that I’ve found helpful here, as there is a lot going on.

  • api.setState('<client_state_parameter_name>', Any value) - One of the most common things to do from a client script is to set a client state parameter value that you can then bind to a component or data resource property.
  • api.state.<client_state_parameter_name> - Access the value of a client state parameter.
  • api.context.props.<page_property_name> - Access the value of a required or optional page parameter.
  • api.context.session.<session_property_name> - Access available session properties like the logged in user’s sys_id, roles, timezone, etc.
  •<data_resource_id>.execute(<inputValuesObject>) - Triggers an execute operation on a data resource that mutates data, most commonly the create or update data resources. Each data resource expects the inputValuesObject to conform to the data resource’s input parameters.
  •<data_resource_id>.refresh() - Triggers a refresh operation for the specified non-mutating data resource instance. This method is asynchronous and emits an internal event to trigger the refresh of the specified data resource instance.
  • api.emit('<EVENT_NAME>', <payloadObject>) - Emits an event with the specified name and payload. Note that the event being emitted must be part of the associated page definition’s dispatched events list.
  • imports['<Client script include API Name>']() - Imports a client script include into your client script. Note that you also have to include it in the details page to the left of the script.

Example Demo

There’s nothing like seeing something in action, so here is a quick demo where I put a few of these common methods and properties into a client script and call it from an event.

Here is the script from the demo:

function handler({api, event, helpers, imports}) {
    const plantName = api.context.props.plantName;
    const userFirstName = api.context.session.user.firstName;
    const {getPlantName,isMyPlantHappy} = imports['x_85636_plant.Plants include']();
    const plantMsg = `Hello ${userFirstName}, ${isMyPlantHappy(plantName)}`;
    api.setState('plantStatusMsg', plantMsg);

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