Description

display.grid.applyFilter() runs a test function against every record in the grid and replaces the grid contents with only the records for which the function returned true. Records that fail the test are removed from the grid.

It works like display.grid.filter(), except that filter() returns the matching records as an array and leaves the grid unchanged, while applyFilter() changes the grid itself.

Syntax

display.gridName.applyFilter(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 for each record that should be kept in the grid.

Return Value

Nothing is returned. The grid is updated in place.

Examples

Example 1: Remove Records the User Selected for Deletion

A grid contains a check box column bound to an indicator field named remove. After the user checks some rows and presses a button, the program keeps only the rows that were not checked. Indicator values are held in record objects as the strings "1" (on) and "0" (off), so the test compares the value to "1" rather than relying on JavaScript truthiness.

Prerequisite: a Rich Display File named display.json with a grid whose record format name is mygrid, containing a check box bound to an indicator field named remove, and a button whose response property is bound to an indicator field named btnDelete.

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

// ... load the grid records here ...

display.screen.execute();   // Let the user check the rows to remove, then press the button

if (btnDelete) {
  // Keep only the records whose "remove" check box is NOT checked
  display.mygrid.applyFilter(function(record) {
    return record.remove !== "1";
  });
}

display.screen.execute();   // Redisplay the grid without the removed rows

Example 2: Keep Only Records Over a Quantity Threshold

Removes every record with a quantity of 15 or less, leaving two records in 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 }
]);

// Keep only records with a quantity greater than 15
display.mygrid.applyFilter(record => record.quantity > 15);

console.log(display.mygrid.getRecords());

// The line above logs:
// [ { product: 2, description: 'ITEM TWO',  quantity: 20 },
//   { product: 4, description: 'ITEM FOUR', quantity: 18 } ]

display.grid.applyFilter()