Initializing help system before first use

Custom Set Sorting

As of JS API 4.7, all Set entities have default sorting applied when the data is loaded into a view. The sorting is based on the Set data type (Integer, String, Boolean) and the values are sorted by default in ascending order. Both of these settings can be configured, allowing you to apply different sorting per Set entity specify and change the sort direction to descending.

When you call insight.Scenario.getSet(), the data returned will be sorted either using default or specified custom sorting. The insight.addSetComparator(), insight.removeSetComparator() and insight.getSetComparator() methods are used to manage any custom Set sorting.

When adding a Set comparator with insight.addSetComparator(), you can specify either:
  • a built-in comparator from the insight.enums.Comparators enums.
  • a JavaScript array of ordered values or a custom comparator function.
You can also specify the sort direction using one of the enum values from insight.enums.SortDirection.
There are some built-in comparators that can be used to sort sets of strings.
  • insight.enums.Comparators.BOOLEAN can cope with Sets of type Boolean, Integer, or String, and will try to cast the value into a Boolean. For example:
    • true values could be t, True, 1, true.
    • false values could be f, False, 0, false.
  • insight.enums.Comparators.DAYS can be used to sort strings representing short or long names of days of the week in English, for example Mon, Tuesday.
  • insight.enums.Comparators.MONTHS can be used to sort strings representing short or long names of months in English, for example Jan, December.

Example using a built-in comparator with a Set of strings

insight.addSetComparator('MonthsOfYear', insight.enums.Comparators.MONTHS);

Example using a JavaScript array of ordered values to sort a Set of strings

insight.addSetComparator('AlertLevels', ['Low', 'Medium', 'High', 'Critical'], insight.enums.SortDirection.DESC);
The comparator function should follow the standard JavaScript CompareFunction interface, for more see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort. This is a function that takes in two values, a and b, and returns one of the following:
  • less than 0 if a has a lower sorting value.
  • 0 if a and b have equal sorting value.
  • greater than 1 if a has a greater sorting value.

Example applying a custom comparator function on a Set of strings

This will sort the value A04 to the beginning of the data, and sort the rest of the values in alphabetical order: 

insight.addSetComparator('AGENCY', function (a, b) {
    return a === 'A04' ? -1 : b === 'A04' ? 1 : a.localeCompare(b);
});

Deprecated Set sorter API

Prior to JS API 4.7 the insight.addSetSorter() method was available. This has been deprecated in JS API 4.7, it will continue to work but may be removed in a later, major release. Instead you should replace any insight.addSetSorter() calls with insight.addSetComparator() and modify the function that performs the sorting to be a CompareFunction as described in the previous section. If both a set sorter and a set comparator are assigned to a given Set entity, the comparator will be applied and the set sorter will be ignored.

Parent Topic Using the JavaScript API to Create Custom Views