UI Builder Essentials: Six Fundamental Features You Need to Know

[MGOPW]

UI Builder Essentials Part 1

Table of Contents

• Pages
• Page Variants
• Components
• Data Resources
• Events
• Scopes

Article Directory

Part 1 - Six Fundamental Features You Need to Know Part 2 - Navigating UI Builder Part 3 - Dynamically bind List with Data Visualization Part 4 - Implementing Popovers Part 5 - Updating Component's Data with a Button

Overview

In this article, you’ll learn each core building block of UI Builder: Pages, Page Variants, Components, Data Resources, Events, and Scopes, plus details about how they interact.

Family Release: Xanadu

UI Builder Release: 26.2.59

Roles Required: admin

Authored by: @michaelburney 

1. Pages

What is a Page?

A Page in UI Builder is the highest-level container or “screen” a user navigates to when using your ServiceNow experience. Think of a page like a webpage in a traditional site—each page typically has a unique URL (or route) and serves a specific purpose.

Key Details

• Single Point of Access: Each page represents a view or experience for end users (e.g., a dashboard page, a request submission page, or a case details page).
• Layout and Structure: The layout defines the overall page with columns, rows, and containers where you can drop UI components.

How It Interacts with Other Concepts

• Page Variants: A page can have multiple variants, allowing you to show different layouts or data based on conditions like user roles or URL parameters.
• Components: You add components onto a page (or page variant) to display data, collect user input, etc.
• Data Resources & Events: Each page (and its components) can connect to data resources and respond to or from events.

2. Page Variants

What is a Page Variant?

A Page Variant is an alternative version of a page that can be displayed under specific conditions (such as user role, query parameters, or device type). It allows dynamic rendering of different layouts or UI elements based on context.

Key Details

• Conditional Rendering: You can configure multiple variants on a single page and define rules—like user role or a parameter in the URL—to load the appropriate variant.
• Targeted Experience: Variants enable you to tailor the user experience without needing to create multiple separate pages. For instance, you can show a higher level reporting variant to a manager user and a more detailed variant to a help desk team member.

How It Interacts with Other Concepts

• Pages: Variants exist under a primary page, sharing the same base route but potentially displaying different structures or components.
• Components: Each variant can have its own set of components or arrangement of shared components.
• Data Resources: Variants may use the same or different data resources, depending on how you want to display information.

3. Components

What is a Component?

A Component is a reusable UI element or widget that you place on a page (or page variant) to present information, capture user input, or offer interactive functionality.

Key Details

• Reusable Building Blocks: Components range from simple text blocks and images to complex widgets like lists, forms, or charts.
• Configuration: In UI Builder, each component has properties and configuration settings you can adjust (like data bindings, appearance, styling, and events).
• Custom Components: You can also build custom components in ServiceNow, typically using frameworks like the now-CLI, and make them available in UI Builder.

How It Interacts with Other Concepts

• Pages and Page Variants: You drag and drop components onto a specific page or variant.
• Data Resources: Components can be bound to data resources so that they display data retrieved from a table API, script or external API.
• Events: Components can emit or listen for events (e.g., a button click event that triggers a data refresh).

4. Data Resources

What is a Data Resource?

A Data Resource in UI Builder is a configuration that defines how data is retrieved and made available to UI components. It might point to a ServiceNow table, a script that returns data, or an external API.

Key Details

• Data Retrieval: Data resources handle the fetching of data from various endpoints (ServiceNow APIs or external APIs).
• Bind Once, Use Everywhere: Once a data resource is set up, multiple components can consume the same data resource within a page (or across pages in the same experience).
• Transformations: Often you can transform data in a resource script or manipulate it before binding it to components.

How It Interacts with Other Concepts

• Components: Components consume data resources to display dynamic data or send updates back to the server.
• Events: An event can refresh or re-fetch a data resource (e.g., after a user submits a form, you might refresh a list of records to view the new submission).

5. Events

What is an Event?

An Event in UI Builder refers to actions or triggers that occur on the page. These could be user-initiated (e.g., button click, form submission) or system-generated (e.g., data resource loaded).

Key Details

• Event Lifecycle: Components can emit events, and other components can listen and respond to them.
• Event Handling: In UI Builder, you configure event handling in the “Events” panel, telling the system what to do when a specific event is triggered (e.g., invoke a data resource action, navigate to another page, show a modal, etc.).
• Chaining Actions: You can chain multiple actions in response to a single event (e.g., refresh data, show a notification, then navigate to a page).

How It Interacts with Other Concepts

• Components: Components often define the events they emit (e.g., “onClick”) or the events they can handle (e.g., “onDataLoad”).
• Data Resources: Event handlers often trigger data fetches or refreshes or process the returned data.

6. Scopes

What is a Scope in ServiceNow?

A Scope in ServiceNow is a logical boundary for an application that governs how resources—such as tables, scripts, and UI components—are encapsulated and protected. Each ServiceNow application runs in its own scope to maintain separation from other apps and from global resources.

Working with Scopes in UI Builder

1. Application Scoping in UI Builder
   • When you create (or edit) a page or component in UI Builder, these artifacts are typically saved in the scope of the currently selected application.
   • All configuration data (including custom components, data resources, page definitions, etc.) belong to that scope unless specifically shared or designated otherwise.
2. Cross-Scope Access
   • Sometimes you may want to reuse a component or script from another application scope. You can configure cross-scope privileges, but generally it’s recommended to keep all relevant pieces in one scope to avoid complexity.
   • If you encounter “Access to these records from scope X is not allowed,” you may need to add cross-scope privileges or replicate the resource in the local scope.
3. Best Practices
   • Develop in One Scope: Keep pages, page variants, data resources, and custom components in the same application scope for consistency and easier maintenance.
   • Use Out-of-the-Box Components: Many out-of-the-box (OOB) components from ServiceNow are in the global scope but are allowed for use in any application.
   • Manage Custom Code: If you write custom data fetch scripts or web components, be mindful of which scope they are stored in. This ensures that your UI Builder configuration can properly reference them.  
4. Scope Impact on UI Builder Configurations
   • If you switch scopes while working in UI Builder, you may see certain pages or components become read-only because they belong to a different scope.
   • Creating or editing pages across scopes can be tricky. Confirm you’re in the correct scope before making changes to avoid scope conflicts.

Summary of Scopes in UI Builder

• Isolation and Protection: Scopes help keep resources separate, avoiding accidental overwrites and security issues.
• UI Builder Context: In UI Builder, the scope you’re in determines which pages, data resources, and components are visible and editable.

Conclusion

Thank you for taking the time to explore the core building blocks of UI Builder with us. We hope this guide has provided you with valuable insights and practical knowledge to enhance your ServiceNow experiences. Don't forget to share this article with your colleagues and friends who might benefit from mastering UI Builder.

Stay tuned for more tutorials and tips to help you create dynamic and engaging user interfaces!

Check out the Next Experience Center of Excellence for more resources