API
@-Formulas
JavaScript
LotusScript
Reg Exp
Web Design
Notes Client
XPages
 
JavaScript Sorting
NOTE: Based on some feedback we received, this tip has been changed. It seems that the example we gave degrades after a few iterations. It seems to be related to the reuse of the variables "a" and "b" in the custom sorting functions. We have changed the code below and the example on Page 2 of this tip to use temporary variables "x" and "y" in the custom sorting functions, instead of reusing "a" and "b". This seems to prevent any errors from happening.

Many of you are aware of the built-in sort function for sorting JavaScript arrays. But you might not realize the true power of this function. This tip will talk about how this built-in function can be used to sort multi-dimensional arrays.

If you have a one-dimensional JavaScript array, then calling the built-in sort method on the array will sort the array in ascending order. But what about the case where you have an array of first names, an array of last names, and an array of ages? You may want to sort the array of first names, but keep the corresponding positions in the last names and ages. This is done by setting up a multi-dimensional array and sorting the proper "column" of the multi-dimensional array.

First, setting up a multi-dimensional array is pretty easy. If you know the values ahead of time, they can be specified in your javascript code:

var myData = new Array();
myData[0] = {FirstName:"John", LastName:"Doe", Age:40};
myData[1] = {FirstName:"Fred", LastName:"Smith", Age:41};
and so on.

If you don't know the values ahead of time, then the easiest thing to do is to build a "constructor" function:

var myData = new Array();
function person(firstName, lastName, age) {
    this.FirstName = firstName;
    this.LastName = lastName;
    this.Age = parseInt(parseFloat(age));
}

Then, to add a new entry to the array, it's just a matter of creating a new person object:

people[people.length++] = new person(form.FirstName.value, form.LastName.value, form.Age.value);

(The example has the values coming from user input on a form).

To sort the array, we need to tell JavaScript how to sort. This comes from a function that returns -1, 0, or +1 as a value. -1 will put the first value before the second in the sorted array, +1 will put the second value before the first, and 0 means the values are equal. For example, if we want to sort by the first names, here is a function that can be used:

function sortByFirstName(a, b) {
    var x = a.FirstName.toLowerCase();
    var y = b.FirstName.toLowerCase();
    return ((x < y) ? -1 : ((x > y) ? 1 : 0));
}

Two values are passed to this function. The values are array objects. If the first name part of the first object is alphabetically less than the second, -1 is returned. If the first name part of the first object is alphabetically greater than the second, +1 is returned. Otherwise, the first name values must be identical and 0 is returned.

But where does this function come in to play? There's an optional parameter to the built-in sort method that can be used. If you pass in a function name, that function name is used to compare elements in the array for sorting purposes. So, using this javascript call:

people.sort(sortByFirstName);

the array will be sorted in ascending order by the first name part of each array object. Similar functions and calls can be created to sort by the last name or by the age.

Note that JavaScript sorts in ascending order by default. But our function returns how things should be ordered. If we changed +1 to -1 in the function (and vice-versa) then the array would sort the first names in descending order. This is how you can sort by descending order.

We have build an example form in page 2 of this tip (see Page 2 link below). The example form allows you to enter in array elements (first name, last name, and age) to build an array and then provides 3 buttons for sorting the array. It uses the example code listed on this page, with some additional checking, but you can view the source to see the actual code.


First, add people to the list:

First Name:
Last Name:
Age: