What is a client-side interaction

Users sometimes interact with pages in order to navigate to other pages. In other cases, users want to make updates to a page's content, appearance, or data. Rather than refreshing the entire page, client-side interactions update only the affected parts of a page.

For example, a user can sort a list by clicking a column header. Sorting redraws only the list and not the entire page.

What are client state parameters

Client state parameters are page variables. Define and configure a client state parameter and use the value to configure components. Client state parameters centralize management of configuration values for page components. UI Builder uses client state parameters to enhance user experience and provide personalized content and services.

Example of client state parameters

In the example, a page has a client state parameter called color. Two of the three components are configured to use the color client state parameter. If color is set to orange, the components are orange. If color is set to purple, the components are purple. If color is set to green, the components are green. The client state parameter is a single place to manage a common value for the page. Without the client state parameter, each component that uses a value would need to be updated individually if that value changed.

For example, a web experience stores the primary color used by components in the color client state parameter. When the components are configured to use the client state parameter, changing the value of the client state parameter updates the components to the new value.

Buttons can be added to the experience to allow users to select a color for the page components. With a single click, a user can simultaneously change the color of all components on a page. Store the user’s color choice in a client state parameter, then use the client state parameter to configure the page’s components. When a user interaction causes the client state parameter value to change, the page’s components are updated in real time.

The client state panel

The client state panel is collapsed by default. Click the client state icon in the left navigation bar to open the client state panel.

Creating client state parameters

To add a client state parameter to a page, click the + Add button in the client state parameters section.

Working with client state parameters

Once you have a client state parameter, what can you do with it? To work with client state parameters, first bind the value of the client state parameter to component configurations. When the client state parameter's value changes, the component updates to use the new value. One way to change a client state parameter's value is with event handlers.

In the creating client state parameters page example, two client state parameters were added to the special occasions application: occasionTypeQuery and occasionListTitle. The occasionTypeQuery parameter has no value by default and occasionListTitle has the default value All Special Occasions. These client state parameters will be applied to the Occasion List component to set the list's title and filter. A button will be used to update the values of these client state parameters to dynamically update the list.

Binding client state parameters

Client state parameter values can be bound to component configuration fields the same way page context, payload, and data resources are. When configuring components, hover over a field, then select the Dynamic data binding button () to bind a client state parameter to the field value. In the example, the Dynamic data binding button is highlighted for the Occasion List component's filter field.

The character @ indicates data binding and the state object contains the client state parameters. Select a client state parameter from the choice list. The example shows selecting the occasionTypeQuery client state parameter. The default value for the occasionTypeQuery client state parameter is empty, so no filter will be applied by default.

The Title for the component is set in a similar manner: select the Dynamic data binding button for the Title field or type @, then select the state.occasionListTitle client state parameter from the choice list. The default value for the occasionListTitle client state parameter is All Special Occansions. The example shows both Title and Filter configured to use client state parameters.

With both client state parameters applied, no filter is applied to the list and the title is All Special Occasions.

The occasionTypeQuery and occasionListTitle client state parameter values remain unchanged until a user interacts with a component that changes the value of the client state parameter.

Change client state parameter values

User the Update client state parameter event handler to change the value of a client state parameter in runtime. The Update client state parameter event handler has two properties: client state parameter to update and the new value to use for the client state parameter.

As an example, a Birthdays button is added above the Occasion List component in the Special Occasions application. The objective of this button is to change the Title of the list to All Birthdays and to adjust the filter of the list to only show birthdays. To achieve this objective, two event handlers are mapped to the Button clicked event for the button, one to change the occasionTypeQuery client state parameter and another to change the occasionListTitle client state parameter. The image shows the Update client state parameter event handler configured to set the occasionTypeQuery client state parameter to special_occasion=birthday, which will filter the list to only show birthdays.

When the Button clicked event is mapped to event handlers to update both the occasionTypeQuery and occasionListTitle client state parameters, clicking the button updates the client state parameters, which automatically updates the Occasion List component with the new values.