FlexGrid Class

If no cell is currently selected, or if the selected cell is not currently within view, this property returns null.

If no cell is currently being edited, this property returns null.

The new row template will not be displayed if the isReadOnly property is set to true.

The default value for this property is false.

Selected rows will not be deleted if the isReadOnly property is set to true.

The default value for this property is false.

If the autoScroll property is set to true, the grid will automatically scroll its contents while the user drags rows or columns into new positions.

The grid allows dragging columns by default.

Dragging rows requires special considerations in bound scenarios.

When you drag rows on bound grids, the rows will get out of sync with the data source (row 4 may refer to item 6 for example). To avoid this, you should handle the draggedRow event and synchronize the data with the new row positions.

Also, remember to set the allowSorting property to false or you the row order will be determined by the data, and dragging rows will be pointless.

This fiddle demonstrates row dragging with a bound grid: Bound Row Dragging.

The default value for this property is AllowDragging.Columns for the FlexGrid control and AllowDragging.None for the PivotGrid control.

This property does not apply to the MultiRow control.

The default value for this property is AllowMerging.None for the FlexGrid control and AllowMerging.All for the PivotGrid control.

This property does not apply to the MultiRow control.

The pin buttons allow users to pin (freeze) columns so they remain in view as the user scrolls the grid horizontally.

The default value for this property is AllowPinning.None.

If resizing is enabled, users can resize columns by dragging the right edge of column header cells, or rows by dragging the bottom edge of row header cells.

Users may also double-click the edge of the header cells to automatically resize rows and columns to fit their content. The auto-size behavior can be customized using the autoSizeMode property.

The default value for this property is AllowResizing.Columns.

The default value for this property is AllowSorting.SingleColumn.

The default value for this property is 1 for the FlexGrid. Set it to zero to disable alternating rows, or to a number greater than one to insert multiple regular rows between alternating rows.

The default value for this property is 1 for the FlexGrid control and 0 for the PivotGrid control.

The default value for this property is false, which causes the grid to move the cursor and keep the selection end anchored.

Setting this property to true causes the grid to move the selection end and keep the cursor anchored. This is Excel's behavior.

The clipboard shortcuts are as follows:

ctrl+C, ctrl+Ins

Copy grid selection to clipboard.

ctrl+V, shift+Ins

Paste clipboard text to grid selection.

Only visible rows and columns are included in clipboard operations.

Read-only cells are not affected by paste operations.

The default value for this property is true.

The column generation depends on the itemsSource property containing at least one item. This data item is inspected and a column is created and bound to each property that contains a primitive value (number, string, Boolean, or Date).

Properties set to null do not generate columns, because the grid would have no way of guessing the appropriate type. In this type of scenario, you should set the autoGenerateColumns property to false and create the columns explicitly. For example:

import { FlexGrid } from '@grapecity/wijmo.grid';
let grid = new FlexGrid('#theGrid', {
  autoGenerateColumns: false, // data items may contain null values
  columns: [                  // so define columns explicitly
    { binding: 'name', header: 'Name', dataType: 'String' },
    { binding: 'amount', header: 'Amount', dataType: 'Number' },
    { binding: 'date', header: 'Date', dataType: 'Date' },
    { binding: 'active', header: 'Active', dataType: 'Boolean' }
  ],
  itemsSource: customers
});

The default value for this property is true for the FlexGrid control and false for the PivotGrid control.

This property is especially useful when the grid has columns configured to word-wrap their content (see Column.wordWrap), and when the grid has a relatively small number of rows (auto-sizing is an expensive operation).

The default value for this property is false.

Row and column dragging are controlled by the allowDragging property.

The default value for this property is true.

The search happens on the column that is currently selected, if it is not editable. The search starts at the currently selected row and is case-insensitive.

See also the caseSensitiveSearch property.

The default value for this property is false.

This property controls what happens when users double-click the edge of a column header.

By default, the grid will automatically set the column width based on the content of the header and data cells in the column. This property allows you to change that to include only the headers or only the data.

The default value for this property is AutoSizeMode.Both.

Big checkboxes are easier to toggle with the mouse, since the user may click anywhere in the cell to toggle them.

The default value for this property is false.

The bottomLeftCells panel appears below the row headers, to the left of the columnFooters panel.

The searches include searching for regular text (see the autoSearch property) as well as searching for items while editing data-mapped cells (see the Column.dataMap property).

The default value for this property is false (searches are not case-sensitive by default).

Set this property to a string to specify the name of the property that contains an item's child items (e.g. childItemsPath = 'items';).

If items at different levels have child items with different names, set this property to an array containing the names of the properties that contain child items et each level (e.g. childItemsPath = ['checks','earnings'];).

Example

The default value for this property is null.

This property does not apply to the MultiRow control.

The default value for this property is null, which causes the grid to select the best setting depending on the browser.

If the itemsSource property was set to an ICollectionView, this property returns that value.

If the itemsSource property was set to an array of data items, this property returns the internal CollectionView created by the grid to support currency, editing, and sorting.

The columnFooters panel appears below the grid cells, to the right of the bottomLeftCells panel. It can be used to display summary information below the grid data.

The example below shows how you can add a row to the columnFooters panel to display summary data for columns that have the Column.aggregate property set:

function addFooterRow(flex) {

  // create a GroupRow to show aggregates
  let row = new wijmo.grid.GroupRow();

  // add the row to the column footer panel
  flex.columnFooters.rows.push(row);

  // show a sigma on the header
  flex.bottomLeftCells.setCellData(0, 0, '\u03A3');
}

The items in the array should be JSON objects with properties of Column objects, plus three optional members:

• 'columns' array containing an array of child columns,
• 'collapseTo' string containing the binding(s) of the child column(s) that should remain visible when the group is collapsed.
• 'isCollapsed' boolean that determines if the group should be initially collapsed.

For example, the code below generates a grid with two column groups, both initially collapsed:

new FlexGrid('#theGrid', {
    autoGenerateColumns: false,
    columnGroups: [
        { header: 'Group 1', align: 'center', collapseTo: ['id', 'country'], isCollapsed: true, columns: [
            { binding: 'id', header: 'ID' },
            { binding: 'date', header: 'Date', dataType: 'Date' },
            { binding: 'country', header: 'Country', dataType: 'String' },
            { binding: 'active', header: 'Active', dataType: 'Boolean' },
        ]},
        { header: 'Group 2', align: 'center', collapseTo: 'sales', isCollapsed: true, columns: [
            { binding: 'sales', header: 'Sales', dataType: 'Number' },
            { binding: 'expenses', header: 'Expenses', dataType: 'Number' },
        ]}
    ],
    itemsSource: getData(20)
});

The column layout string represents an array with the columns and their properties. It can be used to persist column layouts defined by users so they are preserved across sessions, and can also be used to implement undo/redo functionality in applications that allow users to modify the column layout.

The column layout string does not include properties that cannot be converted to JSON, such as dataMap and editor.

If you want to save and restore column layouts and don't require the layouts to be serializable, you can clone the content of the columns property and restore it later using array methods. This is not as convenient as using the columnLayout property, but it does allow you to save and restore data maps and editors.

The default value for this property is true.

If you choose to ignore commit empty edits, the Grid will not commit empty edits to cell values if the original value is null.

This property is especially useful in read-only grids, because the header information typically should not be included when pasting data into the grid.

The default value for this property is HeadersVisibility.None for the FlexGrid control and HeadersVisibility.All for the PivotGrid control.

By default, deferResizing is set to false, causing rows and columns to be resized as the user drags the mouse. Setting this property to true causes the grid to show a resizing marker and to resize the row or column only when the user releases the mouse button.

The default value for this property is false for the FlexGrid control and true for the PivotGrid control.

The default value for this property is null, which causes the grid to show the edit glyph on the last column of the rowHeaders panel.

By default, this property is set to a tooltip with zero show delay (so it appears immediately when hovering over invalid cells), no HTML content, and a "wj-error-tip" class which can be used to customize the tooltip's appearance.

Setting this property to null causes the control to use the cell's "title" attribute to show validation errors.

The default value for this property is true.

Frozen columns do not scroll horizontally, but the cells they contain may be selected and edited.

The default value for this property is 0.

Frozen rows do not scroll vertically, but the cells they contain may be selected and edited.

The default value for this property is 0.

The string may contain any text, plus the following replacement strings:

• {name}: The name of the property being grouped on.
• {value}: The value of the property being grouped on.
• {level}: The group level.
• {count}: The total number of items in this group.

If a column is bound to the grouping property, the column header is used to replace the {name} parameter, and the column's format and data maps are used to calculate the {value} parameter. If no column is available, the group information is used instead.

You may add invisible columns bound to the group properties in order to customize the formatting of the group header cells.

The default value for this property is null, which causes the grid to use a culture-specific version of the string

'{name}: <b>{value}</b>({count:n0} items)'

This default format string creates group headers similar to

'Country: <b>UK</b> (12 items)'
'Country: <b>Japan</b> (8 items)'

The default value for this property is HeadersFocusability.None.

The default value for this property is HeadersVisibility.All.

This property is relevant only for sites/applications in Japanese, Chinese, Korean, and other languages that require IME support.

The default value for this property is false.

The default value for this property is false for the FlexGrid control and true for the PivotGrid control.

The formatter function can add any content to any cell. It provides complete flexibility over the appearance and behavior of grid cells.

If specified, the function should take four parameters: the GridPanel that contains the cell, the row and column indices of the cell, and the HTML element that represents the cell. The function will typically change the innerHTML property of the cell element.

For example:

flex.itemFormatter = (panel, r, c, cell) => {
  if (panel.cellType == CellType.Cell) {

    // draw sparklines in the cell
    let col = panel.columns[c];
    if (col.name == 'sparklines') {
      cell.innerHTML = getSparkline(panel, r, c);
    }
  }
}

Note that the FlexGrid recycles cells, so if your itemFormatter modifies the cell's style attributes, you must make sure that it resets these attributes for cells that should not have them. For example:

flex.itemFormatter = (panel, r, c, cell) => {

  // reset attributes we are about to customize
  let s = cell.style;
  s.color = '';
  s.backgroundColor = '';
  // customize color and backgroundColor attributes for this cell
  ...
}

If you have a scenario where multiple clients may want to customize the grid rendering (for example when creating directives or re-usable libraries), consider using the formatItem event instead. The event allows multiple clients to attach their own handlers.

If specified, the validator function should take parameters containing the cell's row and column indices and a parsing parameter that describes whether the data has already been parsed and applied to the data item (parsing == false), or whether the user was trying to edit the value and entered a value that could not be parsed into the data type expected (parsing == true).

The method returns a string containing an error message, or null if no errors were detected.

For example,

grid.itemValidator = (row: number, col: number, parsing: boolean) => {
    let item = grid.rows[row].dataItem,
        prop = grid.columns[col].binding;

    // parsing failed, show message
    if (parsing) {
        if (prop == 'date') {
            return 'Please enter a valid date in the format "MM/dd/yyyy"';
        } else if (prop == 'id') {
            return 'Please enter a positive number';
        }
    }

    // check that stored (parsed) data is valid
    if (prop == 'date' && item.date < minDate) {
        return 'Please enter a date after ' + Globalize.formatDate(minDate, 'd');
    } else if (prop == 'id' && item.id < 0) {
        return 'Please enter a positive number';
    }
});

See also the CollectionView.getError method.

The default setting for this property is KeyAction.MoveDown, which causes the control to move the selection to the next row. This is the standard Excel behavior.

The default setting for this property is KeyAction.None, which causes the browser to select the next or previous controls on the page when the TAB key is pressed. This is the recommended setting to improve page accessibility.

Note that the default setting for the inherited FlexSheet control is KeyAction.CycleOut (see below).

In previous versions, the default was set to KeyAction.Cycle, which caused the control to move the selection across and down the grid. This is the standard Excel behavior, but is not good for accessibility.

There is also a KeyAction.CycleOut setting that causes the selection to move through the cells (as KeyAction.Cycle), and then on to the next/previous control on the page when the last or first cells are selected.

The default value for this property is true.

If you set the newRowAtTop property to true, and you want the new row template to remain visible at all times, set the frozenRows property to one. This will freeze the new row template at the top so it won't scroll off the view.

The new row template will be displayed only if the allowAddNew property is set to true and if the itemsSource object supports adding new items.

The default value for this property is false.

The preserveOutlineState property implementation is based on JavaScript's Map object, which is not available in IE 9 or 10.

The default value for this property is true.

The default value for this property is true.

This property allows you to specify how the grid should handle white space without changing any CSS rules. You choose to use CSS rules instead, however, since they provide better control over scope.

For example, you could create CSS rules that apply to all grids in the application, to specific grids, or to specific columns.

Be aware that setting this property to true may have undesired effects in applications that use interop cell templates (Vue templates especially).

The default value for this property is false.

Setting this property to false disables quick auto-sizing. Setting it to true enables the feature, subject to the value of each column's wijmo.grid.Column.quickAutoSize property.

The default value for this property is null, which enables quick auto-sizing for grids that don't have a custom itemFormatter or handlers attached to the formatItem event.

Quick auto-sizing uses different strategies when auto-sizing rows or columns.

When auto-sizing columns, it uses a temporary canvas element to locate the row with the widest entry for a column. When the row is located, its contents are measured precisely. The limitation with this approach is that the canvas only renders plain text, so if cells contain HTML the auto-sizing may miss the widest column.

When auto-sizing rows, it uses a cache to store the row heights based on the cell content, and skips measuring numeric cells. The limitation with this approach is that it only improves performance if many cells have the same content, or if many columns are numeric.

If you find that auto-sizing is slowing down your application, it is probably worth setting quickAutoSize to true and checking the results to see if it works correctly and improves performance for your app.

The default value for this property is true.

Row header cells are not visible or selectable. They are meant for use with accessibility tools.

Note: this property can be read in all selection modes, but it can be set only when selectionMode is set to SelectionMode.ListBox.

The first element in the array is the current selection. If the grid's selectionMode property is set to SelectionMode.MultiRange, the array may contain additional ranges that represent the extended selection.

Note that ranges in the selectedRanges array may contain overlapping areas, which may be important when performing actions like aggregating over the extended selection.

Note: this property can be read in all selection modes, but it can be set only when selectionMode is set to SelectionMode.ListBox.

The drop-down buttons are shown on columns that have a Column.dataMap and are editable.

Clicking on the drop-down buttons causes the grid to show a drop-down list from which users can select the cell value.

This setting may be overridden on specific columns using the column's Column.dataMapEditor property.

Cell drop-downs require the wijmo.input module to be loaded.

The grid detects validation errors using the itemValidator property and the CollectionView.getError property on the grid's itemsSource.

The default value for this property is true.

Data groups are created by modifying the ICollectionView.groupDescriptions property of the ICollectionView object used as an itemsSource.

The default value for this property is true.

The default value for this property is false.

If you choose to show the marquee, you may want to improve accessibility by using some simple CSS to make the marquee fully opaque only when the grid has the focus:

.wj-flexgrid:not(.wj-state-focused) .wj-marquee {
    opacity: 0.2;
}

The default value for this property is false.

This property is especially useful in grids that have multiple rows per data item (like the MultiRow grid) and in grids that allow adding new items (see the allowAddNew property).

This property only works with the grid's built-in editor. If you are using custom editors (see the Column.editor property), then you are responsible for setting the placeholder property on those.

The Internet Explorer browser does not show input placeholders on focused input elements, so this property is not useful in IE.

The default value for this property is HeadersVisibility.None.

Sorting is controlled by the ICollectionView.sortDescriptions property of the ICollectionView object used as a the grid's itemsSource.

The default value for this property is true.

The default value for this property is null, which causes the bottom row in the columnHeaders panel to act as the sort row.

The default value for this property is false.

The default value for this property is 14 pixels for the FlexGrid control, and 32 pixels for the PivotGrid.

The grid detects validation errors by calling the CollectionView.getError method on the grid's itemsSource.

The default value for this property is true.

This property is set to zero by default, meaning virtualization is always enabled. This improves binding performance and memory requirements, at the expense of a small performance decrease while scrolling.

If your grid has a small number of rows (about 50 to 100), you may be able to improve scrolling performance by setting this property to a slightly higher value (like 150). This will disable virtualization and will slow down binding, but may improve perceived scroll performance. For example, the code below sets causes the grid to virtualize cells when the data source has more than 150 items:

// virtualize grid when there are more than 150 items
theGrid.virtualizationThreshold = 150;

Setting this property to values higher than 200 is not recommended. Loading times will become too long; the grid will freeze for a few seconds while creating cells for all rows, and the browser will become slow because of the large number of elements on the page.

If you want to set separate virtualization thresholds for rows and columns, you may set the virtualizationThreshold property to an array with two numbers. In this case, the first number will be used as the row threshold and the second as the column threshold. For example, the code below sets causes the grid to virtualize rows but not columns:

// virtualize rows (threshold 0) but not columns (threshold 10,000)
theGrid.virtualizationThreshold = [0, 10000];

The default value for this property is 0, which causes the grid to virtualize all rows and columns.