Results:
Loading...
Javascript Data GridJavascriptReact Data GridReactAngular Data GridAngularVue Data GridVue

Angular Data GridFill HandleEnterprise

When working with a Range Selection, a Fill Handle allows you to run operations on cells as you adjust the size of the range.

Enabling the Fill Handle

To enable the Fill Handle, simply set enableFillHandle to true in the gridOptions as shown below:

<ag-grid-angular
    [columnDefs]="columnDefs"
    [enableRangeSelection]="enableRangeSelection"
    [enableFillHandle]="enableFillHandle"
    /* other grid options ... */>
</ag-grid-angular>

this.columnDefs = [
    { field: 'country' },
    { field: 'year' },
    { field: 'sport' },
    { field: 'total' }
];
this.enableRangeSelection = true;
this.enableFillHandle = true;

It's important to note that if you enable both enableFillHandle and enableRangeHandle, the Fill Handle will take precedence.

Default Fill Handle

The default Fill Handle behaviour will be as close as possible to other spreadsheet applications. Note the following:

Single Cell

  • When a single cell is selected and the range is increased, the value of that cell will be copied to the cells added to the range.
  • When a single cell containing a number value is selected and the range is increased while pressing the Alt/Option key, that value will be incremented (or decremented if dragging to the left or up) by the value of one until all new cells have been filled.

Multi Cell

  • When a range of numbers is selected and that range is extended, the Grid will detect the linear progression of the selected items and fill the extra cells with calculated values.
  • When a range of strings or a mix of strings and numbers are selected and that range is extended, the range items will be copied in order until all new cells have been properly filled.
  • When a range of numbers is selected and the range is increased while pressing the Alt/Option key, the behaviour will be the same as when a range of strings or mixed values is selected.

Range Reduction

  • When reducing the size of the range, cells that are no longer part of the range will be cleared (set to null).

Preventing Range Reduction

Reducing a range selection with the Fill Handle will clear cell contents by default, as can be observed in the Range Reduction example above.

If this behaviour for decreasing selection needs to be prevented, the flag suppressClearOnFillReduction should be set to true.

Fill Handle Axis

By the default, the Fill Handle can be dragged horizontally or vertically. If dragging only vertically, or only horizontally is a requirement, the gridOptions property fillHandleDirection property can be set or set via the API using setFillHandleDirection. This default value is xy.

fillHandleDirection
'x' | 'y' | 'xy'
Set to 'x' to force the fill handle direction to horizontal, or set to 'y' to force the fill handle direction to vertical.
Default: xy
setFillHandleDirection
Function
Sets the preferred direction for the selection fill handle. 
setFillHandleDirection = (
    direction: 'x' | 'y' | 'xy'
) => void;
<ag-grid-angular
    [columnDefs]="columnDefs"
    [enableRangeSelection]="enableRangeSelection"
    [enableFillHandle]="enableFillHandle"
    [fillHandleDirection]="fillHandleDirection"
    /* other grid options ... */>
</ag-grid-angular>

this.columnDefs = [
     { field: 'country' },
     { field: 'year' },
     { field: 'sport' },
     { field: 'total' }
 ];
this.enableRangeSelection = true;
this.enableFillHandle = true;
this.fillHandleDirection = 'x';

Custom User Function

Often there is a need to use a custom method to fill values instead of simply copying values or increasing number values using linear progression. In these scenarios, the fillOperation callback should be used.

fillOperation
Function
Callback to fill values instead of simply copying values or increasing number values using linear progression. 
fillOperation = (
    params: FillOperationParams<TData>
) => any;

interface FillOperationParams<TData = any, TContext = any> {
  // The mouse event for the fill operation. 
  event: MouseEvent;
  // The values that have been processed by the fill operation. 
  values: any[];
  // The RowNode of the current cell being changed. 
  rowNode: IRowNode<TData>;
  // The Column of the current cell being changed. 
  column: Column;
  // The values that were present before processing started. 
  initialValues: any[];
  // The index of the current processed value. 
  currentIndex: number;
  // The value of the cell being currently processed by the Fill Operation. 
  currentCellValue: any;
  // The direction of the Fill Operation. 
  direction: 'up' | 'down' | 'left' | 'right';
  // The grid api. 
  api: GridApi<TData>;
  // The column api. 
  columnApi: ColumnApi;
  // Application context as set on `gridOptions.context`. 
  context: TContext;
}
<ag-grid-angular
    [columnDefs]="columnDefs"
    [enableRangeSelection]="enableRangeSelection"
    [enableFillHandle]="enableFillHandle"
    [fillOperation]="fillOperation"
    /* other grid options ... */>
</ag-grid-angular>

this.columnDefs = [
    { field: 'country' },
    { field: 'year' },
    { field: 'sport' },
    { field: 'total' }
];
this.enableRangeSelection = true;
this.enableFillHandle = true;
this.fillOperation = (fillOperationParams) => {
    return 'Foo';
};

FillOperationParams

Properties available on the FillOperationParams<TData = any, TContext = any> interface.

event
MouseEvent
The mouse event for the fill operation.
values
any[]
The values that have been processed by the fill operation.
rowNode
IRowNode
The RowNode of the current cell being changed.
column
Column
The Column of the current cell being changed.
initialValues
any[]
The values that were present before processing started.
currentIndex
number
The index of the current processed value.
currentCellValue
any
The value of the cell being currently processed by the Fill Operation.
direction
'up' | 'down' | 'left' | 'right'
The direction of the Fill Operation.
api
GridApi
The grid api.
columnApi
ColumnApi
The column api.
context
TContext
Application context as set on gridOptions.context.

If a fillOperation callback is provided, the fill handle will always run it. If the current values are not relevant to the fillOperation function that was provided, false should be returned to allow the grid to process the values as it normally would.

The example below will use the custom fillOperation for the Day of the week column, but it will use the default operation for any other column.

Skipping Columns in the Fill Operation

The example below will use the custom fillOperation to prevent values in the Country column from being altered by the Fill Handle.

When the fillOperation function returns params.currentCellValue that value is not added to the params.values list. This allows users to skip any cells in the Fill Handle operation.

Non editable cells will not be changed by the Fill Handle, so there is no need to add custom logic to skip columns that aren't editable.

Read Only Edit

When the grid is in Read Only Edit mode the Fill Handle will not update the data inside the grid. Instead the grid fires cellEditRequest events allowing the application to process the update request.

cellEditRequest
CellEditRequestEvent
Value has changed after editing. Only fires when readOnlyEdit=true. 
onCellEditRequest = (
    event: CellEditRequestEvent<TData>
) => void;

interface CellEditRequestEvent<TData = any, TValue = any> {
  oldValue: any;
  newValue: any;
  source: string | undefined;
  column: Column;
  colDef: ColDef<TData>;
  // The value for the cell 
  value: TValue;
  // The user provided data for the row. 
  data: TData;
  // The row node. 
  node: IRowNode<TData>;
  // The visible row index for the row 
  rowIndex: number | null;
  // Either 'top', 'bottom' or null / undefined (if not set) 
  rowPinned: RowPinnedType;
  // If event was due to browser event (eg click), this is the browser event 
  event?: Event | null;
  // If the browser `event` is present the `eventPath` persists the `event.composedPath()` result for access within AG Grid event handlers.  
  eventPath?: EventTarget[];
  // The grid api. 
  api: GridApi<TData>;
  // The column api. 
  columnApi: ColumnApi;
  // Application context as set on `gridOptions.context`. 
  context: TContext;
  // Event identifier 
  type: string;
}

type RowPinnedType = 
      'top' 
    | 'bottom' 
    | null 
    | undefined

The example below will show how to update cell value combining the Fill Handle with readOnlyEdit=true.

Suppressing the Fill Handle

The Fill Handle can be disabled on a per column basis by setting the column definition property suppressFillHandle to true .

In the example below, please note that the Fill Handle is disabled in the Country and Date columns.