How to setup a type-ahead search in UI Builder

[Daniel Draes]

With the Quebec Release we have unleashed our new powerful tool to create great user experiences called UI Builder. I hope you have already seen bits and pieces of as we will gradually enhance and build on this in the coming releases.  

As powerful as UI Builder is, it also poses a steep learning curve even for seasoned ServiceNow admins. Not because it is incredibly hard to use, but the concepts underneath are quite a bit different from traditional development in ServiceNow. The strict separation of UI components from data elements and business logic takes some time to get used to.  

Lately, I am working with a customer on the forefront of adopting this new cool technology raising lots of questions. One I found particularly interesting had a big growth opportunity for me and needs a few elements to play together is this one:  

 

Requirement: On a new UX page we need an input field to search and select a user record, to allow a great user experience we want to utilize a type-ahead search like experience we all know and love from Google and the likes.  

Solution: 

As you can imagine by me writing a blog on this, the solution was not as straight forward as I would have imagined. But with some easy-to-follow steps it is not difficult at all. Here we go…  

  

We need the following elements to play together:  

Component: Type ahead search  

This is the UX element rendered on the page and handling the user interactions of typing and selecting. However, it does not come with any link to a data source / table. We need to wire this up.  

Data resource: Lookup Records  

This will handle the database query to find relevant records. We need to fire this query with every character typed in the UI component to update the UI relevant results.  

Client State Parameter: Query String  

The data source needs some form of dynamic query string, best place to store it is in a client state parameter.  

 Client Script: Update Query  

Whenever the user types something into the search component we need to update the search query to get the relevant results. A client script listening to user actions will get us going.  

  

Let's build it from ground up.  

• Open UI Builder by navigating to Now Experience Framework > UI Builder in your navigator  
  
  
• Click Create experience in Platform 
  
  
• Click New 
  
  
• Set the properties as followed:

Title	Type ahead search
Page	UI Builder
App Shell UI	Portal App Shell
URL Path	searchexample
Admin Panel	new record 'type ahead search admin panel'

• Go back to the UI Builder tab and refresh it, your new experience should now be listed, select it    
  
  
• Click Create a page, name it search and select no template
  
  
• Close the success dialog  
    

Now we start putting our content on the page.  

  

• Click Add component in the center of the stage area and select Container  
  
  
• Note: You should always add a container before placing components. This allows a more flexible placement of objects on the page.  
    
• Click Add component (+ sign) in the new container and search for Typeahead. 
  Great, our type ahead is placed and visible. We will wire it up later.  
  
  
  
  
• On the bottom left click the icon for Client State to open the configuration panel of client state parameters  
   
  
  
  
• Click +Add on the header row of that panel to create a new client state, enter these values:  
  
  

Name	user_query
Type	string
Initial Value	<empty>

• On the bottom left click the item for Data to open to data resource configuration panel  
  
  
  
  
• Click +Add on the header row to create a new data resource  
  
  
• Search for the data resource named Look Up Records and click Add 
  
  
  
  
• Once the data resource has been added, configure it like this:  

When to evaluate	Only when invoked	We do this as we want to avoid loading the whole table without a filter on page load
Table	User (sys_user)
Conditions	@state.user_query	Switch to a data binding and select the previously create client state.
Return fields	Name, User ID, Email	You may choose to add more like image if you want, a little late you will see how to make them visible.
Order By	Name
Max Results	10	no need to show more, rather the user should be entering more characters to limit search results.

• On the bottom left click the item for Client Script to open the script configuration panel  
  
  
    
• Click +Add on the header row to create a new client script  
    

Script Name	Refresh Results
Script	/**    * @param {params} params    * @param {api} params.api    * @param {any} params.event    * @param {any} params.imports    */   function handler({api, event, helpers, imports}) {       api.setState('user_query', 'active=true^nameSTARTSWITH' + event.payload.value);       api.data.look_up_records_1.refresh();   }

Note: Check the name of your data resource as you might need to change api.data.look_up_records_1 in that script to match your setup.  

  

As you can see, we build the Glide-Query in this script using the payload value which contains the characters entered by the user. In this example I am only looking in the beginning of the name field in the user table. You can modify this query to use contains or a combination of looking in multiple fields with OR queries.  
  

• Close the bottom panel by clicking again on the Client Script icon to make more room for the stage area. 
    
• If not yet selected, select your typeahead component on the stage or in the component browser on the left. 
    
• Open the configuration panel on the right and select the Events tab. 
    
• Expand the 'Typeahead value set' event and click +Add a new event handler. 
    
• Find the new Script Refresh results and select it, click Add. 
  This will instruct the component to trigger our script with every value change (character typed)  
    
  
   
• Last step, we now need to get the query result to display as drop down as the user types.  
  Open the Config tab and find the Items element. 
    
• The format received by the data source unfortunately does not match the JSON structure you can see here. We need to add a piece of magic. Change the binding to a scripted property value and enter this script:  

/**   
 * @param {params} params   
 * @param {api} params.api   
 * @param {any} params.imports   
 */  
function evaluateProperty({  
    api   
}) {   
  const data = api.data.look_up_records_1.results;   
  return data.map(e => ({   
    id: e.user_name.value, 
    label: e.name.value,   
    sublabel: e.email.value   
  }));   
}  

 

Note: Check the name of your data resource as you might need to change  api.data.look_up_records_1 in that script to match your setup.  
  

This script will convert the JSON from the data source to a JSON the display component understands. Here is also where you would be able to add some extra fields. Check out the docs and examples available for more information.  

• Save your page 

Thats it, we are done. The component is now wired up and ready to use.