UI Builder Essentials: Modals and Modeless Dialogs

[MGOPW]

UI Builder Essentials Part 8

Table of Contents

• What is a Modal Dialog?
• Types of Modals
• Creating a Modal
• Configuring an existing Page
• Configuring the Modal Dialog
• Adding Events
• Linking the Modal to a button
• What is a Modeless dialog?
• Creating a Modeless dialog
• Configuring an existing Page
• Adding Content
• Adding the Button Component
• Adding Event Handler for Button

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 Part 6 - Simple Counter Application Part 7 - Interactive List and Form Configuration Part 8 - Modals and Modeless Dialogs

Overview

In this tutorial, we’ll dive into the world of Modals and Modeless dialogs in UI Builder. You’ll discover what they are, how to configure them, and the key differences that set them apart. To bring these concepts to life, we’ll walk through two practical use cases, giving you hands-on experience with each type of overlay and a deeper understanding of how to leverage them effectively within your experience.

Family Release: Xanadu

UI Builder Release: 26.2.59

Roles Required: admin

Authored by: @sophiasemga 

Thinking Beyond Modals

Configurable Workspaces offer many different opportunities to transform your fulfiller's experiences, so instead of adopting a "Lift and Shift" mentality when migrating to workspaces, I invite you to take a moment to pause. Consider if that requirement you're trying to fulfill with a modal would be better suited to a different location in the workspace, like the sidebar or a page collection. Modals currently see widespread use to address many use cases and requirements for Core UI form views. While looking in to what Modals and Modeless dialogs can do for you in Workspaces, keep in mind that they were likely a popular tool in the past because of how limiting the configuration of Core UI forms was. 

📢

Prerequisites

Before starting this tutorial, ensure you've completed the necessary prerequisites to follow along smoothly. Here are some key articles you might need to reference:

• How to make a workspace from scratch: In this article, we created the Customer Support Workspace.
• Updating Component's Data with a Button: In this article, we created the page we will be adding to in this article.

📌

Troubleshooting

If at any point something isn't working, try clearing the UI Builder cache. 

Within your page variant editor in UI builder, click the hamburger menu icon at the top-left, go to Developer > Clear UI Builder Cache.  You can also try clearing your local browser cache.

What is a Modal Dialog?

A Modal Dialog is a UI overlay/window displayed in front of a page, capturing the user's attention while disabling interaction with the underlying content. The user must interact with the modal before returning to the main page, making it a useful tool for focused tasks, such as gathering input, providing alerts, or confirming actions. UI Builder offers both pre-configured modals to support common use cases, or the ability to create your own custom modals. They can be used to guide users, prompt them to make decisions, or display important information. Let’s explore the types of modals available in UI Builder and their use cases.

Types of Modals in UI Builder

Alert Modal 

An alert modal provides feedback or information related to an action taken by the user or a system event. It is designed to notify users without requiring further input, keeping them informed about what just happened.

Example: After submitting a feedback form, an alert modal pops up with a message like "Thank you for your feedback!" to confirm the action.  

Confirm Modal 

A confirm modal prompts the user to verify their intent before proceeding with an action.

Example: Before logging out of a system, a confirm modal prompts the user with "Are you sure you want to log out?" with options like "Yes, Logout" or "Cancel."

Confirm and Destroy Modal

This modal emphasizes critical actions with irreversible consequences, such as deleting data. The language and design are more directive, often including warnings to highlight the severity of the action.

Example: When attempting to reset a database, the modal displays "This action will erase all records. Do you want to continue?" and requires explicit confirmation.

Custom Modal 

Custom modals address unique scenarios that cannot be handled with standard modal templates. They act as a flexible container where you can add layouts, components, events, and dynamic data resources.

Example: Designing a custom modal to onboard new users with multiple steps, such as filling out their profile, setting preferences, and completing an initial survey.

iFrame Modal 

iFrame modals allow you to embed external content via a URL. They are particularly useful for integrating third-party services or displaying external resources without leaving the experience.

Example: Displaying a live weather widget or a third-party payment gateway in an iframe modal, allowing users to view or interact with external content without leaving the app.

Modal Viewport

The modal viewport dynamically populates its content through event bindings, enabling you to create modals that respond to user actions or real-time data. It’s ideal for scenarios where the content of the modal depends on specific context or user selections.

Example: When a user clicks on an item in a product list, the modal dynamically displays the product's detailed description, price, and available stock.

Let's Create a Modal!

In this section, you'll learn how to configure a modal dialog in UI Builder and link it to a button component. The goal is to create an interactive confirmation modal that appears when a user clicks a button it displays a message about the record, and automatically closes based on user actions.

You will:

• Modify the record page by adding a new button beside the 'Click Me' button.
• Configure a modal dialog component.
• Set up event handlers to display a message and manage modal visibility.
• Link the modal dialog to the newly added button for easy user interaction.

Let's open the Customer Support Workspace.

Step 1. Open UI Builder

1. In your ServiceNow instance, use the Application Navigator to go to UI Builder. (Now Experience Framework > UI Builder)

2. When UI Builder opens, you should see the UI Builder home screen.

3. Select the Experiences tab at the top of the screen.

4. Open the Customer Support Workspace.

Step 2. Configuring an existing Page

1. In the Experience Editor, find Pages and variants.

2. Select the Default page variant under the record page.

3. Select the Button component (“Click Me”) and click the three dots (⋮) beside it. Alternatively, select the Body > Top Right > Clicked button component, then click the three dots (⋮) beside it.

4. Select Add After.

5. Search for Button in the component search bar and select it.

6. Navigate to the Component configuration panel to the right, click the component name above the preset and edit it.

• Component Label: Record Info Button
• Component ID: record_info_button

7. Select Apply.

8. Under the Configure tab, set the Label property to Record Info.

9. Navigate to the Styles tab and add padding to the right to create spacing.

💾  Remember to save your changes!

Step 3. Configuring the Modal Dialog

Adding a Modal Component

1. In the Content Tree, navigate to Overlays > Modal.

2. Click the + (plus) icon next to Modals to add a new modal.

3. Select the Confirm Modal. 

4. A modal dialog will appear, graying out the rest of the screen.

5. Navigate to the Component Configuration panel, click the modal's name above the preset and edit it.

• Component Label: Confirm Message
• Component ID: confirm_message

Modifying the Modal Properties

1. In the Component Configuration panel, under the Configure tab, set the properties below as follows:

• Header: Incident Record
• Content: Confirm this to get a message about the record
• Primary Button Label: Confirm

💾  Remember to save your changes!

Step 4. Adding Events to the Modal Dialog

Configuring the “Confirm” Button Event

1. Navigate to the Events tab.

2. Click Add Event Mapping.

3. In the popover that appears, select the Primary Button Clicked event.

4. Click Continue.

5. Choose the Add Alert Notifications event handler.

6. Click Continue.

7. Click the Edit button to modify the Items property.

8. In the modal, click the Mode dropdown and select JSON.

9. Add this array of objects:

[
      {
        "type": "info",
        "message": "This is an existing Incident Record!"      
      }
    ]

10. Click the stacked lines icon at the top to format the JSON data.

11. Click Apply, then Add.

 

Closing the Modal After Confirmation

1. Under the event we just configured, click Add Handler.

2. Select the Open or Close Modal Dialog event.  

3. Click Continue.

4. In the Modal dropdown menu, select the “Confirm Message” modal we just created.

5. Uncheck the Open Modal Dialog option. This will have  the modal close automatically after the user clicks the confirm button.

6. Click Add.

Configuring the “Cancel” Button Event

1. Still in the Events tab, click Add Event Mapping.

2. Select the Secondary Button Clicked event.

3. Click Continue.

4. Select Open or Close Modal Dialog.

5. In the Modal dropdown menu, select the “Confirm Message” modal we just created.

6. Uncheck the Open Modal Dialog option. This will have  the modal close automatically after the user clicks the secondary button.

7. Click Add.

💾  Remember to save your changes!

Step 5. Linking the Modal to the “Record Info” Button

1. Select the Record Info button (or navigate to Body > Top Right > Record Info Button).  

2. In the Component Configuration panel, open the Events tab.

3. Since the “Button Clicked” event already exists, click Add Handler to add a new event handler.

4. In the modal dialog, select Open or Close Modal Dialog.

5. Click Continue.

6. In the Modal dropdown menu, select “Confirm Message”.

7. Ensure Open Modal Dialog is checked (so the modal opens when the event fires).

8. Click Add.

💾  Remember to save your changes!

Testing and Previewing

1. Click the Preview dropdown menu in the top right, and select Open URL Path.

2. Click the Record Info button,  this should open the modal we created.

3. After clicking "Confirm", a notification should pop up about the record.

What is a Modeless Dialog?

A Modeless dialog is a floating window that overlays a UI Builder page, like a modal. However, unlike modal dialogs, it allows you to interact with both the dialog content and the underlying page content. A modeless dialog can also be moved around on a page, resized, and even minimized.

They can be handy to use for things like:

• Filling out an input form
• Creating a new record
• Viewing an attachment
• Composing an email

Let's Create a Modeless Dialogue!

In this section, you'll configure a UI Builder page to add a modeless dialog that allows users to interact with both the dialog and the underlying page content. The goal is to create a quick way to view logged in user details (such as name, profile picture, and other attributes) without navigating away from the current record.

You will:

• Add a modeless dialog component to the existing record page.
• Configure and add content, including a form and an avatar component, to the modeless dialog.
• Add a button next to 'Record Info' button to trigger the modeless dialog.
• Set up event handlers to control dialog behavior.

Now, let's get started by opening our existing Customer Support Workspace in UI Builder.

Step 1. Open UI Builder

1. In your ServiceNow instance, use the Application Navigator to go to UI Builder. (Now Experience Framework > UI Builder)

2. When UI Builder opens, you should see the UI Builder home screen.

3. Select the Experiences tab at the top of the screen.

4. Open the Customer Support Workspace.

Step 2. Configuring an existing Page

1. In the Experience Editor, find Pages and variants.

2. Select the Default page variant under the record page.

3. In the Content Tree, select the + (plus) button next to Modeless dialogs.

4. Select Modeless Dialog and click on it.

5. The Modeless Dialog should now appear on the Stage Panel, and Modeless dialog default should appear in the Content Tree.

💾  Remember to save your changes!

Step 3. Adding Content to Modeless Dialog

Add a Stylized Text Component (Header)

1. In the Content Tree, select the + (plus) Add Content link under the actions container in the Modeless dialog default modeless dialog. 

2. Search for the Stylized Text Component and select it.

3. Navigate to the Component configuration panel to the right, click the component name above the preset and set the properties as follows: 

• Component Label: User Heading
• Component ID: user_heading

4. Click Apply.

5. Still on the component configuration panel, remove the preset.

6. Click on the preset titled “Record Subheading”.

7. Select Remove Current Preset.

8. Under the Configure Tab set the Text property to: Current Logged In User.

9. Under HTML Tag property, select H3 from the dropdown.

Add a Form Component

1. In the Content Tree, select the + (plus) Add Content link under the content container in the Modeless dialog default modeless dialog. 

2. Search for Form Component and select it.

3. When prompted to "A pply default configurations to data resources", select Configure manually.

4. The Edit Form Controller modal will appear to configure the form controller.

5. In the Edit Form Controller modal, navigate to the Configure Tab.

6. In the Table property, search for the User table (sys_user) and select it.

7. For Sys ID property, click on the Bind Data icon. (Hover over the property's text input field, click the stacked circles icon.)

8. Navigate to Page Properties > Session > User and select the sys_id pill. There are three ways you can add data and formula pills to the top of the Bind data modal:

• Click on the pill, then click the up arrow that appears to the right.
• Drag and drop the pill to the top box.
• Double click the pill.

9. Select Apply.

10. Click the X icon to exit out of the dialog. Ensure the Table and Sys ID properties on the Component configuration panel properly reflect the changes.

11. In the Component configuration panel, click the component name above the preset and edit it.

• Component Label: User Form
• Component ID: user_form

12. Click Apply.

 

Add an Avatar Component

1. In the Content Tree, select the + (plus) Add Content link under the footer container in the Modeless dialog default modeless dialog. 

2. Search for the Avatar component and select it.

3. Navigate to the Component configuration panel, click the component name above the preset and edit it.

• Component Label: User Profile
• Component ID: user_profile

4. Click Apply.

5. Under the Configure tab, find the User Name property, click the Bind Data icon.

6. Navigate to Page Properties > Session > User and select the userName pill.

7. Double-click the userName pill and select Apply.

💾  Remember to save your changes!

Step 4. Adding the Button Component

Add a Button to Open the Modeless Dialog

1. Click on the “Record Info” button on the Stage panel.

2. Click on the three dots beside it and select Add After.

3. Search for the Button component and select it.

4. Navigate to the Component configuration panel, click the component name above the preset and edit it.

• Component Label: Modeless Button
• Component ID: modeless_button

 

5. Click Apply.

6. Under the Configure Tab, find the Label property and set it to User Info.

7. Under the Styles tab, add a small left padding to give it some space.

💾  Remember to save your changes!

Step 5. Adding Event Handler for Button

Configure the Button Click Event

1. Navigate to the Event tab and click Add Handler. 2. Search for and select Open Modeless Dialog.

3. Click Continue.

4. In the Configure section, set the fields as follows:

• Minimized Heading: Current Logged In User
• Modeless Dialog: Modeless Dialog Default

5. Click Apply.

💾  Remember to save your changes!

Test Functionality

1. Click the Preview dropdown menu in the top right, and select Open URL Path.

2. Click the User Info button,  this should open the modeless dialog we just created

3. Verify that the Modeless Dialog appears and displays:

• Current Logged In User Heading
• User Form with Logged-in User’s Data
• User Profile (Avatar)

Conclusion

Congratulations! 🎉  You've successfully mastered the use of Modals and Modeless dialogs in UI Builder. By completing this tutorial, you've gained practical insights and hands-on experience, empowering you to create dynamic and interactive user experiences within your configurable workspaces. 

If you found this guide helpful, consider sharing it with peers or teams looking to elevate their UI Builder skills with dynamic pages. If you like this type of content, please mark the article "Helpful", and leave us your topic ideas in the comments.

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