The DataGrid component

The DataGrid component is a table with components that are set per column. Users can add, remove and edit rows. The DataGrid can also be filled from the back-end by setting values for all table cells in the submission data. Use the setContent method to automatically create the components for the DataGrid without filling them with data. Note that you can use Layout components to create more elaborate cell contents.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any DataGrid component has a label and tooltip property even though these are not explicitly listed here.

Properties

NameDescriptionDatatypeDefault
addAnotherText to display on the button for adding more rows.String'Add another'
addAnotherPositionPosition of the buttons for adding or removing rows.String'bottom'
condensedWhether or not the rows are condensed (narrow).BooleanFalse
disableAddingRemovingRowsWhen set to true, users cannot add or remove rows, only edit the existing ones.BooleanFalse
enableRowGroupsWhether to enable groups of rows in the DataGrid. See the rowGroups property.BooleanFalse
hideLabelWhether or not to hide the label above the datagrid.BooleanFalse
hoverWhether or not rows are highlighted when a user hovers over them.BooleanFalse
initEmptyWhether to initialize the DataGrid without rows.BooleanFalse
labelPositionPosition of the label with respect to the DataGrid. Can be 'top', 'bottom', 'right-right', 'left-right', 'left-left' or 'right-left'.String"top"
layoutFixedWhen set to true, the widths of all columns are equal.BooleanFalse
reorderWhether or not rows are allowed to be reordered by the user.BooleanFalse
rowGroupsCreate groups of rows in the DataGrid with this property. Must be list of dicts / an array of structs with fields:
  • label: Label to display above the rows.
  • numberOfRows: The number of rows of the row group. Must be an integer.
Set easily with the setRowGroups method.
Dict/Struct
stripedWhether or not the rows should be striped in an alternating way (white-gray).BooleanFalse
tableViewWhen true and the component is part of an EditGrid, the component's value is shown (simplified) in the collapsed row of the EditGrid.BooleanFalse

Methods

NameSyntaxDescription
getColumncolumn = obj​.getColumn(​keyOrLabel)Returns the component of the DataGrid's column with the given key or label. Tries to match keyOrLabel with the component keys first and if no matches were found, matches the labels.
setContentobj​.setContent(​labels, keys, types, editable, options)Add components to a DataGrid component with given column labels and component keys, types and editability. When the editability is left out, all components will be editable for users.
setOutputAsobj​.setOutputAs(outputType)Set the output type used by getSubmissionData. The default is a list of dicts (in Python) or a struct array (in MATLAB). The value can be converted to a pandas DataFrame or a MATLAB table.
setRowGroupsobj​.setRowGroups(​labels, nRowsPerGroup, rowNames)Set the DataGrid component to use row groups with given labels and number of rows. Optionally, the DataGrid is initialized with row names in the first column. An example on using this method is given below.

An example of how the setRowGroups method can be used is shown below:

colNames = ["Person", "Hours", "Done"]
keys = [col.lower() for col in colNames]
loggingTable = component.DataGrid("logging", form)
loggingTable.setContent(colNames, keys, ["TextField", "Number", "Checkbox"])

groupLabels = ["Design phase", "Development phase", "Release phase"]
nRowsPerGroup = [2, 3, 2]
rowNames = ["Sketching", "Proposal", "Data retrieval", "Calculations", 
    "Tests", "Documentation", "Deployment"]
loggingTable.setRowGroups(groupLabels, nRowsPerGroup, rowNames)
colNames        = ["Person", "Hours", "Done"];
loggingTable    = component.DataGrid("logging", form);
loggingTable.setContent(colNames, lower(colNames), ["TextField", "Number", "Checkbox"]);

groupLabels     = ["Design phase", "Development phase", "Release phase"];
nRowsPerGroup   = [2, 3, 2];
rowNames        = ["Sketching", "Proposal", "Data retrieval", "Calculations", ...
    "Tests", "Documentation", "Deployment"];
loggingTable.setRowGroups(groupLabels, nRowsPerGroup, rowNames);

The resulting DataGrid after initialization is as follows:

When using this method, the number of group labels must match the number of elements in nRowsPerGroup. If the rowNames input is used, the first component of the DataGrid must be a TextField and the number of row names must be equal to the sum of nRowsPerGroup.

Default value

You can set the initial value of the DataGrid (and EditGrid) by setting the defaultValue property of the component. In MATLAB, this can be a table with columns named after the keys of the components that you provided when calling setContent. Alternatively, it can be a list of dicts (Python) or a struct array (MATLAB), with fields equal to the keys of the DataGrid's components.

columnNames = ["Name", "Age", "Available"]
keys        = [x.lower() for x in columnNames]
users       = component.DataGrid("users", form)
users.setContent(columnNames, keys, ["TextField", "Number", "Checkbox"])

users.defaultValue = [{
    keys[0]: "Marie",
    keys[1]: 39, 
    keys[2]: False}, {
    keys[0]: "Hank",
    keys[1]: 43, 
    keys[2]: True}
]
columnNames = ["Name", "Age", "Available"];
keys        = lower(columnNames);
users       = component.DataGrid("users", form);
users.setContent(columnNames, keys, ["TextField", "Number", "Checkbox"]);

% Two ways of setting the default value of the DataGrid.
users.defaultValue = struct(keys(1), {"Marie", "Hank"}, keys(2), {39, 43}, ...
    keys(3), {false, true});
users.defaultValue = table(["Marie"; "Hank"], [39; 43], [false; true], ...
    'VariableNames', keys);

The default values of rows added by the user (if enabled) can be set by setting the defaultValue property of the relevant component:

users.disableAddingRemovingRows = False
users.components[1].defaultValue = 18
users.components[2].defaultValue = True
users.disableAddingRemovingRows = false;
users.components{2}.defaultValue = 18;
users.components{3}.defaultValue = true;

Initializing the DataGrid using the default values above and then adding one row yields:

See also

  • The EditGrid component is very similar to the DataGrid, but has an expandable row in which elements can be edited.
  • If your DataGrid has many rows, performance may be improved by using a DataTables component instead of a DataGrid. This also provides many additional features for displaying and editing table data.