So You Want a Client-Side “Script Include?”

Script Includes help us employ the DRY method – “Don’t Repeat Yourself.”

If you’re familiar with the concept of ServiceNow Script Includes you probably know that these are server-side scripts that allow you to have a library of re-usable methods that can be accessed from any Client Script using Ajax or any server-side script. Creating Script Includes allows us to employ the programming concept known as DRY – or “Don’t Repeat Yourself.” In the DRY method, the idea is to never write the same code more than once. If we find ourselves writing the same code more than once, we should put that code somewhere where any code can access and use it.

Implementing the DRY method in ServiceNow for server-side code is pretty straightforward using Script Includes, but I found that I really needed a way to reduce duplicating the same code in client-side scripts. I could write and have written GlideAjax client-side code to access common code in a Script Include, but I was pretty sure there was a client-side way to do this.

“Hey Rick, I need something like this for client side too! How’d you do that?“

I’m glad you asked. I found that UI Scripts are just the ticket. I struggled a bit to understand how to create them then access them in a client-side script.

This post is here to show you what I learned and how I’m now using UI scripts to be able to create and use a client-side “Script Include” using the UI Script and effectively employing the DRY method in ServiceNow’s client-side scripting.

Here was my real-world problem.

On a single form, I needed:

• to set the value of a single field,
• but that value depended on the values selected in 3 other separate fields.

This meant I needed to create 3 onChange client scripts to capture the values of each of these 3 fields whenever the value changed. Then, based on not only the value that changed, but the value in those other 2 fields, I needed to implement logic that used the value in all 3 fields to set the value of the one other field.

a direct and flagrant violation of the DRY method

This meant that I would have to have the same code in all 3 of those onChange client scripts — a direct and flagrant violation of the DRY method. If I kept the same code in all 3 client scripts, I would have to update all 3 client scripts each and every time any code changed…this would have created some serious code maintenance headaches.

The Solution? A client-side “Script Include” — or a UI Script.

Creating a UI Script meant I was able to take that logic I was duplicating in 3 onChange client scripts and drop it into a UI Script then call the UI script from each of the onChange client scripts. All the logic and setting of form field values is done in the UI script and all I needed to do in each of the client scripts was call the UI Script method and pass a single parameter.

Here’s what I needed to learn:

1. How are UI Scripts created and formatted in a scoped application?
2. How are UI Scripts called from client-side code in a scoped application?
3. How are form values updated using UI Scripts in a scoped application?

Buckle up … here we go.

1. How are UI Scripts created and formatted in a scoped application?
   • The first thing I figured out is that there are 2 parts to UI Scripts:
     • The public API (what is called from within the client script)
     • The private functions (called from the public API and what does all the work).
   • Creating the UI Script:
     • Enter UI Scripts in the Filter navigator
       • In the list view, click the New button at the top
     • Filling out the UI Scripts form:
       • Script Name: Enter a name with no spaces. When you enter a name it becomes the function name in the Script section.
       • API Name: Read-Only – this will auto-populate with scope name and Script Name with a period in between each (scope_name.scriptName).
       • Active: Check this box if not already checked.
       • UI Type: Choose if it’s:
         • Desktop: only used in the normal UI
         • Mobile / Service Portal: only if used in mobile or service portal.
         • All: if used in either of the above.
       • Description: Enter a description to help any other developers understand what this is used for.
       • Script: This will be pre-populated with a basic structure once the Script Name is entered. The script has two parts:
         • The private functions (called from the public API and what does all the work). In this area you’ll see functions that are formatted like: function _functionName(){}
           • Often the private functions are named with a single underscore in front of the function name to denote a private function.
         • The public API (what is called from within the client script): In this area you’ll see functions that are formatted like: functionName: function() {}. The script section after the return {} is the public API area.
     • Writing code in the Script section.
       • The private functions are the workhorses of the UI Script — they do all the work. These are called from the Public API section of the UI Script and are formatted: function _functionName() {}. So if we wanted to make an alert pop on your form, the private function might be something like this:
         • function _magicAlert(alertMessage) {
           // set a default alertMessage if one is not passed in
           if (typeof alertMessage == ‘undefined’) {
           alertMessage = ‘Awesome – this is an alert.’;
           }
           alert(alertMessage);
           }
       • The Public API is what gets called from the client script. These call the private function. The format is functionName: function() {},. To access the private method above, the Public API function would be something like this (NOTE: the trailing comma is required):
         • showAMagicAlert: function(alertMessage) {
return _magicAlert(alertMessage);
},
2. How are UI Scripts called from client-side code in a scoped application?
   • There is a specific format for calling a UI Script from a client-side script. Calling the UI Script requires the full API Name contained in the UI Script’s form. This is how to call the showAMagicAlert function above:
     • ScriptLoader.getScripts('scope.UIScriptName.jsdbx', function(){
scope.UIScriptName.showAMagicAlert('Wicked Awesome Alert Message');
});
   • Here are specific things to pay attention to in the above call.
     • Use the ScriptLoader.getScripts(‘APIName.jsdbx’, function() {}); API method.
     • Pass in the UI Script’s API Name plus a period then ‘jsdbx’ as the first parameter of the getScripts() call
     • Inside the getScripts() method’s function() {}, pass in the specific Public API function name
     • And that’s it!
3. How are form values updated using UI Scripts in a scoped application?
   • This part is straightforward. In the private function, you can use the g_form API to set form field values. The UI Script is loaded and available from the client side so all that is needed to set a value of a field is a g_form.setValue() call. This blog article doesn’t cover the logic behind determining how to set values, but any logic you typically would write in a client-side script can be written here.