---
sourceDocument: Yokohama Build or modify applications
sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/application-development
Release :
- yokohama
ft:locale :
- en-US
ft:publication_title :
- Yokohama Build or modify applications
ft:clusterId :
- cadev
bundleId :
- cadev
workflow :
- Development, Data, and Analytics
---
# Bind data to UI Builder pages using controllers (advanced feature)
# Bind data to UI Builder pages using controllers (advanced feature) {#ariaid-title1}
* Release version: Yokohama
*
* Updated January 30, 2025
*
*  7 minutes to read
Controllers simplify the linking of data and event logic to enable component presets in UI Builder.
Controllers enable page builders to easily connect data and scripts to their pages in UI Builder. A controller is a type of data resource that [component presets](https://www.servicenow.com/docs/zrx4f9YaC1RRjhOLAHK~EQ#gloss-component-preset-ui-builder "Presets apply predefined configuration values and event mappings to components. Presets apply prebuilt configurations to component properties and events handlers. Presets are only available for certain components.") use to bind data to components. Controllers differ from other data resources in that they contain data and event logic that enables presets for components. A controller
brings data from the server to a component, and it brings updated data back to the server based on interactions with the component. For more information about component presets, see [Automatically configure components using presets](https://www.servicenow.com/docs/BWKbQtnUtb7nqnuy_Q2LvA#presets "Use component presets to automatically configure components on compatible pages.").
Controllers are added by default when you use a UI Builder page template. You can add controllers to UI Builder pages without a controller within the data resources drawer or by selecting a component preset after adding a component to a page. You can view which controllers are configured on your page by opening the data resources drawer.Figure 1. Controller in the Data resource drawer
## Types of data controllers in UI Builder {#controllers__section_ywy_dfn_xyb}
Data controllers
: Data controllers decide what information should be displayed on UI Builder pages. Data controllers use data resources to sync information in real time and update data/tables when a user inputs information. You can manually add data controllers to a page.
UI controllers
: UI controllers are added to pages when using UI Builder page templates and cannot be added manually.
## Using controllers with presets in UI Builder {#controllers__section_qwn_smn_xyb}
You can add multiple controllers to a UI Builder page, but you can't use the same one twice. If you try to use a component preset that needs a controller, UI Builder prompts you to add it.
Not all components work with controllers, but you can easily see which ones do in the component library. If you have a controller configured on your UI Builder page, you can open the component library to view which components have presets. Components with presets available are highlighted in the component library.
Figure 2. Components with presets
## Add a controller {#ariaid-title2}
Add a data controller to your page to use component presets.
### Before you begin
Role required: admin
### About this task
The record controller is the only controller that you can add to a page in Yokohama.
### Procedure
1. Navigate to AllNow Experience FrameworkUI Builder.
2. Open an experience to work in or create an experience by selecting CreateExperience.
For more information, see [Configure how users interact with your applications in UI Builder](https://www.servicenow.com/docs/nDWg0NsWQpdF_OppvTVe5g "Learn what an experience is in UI Builder. Understand what an experience contains.").
3. Create or open a page or page variant.
For more information about how to create a page in UI Builder, see [Create a page in UI Builder](https://www.servicenow.com/docs/qg0Cc5eGfpImb71VJtmSew "Create a page in UI Builder for a portal, workspace, or custom application so that you can build a web experience for your users.").
4. Select the + icon in the data resource drawer.
5. Select Data resource.
6. Enter form in the search field.
7. Select the controller you would like to add to your page.
8. Select Add.
9. Fill in the fields to configure the controller.
### Result
The form controller displays in the Data resources section.
## Edit a controller {#ariaid-title3}
Configure a controller to pull data from a table.
### Before you begin
Role required: admin
### Procedure
1. Navigate to AllNow Experience FrameworkUI Builder.
2. Open an experience to work in or create an experience by selecting CreateExperience.
For more information, see [Configure how users interact with your applications in UI Builder](https://www.servicenow.com/docs/nDWg0NsWQpdF_OppvTVe5g "Learn what an experience is in UI Builder. Understand what an experience contains.").
3. Create or open a page.
For more information about how to create a page in UI Builder, see [Create a page
in UI Builder](https://www.servicenow.com/docs/qg0Cc5eGfpImb71VJtmSew "Create a page in UI Builder for a portal, workspace, or custom application so that you can build a web experience for your users.").
4. Select the controller that you want to edit in the Data and scripts drawer.
5. On the form, fill in the fields.
{#edit-controller__table_s4y_ryn_15b__entry__2}
| Field | Description |
|-|-|
| Type | Controller is predefined as the type for all controllers. |
| Table | Add a table that you want the controller to pull data from. |
| Sys ID | Enter the unique identifier for a record, provide a value, or use -1 to generate a new value. |
[Table 1. Form controller form]
{#edit-controller__table_s4y_ryn_15b}
6. Close the edit controller modal.
7. Select Save.
## Delete a controller {#ariaid-title4}
Delete a controller that you no longer need in UI Builder.
### Before you begin
Role required: admin
### About this task
Controllers cannot be deleted from pages created with a page template.
### Procedure
1. Navigate to AllNow Experience FrameworkUI Builder.
2. Open an experience to work in or create an experience by selecting CreateExperience.
For more information, see [Configure how users interact with your applications in UI Builder](https://www.servicenow.com/docs/nDWg0NsWQpdF_OppvTVe5g "Learn what an experience is in UI Builder. Understand what an experience contains.").
3. Open the page with the controller you want to delete.
4. Select the Menu icon (![Menu icon]()) next to the controller you want to delete.
5. Select Delete.
The controller is removed from the local data resource instances.
## View properties and events in the Controller API {#ariaid-title5}
The controller public API defines the output data that a controller provides to a
preset. This includes the property values and handled events used by a component when a preset is
selected. Property and event information is available to view in UI Builder.
The component property values in a preset can be static values or paths to controller output data. You can use the data resource inspector in UI Builder to display the values from the controller data structure used by a preset.
To view the payload carried by an event in the preset, you can look in the event handler picker for that event.
### Viewing properties in the Controller API {#controller-api__section_epb_1t4_m5b}
You can view preset properties in the UIB data inspector. Knowing the available values helps
you understand how a component will behave in your design and helps you identify any properties
in the preset you might want to override.
This procedure assumes that you have placed a component with a preset on the page and have
configured a controller. For instructions, see [Add a
controller](https://www.servicenow.com/docs/gyIerqFmP0WfCX4GVx9Yuw#add-controller "Add a data controller to your page to use component presets.").
The configuration tab displays preset property values as a path to the controller output. The
base data path is expressed as `@data.`. The remainder of the
path is built using the contents of the categories within the controller data hierarchy. You can
use this path to view the current values for the record for which the controller has been
configured.
1. To view the data resources for a component, select the data icon in the lower left sidebar.
The three column UIB data inspector appears.
2. In the first column where the data resources are listed, select the controller whose output you want to view.
The configuration data for the selected controller appears in the Config tab of the second column. These are the input properties you entered when you configured the controller for the first component with a preset you placed on the page. You can edit these connection values here if you want.
Note:
Configuring -1 for the value in the Sys ID field configures the controller for a new record. The controller then generates a full GUID that you can use to store data against the record before it's saved. This allows you to perform actions in a newly created record such as saving attachments.
3. Select top level outputs in the third column.
This is
the parent level of the controller data hierarchy, indicated with the prefix
`@data.`, followed by the controller ID. This combination
forms the root path to the data. The data contained in the top level outputs
are displayed in the adjacent code field and are available for presets and
scripts to use. Other properties at that level are some common properties that
apply to all
records.
When the preset maps a component property to controller output, the path to the
output is shown instead of the value. Paths are denoted as
@data.\.\ and can be used as
the values or as part of formula expressions.
In this example, the mapping in the preset results in a path to
`@data.gform.table`.
4. To view data below the top level, select the child category indicated by the path in the preset property value.The name of the child category appears in the path as
`@data..`. The data from that category is then
appended to that path. The root path above the code field indicates the child category being
used. In this example, the path to the View property in the
`form` category is expressed as `@data.gform.form.view`. That
preset value displays forms in the workspace view.
In this example, multiple controller output properties are used in a formula expression
to build an object.
5. To view a scripted property value, select the lock icon next to the property.This puts
the property into edit mode and opens a modal for editing the script.
{#controller-api__ol_v1d_pt4_m5b}
### Viewing events in the Controller
API {#controller-api__section_wwz_v54_m5b}
You can view handled events mapped to a component by a preset and their payloads in the Events tab in the UI Builder configuration panel. If the data mapping for an event isn't appropriate for your use case, you can add additional data handlers.
Note:
Data handler mappings provided with the preset are not editable.
1. Select the Events tab in UI Builder.
2. To view the mapping for a preset event, select the event tile.A modal appears
showing the payload properties for the preset event. You can
Disable the event in this modal.
3. To add an event handler to the event, select + Add event handler under the event tile.
A modal appears, showing a list of available, handled events. You can select
any action from the list, including an event handler from one of the
controllers listed.
4. Select an event handler from the list and select Add.
The new handler is listed under the event
tile.
{#controller-api__ol_rg4_1v4_m5b}
*[\>]: and then