feat(grid): Provide row data as argument to column formatter

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes for each version of this project will be documented in this file.
 
+## 12.1.2
+- `igxGrid`
+    - The column formatter callback signature now accepts the row data as an additional argument:
+    ```typescript formatter(value: any, rowData?: any)```
+    The `rowData` argument may be `undefined` in remote scenarios/applying the callback on filtering labels
+    so make sure to check its availability.
+
 ## 12.1.0
 
 ### New Features
@@ -32,7 +39,7 @@ All notable changes for each version of this project will be documented in this
     ```
 - `IgxGrid`, `IgxTreeGrid`, `IgxHierarchicalGrid`
     - Added `batchEditing` - an `Input` property for controlling what type of transaction service is provided for the grid.
-    Setting `<igx-grid [batchEditing]="true">` is the same as providing `[{ provide: IgxGridTransaction, useClass: IgxTransactionService }]`. 
+    Setting `<igx-grid [batchEditing]="true">` is the same as providing `[{ provide: IgxGridTransaction, useClass: IgxTransactionService }]`.
     - **Deprecation** - Providing a transaction service for the grid via `providers: [IgxTransactionService]` is now deprecated and will be removed in a future patch.
     Instead, use the new `batchEditing` property to control the grid's Transactions.
 
@@ -46,14 +53,14 @@ All notable changes for each version of this project will be documented in this
         - `IgxGridCellComponent`,  `IgxTreeGridCellComponent`, `IgxHierarchicalGridCellComponent` are no longer exposed in the public API. Instead, a new class `IgxGridCell` replaces all of these. It is a facade class which exposes only the public API of the above mentioned. Automatic migration will change these imports with `CellType`, which is the interface implemented by `IgxGridCell`
     - **Behavioral changes**
     - `getCellByKey`, `getCellByColumn`, `getCellByColumnVisibleIndex`, `row.cells`, `column.cells`, `grid.selectedCells` now return an `IgxGridCell` the `CellType` interface.
-    - `cell` in `IGridCellEventArgs` is now `CellType`. `IGridCellEventArgs` are emitetd in `cellClick`, `selected`, `contextMenu` and `doubleClick` events. 
+    - `cell` in `IGridCellEventArgs` is now `CellType`. `IGridCellEventArgs` are emitetd in `cellClick`, `selected`, `contextMenu` and `doubleClick` events.
     - `let-cell` property in cell template is now `CellType`.
     - `getCellByColumnVisibleIndex` is now deprecated and will be removed in next major version. Use `getCellByKey`, `getCellByColumn` instead.
 
 - `Transactions`
     - Added `IgxFlatTransactionFactory` - the singleton service instantiates a new `TransactionService<Transaction, State>` given a `transaction type`.
     - Added `IgxHierarchicalTransactionFactory` - the singleton service instantiates a new `HierarchicalTransactionService<HierarchicalTransaction, HierarchicalState>` given a `transaction type`.
-    
+
 - `Toolbar Actions`
     - Exposed a new input property `overlaySettings` for all column actions (`hiding` | `pinning` | `advanced filtering` | `exporter`). Example below:
 

projects/igniteui-angular/src/lib/grids/cell.component.html

@@ -17,7 +17,7 @@
         [groupName]="gridID"
         [value]="
             formatter
-                ? (value | columnFormatter: formatter)
+                ? (value | columnFormatter:formatter:rowData)
                 : column.dataType === 'number'
                 ? (value | number:column.pipeArgs.digitsInfo:grid.locale)
                 : (column.dataType === 'date' || column.dataType === 'time' || column.dataType === 'dateTime')
@@ -34,7 +34,7 @@
         [metadata]="searchMetadata"
     >{{
             formatter
-                ? (value | columnFormatter: formatter)
+                ? (value | columnFormatter:formatter:rowData)
                 : column.dataType === "number"
                 ? (value | number:column.pipeArgs.digitsInfo:grid.locale)
                 : (column.dataType === 'date' || column.dataType === 'time' || column.dataType === 'dateTime')
@@ -56,7 +56,7 @@
     [cssClass]="highlightClass"
     [activeCssClass]="activeHighlightClass"
     [groupName]="gridID"
-    [value]="formatter ? (value | columnFormatter:formatter) : column.dataType === 'number' ?
+    [value]="formatter ? (value | columnFormatter:formatter:rowData) : column.dataType === 'number' ?
         (value | number:column.pipeArgs.digitsInfo:grid.locale) : (column.dataType === 'date' || column.dataType === 'time' || column.dataType === 'dateTime') ?
         (value | date:column.pipeArgs.format:column.pipeArgs.timezone:grid.locale) : column.dataType === 'currency' ?
         (value | currency:currencyCode:column.pipeArgs.display:column.pipeArgs.digitsInfo:grid.locale) : column.dataType === 'percent' ?

projects/igniteui-angular/src/lib/grids/cell.component.ts

@@ -154,7 +154,7 @@ export class IgxGridCellComponent implements OnInit, OnChanges, OnDestroy {
      * @memberof IgxGridCellComponent
      */
     @Input()
-    public formatter: (value: any) => any;
+    public formatter: (value: any, rowData?: any) => any;
 
     /**
      * Gets the cell template context object.
@@ -304,7 +304,7 @@ export class IgxGridCellComponent implements OnInit, OnChanges, OnDestroy {
 
     @HostBinding('attr.title')
     public get title() {
-        return this.editMode || this.cellTemplate ? '' : this.formatter ? this.formatter(this.value) :
+        return this.editMode || this.cellTemplate ? '' : this.formatter ? this.formatter(this.value, this.rowData) :
             this.column.dataType === GridColumnDataType.Percent ?
             this.grid.percentPipe.transform(this.value, this.column.pipeArgs.digitsInfo, this.grid.locale) :
             this.column.dataType === GridColumnDataType.Currency ?

projects/igniteui-angular/src/lib/grids/columns/column.component.ts

@@ -576,12 +576,17 @@ export class IgxColumnComponent implements AfterContentInit, OnDestroy {
     @Input()
     public cellStyles = null;
     /**
-     * When autogenerating columns, the formatter is used to format the display of the column data
-     * without modifying the underlying bound values.
+     * Applies display format to cell values in the column. Does not modify the underlying data.
+     *
+     * @remark
+     * Note: As the formatter is used in places like the Excel style filtering dialog, in certain
+     * scenarios (remote filtering for example), the row data argument can be `undefined`.
+     *
      *
      * In this example, we check to see if the column name is Salary, and then provide a method as the column formatter
      * to format the value into a currency string.
      *
+     * @example
      * ```typescript
      * columnInit(column: IgxColumnComponent) {
      *   if (column.field == "Salary") {
@@ -594,12 +599,19 @@ export class IgxColumnComponent implements AfterContentInit, OnDestroy {
      * }
      * ```
      *
+     * @example
+     * ```typescript
+     * const column = this.grid.getColumnByName('Address');
+     * const addressFormatter = (address: string, rowData: any) => data.privacyEnabled ? 'unknown' : address;
+     * column.formatter = addressFormatter;
+     * ```
+     *
      * @memberof IgxColumnComponent
      */
     @notifyChanges()
     @WatchColumnChanges()
     @Input()
-    public formatter: (value: any) => any;
+    public formatter: (value: any, rowData?: any) => any;
 
     /**
      * The summaryFormatter is used to format the display of the column summaries.

projects/igniteui-angular/src/lib/grids/common/pipes.ts

@@ -305,8 +305,8 @@ export class IgxGridTransactionStatePipe implements PipeTransform {
 @Pipe({ name: 'columnFormatter' })
 export class IgxColumnFormatterPipe implements PipeTransform {
 
-    public transform(value: any, formatter: (v: any) => any) {
-        return formatter(value);
+    public transform(value: any, formatter: (v: any, data: any) => any, rowData: any) {
+        return formatter(value, rowData);
     }
 }
 

projects/igniteui-angular/src/lib/grids/filtering/advanced-filtering/advanced-filtering-dialog.component.html

@@ -111,7 +111,7 @@ <h6 class="igx-filter-empty__title">
                         {{
                             isDate(expressionItem.expression.searchVal)
                             ? getFormatter(expressionItem.expression.fieldName)
-                                ? (expressionItem.expression.searchVal | columnFormatter:getFormatter(expressionItem.expression.fieldName))
+                                ? (expressionItem.expression.searchVal | columnFormatter:getFormatter(expressionItem.expression.fieldName):undefined)
                                 : (expressionItem.expression.searchVal | date:getFormat(expressionItem.expression.fieldName):undefined:grid.locale)
                             : expressionItem.expression.searchVal
                         }}

projects/igniteui-angular/src/lib/grids/filtering/excel-style/grid.excel-style-filtering.component.ts

@@ -551,11 +551,11 @@ export class IgxGridExcelStyleFilteringComponent implements OnDestroy {
         const columnValues = (this.column.dataType === GridColumnDataType.Date) ?
             data.map(record => {
                 const value = (resolveNestedPath(record, columnField));
-                const label = this.getFilterItemLabel(value);
+                const label = this.getFilterItemLabel(value, true, record);
                 return { label, value };
             }) : data.map(record => {
                 const value = resolveNestedPath(record, columnField);
-                return shouldFormatValues ? this.column.formatter(value) : value;
+                return shouldFormatValues ? this.column.formatter(value, record) : value;
             });
 
         this.renderValues(columnValues);
@@ -784,33 +784,33 @@ export class IgxGridExcelStyleFilteringComponent implements OnDestroy {
         this.listData.unshift(blanks);
     }
 
-    private getFilterItemLabel(element: any, applyFormatter: boolean = true) {
+    private getFilterItemLabel(element: any, applyFormatter: boolean = true, data?: any) {
         if (this.column.dataType === GridColumnDataType.Date || this.column.dataType === GridColumnDataType.Time ||
             this.column.dataType === GridColumnDataType.DateTime) {
             return element && element.label ? element.label : this.column.formatter ?
-                applyFormatter ? this.column.formatter(element) : element :
+                applyFormatter ? this.column.formatter(element, data) : element :
                 this.grid.datePipe.transform(element, this.column.pipeArgs.format, this.column.pipeArgs.timezone,
                     this.grid.locale);
         }
         if (this.column.dataType === GridColumnDataType.Number) {
             return this.column.formatter ?
-                applyFormatter ? this.column.formatter(element) : element :
+                applyFormatter ? this.column.formatter(element, data) : element :
                 this.grid.decimalPipe.transform(element, this.column.pipeArgs.digitsInfo, this.grid.locale);
         }
         if (this.column.dataType === GridColumnDataType.Currency) {
             return this.column.formatter ?
-                applyFormatter ? this.column.formatter(element) : element :
+                applyFormatter ? this.column.formatter(element, data) : element :
                 this.grid.currencyPipe.transform(element, this.column.pipeArgs.currencyCode ?
                     this.column.pipeArgs.currencyCode : getLocaleCurrencyCode(this.grid.locale),
                     this.column.pipeArgs.display, this.column.pipeArgs.digitsInfo, this.grid.locale);
         }
         if (this.column.dataType === GridColumnDataType.Percent) {
             return this.column.formatter ?
-                applyFormatter ? this.column.formatter(element) : element :
+                applyFormatter ? this.column.formatter(element, data) : element :
                 this.grid.percentPipe.transform(element, this.column.pipeArgs.digitsInfo, this.grid.locale);
         }
         return this.column.formatter && applyFormatter ?
-            this.column.formatter(element) :
+            this.column.formatter(element, data) :
             element;
     }
 

projects/igniteui-angular/src/lib/grids/filtering/grid-filtering.service.ts

@@ -502,7 +502,7 @@ export class IgxFilteringService implements OnDestroy {
             const column = this.grid.getColumnByName(expression.fieldName);
             const formatter = column.formatter;
             if (formatter) {
-                return formatter(expression.searchVal);
+                return formatter(expression.searchVal, undefined);
             }
             const pipeArgs = column.pipeArgs;
             return this.grid.datePipe.transform(expression.searchVal, pipeArgs.format, undefined, this.grid.locale);

projects/igniteui-angular/src/lib/grids/grid-base.directive.ts

@@ -6762,9 +6762,9 @@ export abstract class IgxGridBaseDirective extends DisplayDensityBase implements
                 columnsArray.forEach((col) => {
                     if (col) {
                         const key = headers ? col.header || col.field : col.field;
-                        const value = source[row].ghostRecord ?
-                            resolveNestedPath(source[row].recordRef, col.field) : resolveNestedPath(source[row], col.field);
-                        record[key] = formatters && col.formatter ? col.formatter(value) : value;
+                        const rowData = source[row].ghostRecord ? source[row].recordRef : source[row];
+                        const value = resolveNestedPath(rowData, col.field);
+                        record[key] = formatters && col.formatter ? col.formatter(value, rowData) : value;
                         if (columnData) {
                             if (!record[key]) {
                                 record[key] = '';
@@ -6832,7 +6832,7 @@ export abstract class IgxGridBaseDirective extends DisplayDensityBase implements
         for (const data of source) {
             selectedColumns.forEach((col) => {
                 const key = headers ? col.header || col.field : col.field;
-                record[key] = formatters && col.formatter ? col.formatter(data[col.field])
+                record[key] = formatters && col.formatter ? col.formatter(data[col.field], data)
                     : data[col.field];
             });
 
@@ -7232,7 +7232,7 @@ export abstract class IgxGridBaseDirective extends DisplayDensityBase implements
         data.forEach((dataRow, rowIndex) => {
             columnItems.forEach((c) => {
                 const pipeArgs = this.getColumnByName(c.field).pipeArgs;
-                const value = c.formatter ? c.formatter(resolveNestedPath(dataRow, c.field)) :
+                const value = c.formatter ? c.formatter(resolveNestedPath(dataRow, c.field), dataRow) :
                     c.dataType === 'number' ? this.decimalPipe.transform(resolveNestedPath(dataRow, c.field),
                         pipeArgs.digitsInfo, this.locale) :
                         c.dataType === 'date' ? this.datePipe.transform(resolveNestedPath(dataRow, c.field),

projects/igniteui-angular/src/lib/grids/grid/column.spec.ts

@@ -134,6 +134,21 @@ describe('IgxGrid - Column properties #grid', () => {
         }
     });
 
+    it('should correctly pass row data context for the format callback', () => {
+        const fix = TestBed.createComponent(ColumnCellFormatterComponent);
+        fix.detectChanges();
+
+        const grid = fix.componentInstance.grid;
+        const formatter = fix.componentInstance.containsY;
+        grid.getColumnByName('ID').formatter = formatter;
+        fix.detectChanges();
+
+        for (let i = 0; i < 2; i++) {
+            const cell = grid.gridAPI.get_cell_by_index(i, 'ID');
+            expect(cell.nativeElement.textContent).toMatch('true');
+        }
+    });
+
     it('should reflect the column in the DOM based on its index', () => {
         const fix = TestBed.createComponent(ColumnCellFormatterComponent);
         fix.detectChanges();

projects/igniteui-angular/src/lib/grids/grid/expandable-cell.component.html

@@ -6,7 +6,7 @@
         [cssClass]="highlightClass"
         [activeCssClass]="activeHighlightClass"
         [groupName]="gridID"
-        [value]="formatter ? (value | columnFormatter: formatter)
+        [value]="formatter ? (value | columnFormatter:formatter:rowData)
             : column.dataType === 'number'
             ? (value | number:column.pipeArgs.digitsInfo:grid.locale)
             : (column.dataType === 'date' || column.dataType === 'time' || column.dataType === 'dateTime')
@@ -17,7 +17,7 @@
         [row]="rowData"
         [column]="this.column.field"
         [containerClass]="'igx-grid__td-text'"
-        [metadata]="searchMetadata">{{ formatter ? (value | columnFormatter: formatter) : column.dataType === "number"
+        [metadata]="searchMetadata">{{ formatter ? (value | columnFormatter:formatter:rowData) : column.dataType === "number"
             ? (value | number:column.pipeArgs.digitsInfo:grid.locale) : (column.dataType === 'date' || column.dataType === 'time' || column.dataType === 'dateTime')
             ? (value | date:column.pipeArgs.format:column.pipeArgs.timezone:grid.locale) : column.dataType === 'currency'
             ? (value | currency:currencyCode:column.pipeArgs.display:column.pipeArgs.digitsInfo:grid.locale) : column.dataType === 'percent'
@@ -28,7 +28,7 @@
     [cssClass]="highlightClass"
     [activeCssClass]="activeHighlightClass"
     [groupName]="gridID"
-    [value]="formatter ? (value | columnFormatter:formatter) : column.dataType === 'number' ?
+    [value]="formatter ? (value | columnFormatter:formatter:rowData) : column.dataType === 'number' ?
         (value | number:column.pipeArgs.digitsInfo:grid.locale) : (column.dataType === 'date' || column.dataType === 'time' || column.dataType === 'dateTime') ?
         (value | date:column.pipeArgs.format:column.pipeArgs.timezone:grid.locale) : column.dataType === 'currency'?
         (value | currency:currencyCode:column.pipeArgs.display:column.pipeArgs.digitsInfo:grid.locale) : column.dataType === 'percent' ?

projects/igniteui-angular/src/lib/grids/grid/grid-filtering-ui.spec.ts

@@ -4604,13 +4604,13 @@ describe('IgxGrid - Filtering actions - Excel style filtering #grid', () => {
 
             // Verify the results are with 'today' date.
             const filteredDate = SampleTestData.today;
-            const inputText = column.formatter(filteredDate);
+            const inputText = column.formatter(filteredDate, null);
             expect((input as HTMLInputElement).value).toMatch(inputText);
 
             // Click 'apply' button to apply filter.
             GridFunctions.clickApplyExcelStyleCustomFiltering(fix);
 
-            const cellText = column.formatter(filteredDate);
+            const cellText = column.formatter(filteredDate, null);
             const cell = GridFunctions.getColumnCells(fix, 'ReleaseDate')[0].nativeElement;
             expect(cell.innerText).toMatch(cellText);
             expect(grid.filteredData.length).toEqual(1);

projects/igniteui-angular/src/lib/grids/tree-grid/tree-cell.component.html

@@ -17,7 +17,7 @@
         [groupName]="gridID"
         [value]="
             formatter
-                ? (value | columnFormatter: formatter)
+                ? (value | columnFormatter:formatter:rowData)
                 : column.dataType === 'number'
                 ? (value | number:column.pipeArgs.digitsInfo:grid.locale)
                 : (column.dataType === 'date' || column.dataType === 'time' || column.dataType === 'dateTime')
@@ -34,7 +34,7 @@
         [metadata]="searchMetadata"
     >{{
             formatter
-                ? (value | columnFormatter: formatter)
+                ? (value | columnFormatter:formatter:rowData)
                 : column.dataType === "number"
                 ? (value | number:column.pipeArgs.digitsInfo:grid.locale)
                 : (column.dataType === 'date' || column.dataType === 'time' || column.dataType === 'dateTime')
@@ -56,7 +56,7 @@
     [cssClass]="highlightClass"
     [activeCssClass]="activeHighlightClass"
     [groupName]="gridID"
-    [value]="formatter ? (value | columnFormatter:formatter) : column.dataType === 'number' ?
+    [value]="formatter ? (value | columnFormatter:formatter:rowData) : column.dataType === 'number' ?
         (value | number:column.pipeArgs.digitsInfo:grid.locale) : (column.dataType === 'date' || column.dataType === 'time' || column.dataType === 'dateTime') ?
         (value | date:column.pipeArgs.format:column.pipeArgs.timezone:grid.locale) : column.dataType === 'currency'?
         (value | currency:currencyCode:column.pipeArgs.display:column.pipeArgs.digitsInfo:grid.locale) : column.dataType === 'percent' ?

projects/igniteui-angular/src/lib/test-utils/grid-samples.spec.ts

@@ -158,6 +158,10 @@ export class ColumnCellFormatterComponent extends BasicGridComponent {
     public multiplier(value: number): string {
         return `${value * value}`;
     }
+
+    public containsY(_: number, data: { ID: number; Name: string }) {
+        return data.Name.includes('y') ? 'true' : 'false';
+    }
 }
 
 @Component({