Sort Function

Owned by Former user (Deleted)
Last updated: Aug 16, 2023 by Jessica Tomkins
2 min read





Similar to the global pui["gridSort"] function configuration option. The sort function can be used to customize the client side grid column sort. Unlike the pui["gridSort"] function, function is only defined for the screen level rather than global. 

When sorting your grid, the sort function will be called many times to compare elements.  You can think of your sort function as a "compare" function. It tells the sort routine which rows should be placed before other rows in the grid.

The following variables are passed to this function:

  • value1 = first field value to compare.

  • value2 = second field value to compare.

  • fieldName = name of the field that the grid is sorted by.

  • isDescending = true if sorting in descending sequence, false otherwise.

  • fieldDateFormat = date format of the field that the grid is sorted by, if the field is not a date null will be passed instead.

  • fieldInfo= formatting information of the field that the grid is sorted by; if the field does not contain any formatting information, a blank object will be passed instead.

    • Some of the properties in the field info are:

      • dataType - the field data type

      • dataLength - data length (only present if the field is a character or a numeric field)

      • formatting - field formatting

  • multiFields= When a multiple-column sort runs, this is an array of information about each column included in the sort. The first preferred sort column is the first entry in the array; the second preferred column is second; etc. This argument is undefined when the sort is for a single column. (Available in Version 6, Fix Packs later than 2.1)

    • Properties of each object are the same as described above:

      • fieldName

      • fieldFormat

      • fieldDateFormat

      • value1

      • value2



Return Value:

The function should return a number that tells the grid which row should be placed before the other:

  • Return a positive value (1 or higher) to indicate that value2 should be before value1

  • Return 0 to indicate that the values are equal

  • Return a negative value (-1 or lower) to indicate that value 2 should be after value1



Examples:

The function code should go directly into the "sort function" property. For example, if the column being sorted is numeric, you could code:

Example
return value2 - value1;

If the "sort function" were to be applied via applyProperty, this would be the syntax:

applyProperty('Grid1', 'sort function', 'return value2 - value1;')





Available in Version 6, Fix Pack 1.0 and later