How to Jumpstart Your Custom UI Builder Component Development

by Jake Laux and Freddy Reza

Have you ever experienced the frustration of forgetting how to do simple tasks when building custom components in the Now Experience UI Framework? We at esolutionsONE have encountered this a number of times. If you're a ServiceNow Developer, chances are you've experienced the same struggle. In this article, we'll walk you through the essential steps to help you regain your confidence, whether you're a beginner or just need a refresher.

PREREQUISITES

We faced issues with users attempting to use the component without certain prerequisites, notably Python3, which is no longer included in recent MacOS versions.

Prerequisites for our example component:

Installations for these can also be found in the Prerequisites section of the readme on the GitHub repository here.

THE COMPONENT

If you have used the REST API Explorer from your instance, our component might seem familiar! Our goal was to build a simple component that encompasses everything you might need to start building custom components and help for testing purposes. It allows the user to choose the kind of REST request they want to make and what table to pull data from. If the request is successful, the response will be displayed at the bottom. Very simple.

OUR GOAL

Taking an iterative approach, we wanted to build something that can help those interested in developing custom components and provide them with resources and examples of how to do simple tasks like making REST requests or setting up similar file structures to what we made. We hope this component becomes a reference if you don’t quite remember how to set up your Action Handlers or configure your properties for UI Builder.

HOW IT WORKS

We won't dive into the granular details of how it all works here (but hey, if you're interested in an in-depth exploration, feel free to check out the GitHub Repo). Instead, we'll focus on the most important pieces that will be in almost any component you want to build: Action Handlers, a View, and Properties.

ACTION HANDLERS

Let’s first talk about how we are using Action Handlers. If you want a quick tutorial on how Actions and Action Handlers work, check out our other creator-DNA article by Nick Allen, covering it here. The first action being dispatched is ‘GET_USER’, which occurs on bootstrapping of the component.

This action is received by the corresponding action handler, which uses the object sent in the dispatch to make the REST request. If the request is successful, it will run the ‘successActionType’ called ‘SET_USER_ID’.

‘SET_USER_ID’ will take the results from the request and update the state variable ‘user’ with the user information we got.

This is the simplest version of a REST call that we make in this component and can be easily added to any component.

VIEW

Next, let’s talk about what is happening in the main index.js where the view exists. If you are not too familiar with React, you might wonder what is going on with these weird HTML elements being used throughout the main index.js file. Below is an example of what I am talking about.

We wanted a good example of creating and using a child component. In the image above, you will see the component being used in different places with different props being passed down. This is standard practice when it comes to React components. The “Path,” “Display Field,” and “Query” are all using the same TextInput component.

Below you can see what makes up the component, which is made up of a

You can find more examples like this in our component to reference how components and props are used.

CONFIGURING PROPERTIES

Finally, let us talk about Properties and how we configured ours. We couldn’t find a clear example in the documentation for building custom components on how to configure properties similar to those in UI Builder. The docs show how to initialize them (see image below) in your main index but not how to make them configurable in UI Builder.

Once the properties are initialized, they need to be configured in the now-ui.json file; this is where you will link the properties you created in your main index.js file to UI Builder. In the image beneath, you will see how each property is a JSON object with specific keys.

If we look at the title property, it gives the simplest example of how to configure a text input from UI Builder.

Using the Config section of the component, once deployed to an instance, you can see all the properties we configured in the now-ui.json file.

It is important to note that our approach to creating these components involved mimicking the property configuration of an existing component. To accomplish this, we explored the sys_ux_macroponent.list and examined the properties utilized by specific components within UI Builder. We will provide a detailed, step-by-step example of how to perform this process in an upcoming article release. Please stay tuned for more information.

CONCLUSION

In conclusion, we have examined several critical aspects of the Rest API Explorer component that we developed and discussed the process behind each component. The Action Handlers, the view, and the properties all play crucial roles and can sometimes present challenges. Our intention is for you to utilize this component to enhance your comprehension of building your components, thus bypassing the need for extensive trial and error that we encountered.