Grid control

Last Update: 9/26/2016

See Use grid for basic usage and advanced samples.

Create a grid

TypeScript

import Controls = require("VSS/Controls");
import Grids = require("VSS/Controls/Grids");

// Create the grid in a container element
var grid = Controls.create<Grids.Grid, Grids.IGridOptions>(Grids.Grid, container, options);

JavaScript

require(["VSS/Controls", "VSS/Controls/Grids"], function(Controls, Grids) {
    // Create the grid in a container element
    var grid = Controls.create(Grids.Grid, container, options);
});

Options

     {
        source: {any},
        expandStates: {number[]},
        header: {boolean},
        height: {string},
        width: {string},
        allowMultiSelect: {boolean},
        allowMoveColumns: {boolean},
        allowTextSelection: {boolean},
        lastCellFillsRemainingContent: {boolean},
        columns: [
            index: {any},
            name: {string},
            canSortBy: {boolean},
            canMove: {boolean},
            width: {number},
            headerCss: {string},
            rowCss: {string},
            text: {string},
            tooltip: {string},
            order: {string},
            hidden: {boolean},
            fixed: {boolean},
            format: {string}
        ],
        gutter: {
            contextMenu: {boolean},
            icon: {
                index: {any},
                tooltipIndex: {any}
            }
        },
        contextMenu: {
            items: {any},
            executeAction: {(args: any): any},
            useBowtieStyle: {boolean},
            columnIndex: {number or string}
        },
        sortOrder: [
            index: {any},
            order: {string}
        ],
        autoSort: {boolean},
        useBowtieStyle: {boolean}
    }
Option Type Default Notes
source any [] Data source of the grid. It can be array of arrays ([[], [], [], ...]), array of objects ([{}, {}, {}, ...])
expandStates number[] Specifies the expand states of each item in the source. If an item has a total of n descendants; -n makes the item collapsed, n makes the item expanded, 0 means no children and descendants.
header boolean true Determines whether the header is displayed or not
height string Height of the grid in px or %
width string Width of the grid in px or %
allowMultiSelect boolean true Determines whether multiple selection is allowed or not
allowMoveColumns boolean true Determines whether moving columns is allowed or not
allowTextSelection boolean false Determines whether selecting text is allowed or not
lastCellFillsRemainingContent boolean false Determines whether the last cell should fill remaining content (if exists)
columns IGridColumn[] [] List of columns to be displayed in the grid
columns.index any index in the columns array Index of the column which can be either number or string. If number specified, each item of the data source is expected to be an array. Then array[index] is displayed in the column. If string specified, each item if the data source is expected to be an object. Then object[index] is displayed in the column.
columns.name string Name of the column used for identification purposes
columns.canSortBy boolean true Determines whether moving this column is enabled or not
columns.canMove boolean true Determines whether sorting this column is enabled or not
columns.width number 100 Width of the column in pixels
columns.headerCss string Css class to be added to the header cell
columns.rowCss string Css class to be added to the cells under this column
columns.text string Display text of the column
columns.tooltip string Tooltip text of the column
columns.order string asc Specifies how ordering should be performed ("asc" or "desc")
columns.hidden boolean false Determines whether the column should be hidden or not
columns.fixed boolean false Determines whether column moving effects this column or not
columns.format string If the value of cell is Date, format is used (like 'mm/dd/yyyy')
gutter IGridGutterOptions false Options about the gutter. If specified false, gutter will be invisible
gutter.contextMenu boolean Determines whether a context menu is show in the gutter or not
gutter.icon.index any String or number value to get the icon value from source item corresponding to current row
gutter.icon.tooltipIndex any String or number value to get the icon tooltip value from source item corresponding to current row
contextMenu IGridContextMenu Options about the context menu displayed when gutter clicked
contextMenu.items any Menu items to be shown when gutter clicked. Value can be a list of menu items or a function which returns an a list of menu items
contextMenu.executeAction (args: any): any Execute action for the popup menu
contextMenu.useBowtieStyle boolean false Specifies whether to use the modern bowtie styling (bowtie styles are in preview and subject to change).
contextMenu.columnIndex number or string Column index for the context menu, if using bowtie styling
sortOrder IGridSortOrder[] [] Initial sort info for the grid
sortOrder.index any Refers to column index
sortOrder.order string asc Determines whether to sort ascending (default) or descending
autoSort boolean true Specifies whether grid should be sorted initially using the sortOrder option
useBowtieStyle boolean false Specifies whether to use the modern bowtie styling (bowtie styles are in preview and subject to change).

Methods

getSelectionCount()

Gets the number of selected items.

Returns

number

setDataSource()

Sets the source of the grid using GridSource object.

Returns

void

Parameters

  • source: IGridSource. GridSource object to set the grid source.

setDataSource()

Sets the data source, expands states, columns and sort order of the grid.

Returns

any

Parameters

  • source: any[]. Optional. New source for the grid (See grid options for details).
  • expandStates: any[]. Optional. Expand states for the new source. If source is not in hierarchical structure, specify null (See grid options for details).
  • columns: IGridColumn[]. Optional. New columns for the grid (See grid options for details).
  • sortOrder: IGridSortOrder[]. Optional. New sort order for the grid (See grid options for details).
  • selectedIndex: number. Optional. Index of the rows to be selected after new data source is set.
  • suppressRedraw: boolean. Optional. If true, grid is not redrawn after data source is set.

getRowInfo()

Gets the information about a row associated with the given data index.

Returns a rowInfo object containing rowIndex, dataIndex and a jQuery wrapper for the actual row.

Returns

IGridRowInfo

Parameters

  • dataIndex: number. The data index for the record to retrieve.

getRowData()

Gets the data being used to display the row at the provided data index.

Returns

any

Parameters

  • dataIndex: number. The data index for the record to retrieve.

getColumns()

Gets the columns currently being displayed in the grid.

Returns

IGridColumn[]

getSortOrder()

Gets the current sort order being used in the grid.

Returns

IGridSortOrder[]

setColumnOptions()

Set new column info for the column associated with the specified column name.

Returns

void

Parameters

  • columnName: string. Name of the column to change the options.
  • options: IGridColumn. Optional. New column options.

expandAll()

Expands all rows of the grid (if source data is hierarchical).

Returns

void

collapseAll()

Collapses all rows of the grid (if source data is hierarchical).

Returns

void

expandByLevel()

Expands all rows at or below specified level (if source data is hierarchical).

Returns

void

Parameters

  • level: number. Level to expand.

collapseByLevel()

Collapses all rows at or below specified level (if source data is hierarchical).

Returns

void

Parameters

  • level: number. Level to collapse.

tryToggle()

Expand or collapse node(s), and set selection focus at a given target index or at the current selected index as default behavior.

Returns

boolean

Parameters

  • expand: boolean. If true, expands the node, otherwise collapsed.
  • applyToAllRows: boolean. True to expand or collapse all nodes, false to expand or collapse the node at a given target index, or at the current selected index as default behavior.
  • targetIndex: number. Optional. The node index to be expanded or collapsed, and get selection focus.

getContextMenuRowInfo()

Gets info about the row on which context menu is opened.

If no context menu is open, returns null.

Returns

IGridRowInfo

Q & A

Q: How is the performance with huge data?

A: Grid uses UI virtualization which performs great on tens of thousands of rows.

Q: Can I have variable height rows?

A: No at the moment. This is caused by UI virtualization where scrolling is managed by grid itself. However, we are thinking to improve this scenario.