This article gives some information on how to edit minor features of Out of the Box widgets in the Service Portal. It mainly covers how to add or remove UI elements based off of existing data and how to manipulate the data if needed. It should help with questions like How to add more field information to a widget, How to remove an unwanted button, or How to change the order or length of something in a widget.
NOTE: Many of the suggestions in the article require a cloned version of a widget and those changes will not be supported.
The first step you can take when trying to change the behavior of a widget is to Edit the Instance Options to see if one of the Out of the Box options will achieve the desired result.
If there is not an Out of the Box Instance Option that will change the behavior in a way you need, you will need to Clone and Edit the Widget HTML.
If the data is not available in the widget you may need to Manipulate the Widget Data.
I am going to use a simple OOB widget "KB Top Rated" as an example, but the same steps can be taken with most widgets to achieve similar basic changes.
Edit the Instance Options
Instance options make a widget configurable so you can have the same widget multiple times but have it behave in different ways. (Documentation)
In our example, if you wanted to change the title of the KB Top Rated widget from "Top Rated Articles" to something Like "Most Helpful Knowledge" the first place to check is in the Instance Options. You can see these by Ctrl + Clicking on the widget and selecting Instance Options.
You can set the Title option to "Most Helpful Knowledge" and it will change the title of the widget.
NOTE: At this point, you will be making a customization so the edited widgets will not be supported by Service Now and if you face issues with those widgets, you should first confirm the same issue is happening with the OOB version of the widget.
Clone and Edit the Widget HTML
When trying to change the behavior or look of a widget, you need to identify the HTML that you want to change within the widget template and if needed identify any data you need from the scope. You can do this using your browser's Dev Tools Such as the Chrome Dev Tools and the HTML template of the widget.
Our example will be adding the Article View Count to the KB Top Rated widget between the Article Description and the Article Rating.
1) Inspect the HTML of the widget on the page.
Right-click the area or text you need to change and select Inspect to open up the Elements panel in you Dev Tools and focus on that element.
Inspecting the element should result in something similar to this screenshot.
2) Identify the HTML you need to change.
In our example, we can see that the what we want to change is within the <li> tags which represent the article item and need to add something between the <a> which is the Link / Description and the <div> which is the Rating.
3) Compare this to the HTML of the widget in the Widget Editor.
Since the widget HTML is a template, it might not exactly compare with what we see when Inspecting, but an understanding of the angular directives (Quick Reference) and how we load data from scope should help to easily compare the widget HTML code to the HTML that we see when Inspecting the widget.
If we check the HTML in the Widget Editor we see the same <a> and <div> tags within the <li>.
4a) If you are just trying to remove something from the widget, you can delete the corresponding HTML from the template and you are finished!
4b) If you need to add something to the HTML, you should identify the related data object in the HTML template.
In our example widget, we have this line of code inside the <li> tag:
ng-repeat="a in ::data.articles"
We can see that the data for each article is being referenced as "a" within each item and the array which is being used to populate the "a" objects is data.articles. This data.articles is coming from the Server Script of the widget.
5) Check the available data in scope using 'Log to Console'.
To find what values are available within the "a" data object once the widget is loaded into the page we can Ctrl + Click the widget and select Log to console: $scope.data.
Then if we switch to the Console tab of our browser Dev Tools we can expand the data object to find the articles array and see the values available within each item.
Here we see the view count is referenced within each article as sys_view_count.
6a) If the data you need is not there you need to Manipulate the Widget Data (see below).
6b) If the data is there, edit the HTML template of the widget to use that data.
From checking the scope, we know we can get the view count using "a.sys_view_count" within the <li> of our template. So we can add a new <div> with that data and a hard coded string "Views:" between the existing <a> and <div>in our widget HTML Template.
If we refresh the page we can see the view count for our article.
Manipulate the Widget Data
If you need to add something that was not already there in $scope.data, you need to edit the Server Script or Client Controller of the widget to manipulate the data before you can change the HTML.
Our example will be adding the Article Author even though it is not available within the scope of the Out of the Box widget.
1) Find where the data within scope are being set.
When a widget is being loaded, we evaluate the Server Script first and then run the Client Controller, so to identify what is setting the data we should work backward and check the Client Controller first to see if it is changing the data at all then check the server script which is normally what gathers the data. In our case, the Client is not manipulating the data at all so we move on to the server script.
2) Identify what code is specifying the values.
In our example, the Server Script uses two methods for gathering data.
- The first is $sp.getRecordValues() (Documentation) on line 16 which gets most of the article fields.
- The second is getDisplayValue() on line 17 called on the GlideRecord object "z". This is setup using a GlideRecord query earlier in the script.
3) Edit the code to get the new data needed.
Because we need the Display value of the Author instead of the DB value (which is a sys_id) we need to mimic the second method call.
a.author = z.getDisplayValue("author");
4) Edit the HTML as described above to use the new data value.
We can use "a.author" in our HTML like this.
NOTE: If we were getting some other field values such as the article type we could edit the getRecordValues() call and specify which fields we want to end up in our array like this.
$sp.getRecordValues(a, z, 'short_description,sys_view_count,sys_id,published,rating,type'); <-- added type to the list of fields we want to end up in data.articles.
As mentioned before, cloning a widget and making changes is a customization. So if you face issues with the widget in the future, you should first check that the same issue is there in the OOB widget before reaching out to support.
This article explains how to check against the OOB widget. KB0683868
Also, you can check out our Widget Troubleshooting Guide for ways to investigate issues with customizations to a widget.