Data Grid

The data grid component lets you display data from a source table, as a set of rows and columns. This page includes quick steps for creating data grids and answers to some frequently asked questions about data grids.

For a detailed reference of properties that affect data grids, see Common Properties and Data Grid Properties.

A data grid component in DGLux5

About Column Editors and Column Order

When you create a data grid, you use column editors to control which columns appear in the grid and to control some properties of those columns, such as sortability.

There are three types of column editors: All, Name, and Repeater.

By default, one All column editor is included in a new data grid component. The All type of column editor dictates that all of the columns from the source table are included in the grid, except for those that you filter out of the entire grid. The All column editor also lets you edit properties for all grid columns. Regarding column order, when you use the All column editor, grid columns will appear in the same order as source table columns, unless you use a whitelist filter—in that case, grid columns appear in the order specified in the Filter property. With the All column editor type, grid columns have the same column heading text as source table columns.

If you prefer, you can use Name column editors instead. Each Name column editor dictates that one specific table column is included in the grid, and each Name column editor also allows you to edit properties for that particular column, including the column heading text. When you use Name column editors, columns in the grid appear in the order that the column editors appear in the Outline, unless you use a whitelist filter. Just as with an All column editor, the column order in the whitelist filter overrides the column order elsewhere. Additionally, Name column editors allow you to create and manage categories.

Name column editors are also useful when creating column renderers. A column renderer displays a specified symbol in each cell of a column, using symbol parameters and data from the source table to affect each symbol instance. Column renderers are similar to repeaters. You can see two examples of column renderers in the FAQ, under "How do I put images in my data grid?" and "How do I clip content in my data grid?"

The third and final column editor type is the Repeater column editor. This is the most complex type and allows for the most flexibility in the data grid. A Repeater column editor lets you use a configuration table to determine:

Which source table columns appear in the grid
Which symbols represent those columns (if any)
Properties of the symbols

You can see an example of a Repeater column editor in the FAQ, under "How do I use a Repeater column editor? How do I make a grid with a dynamic number of columns?"

Load Data

Typically, before you can design a chart or data grid, you must load a table in the dataflow.

To load a table, follow the steps in Working with Tables.

Create a Data Grid

This section shows quick steps for creating a data grid.

After inserting a data grid component and loading data:

In the Outline, select the data grid, and click Dataflow to open the dataflow window.
Bind the output table from your dataflow to the Table property of the data grid.

The data appears in the data grid component.
With the data grid selected in the Outline, in the Selection properties, choose a fill and stroke and a selection behavior.

If you want to allow the user to select multiple rows, choose Multi-Select.
In the Outline, select the data grid's header.
Style the data grid's header using the Property Inspector.
In the Outline, select the data grid's rows.
Style the data grid rows using the Property Inspector.
In the Outline, select the "Column 0" column editor, which is a child of the "Columns" node.
Set Sortable to TRUE.

This allows the user to sort the data grid by any column.

Using the Category Feature

Data grid categories allow you to create multiple levels of headers for grid columns. If columns within the same category are adjacent, their category headings are merged:

If columns within the same category are not adjacent, the category headings are not merged:

When you create data grid categories, you add them to the Outline as column editors.

These steps show you first how to use the category feature to categorize columns by type of data, and then how to change the categorization to be by device. These steps illustrate adding only one level of categorization, but you could use the same process to create multiple levels.

Create a table for your data grid that looks like the table below. Use the following column headers:
- device_1_temp
- device_2_temp
- device_1_airflow
- device_2_airflow
Delete the existing column editor, and create six new column editors for your data grid by clicking the Add Column button six times.
Set the Type property for all six column editors to Name. You can select all six column editors and then change the property once.
Set the Selector and Category properties for each column editor as follows:
- For Column 0, set Selector to Temp and leave Category blank.
- For Column 1, set Selector to device_1_temp and set Category to Temp.
- For Column 2, set Selector to device_2_temp and set Category to Temp.
- For Column 3, set Selector to Flow and leave Category blank.
- For Column 4, set Selector to device_1_airflow and set Category to Flow.
- For Column 5, set Selector to device_2_airflow and set Category to Flow.
  
  This creates a table with four columns that are grouped into two categories.
You can change the names in the Outline for clarity, and this will also update the Label property for each editor, changing what appears in the headers.
As another example, change the categories to the following:
- For Column 0, change Selector to Device 1 and leave Category blank. Change Label to Device 1.
- For Column 1, keep Selector as device_1_temp and set Category to Device 1.
- For Column 2, keep Selector as device_2_temp and set Category to Device 2.
- For Column 3, set Selector to Device 2 and leave Category blank. Change Label to Device 2.
- For Column 4, keep Selector as device_1_airflow and set Category to Device 1.
- For Column 5, keep Selector as device_2_airflow and set Category to Device 2.
  
  This creates a table with four columns that are grouped into two categories, but the categories are not together.
To place columns in the same category next to one another, select column editors in the Outline and then use the Bring Forward and Send Backward commands in the Quick Access panel. You cannot reorder column editors in the Outline by dragging.

This creates a table with four columns that are grouped into two categories.

Data Grid FAQ

For frequently asked questions about manipulating the tables that determine the contents of a data grid, see Working with Tables.

How do I edit data grid properties?

How do I edit data grid properties?
In general, to edit properties for a data grid or the elements it comprises:

Use the Outline to select a data grid, its header, its rows, or one of its column editors.
Use the Property Inspector to edit properties for the selected element.

For detailed information about each data grid property, see the Data Grid Properties reference.

How do I sort a data grid?

How do I sort a data grid?
You can sort the source table using a Sort block, or you can use the data grid's properties:

In the Outline, select the data grid.
In the Property Inspector, type the name of the column to sort by in the Sort Column field.
For Sort Order, select "Ascending" or "Descending."
In the Outline, select Column 0, or another column editor that includes the column you want to sort by.
In the Property Inspector, set Sortable to TRUE.

The data grid is sorted by the column you specified.

How do I filter out data grid columns?

In the Outline, select the data grid.
For the Column Filter property, enter a comma-separated list of table column names.

These can either be the columns to include or the columns to exclude.
For the Filter Type property, select Whitelist to include the listed columns, or Blacklist to exclude them.

What is a column editor? How do I specify different properties for each column?

What is a column editor? How do I specify different properties for each column?
You edit column properties using column editors. You specify whether each column editor affects all columns or just one column. Using a column editor, you can edit properties such as Sortable, column width, and header label.

To edit all of the data grid columns at once, you can use the default "Column 0" editor, which is a child of the "Column" node in the Outline.

To edit each data grid column individually:

In the Outline, select "Column 0."
In the Property Inspector, for Type, select Name, and for Selector, type the name of one of your table columns.
In the Outline, select the data grid.
In the Property Inspector, under the Data Grid properties, click Add Column.
In the Outline, select the new column editor.
In the Property Inspector, for Type, select Name, and for Selector, type the name of another one of your table columns.
Repeat steps 3–6 until you have an editor for each column.

Now you can edit each column's properties individually.

How do I change column header text?

How do I change column header text?
You can change your column header text at the table level using a Column Mapping block, or you can do it in Property Inspector.

To edit header text using the Property Inspector:

Create column editors for each column as described above.
In the Outline, select a column editor.
In the Property Inspector, under the Column properties, for Label, type the label you want to use.

To style header text:

In the Outline, select the header.
In the Property Inspector, use the Text and Font properties to style the header text.

How do I style the background and gridlines?

How do I style the background and gridlines?
To style the background and gridlines for the data grid rows:

In the Outline, select Rows.
In the Property Inspector, under Gridlines, specify whether you want vertical, horizontal, or both.
Select the stroke color, style, and weight for the horizontal and vertical gridlines separately.
In the Property Inspector, under Fill and Stroke Properties, edit the properties for Main.

The properties are applied to all of the data grid rows.
If you want alternating row colors, edit the properties for Alt.

The Alt properties are applied to alternating data grid rows.

To style the background and gridlines for the data grid header:

In the Outline, select Header.
In the Property Inspector, under Gridlines, specify the stroke color, style, and weight for the vertical gridlines between column headers.
In the Property Inspector, under Fill and Stroke, specify:
- The stroke color, style, and weight for the outlining the data grid's header.
- The background fill for the data grid's header.

How do I style the row that the user mouses over?

How do I style the row that the user mouses over?
You can add interactivity by styling the row that the user mouses over.

In the Outline, select Rows.
In the Property Inspector, under Fill and Stroke Properties, edit the properties for Hov.

"Hov" stands for "Hovered Row."

How do I let the user select rows? How do I style selected rows?

How do I let the user select rows? How do I style selected rows?
You can enable the user to select rows by clicking. You can make selection interactive by styling the selected rows.

Even if you do not enable the user to select rows, you can manually specify one selected row using the Selected Index property.

To enable the user to select rows by clicking:

In the Outline, select Data Grid.
In the Property Inspector, under Selection, choose a selection type.
- Single Select: The user can select one item.
- Toggle Select: The user can select one item, and click it to deselect.
- Multi-Select: The user can select multiple items, and click them to deselect.

To style the selected row or rows:

In the Outline, select Rows.
In the Property Inspector, under Fill and Stroke Properties, edit the properties for Sel.

"Sel" stands for "Selected Row."

How do I put images in my data grid?

How do I put images in my data grid?
These steps show you how to make a data grid that includes a column of images with tooltips. In these steps, you will use Table and Column Mapping dataflow blocks and a symbol.

Configure the Table and Upload Images

Right-click the Stage in the Document window or Outline, and select Insert > Components > Data Grid.
Download the following three images, and upload them into the assets folder in the Project panel:
In the Outline, right-click the data grid, and select Dataflow to open the dataflow window.
Drag a Table dataflow block to the dataflow window.
Click the button for the data property to open the table, and then edit the table so that it appears as shown in the image below. For help, see Enter Data in a Table Dataflow Block.
Add a Column Mapping dataflow block to the dataflow window.
Bind the data property of the Table block to the input property of the Column Mapping block.
For the Column Mapping block:
1. Set retainColumns to TRUE.
2. Set name 0 to Image.
3. Set from 0 to ="assets/"+Status+".png"
  
  This creates a new table that contains the image paths in a column.
With the data grid selected in the Outline, bind the output table of the Column Mapping block to the Table property.

The contents of the table are displayed in the data grid component.

Create the Symbol

Right-click the Stage in the Document window or Outline, and select Insert > Components > Image.
Right-click the image component that you added, and select Convert to Symbol.
When prompted, name the symbol status, and click OK.
In the Symbols panel, right-click status, and select Edit.
In the Outline, right-click status, and select Edit Properties.
In the Symbol Parameters dialog, drag one string and one path to the right-hand panel.
Double-click the parameter names to rename the string parameter Tooltip and the path parameter Image.
Bind the Tooltip parameter to the Tooltip property in the Property Inspector.
Bind the Image parameter to the URL property in the Property Inspector.
Close the Symbol Parameters dialog, and then click OK to close the symbol editing dialog.

Edit the Column Properties

With the data grid selected in the Outline, under Data Grid, click Add Column twice.

The column editors appear under the Columns node in the Outline.
Select "Column 1" in the Outline.
For Column 1:
1. Set Type to Name.
2. Set Selector to Status.
3. Set Visible to FALSE.
Select "Column 2" in the Outline.
For Column 2:
1. Set Label to Status.
2. Set Type to Name.
3. Set Selector to Image.
4. Set Symbol to status.
Click Dataflow to open the dataflow for the data grid.
Select the Column Mapping block, and click the button to open the output table.
Expand "Status" in the Outline, and select renderer.
Drag the Status table column header to the Tooltip property.
Drag the Image table column header to the Image property.

This populates the Status column of the data grid with images that display tooltips when moused over.

How do I clip content in my data grid?

How do I clip content in my data grid?
Clipping content is similar to including images as described above. In both cases, you must use a column renderer to customize the content of the cells. To clip cell content using a column renderer:

Create a symbol based on a text component. Set the Clip Content property of the text component to TRUE. Then, create a string parameter and bind it to the Text property of the text component insider the symbol.
In the Data Grid properties, create a separate column editor for every column in which you want to clip content.
Use the symbol that you created in step 1 for the Symbol property of all of the column editors. This creates column renderers. If you want to clip content in the headers as well, you can bind the same symbol or a different symbol to the Header Symbol property.
Bind the columns of the data grid's source table to each renderer's string property by dragging the table column headers. If you created header renderers, bind the table column headers to these fields as well.

How do I use a Repeater column editor? How do I make a grid with a dynamic number of columns?

A Repeater column editor lets you use a configuration table to determine:

Which source table columns appear in the grid
Which symbols represent those columns (if any)
Properties of the symbols

These steps show you how to create a data grid that uses a basic Repeater column editor:

Create symbols for your data grid like the four shown below.
1. typeSym:
  - Based on an image component
  - Parameter: a path parameter named path that is bound to the image's URL property
2. progressBar:
  - Based on a group that uses Horizontal layout and that contains a shape with a percentage width
  - Parameter: a string parameter named progress_percent that is bound to the shape's Width property
3. buttonSym:
  - Based on a text component that has an Open Page onClick action
  - Parameter: a string parameter named page that is bound to the onClick action's Dashboard property
4. headingSym:
  - Based on a text component
  - Parameters: a string parameter called heading_text that is bound to the Text property; optional formatting parameters
In the dataflow, create a "data" table for your data grid that looks like the table below. Use these column headings:
- ID
- description
- type_image_path
- progress_percent
- page
Bind the data table to the data grid.
In the dataflow, create a "config" table for your data grid that looks like the table below. Use these column headings:
- selector (Use data table column names in this column. Names are case sensitive.)
- symbol (Use symbol names in this column. Names are case sensitive.)
- headingSym (Use symbol names in this column. Names are case sensitive.)
- sortable (Use boolean values.)
- heading_text
In the Outline, select the default column editor, which is named "Column 0", and set Type to Repeater.
With the "Column 0" column editor selected, create these bindings:
1. Bind the "config" table to Configuration Table.
2. Bind the selector column to the Selector property.
3. Bind the symbol column to the Symbol property.
4. Bind the headingSym column to the Header Symbol property.
5. Bind the sortable column to the Sortable property.
In the Outline, select the renderer, and bind data table columns to the path, progress_percent, and page properties.
Select the header renderer, and bind the heading_text column of the config table to the heading_text property.
Style the two remaining columns, either using the data grid Rows properties, or using custom symbols that you create.

Notes

You can bind to a Repeater column renderer property from either the data table or the configuration table.
If multiple symbol properties have the same name and data type and are used by the same Repeater column renderer, those properties will only appear once in the renderer properties and will share the same data binding.

Data Grid Properties

The following properties affect the data grid component. For data grids, you can customize properties for the header, rows, and columns.

For a guide to using the data grid component, see Data Grid.

Data grid components are also affected by Common Properties.

General Data Grid properties

Data Grid Header properties

Data Grid Row properties

Data Grid Column properties

General Data Grid properties

These properties affect the entire data grid. To see these properties in the Property Inspector, click on your data grid on the Stage or in the Outline.

Table

Table
Defines the table that the data grid uses as a data source.

The Table property

Column Filter

Column Filter
Specifies the columns for a filter, as a comma-separated list of table column names. Use the Filter Type property to specify whether these columns are shown in this data grid or hidden from it. The order of columns in a whitelist filter overrides the column order in the Outline and the source table.

The Column Filter property

Filter Type

Filter Type
Specifies how this filter handles the listed columns.

Whitelist
Only the listed columns are shown in this data grid. Columns appear in the order specified in the filter.

Blacklist
The listed columns are hidden from this data grid.

The Filter Type property

Sort Order

Sort Order
Specifies whether the data is sorted in ascending or descending order.

To change whether the data is treated as strings or numbers when sorted, open the dataflow for this data grid and edit the Sort block.

The Sort Order property

Sort Column

Sort Column
Specifies the name of the column by which to sort the data. Only works if the column has the Sortable property enabled.

The Sort Column property

Add Column

Add Column
Click this button to add a column editor to the Outline. Each column editor lets you edit the properties of a group of one or more data grid columns.

The Add Column property

Data Grid Header Properties

These properties affect the data grid header. There are four groups of Data Grid Header properties. To see these properties in the Property Inspector, click on Header in the Outline.

Header Text and Font

The Text and Font properties for headers are similar to those for text components.

Header Gridlines

These properties control the style of the vertical lines between column headings and the horizontal lines between column headings and category headings.

Header Horizontal Stroke Color

Header Horizontal Stroke Color
Defines the stroke color for the horizontal lines that divide the column headings and category headings.

The Header Horizontal Stroke Color property

Header Horizontal Stroke Style

Header Horizontal Stroke Style
Defines the stroke style for the horizontal lines that divide the column headings and category headings.

The Header Horizontal Stroke Style property

Header Horizontal Stroke Weight

Header Horizontal Stroke Weight
Defines the stroke weight for the horizontal lines that divide the column headings and category headings.

The Header Horizontal Stroke Weight property

Header Vertical Stroke Color

Header Vertical Stroke Color
Defines the stroke color for the vertical lines that divide the column headings.

The Header Vertical Stroke Color property

Header Vertical Stroke Style

Header Vertical Stroke Style
Defines the stroke style for the vertical lines that divide the column headings.

The Header Vertical Stroke Style property

Header Vertical Stroke Weight

Header Vertical Stroke Weight
Defines the stroke weight for the vertical lines that divide the column headings.

The Header Vertical Stroke Weight property

Header Fill and Stroke

The Fill and Stroke properties for headers are similar to those for most components.

Header Position and Size

This property controls the height of the header.

Header Height

Header Height
Defines the height of the header in pixels. A value of Auto makes the header height follow the size of its content.

The Header Height property

Data Grid Row Properties

These properties affect data grid rows. There are four groups of Data Grid Rows properties. To open these properties in the Property Inspector, click on Rows in the Outline.

Row Text and Font

The Text and Font properties for data grid rows rows are similar to those for text components.

Row Gridlines

These properties control the lines that divide the columns and rows.

Gridlines

Gridlines
Specifies whether the Property Inspector displays property editing options for horizontal gridlines, vertical gridlines, or both. Changing which gridline properties are displayed does not reset any properties.

The Gridlines property

Horizontal Line

Horizontal Line
These properties define the horizontal lines between rows. They are similar to the Stroke properties for most components

The Horizontal Line properties

Vertical Line

Vertical Line
These properties define the vertical lines between columns.They are similar to the Stroke properties for most components.

The Vertical Line properties

Row Fill and Stroke

The Fill and Stroke properties for rows are similar to those for most components. You can define fill and stroke for the types of rows listed in the table. In each case, the properties define the fill for the row, and the stroke that outlines the row.

Property	Description
Main Rows	The first group of alternating rows.
Alternate Rows	The second group of alternating rows.
Hovered Row	The row that the user mouses over.
Focused Row	The row that is in focus.
Selected Rows	The selected rows. Only works if selection is enabled for this data grid.

Row Position and Size

This property controls the row height:

Row Height

Row Height
Defines the height in pixels of each data grid row.

The Row Height property

Column Properties

These properties affect data grid columns. There are three groups of column properties. To open these properties in the Property Inspector, expand Column in the Outline, and select a column editor.

A column editor lets you edit the properties of a group of one or more data grid columns. To add a column editor, go to the General Data Grid Properties and click Add Column.

Column Editor Properties

These properties specify which columns this editor controls, as well as sorting and visibility for those columns.

Column Label

Column Label
Defines the label to be used as heading text for columns controlled by this column editor.

The Column Label property

Column Editor Type

Column Editor Type
Defines the kind of column group this column editor controls. See About Column Editors and Column Order

all 
An All column editor dictates that all of the columns from the source table are included in the grid, except for those that you filter out of the entire grid. Grid columns appear in source table order, unless you specify another order using a whitelist filter. Properties edited for this column editor apply to all columns.

name 
Each Name column editor dictates that one column from the source table is included in the grid. Grid columns appear in the order in which they appear in the Outline, unless you specify another order using a whitelist filter. Properties edited for this column editor apply to this column.

repeater
A Repeater column editor lets you use a configuration table to determine which source table columns appear in the grid, which symbols represent those columns (if any), and properties of the symbols.

The Column Editor Type property

Selector

Column Editor Selector
Specifies which column or columns this column editor controls. If the column editor type is All, this property does nothing. If the column editor type is Name, this property specifies the name of one column in the source table. If the column editor type is Repeater, this property specifies which column of the configuration table contains the data table column names.

The Selector property