The Zurich release has arrived! Interested in new features and functionalities? Click here for more

UI Builder Essentials: Client Scripts in UI Builder

MGOPW
ServiceNow Employee
ServiceNow Employee
3 hours ago

Client Scripts in UI Builder

Articles Hub

Want to see all of our other articles and blogs related to UI Builder and Workspaces?

You can copy the link above and share it!

We Value Your Feedback!

Have any suggestions or topics you'd like to see in the future? Let us know!

 

Overview

In this article we will learn all about Client Scripts in UI Builder as well as their alternatives and what scenarios they best fit into. Afterwards, we will do two small step by step tutorials to understand the fundamentals of client scripts in UI Builder. 

Before we get started, at a minimum, make sure you can meet these environment requirements:
Family Release: Xanadu
UI Builder Release: 26.2.74
Roles Required: Admin
Prerequisites: Customer Service Workspace
📢

Prerequisites

Before starting this tutorial, ensure you've completed the necessary prerequisites to follow along smoothly. Here are some key articles you might need to reference:

📌

Troubleshooting

If at any point something isn't working, try clearing the UI Builder cache. 

Within your page variant editor in UI builder, click the hamburger menu icon at the top-left, go to Developer > Clear UI Builder Cache.  You can also try clearing your local browser cache.

What Are Client Scripts in UI Builder?


Client Scripts in UI Builder are bits of client-side JavaScript that run in response to user interface events. They enable dynamic behavior in Workspaces and Pages built with UI Builder. For example: A client script can respond to a button click or form field change, then update data or a parameter on the page. This is essential for making your UI interactive beyond static data binding.

Differences from Core UI Client Scripts: It’s important to note that UI Builder Client Scripts are not the same as legacy client scripts on forms in the traditional platform UI. In the classic UI (UI16/UI15), client scripts run on form load/change/submit for specific forms and fields. In UI Builder, client scripts are tied to the page and it's components and are triggered by events in that page (like a button click, list loading, etc.).
 
Core UI client scripts are limited to using g_form to interact with the form, whereas UI Builder client scripts have access to the page’s context, including client state parameters, page properties, and data resources on the page.

This means in UI Builder you can reuse scripts across components/events and even perform asynchronous operations, making your Workspace pages more dynamic than their Core UI counterparts. 

UI Builder client scripts let you extend your UI’s functionality without needing a full backend flow. They can manipulate data on the fly, trigger additional UI changes, or communicate between components. For instance, you might auto-fill form fields, show or hide components based on user input, validate data before submission, or fetch additional data – all in the user’s browser for a snappier experience.

In summary, client scripts are a key tool for making sure your applications are as interactive and dynamic as possible.
 
Now, let's use client scripts in UI Builder to solve a couple scenarios such as, using a button press to display alerts, and using a button press to toggle a lists records.
 

Scenario 1: Button Press Displays Alert


Let's say you are tasked with making internal documentation for UI Builders alert types for your organization's knowledge base. We will create a simple way to display all available Alert types, so you can take a screenshot, to add to your organization's documentation.

Step 1. Open UI Builder


  1. In your ServiceNow instance, use the Application Navigator to go to Now Experience Framework > UI Builder.
  2. When UI Builder opens, you should see the UI Builder Home screen.
  3. Select Experiences Tab at the top of the screen.
MichaelB6948013_12-1746490426013.png
 
4. Open the Customer Support Workspace.

Step 2: Create a Page


  1. In the Experience Editor, find Pages and variants.
  2. Click the + icon next to it.

 

MichaelB6948013_13-1746490426014.png

 

 3. Select Create a new page.

MichaelB6948013_14-1746490426014.png

 

4. Select Create from scratch instead.

 

MichaelB6948013_15-1746490426014.png

5. Set the fields as follows:
Name: Alert Types
URL path: alert-types
MichaelB6948013_16-1746490426015.png
 
6. Then select Continue in the bottom right-hand corner.
7. Next, select Looks Good. When the 'Tell us about your variant' page appears, leave the name as Default, then select Continue in the bottom right-hand corner.
8. The option to make your application responsive will appear. Select Build responsive then Create.
 
MichaelB6948013_17-1746490426015.png

Step 3: Add Button Component


  1. Under the content tree, select '+ Add content'.
  2. Then search for Button in the component search pop up.
  3. Select the Button component.

 

MichaelB6948013_18-1746490426015.png

4. Rename the button by hovering over the 'Button 1' component underneath the Body section of the content tree.
 
MichaelB6948013_19-1746490426016.png
 
5. Then select Rename
 
MichaelB6948013_20-1746490426016.png
 
The "Renaming" pop up will now appear on the configuration panel.
6. Rename as follows:
     Component label: Showcase Alerts
     Component ID: showcase_alerts
 
MichaelB6948013_21-1746490426016.png

7. Select Apply.

Step 4: Create a Client Script

 

1. Select + to the right of Client scripts, underneath the Data and scripts section, on the bottom left side of page.

MichaelB6948013_0-1746638551542.png

 

2. After the "Edit client script" pop up opens, update as such:
      Script Name: Alerts
      Script: Delete all default information 
 
3. Copy and paste the following script into the client script pop up windows script:
/**
* @param {params} params
* @param {api} params.api
* @param {any} params.event
* @param {any} params.imports
* @param {ApiHelpers} params.helpers
*/
function handler({
    api,
    event,
    helpers,
    imports
}) {
    api.emit("NOW_UXF_PAGE#ADD_NOTIFICATIONS", {
        items: [
            {
                id: "alert1",
                status: "critical",
                icon: "circle-exclamation-fill",
                content: {
                    type: "string",
                    value: "Critical: System failure detected!"
                },
                action: { type: "dismiss" }
            },
            {
                id: "alert2",
                status: "high",
                icon: "circle-exclamation-outline",
                content: {
                    type: "string",
                    value: "High: CPU usage exceeded 90%"
                },
                action: { type: "dismiss" }
            },
            {
                id: "alert3",
                status: "moderate",
                icon: "circle-pause-outline",
                content: {
                    type: "string",
                    value: "Moderate: Disk space is below 20%"
                },
                action: { type: "dismiss" }
            },
            {
                id: "alert4",
                status: "warning",
                icon: "triangle-exclamation-outline",
                content: {
                    type: "string",
                    value: "Warning: Unusual login activity detected"
                },
                action: { type: "dismiss" }
            },
            {
                id: "alert5",
                status: "info",
                icon: "circle-question-fill",
                content: {
                    type: "string",
                    value: "Info: A new software update is available"
                },
                action: { type: "dismiss" }
            },
            {
                id: "alert6",
                status: "positive",
                icon: "check-circle-outline",
                content: {
                    type: "string",
                    value: "Positive: Backup completed successfully"
                },
                action: { type: "dismiss" }
            },
            {
                id: "alert7",
                status: "low",
                icon: "bell-fill",
                content: {
                    type: "string",
                    value: "Low: Minor update recommended"
                },
                action: { type: "dismiss" }
            }
        ]
    });
}
This script will add a flurry of alerts to the page, but don't worry! UI Builder has a way of handling large groups of alerts.
 
5. Then select the Format code button (multiple lines button) at the top of the window - next to the Toggle check Syntax icon. (scroll with check icon button)

 
MichaelB6948013_23-1746490448583.png
 
6. Select Apply.

Step 5: Connect Functionality


MichaelB6948013_24-1746490448583.png
 
  1. Underneath the content tree, Select the button we created: Showcase Alerts.
  2. In the configuration panel, Select the Events tab.
  3. Select Add handler underneath the Button clicked event.
  4. Search for alerts.
  5. In the Scripts section you will see the Alerts script we created, Select it.
  6. Select Continue.
  7. For When to trigger select Always.

MichaelB6948013_25-1746490448587.png
8. Click Add.


Save and Test


  1. In the upper right corner of the page, select Save.
  2. Select Preview (to the left of Save).
    The preview pane will now display.
 
    3. Click your button to display the alerts.

Because there are so many alerts showing at once, the page may automatically stack the alerts, to show all alerts, select 'Show alerts' in the middle of the stack.

MichaelB6948013_26-1746490448587.png

Scenario 2: Button Press Toggles List


Imagine your organization needs help streamlining an audit process. To save time for the audit agent, as well as minimize page flipping and screen real estate, the organization would like a single list that can display Incident records and can 'switch' to view Change records.

Step 1. Open UI Builder


  1. In your ServiceNow instance, use the Application Navigator to go to Now Experience Framework > UI Builder.
  2. When UI Builder opens, you should see the UI Builder Home screen.
  3. Select Experiences Tab at the top of the screen.

 

MichaelB6948013_27-1746490448588.png

 

  4. Open the Customer Support Workspace.

 
 

Step 2: Create a Page


  1. In the Experience Editor, find Pages and variants.
  2. Click the + icon next to it.

 

MichaelB6948013_28-1746490448588.png

 

   3. Select Create a new page.

 

MichaelB6948013_29-1746490448589.png

 

   4. Select Create from scratch instead.

 

MichaelB6948013_30-1746490448589.png

5. Next, update the form as such:
     Name: Audit Streamline POC
     URL path: audit-streamline-poc
 
MichaelB6948013_31-1746490448589.png
6. Then select Continue in the bottom right-hand corner.
7. Next, select Looks Good, then the 'Tell us about your variant' page appears, leave the name as Default, then select Continue in the bottom right-hand corner.
8. The option to make your application responsive will appear. Select Build responsive then Create.
 
MichaelB6948013_32-1746490448589.png

Step 3: Add Button Component


  1. Under the content tree, select '+ Add content'.
  2. Then search for Button in the component search pop up.
  3. Select the Button component.

 

MichaelB6948013_33-1746490475756.png

4. Rename the button by hovering over the 'Button 1' component underneath the Body section of the content tree.

MichaelB6948013_34-1746490475757.png
 
5. Then select Rename
 
MichaelB6948013_35-1746490475757.png
The renaming pop up will now appear on the configuration panel.
6. Rename as follows:
     Component label: Table Toggle
     Component ID: table_toggle
 
MichaelB6948013_36-1746490475757.png

7. Select Apply.
8. Afterwards, on the configuration panel, underneath the Configure tab, change the Label to Table Toggle.

MichaelB6948013_37-1746490475757.png


Step 4: Add a List Component


MichaelB6948013_38-1746490475758.png
  1. In the Content Tree, Select the +Add Content button.
  2. Search for List, in the component search.
  3. Select the List component.
  4. In the content tree, select the menu dots to right of 'List 1' (they display after hovering over the List 1 text).
  5. Select Rename

 

MichaelB6948013_39-1746490475758.png
 
6. Change the following:
      Component label: Table
      Component ID: table
 
MichaelB6948013_40-1746490475759.png
 
7. Select Apply

Step 5: Create Client State Parameter


  1. On the bottom left of the page, underneath Data and scripts, select Client state parameters.

 

MichaelB6948013_41-1746490475759.png

2. In the Edit client state parameters pop up, add the parameter:
Name: 'myTable'
Type: String
Initial value: change_request
MichaelB6948013_42-1746490475759.png
3. Select the X to close the pop-up window.

 


Step 6: Bind Parameter


MichaelB6948013_43-1746490515757.png
 
1. In the Content tree, select the component named Table.

2. In the Configuration panel, Select the Configure tab > Data > Table.

3. Hover over the Table field until you see the Data Bind icon (stacked circles) > Select the Data Bind icon.


The Bind data to Table pop up will appear

4. Underneath Data types tab > select Client states > select myTable data pill.
5. A small arrow to the right side of the pill will appear, select the arrow.
 
MichaelB6948013_44-1746490515758.png
 
6. Select Apply.


Step 7: Create a Client Script


  1. In the bottom left corner of the page, select Data and scripts, then select Client scripts.
  2. Change the name of the script to Toggle Logic.
  3. Delete the prepopulated client script that appears.
  4. Copy then paste the script below, in its place.
/**
 * @param {params} params
 * @param {api} params.api
 * @param {any} params.event
 * @param {any} params.imports
 * @param {ApiHelpers} params.helpers
 */
function handler({
    api,
    event,
    helpers,
    imports
}) {

    // if client state parameter is incident 
    if (api.state.myTable == 'incident') {

        // set client state parameter to 'change_request'
        api.setState('myTable', 'change_request');

    } else {

        // else set client state parameter to 'incident'
        api.setState('myTable', 'incident');

    }

}
This script will check the value of our client state parameter then re assign a new value accordingly, creating a 'toggle' effect. Pretty cool right! 
 
5. Select Apply.


Step 8: Connect Functionality


MichaelB6948013_45-1746490515758.png
 
1. In the content tree, select the Table Toggle button we created earlier.
2. Select Events tab on the configuration panel
3. Below Button clicked, Select Add Handler
4. Search for Toggle Logic (the name of the client script we created earlier)
5. In the Scripts section, select the script named Toggle Logic
6. Select Continue
7. Below When to trigger > Select Always
MichaelB6948013_46-1746490515759.png
 
8. Then Select Add

Save and Test


1. In the upper right corner of the page, select Save.

2. Select Preview (to the left of Save).


    The preview pane will now display.

3. Repeatedly click your Table Toggle button to change the table contents from Change to Incident and vice versa.
Your end result should display the records from the, change_request table, then after selecting the Table Toggle button, display records from the incident table, as below:
 
MichaelB6948013_47-1746490515760.png
 
 
MichaelB6948013_48-1746490515760.png
 

Conclusion

Congratulations! 🎉 With the fundamentals covered, you can continue to experiment in UI Builder. Try combining multiple events and scripts to create richer interactions. And be sure to consult the official docs and developer community for deeper dives into UI Builder Client Scripts!

 

If you found this guide helpful, consider sharing it with peers or teams looking to elevate their UI Builder skills. If you like this type of content, please mark the article "Helpful" leave us your topic ideas in the comments, and fill in the survey at the top!

 

Keep an eye out for future tutorials where we’ll dive deeper into crafting immersive, data-driven experiences. Until then—happy designing, and stay curious!

Check out the Next Experience Center of Excellence for more resources

0 Helpfuls
  • 79 Views
Popular Blog Posts