Events, Client State Parameters, and Client Scripts in UI Builder
Events, client state parameters, and client scripts play essential roles in UI Builder, facilitating communication and data sharing among components within a page. Let's explore how these elements work together:
Events:
An event in UI Builder signifies a change in the state of an object, often triggered by user interactions. UI Builder assigns a default set of events to most components, pages, and data resources. These events serve as a basis for adding further actions to your page through the use of event handlers.
There are four types of events in UI Builder:
- Component Events
- Page Events
- Data Resource Events
- Event Handlers
Component Events:
Most components have a range of associated events. For example, the List – Simple component offers events like "Row Clicked" and "Scroll Updated," while the Button component has the "Button Clicked" event.
Page Events:
Pages have default events tied to actions for the entire page. These include "Page Ready" and "Page Property Changed." Variant events, like "Link to Destination Relay," are used to relay events dispatched from page components up to a user session event handler.
Data Resource Events:
Data resources have default events related to fetching data, such as "Data Fetch Initiated," "Data Fetch Succeeded," and "Data Fetch Failed."
Event Handlers:
An event handler is an action that you configure to run when an event is triggered on a component, page, or data resource. For instance, when a user clicks a Button component, the "Button Clicked" event is triggered, and you can configure an event handler to redirect the user to another page or perform a specific action.
There are different types of event handlers:
Inherited Event Handlers: Exposed from the page you are working on. Examples include "Link to Destination" and "Open and Close Modal Dialog."
Page-level Event Handlers: Common to all pages. Examples include "Add Alert Notification" and "Update Client State Parameter."
Data Resource Event Handlers: Triggered during data fetching or updating.
Client Scripts: Client scripts in UI Builder are used to define and execute scripts when a component event is triggered. You can bind client scripts to a component using an event handler. Client scripts can:
Retrieve data and store it in a client state parameter.
Access data resource results.
Execute data resource operations.
Dispatch events.
These scripts can be created and edited using the Now Code Editor, which is integrated into UI Builder. It supports rich editing of JSON, CSS, and Client Scripting, including features like Intellisense, auto-complete, code formatting, error handling, find and replace, and syntax highlighting.
Event Mapping in UI Builder:
Event mapping is a fundamental concept in UI Builder, and it's the process of associating an event with an event handler to trigger specific actions.
Here's how you can add event handlers to different types of events in UI Builder:
- Add an event handler to a component event
- Add an event handler to a page event
- Add an event handler to a data resource event
1. Add an event handler to a component event:
- Within UI Builder, select the desired component in the Content tree.
- In the Configuration Panel, click on the Events tab.
- Select "+ Add event mapping" and choose the event that should trigger the event handler.
- In the Event window, choose the event handler you want to add from the list in the left panel.
- Configure the event handler settings within the right panel. Each event handler may have different configuration options.
- Finally, select "Add."
2. Add an event handler to a page event:
- Within UI Builder, select "Body" within the Content tree.
- In the Configuration Panel, go to the Events tab.
- Select "+ Add event mapping" and choose the event that should trigger the event handler.
- In the Event window, choose the event handler you want to add from the list in the left panel.
- Configure the event handler settings within the right panel, keeping in mind that different event handlers may have varying configuration options.
- Finally, select "Add."
3. Add an event handler to a data resource event:
- In UI Builder, select the "Data resources" icon in the left vertical menu to open the Data resources panel.
- Choose the local data resource to which you want to add the event handler.
- Within the Configuration Panel, access the Events tab.
- Select "+ Add event mapping" and choose the event that should trigger the event handler.
- In the Event window, choose the event handler you want to add from the list in the left panel.
- Configure the event handler settings within the right panel, taking into account that each event handler may have different configuration options.
- Finally, select "Add."
These event mappings allow you to create interactivity and define how components, pages, and data resources respond to user interactions and other events in your UI Builder experience.
Client State Parameters:
Client state parameters act as page-specific variables used to store data relevant only to that particular page. They can handle various data types such as Strings, Numbers, Boolean, and JSON.
Once defined, you can update them using client scripts, and you can also bind the value of a client state parameter to a component property using the "@state" syntax.
Create client state parameter
To create a client state parameter:
1. Open the client state parameter panel:
Open an experience within UI Builder, select a page, and click on the "Client state parameters" icon in the left vertical menu to open the Client state parameters panel.
2. Add and define the client state parameter:
Select "+ Add" and specify a Name, Type, and Initial value. The Client state preview panel on the right displays the parameter names and their initial values.
3. Save your work:
Select the "Save" button in the upper right-hand corner of the page.
This process allows you to create and utilize client state parameters within your page, which can store data specific to that page.
Client Scripts:
Client scripts in UI Builder enable you to define scripts that are executed in response to triggered events.
You can bind client scripts to any component using an event handler. They can be used to access and manipulate data, store it in a client state parameter, access data resource results, execute data resource operations, and dispatch events.
Create a client script
To create a client script:
1. Open the Page scripts panel:
Open an experience within UI Builder, select a page, and click on the "Client scripts" icon in the left vertical menu to open the Page scripts panel.
2. Create the script:
Select "+ Add," specify a Script name, and optionally add Script includes to include with your script. These objects will appear in the imports parameter of your client script function. When you bind a script to a component using an event handler, the component will be listed under the "Triggered by" tab.
3. Write the client script:
Within the Now Code Editor, write your script.
4. Save your work:
Select the "Save" button in the upper right-hand corner of the page.
This process completes the creation of your client script, which can now be used within your page.
These elements, including event mapping, client state parameters, and client scripts, work in harmony to create dynamic and interactive user experiences in UI Builder.
Knowledge Test
Q1. What is an action that is configured to run when an event is triggered?
- a) Client state parameter
- b) Event
- c) Event handler
- d) Event mapping
Correct Answer: c) Event handler
An event handler is an action that is configured to run when an event is triggered.
Q2. What type of events can an event handler be added to?
- a) Component
- b) Page
- c) Data resource
- d) All of the above
Correct Answer: d) All of the above
An event handler can be added to all of the above events.
Q3. What are client state parameters used for?
- a) To store a piece of data specific to an experience.
- b) To execute a client script.
- c) To trigger an event.
- d) To store a piece of data specific to a page.
Correct Answer: d) To store a piece of data specific to a page.
Client state parameters are used to store a piece of data specific to a page.
Q4. Bind client scripts to any component using what?
- a) Data resource
- b) Client state parameter
- c) Page event
- d) Event handler
Correct Answer: d) Event handler
You can bind client scripts to any component using an event handler.
Next
Lesson 12 - Lab 4: Configure a Workspace Experience