Description

display.grid.find() returns the first record in the grid that passes the test implemented by the provided function. Records are tested in grid order and testing stops at the first match. If no record passes the test, undefined is returned.

It is modeled on the JavaScript Array.prototype.find() method. To get the position of the record instead of the record itself, use display.grid.findIndex().

Syntax

display.gridName.find(callback)

Parameters

Callback (Function) - The function to run for each record. It receives the following arguments:
1. Record (Object) - A copy of the current grid record, with one property for each field in the grid. Changing this object does not change the record in the grid.
2. Index (Number) - The zero-based index of the record being processed.
3. Records (Array) - The array of all grid records that is being processed.
The function must return true when the record is the one being searched for.

Return Value

Object - The first matching record, with one property for each field in the grid, or undefined if no record matches. Each record object is a copy of the grid record. Numeric fields (packed, zoned, and float) are returned as JavaScript numbers, character fields as strings, and indicator fields as the strings "1" and "0". Changing the object does not change the record in the grid.

Examples

Example 1: Find a Record by Field Value

Looks up the record for product 3. Because the record object is a copy, the description can be read from it without affecting the grid.

Prerequisite: a Rich Display File named display.json with a record format named screen that contains a grid whose record format name is mygrid, with the fields product, description, and quantity bound to its columns.

pjs.defineDisplay("display.json");  // Object name defaults to "display"; display.json defines mygrid

// Load four records into the grid so there is something to work with
display.mygrid.replaceRecords([
  { product: 1, description: "ITEM ONE",   quantity: 15 },
  { product: 2, description: "ITEM TWO",   quantity: 20 },
  { product: 3, description: "ITEM THREE", quantity: 12 },
  { product: 4, description: "ITEM FOUR",  quantity: 18 }
]);

// Find the record for product number 3
var found = display.mygrid.find(function(record) {
  return record.product === 3;
});

console.log(found);

// The line above logs:
// { product: 3, description: 'ITEM THREE', quantity: 12 }

Example 2: Handle the Case Where Nothing Matches

Searches for a product that is not in the grid and checks the result before using it. Testing the result for undefined avoids an error when reading a property of a missing record.