Dojo in XPages – 5: Array Utilities

In this post, we’ll take a look at array manipulation functions that are available with dojo. The array module is not loaded automatically, but you can easily include it in order to make it available. In this post, I included it at the page level.

Now that the module is available on the page, we can take advantage of its methods.

• indexOf()
• lastIndexOf()
• forEach()
• some()
• every()
• filter()
• map()

As with the string module functions, none of these are complicated procedures, but they can conveniently save you some time from having to write them yourself.

In fact, some of these methods (indexOf and lastIndexOf) are already available in modern browsers without using Dojo. The advantage of using the Dojo methods is cross-browser compatibility. The syntax of the built-in JavaScript method is more compact, but if you aren’t sure whether it will be supported, it’s safer to use Dojo. For example, I’ve been bitten by the use of the JavaScript’s Array.indexOf() because it fails in IE8 and below (or IE9 in compatibility mode).

Sample Array

This is the array that I will use for testing in all of the scripts. I don’t want to clutter this post by repeating it constantly, so I’ll just display it once here:

var myArray = ["car", "train", "boat", "plane", "car", "submarine", "helicopter", "motorcycle"];

indexOf()

Just like the string version of the method, indexOf returns the index of a specified element in the array. If that element is not found, it will return -1.

The method must accept two parameters, the array to search and the value to locate. In addition, there are two optional parameters — a starting index for where to begin searching the array and a boolean for whether it should locate the last instance of the specified value.

The first test returns 0, because the element ‘car’ is in the first position of the array and arrays are 0-based. The second test returns -1, because that value is not found in the array.

The next few tests returned unexpected values. Setting the 4th parameter to true tells it to return the last index of the specified value in the array. However, it doesn’t seem to work properly, based on the 3rd parameter, which is the starting index. The last index of ‘car’ in the array is 4, so the last four tests should have all returned 4. But it doesn’t work when the starting index is between 0 and 3.

My guess is that it’s a bug with the logic and that the ‘starting index’ parameter is being treated like a string character number rather than an array index number, which is quite confusing. In my opinion, this makes it dangerous to use. Fortunately, there’s a lastIndexOf method to solve that problem anyway.

lastIndexOf()

As you would expect, this method returns the position of the last instance of a specified value in an array.

The lastIndexOf method accepts the array to search and the value to find. It also accepts an optional third parameter for the starting point to search the array.

Pretty straightforward. In our array, the value ‘car’ is included twice and this returns the index of the last instance of it.

forEach()

This method iterates over an array and acts upon each element. It accepts the array and a callback function to process each element. You can optionally pass a third parameter with an object to scope the procedure.

some()

The some method returns a boolean value for whether at least one element in the array matches the provided condition. It will stop processing and return true as soon as it finds one match. Otherwise, it will return false.

The first example below checks whether at least one element in the array starts with the letter ‘c’. The second example checks whether at least one element in the array starts with the letter ‘x’.

every()

The every method returns a boolean value for whether every element int he array matches the provided condition. It will stop processing and return false as soon as it finds one element that does not meet the condition.

The some and every methods can be more efficient than using the forEach method and checking every element in the array if you’re looking for 1 match or all matches, because they’ll short-circuit when the condition fails.

filter()

The filter method filters an array and returns an array of values from the first array that return true when checked against the provided condition.

The first parameter is the original array and the second parameter is a function to process each array element and return true or false for whether it matches the filter.

This example checks the array and returns an array of values that start with the letter ‘c’.

map()

The map method checks each element in the array, processes them according to the callback function, and returns

another array with the updated values. It does not modify the original array.

You can also use map with objects, although the original object is modified.