• David Tessaro

Tab-Style Menu for Simple Lists

Updated: Jan 10, 2021

Enhancing the Simple List widget with user-friendly navigation

One essential and often under-appreciated feature of every self-service portal is the My Tickets page. This is usually as simple as one list of open tickets, whether they be incidents, requests, or maybe a unified list. However, often enough I come across the need to display multiple views of ticket lists.

For example, giving access to closed tickets would result in two lists: My Open Tickets, and My Closed Tickets

What if you are a manager and you want to see your team’s tickets? Then you may want these four lists:

  1. My Open Tickets

  2. My Closed Tickets

  3. Team’s Open Tickets

  4. Team’s Closed Tickets

There may be even more lists that you want to show. On average I see two to four, but I’ve seen as many as eight different tickets lists in a portal.

Sure, you could put a dropdown menu in the header, but a much nicer solution would be a tabbed menu of sorts. This would be easier to access, and it can give easy indication of what list is currently being displayed. Something like this:

Let’s create a menu widget designed specifically for navigating a series of lists. Actually, we’re going to create two widgets:

  1. Menu for Lists

  2. Simple List w Menu

You may be thinking, why don’t we just create one widget to put at the top of a list? Why two widgets? Because, if we have multiple lists to navigate, that will result in multiple pages. If we put a Menu for Lists widget on each page, then we will have an instance of that widget for every page. We’re already going to have an instance of Simple List on each page. So, we can simply call our Menu for Lists from the Simple List widget and avoid the need for additional instances of a widget that isn’t going to change. If you’re brain hurts, just read on and you’ll understand.

Step 1: Clone the Simple List widget.

Go to the Widgets module and open the Simple List widget. It’ll be read-only.

Click the Clone Widget button in the upper right to create your own copy.

Give the widget a new name. I’ll use the name “Simple List w Menu”. Click Update.

Step 2: Create option for selecting a menu

We’ll want the option of choosing which menu to use for our list. Let’s create an option for that purpose. To do that, we’ll use the Widget Editor. Find and click Service Portal Configuration in the navigator:

Then click on the Widget Editor button

Find your new widget in the Recently Updated list and click on it.

This opens your widget in editor mode.

Click on the menu in the upper right.

Choose Edit option schema. That will open the options panel where we can add a new option.

You’ll see all the existing options for this widget, which we’ll leave alone. Click on the plus icon in the upper right to add a new option. You’ll need to look to the bottom of this window to see your new, blank option.

We are creating an option to reference the Widget Instance table so we can select the menu we create in later steps. Fill in the fields like below, then click Save.

The widget options seem to be broken in Istanbul. You can add a new option via the Widget Editor. But to configure the option in a widget instance, you’ll have to do that manually via the Additional options, JSON format field on the widget instance record. Check out Step 11 for some insight into manually configuring instance options.

Step 3: Reference the option in the server script

We’ll need a way to tell our HTML template what menu to include at the top of the list. Keep in mind, we haven’t yet created the menu that we will be referencing; we’ve only created the option for selecting the menu. We’ll create the menu widget and instance in later steps. But for now, we’ll use the following objects and function in the server script to enable our List w Menu widget to include a menu.

  1. data is an object we use to share data across our widget’s scripts. listMenu is a namespace that we create. Therefore, listMenu is the object we’ll use to hold our menu widget instance.

  2. options references the widget options, and menu is the name we gave our new option. Therefore, menu will equal the sys_id of the menu that we select (after we create the menu in later steps).

  3. $sp.getWidgetFromInstance () is a Service Portal function that will get everything we need from a widget file in order to render it in our HTML template.

Now we combine these elements to form this line:

data.listMenu = $sp.getWidgetFromInstance(options.menu);

Add this line to the bottom of the server script, right before the closing })(). Like this:

Note: If you place this line at the beginning of the widget server script, your widget will break! So be sure you put it at the end of the function.

Click Save, but don’t go away from here yet. We’re going to update the HTML template now.

Step 4: Include the widget in the Simple List w Menu HTML template

We’ve already substantiated the selected menu as an object held by the namespace data.listMenu, so now we can include it in the HTML template with this snippet:

<div><sp-widget widget="data.listMenu"></sp-widget></div>

Add this to the top of the HTML template, like this:

(Please note that the first line below erroneously uses data.ticketsMenu. The correct object is data.listMenu, like mentioned above.)

Okay, we’re done with this widget. Now click Save.

Step 5: Create new widget for List Menu.

We did the necessary work for including a menu at the top of our new Simple List w Menu widget. Now let’s create the List Menu widget. Follow Step 2 to get back to the Widget Editor. But this time, instead of picking an existing widget, click the Create a new widget link.