Building a Killer Experience with UI Builder

Goal

In this lab you will learn how to use UI Builder to build and configure a front-end for a custom application. You will start with a prebuilt application for a recipe database where you can search, view, add and edit recipes. The application is seeded with recipes from both the author and ServiceNow developer community.

You will use UI Builder to open a start portal experience created from App Engine Studio to build a front-end to make it easier to interact with the application. This lab will touch on a number of different parts of UI Builder while you create the custom experience including but not limited to:

Creating new pages
Page parameters
Data resources
Client state parameters
Client scripts
Configuring components
Using the new repeater component
Using the new formula editor
Updating ServiceNow records from the experience
Theming and branding
Building custom menus

(Optional) Pre-flight check

If you’re doing this lab during CreatorCon, you’ll be working on an instance on NowLearning loaded with the Recipe DB application. If you’re following along with this lab guide on a Personal Developer Instance (PDI), please follow the instructions in the Appendix at the end of this lab guide to learn how to pull in the Recipe DB application.

Exercise 0 - Get Familiar with the Recipe DB App

Goal

In your instance, you will find a Recipe DB app with a couple of tables loaded with data. Let’s take a look.

In the top menu in your instance, click All, type App Engine into the filter, and click App Engine Studio to launch App Engine Studio, or AES as we’ll call it moving forward.
The app currently consists of:
- Data (tables)
  - Category
  - Recipe
- Experiences
  - Recipe DB (Portal experience)
  - New Recipe (Record producer)

Exercise 1 – Build the Recipe Page

Goal

In this exercise you will build a new page with a required parameter that displays a single recipe with an image, link button, and recipe information.

Open UI Builder

From within App Engine Studio, in the Experience section, click the three horizontal dots icon at the very right-hand side of the Recipe DB experience and choose Edit.
This will launch UI Builder (UIB) in a tab within App Engine Studio (AES). You can save some vertical real estate in AES/UIB by finding and clicking the Enter full screen icon at the very right hand side of the tab bar.

You can also use UIB outside of AES and you get an additional 50px of vertical screen real estate, but I prefer being able to easily get back to the home tab and look at my data model.

Create the page

Now that you have UI Builder open you will need to create a new page to display your recipe.

Use the three vertical dots menu at the top of the page sidebar to choose Create page and launch the Create a page dialog.
Name the page Recipe and choose Create.
In the success modal that appears choose Add required parameters.
Click the +Add button on the right side of the modal.
Enter recipeId as the name of the parameter
Click Save on the Edit required parameters modal.
Click Done.

Add a Data Resource to the Page

The first thing you’ll do on the new page is set a default value for the required parameter so you can see real data on the page. Click on ** in the URL box and paste **bf86d000113a89107f4444bd6579adb2 into the recipeId input field. If you can’t copy/paste that sys_id you can grab any of the recipe sys_ids and use them.
Next, you’ll add a data resource that uses the sys_id parameter. Click the data icon at the bottom left of the UI Builder window.
Click the +Add icon to the right of Data resource instances to add a data resource to the page.
In the dialog that comes up, search for and select the Look Up Record data resource.
Scroll all the way down in the Look Up Record dialog box and click the Add button.
Now, you’ll need to configure the data resource. Don’t worry about the something went wrong message if that pops up. In the configuration panel, choose the i icon to the right of Look up record.
Change the label and name to:
- Data broker label: Look Up Recipe
- Data broker ID: look_up_recipe
Click Apply.

You can rename most data resources, components, containers, page scripts, etc. in UIB, but data resources are especially important to rename as you will probably end up with multiple on a page, and they are referenced by name in different places.
In the Table property select Recipe [x_snc_recipe_db_recipe].
In the record property you’re going to bind the recipe ID page parameter. Hover over the field and click the Dynamic data binding icon.
After toggling to data binding, enter @context.props.recipeId. This will bind the sys_id from the page’s required parameters to the sys_id property on the data resource.
In the Return fields property add the following fields (one at a time, sorry) by clicking the +Add button, choosing the field, and clicking OK. Rinse and repeat:
- Category
- Directions
- Favorite
- Image
- Information
- Ingredients
- Name
- URL
You’ll see that as you add fields you can see the data returned (and its structure, which is nice) in the data resource preview panel on the right.
Save the page using the Save button at the top right or with CMD/CTRL + S.
Close the data resource panel using the same icon you used to open it.

Now it’s time to connect the data returned in your data resource to the components on the page. You’ll be adding the components using the content panel on the left and configuring them with the configuration panel on the right. The middle of the page will show you a preview.

In the Content panel click + Add Component under Body (Flex) and choose Container.
In the configuration panel on the right, choose the i icon to the right of Container 1 and rename the container:
- Component label: Row 1
- Component ID: row_1
Click Apply.
In the Styles tab below where you renamed the container, set the following:
- Align items (not alignment): Center (this will be the middlemost of the 5 icons)
- Background: Click the + icon and choose Primary 1
Now, you’ll add another container inside your Row 1 container by using the Add component link in the Content panel the same way you did the previous one.
You’ll leave the name of this one alone and set the Maximum width property to 80rem. Depending on the width of your display you may or may not see a difference at this point. This sets a maximum width so the contents will render nicely on a wide screen and not stretch the full page.
Inside of the new Container 1, choose + Add Component.
Search for and choose the Stylized text component.
In the Config panel on the Text property, switch to Dynamic Data Binding and enter @data.look_up_recipe.result.name.displayValue. You should now see the name of the recipe appear in the preview pane.
In the CSS property still on the Config tab, click Edit text CSS.
In the CSS Editor enter { color:white } and click Apply.

Add Components to the Page Body

Click on Row 1 in the content panel, then click on the three vertical dots to the right, choose Add component after, and add another container.
In the configuration panel on the right, choose the i icon to the right of Container 1 and rename the container to the following and Apply:
- Component label: Row 2
- Component ID: row_2
In the Styles tab below where you renamed the container, set the following:
- Align items (not alignment): Center (this will be the middlemost of the 5 icons)
- Padding: Click the + icon and choose Lg (1rem)
- Background: Click the + icon and choose Neutral 2
Now add another container inside of your Row 2 container by using the Add component link in the Content panel the same way you did the previous one.
You’ll leave the name of this one alone and set the Maximum width property to 80rem. Depending on the width of your display you may or may not see a difference at this point.
Inside of that Container 2, add another container.
Set the following styles for the new Container 3:
- Type: Grid
- Spacing: Xxs (0.125rem)
- Columns: 3
- Rows: 1
This container is using the new CSS grid layout introduced in the San Diego release.
Next add another container inside the Grid container you just configured. You should have 4 nested containers starting with Row 2.
Inside the newest Container 4 container add a new component and select the Image component.
Configure its properties as follows:
- Image source: switch to dynamic data binding and enter @data.look_up_recipe.result.image.displayValue
- Fit: Stretch to fit
- Position: Top-Left
Add another container after Container 4 by clicking on Container 4, clicking the 3 vertical dots icon, choosing Add component after and clicking Container. You’ll see how it appears next to the image in the grid layout.
In the new Container 5 set the Margin property to Lg (1rem).
Add a Stylized text component within the Container 5 and set the following properties:
- Text: Ingredients
- HTML Tag: H2
Search for and add a Rich text component after the stylized text component.
Mouse over the Edit html button (which is a property) and toggle to dynamic data binding.
Set the value of the HTML property to @data.look_up_recipe.result.ingredients.value.
Now you’ll add the third container to the grid. Add another container after this most recent container 5 and set the Margin to Lg (1rem).
Similar to the previous component, inside the new container add a stylized text component with the following properties:
- Text: Recipe Info
- HTML Tag: H2
After that stylized text, add a rich text component, switch to dynamic data binding for the HTML property and enter @data.look_up_recipe.result.information.value.
Now you’ll add a container below the grid container that will show the recipe instructions. Click on Container 3, click the 3 vertical dots, click Add component after, and choose Container.
Now add another Stylized text component within that container and configure the following properties:
- Text: Directions
- HTML tag: H2
Now add a Rich text component after the Stylized text component.
After that stylized text, add a rich text component, switch to dynamic data binding for the HTML property and enter @data.look_up_recipe.result.directions.value.

At this point, your page should look something like this.
Save your page and use the Open link to preview the page in the runtime.

Notice that your page also has a header and footer that is added when it is rendered in the runtime. You’ll be updating some of that in exercise 3. Now you’ll move on and create a home page for your app.

Exercise 2 – Build the Home Page

Goal

In this exercise you will build a homepage using the repeater component to show a list of recipes with a button that opens the recipe page you created in exercise 1.

Create the page

From within UI Builder, create a page by clicking on the three vertical dots icon to the right of your current page name (which is Recipe if you’re following directly from exercise 1) and clicking + Create Page.
Name your page Home and click Create.
This page won’t take any parameters so just click Done in the dialog.

Add a Data Resource

Next you’ll add a data resource that will fetch the recipes marked as favorites. Click the data icon at the bottom left of the UI Builder window.
Click the +Add icon to the right of Data resource instances to add a data resource to the page.
In the dialog that comes up search for and select the Look up Records data resource and click Add.

ATTENTION! Make sure you select the Look up Records with an ‘s’ and NOT the Look up Record singular data resource as they’ll behave differently.
In the Data Resource Configuration panel click the i icon and rename the data resource to:
- Data broker label: Look Up Favorites
- Data broker ID: look_up_favorites
Click apply and make sure your data resource is renamed.
Configure the data resource properties as follows:
- Table: Recipe
- Edit conditions: [Favorite] [is] [true]
- Return fields: [Name] [Image] [Sys ID]
Save the page and collapse the Data resource panel.

Add a header

For this page we’ll use two Rows like the previous one. In the content panel click + Add component and add a Container.
In the configuration panel on the right, choose the i icon to the right of Container 1 and rename the container:
- Component label: Row 1
- Component ID: row_1
Choose Apply.
In the styles panel for your Row 1 container configure the following properties:
- Align items: Centered
- Padding: Lg (1rem)
- Background: Primary 1
Now add another Container within Row 1.
Configure the Styles panel by setting the Maximum width to 80rem.
Within that container, add a Stylized Text component and configure its Config properties:
- Text: My Recipe DB
- HTML Tag: H1
- CSS: <Edit text CSS> and enter { color:white } and click Apply.
Go ahead and save the page at this point.

Build the Page Body

Now add another component after your Row 1 component.
In the configuration panel on the right, choose the i icon to the right of Container 2, rename the container to the following, and Apply:
- Component label: Row 2
- Component ID: row_2
In the Styles tab below where you renamed the container, set the following:
- Align items (not alignment): Center (this will be the middlemost of the 5 icons)
- Background: Click the + icon and choose Neutral 2
Now add another container within Row 2 and configure its styles:
- Maximum width: 80rem
- Margin: Click the plus and then change the dropdown to Use CSS Custom Value. Click the three horizontal dots to the right and set Bottom to 3xl (2.5rem)
Add another container inside that one and change the Direction property from Column to Row.
Add a Stylized Text component within that container and set its properties:
- Text: My Recipes
- HTML tag: H3
Your content tree should now look something like:
Now you’ll add another component after Container 3 called a Repeater. Make sure you do this after and not within Container 3.

The repeater component is basically a container that lets you iterate, or repeat, through a set of data in the form of an array.
In the Config tab of the repeater component, use the Dynamic Data Binding icon to switch to binding on the Data array property.
Enter @data.look_up_favorites.results and after a couple of seconds you should see the repeater component in the content tree updated with an icon showing the number of results returned by the data resource.
Click into the Styles tab on the configuration panel and click the Enable styles link. This allows the repeater to act like a container as well, which simplifies things for us.
Configure the repeater styles as follows:
- Type: Grid
- Spacing: Lg (1rem)
- Columns: 4
- Rows: 1
Within the repeater add a Container component.

You will notice that even though the repeater has 5 items, only the first element of the grid has a container. The repeater component does this on purpose to help out with page performance within UI Builder. When the page is rendered in runtime it will show all 5 elements.
Configure the Container as follows:
- Margin: Lg (1rem)
- Background: Primary 0
- Border: * Thickness: Xxs (0.125rem) (this didn’t change) * Type: solid (this didn’t change) * Color: Primary 1 * Radius: Lg (0.5rem) * Shadow: Click the plus icon and leave the Md value
Inside the new Container 4 add a Stylized text component.
Configure its properties as follows:
- Text: <switch to dynamic data binding> @item.value.name.value
- HTML tag: H3
You may have noticed that @item.value.name.value is a different data binding than you’ve used so far. This is specific to the repeater component where item.value refers to the element in the repeater. You may also notice that the data binding within the repeater component doesn’t always autocomplete. That’s why you’re copying and pasting in the his lab.
After the Stylized text component, add an Image component.
Set the Image source property to dynamic data binding and set its value to @item.value.image.displayValue.
After the Image component, add a Button component and set its Config properties.
- Size: Large
- Label: Open
In the Styles tab click the plus on Margin, set it to Use Custom CSS Value, click the three horizontal dots and set Top to Lg (1rem).
Now that the button is styled you need to make it do something. Click the Events tab on the button configuration.
Under the Button clicked click the Add a new event handler link.
Choose the Link to destination Inherited event handler and then click Select destination.
In the Configure navigation model choose App routes > Recipe.
In the recipeId field that comes up, switch to dynamic data binding, enter @item.value.sys_id.value, and click OK.
Click Add.
Save the page and open it in runtime. You should see multiple recipes that you can click into.

Add Favorites Filtering

Now you’ll add a checkbox where you can show only favorites or all recipes in the repeater component.

Back in UI Builder, click the Client State Parameters icon (the one below the data icon you have used) to open the CSP panel.

You can think of client state parameters as the page’s scratchpad where you can define variables and then assign values from event handlers or page scripts.
Click Add and fill out as follows:
- Name: favoritesOnly
- Type: Boolean
- Initial value: true
Collapse the client state parameters panel.
Now add a Checkbox component after the Stylized text 2 component (the one that says My Recipes).
Set its Config properties as follows:
- Label: Favorites only
- Checked: true
In the Styles tab set the Margin to Lg (1rem).
In the Events tab choose Add a new event handler under the Checkbox checked set event.
Choose the Update client state parameter Page level event handler and fill in his properties as follows:
- Client State Parameter Name: favoritesOnly
- New value: <toggle to dynamic data binding> and enter @payload.value
Click Add.
Now use the Add a new event handler under the Checkbox checked set event to add another event handler to that event. This will set the parameter and then refresh the data resource so it uses the new parameter value.
Choose the Refresh event handler under Look up favorites and click Add.
Now use the Data icon to open the Data resource instances panel.
Click into the Look up Favorites data resource and click the Edit conditions property.
Hit the Or button and add [Favorite] [is] [@state.favoritesOnly] (make sure to switch to dynamic data binding) and click Apply.
Close the Data resource instances panel, Save the page, and open it in the runtime. You should be able to uncheck and check the Favorites only checkbox and see more recipes on the page.

Exercise 3 – Theming and Menus

Goal

In this exercise you will upload a new logo, change the colors, add a header menu, and edit some other header settings.

Branding and Theming

First, you’ll change the logo and colors.

From within UI Builder near the top of the UIB window, go to Menu > Edit experience settings.
Click on Branding and Theming and the click Advanced settings. This will open in a new tab.
This should open the UX App Configuration record for the experience. You should see about 8 fields on the form. Find the Landing Path field and change it from the default landing to home. Right-click on the header (or use the hamburger icon at the far left of the ehader) and choose Save.
Now close the UX App Configuration - Recipe DB Config browser tab and return to UI Builder.
Back on the Recipe DB settings page on the Branding and theming tab from step 1, click Open current theme.
This will open the theme record in a new tab. Change the Name field from Light Theme to Recipe Theme and Save the record.
Now you’ll replace the logo. First download the logo file.
Now, click on the Legacy: Experience Theme tab, then mouse over the now-logo-dark UX Theme Asset, then click the little preview icon to the left, and then click the Open Record button on the popup.
On the UX Theme Assets record, click the magnifying glass next to the Asset input. This will open the UX Theme Assets list.
Create a new theme asset by click the New button at the top right of the browser tab.
Fill out the form by entering recipe-logo in the Name field, then click the attachments icon at the top right and attach the RecipeDBLogo.png image you downloaded.
Close out of the attachment modal and click Submit.
Now click Update on the UX Theme Assets record.
Now you’ll update the theme. If the theme field is empty you may be experiencing a known issue with this form, go ahead and click into the theme field, and then use the header icon or right click and choose Reload Form. That should make the existing styles show up.

You’ll see something that may look slightly familiar if you know CSS, except the properties will look different. In UI Builder we’re using CSS custom properties (or theming hooks) to apply CSS.

Now paste the following code into the the theme field:

{
    "--now-form-field--scale-size-block": "2",
    "--now-color--primary-0": "134,237,120",
    "--now-button--bare_secondary--color": "134,237,120",
    "--now-color--primary-1": "03,45,66",
    "--now-button--primary--background-color": "03,45,66",
    "--now-color--neutral-3": "219,219,219"
}

Notice that some of these CSS custom properties match some of what you’ve set in the lab so far.

Click update on the UX Theme record and Update the record.
Now let’s see how the page looks. Go ahead and close out of the Recipe DB settings using the X icon or Cancel button, and then using the Open link to preview the new theme in the runtime. You should notice a new logo and color scheme. If you still see the old logo it may be stored in your browser’s cache. You can do a hard refresh with CMD+SHIFT+R on a mac or CTRL+SHIFT+R on windows.

Header Properties

Now that you’ve themed the portal you need to take care of some of the header settings for your experience. You’ll hide the search box, change the page that loads when the logo is clicked, and change the endpoint for the Report issue button.

First, go ahead and refresh your browser with AES/UIB so you get the new theme colors in UIB.
From within UI Builder near the top of the UIB window, go to Menu > Edit experience settings.
In the General tab, click Advanced settings. This should open the UX Application record in a new browser tab.
Scroll down the the UX Page Properties related list and click on the chrome_header link with the corresponding Required Translations field that starts with [{“message”:”Logout”…

Paste the following into the Value field:

 {
     "privatePage": {
         "searchEnabled": false,
         "userPrefsEnabled": true,
         "currentScreenLinkConfiguration": {
             "roles": [
                 "admin"
             ],
             "position": 250
         },
         "globalTools": {
             "collapsingMenuId": 0,
             "primaryItems": [
                 {
                     "label": "UserMenu",
                     "icon": "user",
                     "type": "menu",
                     "primaryDisplay": "icon",
                     "value": {
                         "children": [
                             {
                                 "label": {
                                     "translatable": true,
                                     "message": "Settings"
                                 },
                                 "position": 100,
                                 "type": "navigation",
                                 "value": {
                                     "type": "route",
                                     "value": {
                                         "route": "settings",
                                         "fields": {}
                                     }
                                 }
                             },
                             {
                                 "label": {
                                     "translatable": true,
                                     "message": "Logout"
                                 },
                                 "position": 500,
                                 "type": "navigation",
                                 "value": {
                                     "type": "AUTH_ROUTE_BINDING",
                                     "binding": {
                                         "address": [
                                             "logout"
                                         ],
                                         "params": {
                                             "reload": true
                                         },
                                         "default": "/logout.do"
                                     }
                                 }
                             }
                         ]
                     }
                 }
             ],
             "secondaryItems": []
         }
     },
     "publicPage": {
         "menuEnabled": true,
         "logoRoute": {
             "type": "route",
             "value": {
                 "route": "home",
                 "fields": {}
             }
         },
         "searchEnabled": false
     }
 }

This will have hidden the search box and changed the logo link. Feel free to test in the runtime to see changes.

Next, open the chrome_menu_actions UX Page Property and replace the Value field with the following:

 {
     "label": {
         "translatable": true,
         "message": "New Recipe"
     },
     "value": {
         "route": "catalog",
         "fields": {
             "sysId": "4d71937d1b3ec5500ef897941a4bcbcc"
         }
     }
 }

This will change the report issue button to a New Recipe button and point it to the Record Producer (using the sysId property) that creates a new recipe.

Click Update.

Lastly, we’ll change the menu structure. Open the chrome_menu UX Page Property and paste the following JSON into the Value field:

 [
     {
         "value": {
             "label": {
                 "translatable": true,
                 "message": "Home"
             },
             "target": "",
             "type": "route",
             "value": {
                 "route": "home"
             }
         }
     },
     {
         "value": {
             "label": {
                 "translatable": true,
                 "message": "Recipe Tools"
             }
         },
         "children": {
             "items": [
                 {
                     "value": {
                         "label": {
                             "translatable": true,
                             "message": "Food.com Measurement Converter"
                         },
                         "type": "external",
                         "rightIcon": "open-link-fill",
                         "value": {
                             "href": "https://www.food.com/library/units-converter"
                         }
                     }
                 },
                 {
                     "value": {
                         "label": {
                             "translatable": true,
                             "message": "NY Times Cooking Substitutes"
                         },
                         "type": "external",
                         "rightIcon": "open-link-fill",
                         "value": {
                             "href": "https://cooking.nytimes.com/guides/79-substitutions-for-cooking"
                         }
                     }
                 },
                 {
                     "value": {
                         "label": {
                             "translatable": true,
                             "message": "Baking Conversion Chart"
                         },
                         "type": "external",
                         "rightIcon": "open-link-fill",
                         "value": {
                             "href": "https://www.kingarthurbaking.com/learn/ingredient-weight-chart"
                         }
                     }
                 },
                 {
                     "value": {
                         "label": {
                             "translatable": true,
                             "message": "Cake Pan Converter"
                         },
                         "type": "external",
                         "rightIcon": "open-link-fill",
                         "value": {
                             "href": "https://www.bakinglikeachef.com/cake-pan-converter/"
                         }
                     }
                 }
             ]
         }
     },
     {
         "value": {
             "label": {
                 "translatable": true,
                 "message": "Recipe Sites"
             }
         },
         "children": {
             "action": {
                 "label": {
                     "translatable": true,
                     "message": "New Recipe"
                 },
                 "type": "route",
                 "value": {
                     "route": "catalog",
                     "fields": {
                         "sysId": "4d71937d1b3ec5500ef897941a4bcbcc"
                     }
                 }
             },
             "items": [
                 {
                     "value": {
                         "label": {
                             "translatable": true,
                             "message": "Brad's favorites"
                         }
                     },
                     "children": {
                         "action": {},
                         "items": [
                             {
                                 "value": {
                                     "label": {
                                         "translatable": true,
                                         "message": "Grilling and BBQ"
                                     }
                                 },
                                 "children": {
                                     "action": {},
                                     "items": [
                                         {
                                             "value": {
                                                 "label": {
                                                     "translatable": true,
                                                     "message": "AmazingRibs"
                                                 },
                                                 "type": "external",
                                                 "rightIcon": "open-link-fill",
                                                 "value": {
                                                     "href": "https://amazingribs.com/"
                                                 }
                                             }
                                         },
                                         {
                                             "value": {
                                                 "label": {
                                                     "translatable": true,
                                                     "message": "HowToBBQRight"
                                                 },
                                                 "type": "external",
                                                 "rightIcon": "open-link-fill",
                                                 "value": {
                                                     "href": "https://howtobbqright.com/"
                                                 }
                                             }
                                         },
                                         {
                                             "value": {
                                                 "label": {
                                                     "translatable": true,
                                                     "message": "Vindulge"
                                                 },
                                                 "type": "external",
                                                 "rightIcon": "open-link-fill",
                                                 "value": {
                                                     "href": "https://vindulge.com/"
                                                 }
                                             }
                                         }
                                     ]
                                 }
                             },
                             {
                                 "value": {
                                     "label": {
                                         "translatable": true,
                                         "message": "Other"
                                     }
                                 },
                                 "children": {
                                     "action": {},
                                     "items": [
                                         {
                                             "value": {
                                                 "label": {
                                                     "translatable": true,
                                                     "message": "Americas Test Kitchen"
                                                 },
                                                 "type": "external",
                                                 "rightIcon": "open-link-fill",
                                                 "value": {
                                                     "href": "americastestkitchen.com/recipes"
                                                 }
                                             }
                                         },
                                         {
                                             "value": {
                                                 "label": {
                                                     "translatable": true,
                                                     "message": "Dinner at the Zoo"
                                                 },
                                                 "type": "external",
                                                 "rightIcon": "open-link-fill",
                                                 "value": {
                                                     "href": "https://www.dinneratthezoo.com/"
                                                 }
                                             }
                                         }
                                     ]
                                 }
                             }
                         ]
                     }
                 },
                 {
                     "value": {
                         "label": {
                             "translatable": true,
                             "message": "SNDevs Favorites"
                         }
                     },
                     "children": {
                         "action": {},
                         "items": [
                             {
                                 "value": {
                                     "label": {
                                         "translatable": true,
                                         "message": "SNDevs Favorites"
                                     }
                                 },
                                 "children": {
                                     "action": {},
                                     "items": [
                                         {
                                             "value": {
                                                 "label": {
                                                     "translatable": true,
                                                     "message": "Serious Eats"
                                                 },
                                                 "type": "external",
                                                 "rightIcon": "open-link-fill",
                                                 "value": {
                                                     "href": "https://www.seriouseats.com/"
                                                 }
                                             }
                                         },
                                         {
                                             "value": {
                                                 "label": {
                                                     "translatable": true,
                                                     "message": "Smitten Kitchen"
                                                 },
                                                 "type": "external",
                                                 "rightIcon": "open-link-fill",
                                                 "value": {
                                                     "href": "https://smittenkitchen.com/"
                                                 }
                                             }
                                         }
                                     ]
                                 }
                             }
                         ]
                     }
                 }
             ]
         }
     }
 ]

It’s a lot of JSON, but that will recreate the menuing with the structure we want for the portal.

Click Update and then close the tab. Go back and test the page in the runtime. Click through the menus and buttons and see what’s changed.

Exercise 4 – Enhance the Home Page

Goal

In this exercise you will add a typeahead search field to the homepage. There are a few different ways to add search to your experience, but in this lab you’ll use the typeahead search component.

Add a client state parameter

Make sure you’ve got the Home page opened in UI Builder. Click on the Client State Parameters icon to open the CSP panel.
Use the +Add button to to create a new client state parameter as follows:
- Name: searchFilter
- Type: String
- Initial value: <Leave empty>

Add a Data Resource

Use the *Data resource icon to open the *Data resource instances panel.
Use the +Add button to add a new data resource.
Search for and add the Look Up Records data resource.
Rename it to:
- Data broker Label: Look Up Recipes
- Data broker ID: look_up_recipes
Fill out the data resource properties as follows:
- When to evaluate this data resource: Only when invoked (explicit
- Table: Recipe [x_snc_recipe_db_recipe]
- Edit conditions: [Name] [contains] <switch to dynamic data binding> [@state.searchFilter]
- Return fields: [Name] [Category] [Image] [Sys ID]
- Order by: Name
Close the date resource panel and Save the page.

Add the Typeahead Search Component

At this point you have a data resource that filters the name based on the value in the searchFilter client state parameter. We just need to set that parameter and then bind the results of the search to the dropdown.

In the content panel, find the Stylized text 1 component in Row 1 and add a Typeahead component after the stylized text.
Configure its properties as follows:
- Label: <clear out the label>
- Placeholder text: Search Recipes
You’re going to script the Items property, so mouseover that property and use the <\/> icon (next to dynamic data binding) to open the Edit scripted property value modal.

Paste the following script into the modal. This will convert the data returned by the data resource into an array with a format that the property is expecting.

 function evaluateProperty({api}) {
     const data = api.data.look_up_recipes.results;
     return data.map(e => ({
         id: e.sys_id.value,
         label: e.name.value,
         sublabel: e.category.displayValue,
         avatarProps: {
             userName: e.name.value,
             imageSrc: e.image.displayValue
         }
     }));
 }

Click Apply
Now click into the Styles tab for the Typeahead component and set the Background property to Neutral 1.
Lastly, you’ll need to add some event handlers so click on the Events tab.
Add a new event handler to the Typahead value set event and choose Update client state parameter under Page-level event handlers and configure it:
- Client State Parameter Name: searchFilter
- New Value: <switch to dynamic> @payload.value
Click Add.
Now add another event handler under that one to Refresh the Look Up Recipes data resource and click Add.
You still need to configure what happens when someone chooses something from the dropdown, but go ahead and Save the page and test it in runtime.
Now you need to open that recipe when it is clicked. Go back into UI Builder and add an event handler to the Typeahead selected item set event and choose Link to destination.
Use the Select destination button to open the configure navigation modal.
Choose the Recipe App route, change recipeId to dynamic data binding and enter @payload.item.id.
Click OK and then Apply.
Save the page again and test it in the runtime. When you search for and click on a recipe it should take you to that recipe.

Exercise 5 – Enhance the Recipe Page

Goal

In this exercise you will add a go to recipe button and favoriting to the recipe page.

Add a Go to Recipe Button

Switch from the homepage to the recipe page.
The first thing you need to do is change Container 1 (inside Row 1) to flex items in a row rather than a column. Click Container 1 in the content tree and in its Styles tab, change direction from Column to Row. Also set the Align items property to center vertically.
Now add a Button component after the Stylized text 1 component in Row 1.
First, you’re going to set the visibitlity on the button. Not all recipes have an external url and this button should only show up for those that do. In the configuration panel to the right of Button 1 click the eye icon.
In the Hide component property that comes up (notice it’s already set to dynamic data binding) enter EMPTY(@data.look_up_recipe.result.url.value). This is a formula (introduced in the San Diego release) that tests whether the value is empty and returns a true instead of false. If it’s empty it returns true and the button is hidden.
Set other properties as follows:
- Label: Go to Recipe
- Icon: Arrow Up Right Fill
In the button’s Styles tab, set its Padding to Lg (1rem).
Now click into the Events tab and add an event handler to the Button clicked event.
Choose Link to Destination and click Select Destination.
In the modal, choose External URL and dynamically bind @data.look_up_recipe.result.url.value to External URL.
Click OK and Add.
Save the page and test it. Find a the Mom’s Pork Tenderloin recipe and make sure the button doesn’t show up for that and that your condition is working.

Add favorites

Now that the open recipe button works, you’ll add favoriting.

Open the data resources panel and add an Update Record new data resource.
Rename it to Update Recipe and then close the data resources panel.
Add a Button iconic component before the Go to Recipe button you added.
Use the eye icon again to set the new button’s visibility to hide the component using IF(@data.look_up_recipe.result.favorite.value, true, false).
Set its properties:
- Icon: Heart Outline
- Size: Large
- Padding: Show
- Tooltip text: Mark as favorite
Add an event handler to the button iconic’s event.
Choose Execute under Update Recipe and configure the form:
- Table: Recipe
- Record: <dynamic data binding> @context.props.recipeId
- Edit field values: [Favorite] [is] [true]
Click Apply and then Add.
Add another event under that one to refresh the Look Up Recipe data resource.

This will set the favorite field on the recipe record to true when it is clicked and then refresh the data resource on the page so the visiblity changes on the button.
Now add another Button iconic component after the last one. This one will show when the recipe is already a favorite.
Set its visibility to hide the component using IF(!@data.look_up_recipe.result.favorite.value, true, false).
Set its properties:
- Icon: Heart Fill
- Size: Large
- Padding: Show
- Tooltip text: Unmark as favorite
Add an event handler to the button’s event.
Choose Execute under Update Recipe and configure the form:
- Table: Recipe
- Record: <dynamic data binding> @context.props.recipeId
- Edit field values: [Favorite] [is] [false]
Click Apply and then Add.
Add another event under that one to refresh the Look Up Recipe data resource.
Save the page and test it. Try marking and unmarking some favorites. Is it reflected on what shows up on the homepage?

Conclusion

I hope you learned a little something about UI Builder and how it can be used to create small, targeted, custom portal experiences for custom applications.

You learned how to use UI Builder to open a starter portal experience created from App Engine Studio to build a front-end to make it easier to interact with the application. You touched a number of different parts of UI Builder while you created the custom experience including, but not limited to:

Creating new pages
Page parameters
Data resources
Client state parameters
Client scripts
Configuring components
Using the new repeater component
Using the new formular editor
Updating ServiceNow records from the experience
Theming and branding
Building custom menus

For more information on UI Builder and the Next Experience UI Framework visit out Next Experience COE and don’t hesitate to reach out on LinkedIn or SNDevs slack (@btilton).

Challenge Exercises

Goal

There are a couple of challenge exercises associated with this lab. They will not be as step by step as the entire lab (hence the challenge), but there is a completed version of the app available.

Challenge 1 - Add an edit recipe page

There already exists a record page template you can use. Create a new page using the Record Page template and select the Copy template contents (fully customizable) radio button. This will let you customize the new page when it’s created. You’ll also need to create a couple of page parameters called table and sysId that take the table name of the recipe table and the sys_id of the recipe record being shown.

Super Challenge 2 - Add Notes to the Recipe Page

There is a journal field on the recipe record called Notes. UI Builder doesn’t support journal fields very well at the moment so you’ll need to create a transform data resource that pulls journal entries that can be displayed on the page. The UI Builder - Data Resources blog post may be helpful to use as a reference.

Appendix

Setting up your PDI for this lab

To learn how to request, access, and manage your Personal Developer Instance, check out this Guide.

Download and install the app from this Update Set:
- RecipeDB_BaseAppDatav1.2.xml
Follow Steps 2a-e in this Share Guide to learn how to import and install an Update Set.

Finished App

You can find an update set with this lab complete through the likes section of the challenge exercise at RecipeDB_CompletedAppv1.0.

Github Info

You can also find the base application, completed exercises, and the completed app at this github repo: https://github.com/ServiceNowNextExperience/killer-experience-lab-22. You can fork the repo and import the app into your instance. This Github Guide may be useful if you’re not familiar with this process. This is an alternative to using update sets.

Building a Killer Experience with UI Builder

Goal

(Optional) Pre-flight check

Exercise 0 - Get Familiar with the Recipe DB App

Goal

Exercise 1 – Build the Recipe Page

Goal

Open UI Builder

Create the page

Add a Data Resource to the Page

Add Components to the Page Header

Add Components to the Page Body

Exercise 2 – Build the Home Page

Goal

Create the page

Add a Data Resource

Add a header

Build the Page Body

Add Favorites Filtering

Exercise 3 – Theming and Menus

Goal

Branding and Theming

Header Properties

Exercise 4 – Enhance the Home Page

Goal

Add a client state parameter

Add a Data Resource

Add the Typeahead Search Component

Exercise 5 – Enhance the Recipe Page

Goal

Add a Go to Recipe Button

Add favorites

Conclusion

Challenge Exercises

Goal

Challenge 1 - Add an edit recipe page

Super Challenge 2 - Add Notes to the Recipe Page

Appendix

Setting up your PDI for this lab

Finished App

Github Info