Overview
There are very few applications that you will build with UI Builder where every component will be statically configured. Dynamism is the core of every application and UI Builder gives you powerful tools to tap into the power of dynamic properties. Today we will take a look at these tools and talk about the best practices when configuring components, data resources, event mappings, and more.
Family Release: Xanadu
UI Builder Release: 26.2.59
Roles Required: admin
What are dynamic property values?
Probably the easiest way to understand dynamic property values is to contrast them with "static" property values. These are the types of property values that are set when you check (or uncheck) a checkbox, enter text into an input, or choose a record from a reference picker. These values will always be the value used for this property when the component is shown.
This "Label" property will always be "Record not found" regardless of what's happening on the page or the broader application.
But what if you need this Label to change? That's where dynamic property values come in. They allow you to describe how this property will be configured based on other data available to this component. This could be a data resource on your page, or a client state parameter, or even the value of a URL field or optional parameter. And you can even transform that data into exactly the shape you want for your use case.
As of UI Builder's Washington Store Release 2, we configure dynamic data in Formula Builder. Let's use Formula Builder and explore what possibilities we have when configuring dynamic property values.
Using Formula Builder
You can access Formula Builder anywhere you configure property values by hovering over the property you want to configure, and then choosing the "Bind data or use scripts" button in the configuration options popover that appears in the top right corner.
When you click on that button, you will see the following:
Let's break down the pieces of this UI:
- At the top, under the modal header, you will see the "Formula area". This is where the currently configured value will appear. If the Apply button is active, clicking it will cause the formula that appear to be the value for the property.
- In the bottom left panel, you have the Data Type Category Selector (and a tab to access the Formula Category Selector). This will allow you to browse different data you can use to configure the value.
- In the bottom right panel, you will see the Pill View. This gives you a "dot walk"-able display of the different data that is available for the selected category. Clicking a pill will either allow you to add that pill to the Formula Area and/or dot walk further into the data.
Data Types
Focusing on the bottom left panel, here you have all of the categories of data types that you can use for your dynamic properties.
- Page Properties: This is all data coming into your page from outside of it.
- App: These are values set up in
sys_ux_page_propertiesfor your application. Don't worry about that too much right now if you don't know what these are. - Props: These are the values of the Properties of your page. You can see what properties are available on your page by clicking on Body in the Component Tree Navigator and going to the Config tab in the Component Configuration panel to the right. The most common use of these are for the properties that expose the Required Fields and Optional Params for this Page (such as table or sys_id for instance in a Record page).
- Session: These are commonly used values from the user's GlideSession. Keep in mind this is the GlideSession of the user that is viewing your page. Some useful data in here is things like the user's first name, last name, avatar URL, and timezone.
- App: These are values set up in
- Data Resources: All the data resources available to this page. Most of them will be data resources that you have added to this page explicitly, though some may be "inherited" - usually when you are creating a Viewport/Page Collection page. In the bottom right panel there will be pills for each data resource, and you will be able to "dot walk" down the data they output to select the exact piece of data you would like to use.
- Component: This is a rarely used option, but some components expose data themselves for use by other components. An example of this is the List Menu component. Most usages of this category have been deprecated in recent releases of the Next Experience Framework. The bottom right panel will have pills for any component that exposes a property that can be bound in this way. You can "dot walk" it just like everything else.
- Client State: Here you will have listed all of the client state parameters you have created for this page. In the bottom right panel, you will see a pill for each of them, and if any of them are complex data, you will be able to "dot walk" it as well.
Pill View / JSON View
This area will list the data that is available for you to use to configure a property. Much of this data will be complex (think of a reference to another record, or a list of records). If you select a pill that represents complex data, pills for the data available inside of that piece of data wil be shown in a column to the right. If at any time, you select a pill that contains the data you want to use, and there is an up arrow (ꜛ) button on the right side you can either click that arrow, or drag the pill onto the Formula Area to use it.
Let's look at an example. Suppose I want to configure a property to show the logged in user's display name. We would open Formula Builder and then we would see this:
We know the user's data is in the session, so we'll select the "session" option:
We now see that there is a pill for "user", that looks promising! Let's click that.
And there it is! You should select "displayName" here and you will see the up arrow button. Click it and you should see an item appear in the Formula Area:
When you hit Apply you should see the display name used on the Stage.
Understanding how dynamic properties work
To understand dynamic properties - let's use a comparison to spreadsheet software like Microsoft Excel. In a spreadsheet, you are able to write formulas in a cell and those formulas can have a reference to another cell (like #A1). Whenever that other cell updates, the cell that has your formula updates as well. Dynamic values work in the same way - but with more complex data than what can be stored in a cell in a spreadsheet. This includes arrays and objects that contain other arrays and objects. Not just numbers and strings.
This is important to understand, because it means that anything that has a dynamic property will always be up to date based on the other data that it references.
More complex dynamic property configuration with formulas
Going back to our analogy with Excel, you can also use formulas to configure a dynamic property - not just a single reference to another piece of data. This allows you to format and/or transform a single piece of data, or use different data based on certain dynamic conditions.
Let's take a look at how formulas look in Formula Builder:
In the Formula Area, you can see a formula that is actually used in a real Out of The Box (OOTB) application available. (CMDB Workspace > Record Page).
IF(!@data.rpCtrl.activityStream.isComposeVisible, "stacked", @data.rpCtrl.activityStream.layout)This works the same as the
IF function in Excel. Inside the parentheses are the inputs to the function:- The first input is a condition, which means the value will either be
trueorfalse. Here the condition is referencing a condition that is output from a Controller and then using the!or NOT function to flip the condition. - The second input is some text. If the condition is true, this will be the value of the property.
- The second input is a reference to some other data from the same controller as the first input. We can assume that is normally has a text value as well. If the condition is false, this will be the value of the property.
❓
Quiz time
Reading the formula above, if @Data.rpCtrl.activityStream.isComposeVisible is true, what will the value of the property be?
Answer ▼
stacked will be the value of the property.
Reading the formula above, if @Data.rpCtrl.activityStream.isComposeVisible is false, and @Data.rpCtrl.activityStream.layout is other, what will the value of the property be?
Answer ▼
other will be the value of the property.
How formulas work at runtime
Formulas work the same as having just a reference to dynamic data - if the dynamic data changes the entire formula will be executed again and the value of the property will be updated, and the component should change it's appearance or behavior as appropriate.
High performance data configuration patterns
Using dynamic configuration for properties can have an impact on page performance. Normally this is only really felt at scale, but you can get ahead of the problem by following these principles:
- Only use dynamic configuration when actually needed. Make sure that the data actually changes. If not, just use static configuration.
- Try to only reference data, avoid formulas. If you know when the referenced data will change, it's better to calculate the value you need in a Client Script and save it to a client state parameter and just reference the client state parameter.
- Go out of your way to not repeatedly process arrays to create a value. Deriving a value from an array, or transforming an array should almost never be done at the property configuration level. This will be done more often than you think, and can lead to significant page performance issues at scale.
Dynamic properties using scripting
At this point, some (usually more experienced) users of UI Builder may be asking, "Why can't I just write a script to configure this property value?". The truth is you can. But it was left here at the end because it is strongly recommended to avoid them. There are several performance issues that can occur when using Scripted property values. But in the spirit of completeness, let's discuss how to use them (sparingly).
How to access the script editor in Formula Builder
To access the script editor, just click the
<> button in the top right of the Formula Builder. You'll see it highlighted in the following screenshot:
When it's clicked, you'll see a script editor complete with autocomplete and syntax highlighting:
Using scripts to dynamically configure properties
- While the scripting language is JavaScript, many APIs normally available in the browser are not available. This includes anything that would allow you to change elements directly using builtin Document Object Model (DOM) APIs.
- Try to do as little work as possible in the script.
- If it can be a formula, make it a formula - even if you write a script to figure things out at first.
- When you change the element ID of an element or data resource, or the name of a client state parameter, your scripts will NOT be updated. Formulas will always have references updated when IDs change.
Conclusion
Congratulations! 🎉 You've gotten a whirlwind tour of all the capabilities that UI Builder offers for configuring dynamic properties. Let's recap.
- Data references offer a simple way to connect the value of a property to another piece of data available on the page.
- These references ensure that the property value is always up to date when the referenced data changes.
- Formulas allow you to use basic logic and perform a number of transformations of static and referenced data.
- Scripting is an option, but should be used rarely and with caution.
Formulas are a deep topic of their own, and time does not allow us to cover all of it in the article. If there is some part of this topic you'd like to see a deeper dive on, please let us know in the comments below.
If you found this guide helpful, consider sharing it with peers or teams looking to elevate their UI Builder skills with dynamic visualizations.
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
1 Comment
