Widget Instance Options in Service Portal
With Lauren Toomey
In this article, we will cover widget instance options. Why are widget instance options good? Why do you want to use them in your custom widgets? Let's imagine that our customer wants a widget on their homepage that is easily edited. They want to be able to change things, like the link, description, and the title, to whatever information is most relevant to their user at that time — maybe they want to update it for holidays or different times of the year. You don't want them having to go into the code to change those types of things, so we add in widget options.
Creating a Widget
The widget added is going to fill our requirements (refer to 1:005 the video to view the widget that was added). The widget has a title, a short description, and a button. If we click this button, it'll go somewhere, but we don't have a URL yet, so it's not going anywhere. When we Ctrl + right-click and open the instance options, you'll see that this is what our user is going to be able to change without having to go into the code.
They can change the title to say catalog, change the button to say go to the catalog, and add in a short description to say this is the catalog where you can find helpful resources. can change the button URL to go to the catalog. If we save that, this widget is now updated without having to change the code to do any of that. So if we click the button on the widget, it's going to take us to the catalog. In this example, you’ll also notice that we have three instances of this widget, and it only changed one widget, which is great because that means you can build a widget once, put it on a page multiple times or on multiple pages, and change it to have different things in it without having to rebuild the widget. Again, this allows our users to change important information without having to touch the code.
How to Add Widget Instance Options
The first thing you're going to do is Ctrl-click on your widget and navigate to widget options schema — this is where you'll add your options. In this example, there are four options that have already been added. The items you're going to want to define when you add an option include:
Label; this is what your user is going to see so make it something that they'll understand
Name; this will populate based on your label, but you can change it if needed
Type; in this example, the type is set to string. You can change it to other things, such as reference to reference a table or choice values; however, string will get you quite far.
We're going to add another fun widget option which is a string, but it's going to display an image for us. Although it’s not required to add a default value, like to add a default value because it's helpful to your user when they add this widget to a page, or when you add it to a page, it will not show up blank where you have those values. If there wasn't a default value where it said item title, this widget would just show a blank space, and you might not know that there are configurable elements to that widget. You can also add a section of the instance options where you would like it to show if that’s relevant to you.
You'll see as we scroll down, that you’ve got all your widget options. This is how they look with the default values (reference video at 4:18). Let's save that and open the widget instance options so you can see those default values at work. Notice they're kind of grayed out, and the user can type over them like we did when we changed the title to catalog. That's helpful so that the user can see the widget populated with some demo data. You'll notice we didn't add a default value for the URL; in this example, we’ll leave that blank for the user to fill in what they want. Once you’ve added in the option schema, it doesn't automatically just show up in the widget; we have to reference it in our HTML. To do this, you're going to have to open your widget in the editor, so you can access the code.
Referencing Your Option
You'll see the widget is simple (reference the video at 5:15). It’s just a few lines of code, and there’s not any server or client script to be able to reference our widget options. There is some CSS on this widget, but that's not relevant to our widget options. The way you're going to reference your option after you've created it, is options.title (always begin with options and replace title with whatever you named your option). In this example, we have the code below (reference the video at 5:58):
Taking a look at the highlighted code in the above image you'll notice that this looks a little bit different. This is because this option the URL is within our <a> tag. When within the visible part, for example, is actually going to show the user. The URL shown isn't going to show to the user, so that's within the tag. So when you add it, you'll have those double curly braces, but you'll prefix it with two colons and then follow it with options.title — that will give you all of your options in here. Whenever a user changes it, it will know to populate the short description or the title with whatever the user input.
Adding a New Widget Option
Let's add a new widget option. Let’s say our user wants to add an image to make it a little bit prettier, and they might want to add a little more visual context. Let's add our option schema. First, you'll notice that in the widget editor we have these three lines. If we open that up, we can also access our options schema from the widget editor. We'll open that, click a plus, and you'll have to scroll down because it's going to add our new option at the bottom.
Let's call this image, which will auto-populate the name field, and it can be changed if you would like. We're going to keep it as a string type. You might be questioning why it's a string type when we're wanting to import an image. It's a little bit fiddly to input an image, but it's a great way to make this more customizable for your users; without having to rely on icons, can use their own company images. We're not going to add in a default value, although you can if you want it to always show a certain image when the user uploads the widget. Let's save this and remember what we named it, image.
Now we are going to add this code to populate an image on our tile. When you add in an image, you're going to put src=“. Within the quotation marks, we type {{::options.image}} (reference video at 8:14).
We're going to save that and reload our page. You’ll see that nothing's going to show quite yet because we haven't added the image; we've just given the user the option to add the image. You'll notice the widgets all now have this blank space above them where the image is supposed to go. If we Ctrl-click, we open our instance options, and you'll see there is a new space for the image. Now, how do you add an image here?
You'll go back to the backend of your instance to the images table. In this example, we’ve already added this ServiceNow image within here. So what you'll do is upload an image to the image table and give it a name, it always needs to be suffixed by whatever type of image it is; an example would be .PNG, .JPEG, .GIF, .SVG, etc. You're going to copy this name — remember when you do this, your image must be uploaded to the images table, which you can access under system UI images.
Let's go back to the portal, and we're going to paste that name into our image string field, and that's going to tell our HTML what you want to call this specific image. We're going to click save and refresh the page. You’ll see now we have a beautiful image above our tile. We can put different images for each of our widgets. You can see in just a few minutes, we’ve gotten a custom widget; it’s reusable and it's easily editable by our user without having to touch the code, all with just a few lines of code and adding in some instance options. This not only creates less work for a user but creates less work for you.
Did you find this Widget Instance Options in Service Portal article helpful? Are you ready to start your journey with ServiceNow? If you want to find out more information about GlideFast Consulting and our ServiceNow implementation services, you can reach out to us here.
About GlideFast Consulting
GlideFast is a ServiceNow Elite Partner and professional services firm that provides tailored solutions and professional services for ServiceNow implementations, integrations, managed support services, application development, and training. Reach out to our team here.