Key Features of Experiences:

• URL Structure: Each experience is accessed via a unique URL, structured as a child URL of the experience's root URL (located after /now/ on your instance).
• Landing Page: Users are directed to a default landing page when they access the experience URL.
• App Shell UI: Each experience includes an App Shell UI, which consists of common UI elements across all pages within that experience. This "App Chrome" frames where individual pages are rendered and is configured primarily in Core UI and UI Builder.
• Functional Elements: The App Shell is responsible for crucial functionalities, such as loaders, login/logout interfaces, help features, and search configurations.

Example of a Workspace Experience

• A default page located at /home, often featuring dashboards or analytics.
• A list page at /list.
• A record page at /record.
• A customizable vertical icon list and tabs or breadcrumbs for navigation.

Parent App Shells

Exploring the Macroponent Record

 

 

1. Layout: Defines the overall structure and rendering rules of the Macroponent. Any changes made to the styles for the “Body” or “Root” element in UI Builder will reflect in this field. The layout model has evolved to support enhanced capabilities, including responsive design.
2. Composition: This field houses the components and their configurations. For instance, if you create a page in UI Builder with a heading, a button, and an image component, all these elements and their configurations will reside in the composition field. When you modify the metadata in the Macroponent, such as changing a heading label, the updates will be visible upon refreshing the page.
3. Events: Events play a crucial role in the interactivity of your components. For example, a button click event might be mapped to open a modal, and this mapping is reflected in the Macroponent record. Events can become complex, and they often require relay mappings to communicate with the App Shell for actions like opening and closing modals. For more information on Events, check out this community article.
4. Data: The data field contains a list of data resources and their configuration values. Data resources, akin to components, have configuration properties and events but do not have a user interface. Instead, they output data based on their configuration. For example, if you configure a "Lookup a single record" data source to retrieve a record from the Task table, a GlideQuery fetches the desired fields. Changes to the configuration of a data resource automatically update the output, allowing for flexible data binding on the page.

Client Scripts

Getting Started

When you access an experience in UI Builder, you encounter what we refer to as the Experience View. This interface lists all the pages and their variants within the selected experience, along with options to edit and configure each component.

 

 

Understanding Pages and Variants

Pages:

• Each page within an experience can host one or more variants.
• Similar to Form views in tables, a page has a designated name and URL path, and it may include Required or Optional parameters.
• When a user navigates to a URL associated with an experience, they are directed to a specific page.

Variants:

• The variant represents the actual user interface presented to the user.
• While multiple records facilitate this process behind the scenes, it’s helpful to conceptualize the variant primarily as the Macroponent record.
• Variants can be tailored based on criteria to determine which specific variant will be displayed.
• For example, workspaces often include multiple record page variants targeting distinct tables, such as a different record page for the user table versus the incident table.
• When creating a variant, you establish the criteria and order for display. The most specific variants should have the lowest order value, while the more general ones should have a higher order value.

Pages can be targeted to specific user criteria using audiences, offering a powerful customization feature. You can find more information on audiences in this ServiceNow Docs article.

Parameters in Pages

Required Parameters:

• These parameters are essential for loading a page. If they are not provided, the page will not render and will return a 404 error.
• Taking the standard workspace record page as an example, it requires two parameters: Table and SysId.
• Any number of required parameters can be defined at the page level, and all variants of that page will require these same parameters.

Optional Parameters:

• Optional parameters allow for added functionality without hindering the page’s accessibility.
• The workspace record page, for instance, includes four optional parameters: query, extraParams, views, and selectedTab.
• When navigating between tabs on a record page, the selectedTab parameter changes, allowing users to copy links that maintain their tab state for others.

Parameter Order and Management

• Required parameters are always listed first in the URL, and the order of these parameters is crucial.
• Optional parameters follow the /params/ segment in the URL and are order-agnostic due to their label-value structure.
• If you add or remove any required parameters after creating links, you must update those links to ensure they contain the necessary parameters; otherwise, users will encounter a 404 error.

Page Editor

 

 

The UI Builder editor is designed to facilitate the creation and customization of pages, structured into three main regions: Inventory, Stage, and Configuration.

 

Let’s explore each of these areas in detail.

 

Inventory

The Inventory section displays a content tree that outlines all the containers and components present on the page. This is roughly equivalent to the Document Object Model (DOM) structure. Below the component listing, you'll find:

• Data Resources: Lists all data resources associated with the page.
• Client Scripts: Displays any client-side scripts that are linked to the page.
• Client State Parameters: Shows the parameters that help manage the state of the client interface.

You can select components either by clicking directly on them in the Stage area or by selecting them from the content tree in the Inventory.

 

Stage

The Stage area is where the actual page preview is displayed. This is where you can see how the components will appear to end-users as you edit and configure them.

 

Configuration

The Configuration panel on the right side changes based on the selected component, offering specific configuration options divided into three tabs:

• Config: Here, you can adjust the various settings and properties for the selected component.
• Styles: This tab controls the visual aspects of the layout and CSS for the component.
• Events: In this section, you can configure the events associated with the component.

To better understand how each component operates, you can refer to the Horizon Design System website, which provides documentation and guidance on many of the available components in UI Builder.

 

Styles Tab

The Styles tab allows for visual configuration of components and layout through CSS. However, remember that many visual properties are dictated by the theme set in your instance. For instance, background colors for buttons typically derive from the theme rather than being adjusted directly in UI Builder. To customize these properties, you would use Theme Builder, which you can install from the ServiceNow Store for easier theme management.

 

ServiceNow Store - Theme Builder

 

Within the Styles tab, you can control:

• CSS for Components: Customize the appearance of individual components.
• Page Layout CSS: Adjust how the entire page is presented visually.

UI Builder utilizes modern CSS features such as Flexbox and Grid for layout management. If you're not familiar with these technologies, there are numerous resources available on sites like MDN (Mozilla Developer Network) that provide tutorials and explanations.

 

Layout Management

 

Simple Page Layouts

For straightforward pages, starting with basic column layouts is recommended, as these layouts are easy to configure without extensive CSS knowledge. UI Builder supports layouts with up to six columns and includes common column arrangements for quick setup. Additionally, columns allow you to adjust their count with ease (e.g., transitioning from two columns to three).

 

 

 

Complex Page Layouts

For more complex designs, you can implement Flexbox or Grid containers:

• Flexbox: Typically used for one-dimensional layouts, Flexbox is user-friendly and facilitates arrangements in either horizontal or vertical directions. By default, blank pages in UI Builder are set to a vertical flexbox layout.
• Grid: A two-dimensional layout system that is particularly useful for handling variable datasets. For example, if you’re querying the incident table for records assigned to a user, the data volume can fluctuate greatly.

Flexbox Layout Docs Grid Layout Docs

 

Using a grid layout allows you to define a structure, such as a card layout with up to five cards wide, which automatically adjusts as new data is added. You can configure the grid to display a set number of rows and columns, while the browser takes care of dynamically generating additional rows based on the dataset size.

 

Understanding the page editor and its components is crucial for effective UI design in ServiceNow. The flexibility provided by both Flexbox and Grid layouts ensures that you can accommodate a variety of use cases, from simple forms to complex data presentations. 

 

Events

In the UI Builder editor, the Events configuration tab plays a vital role in establishing interactions within your application. Here's a closer look at how events function and their significance in enhancing user experience.

 

Overview of Events

• Types of Events: Events can range from straightforward actions, such as a user clicking a button, to more complex triggers that fire when data is loaded successfully or fails to load. Not all components will have events associated with them, and some may have multiple events defined.
• Default Behavior: By default, events do not perform any action until they are connected to an event handler. This connection is referred to as event mapping.

 

Example of Event Mapping

For instance, if you want a button to navigate to servicenow.com when clicked, you would:

1. Identify the Button Clicked event.
2. Bind this event to the “Link to Destination” event handler.

This action allows the button to respond effectively to user interactions. Essentially, events act as the "glue" that connects various interactions within the UI.

 

Common Event Handlers

Here are some examples of event handlers that can be associated with events:

• Page Navigation: Transitioning the user to a different page.
• Displaying Modals or Popovers: Triggering pop-up windows for additional information.
• Client Scripts: Running client-side scripts based on user actions.
• Changing or Setting Client State Parameters: Updating parameters to reflect changes in the UI.
• Loading Animations: Indicating that data is being processed or loaded.

Multiple Handlers for a Single Event

An individual event can be linked to multiple event handlers, providing greater flexibility in response to user interactions. Furthermore, data resources—discussed in the next section—can also introduce additional event handlers to your page, so the number of handlers may vary depending on the specific configuration of the page.

 

Lifecycle Events

In addition to component and data resource events, UI Builder supports lifecycle events such as macroponent_ready and macroponent_property_changed. These events are triggered at various points in the lifecycle of a page or component and can be particularly useful for managing state and transitions.

 

UI Builder's user interface is designed to feel familiar and incorporates patterns found in other WYSIWYG (What You See Is What You Get) UI building tools. However, it differs from simpler tools in that it emphasizes data-driven applications rather than static web pages or marketing sites. UIB is tailored for constructing complex web applications that can drive organizational processes and efficiencies.

 

• Definition: Data Resources are integral components within UI Builder that provide a means to access and manipulate data. They are akin to other components, as they are added to the macroponent using JSON, have configurable options, support events, and are designed for reuse.
• Data Resources can:
  • Query Data: Retrieve information from a ServiceNow instance using Glide queries or custom GraphQL queries.
  • Transform Data: Alter the format of data to suit specific requirements.
  • Read and Write: Both read data from and write data to a ServiceNow instance.

• User name
• Roles
• Local timezone
• Preferences

• Role of Controllers:
  • Think of a Controller as a container or folder that encapsulates the data, business logic, and state information required to manage a complex page or specific use case within a page.
  • Controllers can include any number of Data Resources, Client Scripts, and Client State parameters, which helps simplify the data management process.
• User Experience Enhancement:
  • When the standard Workspace record page transitioned to this Controller paradigm, the number of visible items in the data panel was drastically reduced from over 20 to just 1. This consolidation helps users navigate and configure their pages more effectively.
  • Each Record Page Controller offers an output API that supplies the necessary data to all components on that page.
• Backwards Compatibility: ServiceNow-built Controllers follow a defined API contract, ensuring backwards compatibility. The internal workings of Controllers are concealed from users, allowing authors to update and enhance the Controller without affecting the user experience.

• Definition: Data binding is the process of connecting a component to a data source. It allows components to pull in data from various origins as long as the data is formatted correctly for the component.
• Sample Data: When a component is added to a page, it initially comes with sample data to illustrate how it functions and what it looks like. For instance, the heading component may default to the label: "We make work, work better for people with modern digital workflows." This can be customized to any text that fits your needs.

• Personalization Example: When a user logs into the instance and sees a greeting such as "Hi, Chris," the heading component retrieves the user's first name from the session data and concatenates it with a greeting string. This creates a personalized experience, as each user sees their name reflected in the same component.

• Versatility: Any configuration property of a component or data resource within UI Builder can be bound to data. This includes various data types such as strings, booleans, choices, references, arrays, and complex objects. Beyond components, event mappings, scripts, and client state parameters can also leverage data binding.
• Data Binding Syntax: Data binding employs a "dot walk" syntax that acts as an address for a specific part of the data output. For example, the address for the short description in the Record Controller might look like: @Data.record.form.header.primaryItem.displayValue

• Visual Data Navigation: UI Builder provides a data UI that allows developers to visually navigate the output. This feature enables users to drag and drop "data pills" for easy data binding without needing to type long addresses manually.
• Functions: The data UI supports functions like Concatenate, which can help reduce the need for scripting in many cases, simplifying the development process.

1. Hover over the Configuration Property. This action reveals the option to switch to data binding.
2. Click the Database Icon. This initiates the data binding process, allowing you to connect to the desired data source.

• Automatic Upgrades: One of the primary advantages of using ServiceNow components is that you receive automatic upgrades and improvements. You always use the latest version of UI Builder components, such as buttons, forms, lists, headings, and over 150 others, without needing to make any changes.
• API Contracts: ServiceNow ensures that component APIs are supported through an API contract, meaning the functionality remains stable even after upgrades. Components that come from plugins or store apps may update more frequently, but the principle of automatic upgrades applies to custom components as well. Any changes made to custom components will reflect across all pages utilizing them, so it's crucial to be aware of how changes to the component API might impact existing pages.

• Similar to Components: Controllers, much like components, maintain an API contract, ensuring that changes do not disrupt the pages that depend on them. Any alterations made to a controller automatically apply to every page that uses that controller.
• Encapsulation: Controllers encapsulate data fetching, business logic, and state, providing a structured approach to manage complex workflows and applications.

• Presets were introduced in the Tokyo release to encapsulate configuration in an upgrade-friendly manner and speed up page building. They allow for the automatic configuration of components and data by connecting components to a controller.
• Use Case Example: A common use case involves the heading component displaying the primary field (often the short description). When you select the heading component and choose the "Record title" preset, the preset automatically sets all necessary configuration properties to bind the heading to the primary field data.
• Form Controller Integration: If no controllers are present on the page, the preset will add a Form Controller to facilitate querying the short description from the database.
• Custom URL Parameters: The Form Controller defaults to use required URL parameters to get its Table and SysId. Users are notified if this action will modify the URL structure for the page. If desired, users can choose to configure this manually by hardcoding the Table and SysId.

• Override Functionality: If a user wants to modify a specific configuration (e.g., changing the heading text style), they can do so by overriding just that property instead of removing the preset entirely.
• Maintaining Upgrades: By overriding a single configuration property, users retain the advantages of the preset's upgrades for other properties while maintaining their custom changes. The preset continues to control all other properties, ensuring that users continue to receive updates and enhancements without losing their specific configurations.
• Storage of Overrides: Overrides are stored within the macroponent record being edited, meaning users can only override settings for pages they have edit access to.