Secrets of the Simple List Widget

serviceportal

By now, you’ve probably already used the Simple List widget. It is one of the default widgets on the OOB portal homepage. Similar to the Data Table widget, it is used to display a list of records from a table. However, there is a lot more to this widget than you might think. In this post, we will cover some of the secrets of the simple list widget.

To give you a quick sample of its capabilities, there is an OOB demo page available at:
https://yourinstance.service-now.com/sp?id=test_list

Features Include:

  • Display records from any table and filter
  • Support for image fields
  • Show primary and multiple secondary fields
  • Limit the height with scrollable body
  • Trigger an event
  • Customizable actions

To get started, let’s first create a widget which shows the payload of the event that get’s triggered when clicking a record.

HTML:

Client Script:

Now if you place this widget on the same page as the Simple List widget, and if you don’t specify a “Link to this page” in the Instance Options, you will see the JSON representing the record you clicked on.

With this event, it’ll be very easy to trigger a modal window or other user interaction, but for now let’s proceed to adding some List Actions.

LIST ACTIONS

The Simple List widget supports adding additional actions for the records in the list. For some reason this related list is not visible on the form by default, so we’ll need to add it:

  1. Pull up the Platform View of the Instance Record of the Simple List
  2. Click the hamburger icon > “Configure” > “Related Lists”
  3. Add “List Action -> Parent List”
  4. Now you should see the List Actions Related List

When adding List Actions, you are able to include properties from the record in the URL field using double brackets:

However, there are a couple of unfortunate limitations:

  • You cannot link to an external URL
  • You cannot use URL prefixes such as “mailto:” or “tel:”
  • Clicking a List Action does not trigger an event

This limits the List Actions to just linking to other pages, but hopefully this will get fixed in an upcoming release.

DEMO

Here is a quick video demonstrating how to configure some List Actions on the Simple List widget.

FURTHER READING

18 comments

  1. Hi I tried to follow the video, but as there are no instructions, and it dosen’t match what I find on my own instance, it is not possible.

      1. Is it possible to render filtered table and on clicking the record it shows its form in the same widget instead of going to new page and with header and left menu as it is?

    1. Below is the client controller code to do this for the data table widget. The rest of the steps are pretty much the same. The only thing you’re changing is the event name from ‘$sp.list.click’ to ‘data_table.click’.

      function($rootScope) {
      var c = this;

      $rootScope.$on(‘data_table.click’,function(e, response) {
      c.response = response;
      });
      console.log($rootScope);
      }

      For posterity on how I figured this out, I opened the Simple List widget and found this line:
      $rootScope.$broadcast(‘$sp.list.click’, evt);

      Then I opened the data table widget and found these lines and connected the dots:

      var eventNames = {
      click: ‘data_table.click’,
      setFilter: ‘data_table.setFilter’,
      setKeywords: ‘data_table.setKeywords’
      };

  2. Hi,
    I am having a go at this and my URL in the list action is ?id=room_booking_form&table=facilities&view=self_service_rb&sys_id={​{sys_id}}
    Unfortunately, it doesn’t seem to recognise the value in the brackets and I am getting
    ?id=room_booking_form&table=facilities&view=self_service_rb&sys_id=%7B​%7Bsys_id%7D%7D. Are you able to help please?
    Thanks,
    Maddie

    1. Hi Madeleine,

      Strange, your URL structure looks okay, so I would expect that to work. Are you seeing any errors in the developer console? What version of ServiceNow are you on? If it’s still not working, shoot me an email and I’ll see what I can find.

  3. Ok, this is actually excellent. I didn’t understand initially, but then it clicked. Now, a couple questions.

    Can I possibly use a type ahead search field to filter what’s in the list? i.e. If I have 50 items, can I search for something and have the list shrink accordingly?

    Can I use this on a page where people essentially select one item of the 50, then get passed to a record producer, catalog item, order guide to finish “ordering” some item/device?

    Or, can I use this list functionality in an order guide, catalog item, or record producer so an individual can select 1 of 50 choices that submit a request for said item?

  4. Hi,
    Is there any possible way to change the color for only one of the secondary variables? for example i showing all incidents opened by me and i selected secondary variables as number, update_on and state.in this scenario i just want to use different colors for different states like below
    New – #515559
    In progress – #E9730C
    Resolved – #107F3E

  5. Hi Nathan Firth,
    My name is Ajaykumar and I am a new learner on the service portal please suggest to me and where to start and which document search

  6. Thank you for this. On your example the glyphs all appear in a neat row on the left hand side of each list entry. On mine the glyph appears justified to the text and so looks a little bizarre. How do you justify the glyphs to the right?

Leave a Reply to Nathan Firth Cancel reply

Your email address will not be published. Required fields are marked *