Mashup Builder > Widgets > Advanced Grids > Properties for Advanced Grids
Properties for Advanced Grids
The advanced and tree grid properties in the Mashup Builder design view can vary depending on whether you are configuring the grid through the Mashup Builder, a static configuration, or through a service, a dynamic configuration. The following table lists all the properties available when configuring the grid from the Mashup Builder.
Properties that are only configurable from the Mashup Builder, and not through a dynamic configuration, are marked with an asterisk * in the table.
Property Name
Description
Base Type
Default Value
Bindable (Y/N)?
Applicable to Grid or TreeGrid?
Id*
A unique identifier used internally by ThingWorx.
INTEGER
Gridadvanced-<id>or
Treegridadvanced--<id>
N
Both
Type*
The widget type.
n/a
Grid-Advancedor Tree-Grid-Advanced
N
Both
DisplayName*
A user-defined name to identify the grid when displayed.
STRING
gridadvanced-nor treegridadvanced-n
N
Both
Description*
A user-defined description.
STRING
n/a
N
Both
Data*
Source of data that loads when the grid is launched.
If the grid is bound to a data source, a filled arrow appears: If there is no data source, appears.
INFOTABLE
n/a
Y
Both
ChildData*
Source of child data that loads dynamically when nodes are expanded.
If the grid is bound to a child data source, a filled arrow appears:
If there is no child data source, appears.
INFOTABLE
n/a
Y
TreeGrid only
ParentIDFieldName
Identifies the parent ID Field Name. This property is required to create the hierarchical tree structure.
* 
For the top-level row that does not have a parent, the value should be a forward slash (/).
STRING
parentId
N
TreeGrid only
IDFieldName
The primary key column for the grid. The values in this column act as unique identifiers for each row of data. This property is optional for the advanced grid but required for the tree grid.
When no field is specified, or if the specified field does not exist, the grid creates its own internal row ID.
* 
Row id indexes are required to start with index value of 1. An error appears in the JavaScript console when a row with an id of “0” (zero) is encountered and that row does not appear in the grid.
STRING
id
N
Both
IDPathSeparator
Enables configuring the path separator character.
The path separator character is used in Tree Grid for selections of rows that are dynamically loaded by the grid but are not loaded on the client side. See section Row Selection of Dynamically Loaded Rows.
STRING
:;
N
TreeGrid only
HasChildrenFieldName
Specifies the name of the column that indicates whether a row has child data available.
To indicate that the row does not have children, enter one of the following: ‘0’, 0, ‘false’, false, empty string, or undefined.
Any other value means that the row does have children.
STRING
hasChildren
N
TreeGrid only
Configuration*
If the grid is bound to a configuration service, a filled arrow appears:
If there is no configuration service, appears.
* 
Add is available for the Configuration property, that you use to enter a JSON in the page that opens. Add becomes Edit when you enter the JSON, click Done, and go back to the property panel.
STRING
n/a
Y
Both
IsEditable
Determines whether you can edit the values in grid cells when the grid appears in run time.
* 
To edit values in a specific column, you must also configure the column as editable. See the Cell Editing Options section in the Column Configuration from the Context Menu.
BOOLEAN
False
N
Both
EnableEditButtons
Activates the Edit, Save, and Cancel in the grid tool bar to manually save edits.
If you want changes to save automatically, set the IsEditable property described above. If you want to save changes manually, set the EnableEditButtons property.
See the Cell Editing in Advanced Grids for more information.
When you set this property, EnableAddDeleteButtons property appears in the mashup properties panel.
BOOLEAN
False
N
Both
EnableAddDeleteButtons
If you set this property to True,Add and Delete appear in the grid tool bar so that you can add or delete rows in the grid.
* 
Click Edit at run time to view Add or Delete in the tool bar.
BOOLEAN
False
N
Advanced Grid only
EditedTable
A bindable property that specifies an output location for updated values when cells are edited at run time. This property must be bound to an infotable update service to save the updated values. For example, bind to AddOrUpdateDataTableEntriesservice on a DataTable thing.
* 
Before using the EditedTable property, you must set the IsEditable property. In addition, specific columns must be configured as editable. See the Cell Editing Options in the Column Configuration from the Context Menu
INFOTABLE
n/a
Y
Both
DeletedTable
This property specifies an output location for rows that are deleted from a grid at run time.
This property must be bound to an infotable update service to save the updated values. For example, bind the property to the AddOrUpdateDataTableEntries service on a DataTable thing.
INFOTABLE
n/a
Y
Advanced Grid only
DefaultSelectedRows
Defines which row numbers are highlighted by default when the grid appears. Values can include comma-separated numbers and ranges.
Example: 1,2,4-5
The property can also be defined by a bound service. If service is bound appears.
If there is no service appears.
* 
This property has no effect if the RowSelection property is set to none. To select multiple rows, the RowSelection property must to be set to multi.
In a tree grid, default row selection depends on which rows are in view. When the ExpandLoadedRows property is set, all of the preloaded rows are expanded and the default selection starts at the top and counts down including both parent and child rows. If the preloaded rows are not expanded, the default selection starts at the top and incudes only parent rows.
STRING
n/a
Y
Both
SelectedRows*
Defines, through an INFOTABLE source, which rows are highlighted by default when the grid appears.
When used in a Tree grid, only the Row ID column is required to make row selections but you can include other columns.
In an Advanced grid, row selections are handled by binding the output of the SelectedRows parameter in a service to the input SelectedRows property on the grid.
This property is bindable in either an output or an input direction so that one entity can control the selection of rows in another. For example, one table can control the selection of rows in a second table, or you can use a 3D image to select rows in a table.
For the controlling entity, bind the service as an output INFOTABLE
For the entity being controlled, bind the service as an input INFOTABLE:
* 
This property has no effect if the RowSelection property is set to none. To select multiple rows, the RowSelection property must to be set to multi.
INFOTABLE
n/a
Y
Both
IncludeRowExpansionParents*
Determines whether parent rows that are not included in preloaded client-side data is included when selecting or expanding child rows. If True, the parent rows are fetched with the child rows so the hierarchy can be recreated.
* 
Depending on the depth and size of your data, using this property can affect grid performance. See Performance Guidelines for the Tree Grid Widget.
BOOLEAN
False
N
TreeGrid only
ExpandRows*
IDs of any top-level or child rows in the grid that should be expanded. Only the Row ID column is required to select rows for expansion.
INFOTABLE
n/a
Y
TreeGrid only
ExpandLoadedRows*
Automatically expands all preloaded data when the grid is launched.
* 
Multiple levels of preloaded data must be available. When this property is set, it affects the way rows are highlighted when DefaultSelectedRows are defined. This property must be turned off to use the PreserveRowExpansion property.
BOOLEAN
False
Y
TreeGrid only
ExpandRowOnDoubleClick
Expands a row with children when you double click the row or click the node icon.
In a JSON configuration service, the property name is: treeSettings.expandRowOnDoubleClick.
BOOLEAN
False
N
TreeGrid only
PreserveRowExpansion
Preserves row expansion selections when the grid is refreshed. When using this property, make sure the maxLevels property in your tree-loading data service is set to a value greater than the level you want to expand to. For more information about the data service, see Working with Tree Grid Data
* 
If the ExpandLoadedRows property is set, it overwrites this property and expands all the preloaded rows. To preserve a specific expansion of rows, turn off the ExpandLoadedRows property when you turn on PreserveRowExpansion. You must set the CookiePersistence property to preserve row expansion values.
BOOLEAN
False
N
TreeGrid only
RowSelection
Controls what row selection is possible to configure. Options: none, single, or multi.
* 
If none is selected, other row selection properties have no effect.
* 
When you set the IsEditable or EnableEditButtons properties, RowSelection property does not take effect in the grid. You can select rows when the grid is not in edit mode.
STRING
None
N
Grid only
AutoScroll
Controls whether or not the grid automatically scrolls to selected rows when the grid is resized or the service is refreshed.
BOOLEAN
False
N
Both
CookiePersistence*
Activates client-side persistence for certain column settings order, size, visibility, and sort order.
BOOLEAN
True
N
Both
EnableContextMenu*
Enables or disables the display of a grid context menu, at run time, that an end user can use to show or hide specific columns. Works in conjunction with CookiePersistence:
• If both properties are set – a user can show and hide columns and those selections persist.
• If EnableContextMenu is not set and CookiePersistence is set – a user cannot show or hide columns but previous selections persist.
• If EnableContextMenu is set and CookiePersistence is not set– You can show and hide columns, but only for the current request.
In a JSON configuration service, you can set the property as a top-level parameter as follows:
var config = {“enableContextMenu”: false,...}
BOOLEAN
True
N
Both
EnableSorting
Must be set for any type of column sorting to take place, including switching between ascending and descending from headers, the MultiColumnSortOrder property, or binding a sorting service. When this option is set, the following properties become available in the properties panel:
• QueryFilter – Bindable filter query to use with a data service
• Filter — Bindable event property to trigger a query data service
BOOLEAN
False
N
Both
MultiColumnSortOrder
Sets a default column sort order. Syntax: column name:order,column name:order
Example: office:asc,title:des
* 
You must set EnableSortingfor MultiColumnSortOrder to have any effect.
STRING
n/a
N
Both
EnableGridSearch
Places a toolbar with a global search box on the grid. When this option is set, the following properties become available in the properties panel:
• QueryFilter – Bindable filter query for use with a data service
• Filter – Bindable event property to trigger a query data service
BOOLEAN
False
N
Both
GridSearchLocation
Defines where to place the search box. This option only becomes available when the EnableGridSearch property is set.
STRING
n/a
N
Both
QueryFilter*
A bindable query property used to bind a query service as the input query parameter to control sorting, searching, and filtering of the data. This property becomes available when either the EnableSorting or EnableGridSearch properties are turned on. It can be set from the properties panel or from the context menu on the grid itself.
If you are using a data filter widget in your mashup, the output QueryFilter property can be bound to the input query property from either an Advanced or Tree grid widget. The grid combines all the query parameters to create a single output filter that is bound to the specified service. When the query filter is bound in both directions like this, filled arrows appear:
If there is no data filter widget and the binding is only in the output direction, one arrow is filled and the other is unfilled:
QUERY
n/a
Y
Both
EnableGridReset
Places a toolbar with a grid Reset button. Click Reset to clear all grid user settings stored in cookies and return the grid to its default configuration.
BOOLEAN
False
N
Both
EnableFilterEventOnConfigChange*
Switches event firing on or off when a configuration is updated from a service.
When this property is set, and a bound configuration is changed, a filter event is fired to update the data as well. If this property is not set, the filter event does not fire when the bound configuration is updated.
BOOLEAN
True
N
Both
EnableFooter
Enables a footer section in the grid. When you set this property to True, two additional properties named FooterData and TableFooterStyle are set.
The data in the footer section is bound using the FooterData property.
For more information, see Footer Section in Advanced Grids
BOOLEAN
False
N
Both
FooterData
Contains the data that appears in the footer of the grid.
INFOTABLE
n/a
Y
Both
GridResetButtonLocation
Defines where to place the grid reset button.
STRING
n/a
N
Both
RowFormat
Opens a dialog box where you can define optional row-based rules to apply dynamic State Formatting. These row-based rules can be over ridden by cell-based state formatting, which is available from the Configure Grid Columns option on the grid context menu.
STATE FORMATTING
State Formatting
N
Both
TableWrapperStyle
Defines the grid background styles. This adds outline color around the entire table and sets the background color. Attributes that are supported are line color, weight and type, background color, and alternate background color.
STYLEDEFINITION
DefaultTableWrapperStyle
N
Both
TableHeaderStyle
Defines the grid header styles.
STYLEDEFINITION
DefaultTableHeaderStyle
N
Both
FocusStyle
Defines the style of a row that has focus in the grid.
STYLEDEFINITION
DefaultFocusStyle
N
Both
RowBackgroundStyle
Defines a row background style. This adds background color, font color, and weight style. But it does not add line style to each row.
STYLEDEFINITION
DefaultRowBackgroundStyle
N
Both
RowAlternateBackgroundStyle
Defines a second row background style for alternate rows. This adds font color and weight style, but does not add line style.
STYLEDEFINITION
DefaultRowAlternateBackgroundStyle
N
Both
RowHoverStyle
Defines the style of a row when you place the pointer on a row. This adds background color and font to every cell. Line color, weight and type is applied only to the row on which the pointer is placed.
STYLEDEFINITION
DefaultRowHoverStyle
N
Both
RowSelectedStyle
Defines the style of a row when selected. This adds background color and font to every cell. Line color, weight and type is applied only to the selected row.
STYLEDEFINITION
DefaultRowSelectedStyle
N
Both
RowBorderStyle
Defines the row border styles. This adds line color, weight and type to horizontal sides of the cell.
STYLEDEFINITION
DefaultRowBorderStyle
N
Both
CellBorderStyle
Defines cell border styles. This adds line color, weight and type to vertical sides of the cell.
STYLEDEFINITION
DefaultCellBorderStyle
N
Both
ToolbarStyle
Defines styles for toolbars.
STYLEDEFINITION
DefaultToolbarStyle
N
Both
TableFooterStyle
Defines the style for footer section in the grid. This includes background color, border style, and font style.
STYLE DEFINITION
DefaultGridAdvancedFooterStyle
N
Both
TooltipStyle
Defines styles for tooltips.
STYLEDEFINITION
DefaultTooltipStyle
N
Both
SortAscendingStyle
Defines the style of the sort ascending icon.
STYLEDEFINITION
DefaultSortAscendingStyle
N
Both
SortDescendingStyle
Defines the style of the sort descending icon.
STYLEDEFINITION
DefaultSortDescendingStyle
N
Both
CellValidationErrorStyle
Defines the style of the cell when a validation error occurs.
STYLE DEFINITION
DefaultCellValidationErrorStyle
N
Both
CellValidationErrorTooltipStyle
Defines the style of the cell tooltip when a validation error occurs.
STYLE DEFINITION
DefaultCellValidationErrorTooltipStyle
N
Both
RowIconStyle
Defines the style of the folder icon for tree nodes.
STYLEDEFINITION
DefaultRowIconStyle
N
TreeGrid only
RowExpansionIconStyle
Defines the style of the expansion icon for tree nodes.
STYLEDEFINITION
DefaultRowExpansionIconStyle
N
TreeGrid only
RowCollapseIconStyle
Defines the style of the collapse icon for tree nodes.
STYLEDEFINITION
DefaultRowCollapseIconStyle
N
TreeGrid only
HeaderOverflow
Provides options for handling header cell text that overflows. Options:
• fitted – Text is fitted to the column width and subsequently wraps, even in mid-word.
• wrapped – Text wraps to additional lines on white space or a dash.
• clipped – Text is cut off at the end of the header cell.
• ellipsis – Text is cut off but with an ellipsis (…) to show there is more text.
• tooltip – Text is cut off with an ellipsis (…) and full text appears in a tooltip
STRING
tooltip
N
Both
DataOverflow
Provides options for data cell text that overflows. The same options are available as in the HeaderOverflow property.
STRING
clipped
N
Both
MaxHeaderHeight
The maximum height in pixels to which the header row can expand before vertical scroll bars appear.
NUMBER
100
N
Both
MinRowHeight
The minimum height setting in pixel for a row in the grid.
Suppose you are not using an image renderer for a column that is showing images that are larger than the default minimum row height of 30 pixels. An example is a state definition that applies styles containing images. In this case, ensure you enlarge the row height setting to accommodate the height of the image.
NUMBER
0
N
Both
MaxRowCacheSize
The maximum number of rows that you can expand, client-side, in the grid. When the limit is reached, a warning is generated, and nodes must be collapsed before additional expansion.
NUMBER
5000
N
TreeGrid only
DoubleClicked*
A bindable event property fired when the grid is double-clicked.
EVENT
n/a
Y
Both
Filter*
A bindable query property used to bind a query service as the input query parameter to control sorting, searching, and filtering of the data. This property becomes available when either the EnableSorting or EnableGridSearch properties are turned on. It can be set from the properties panel or from the context menu on the grid itself.
EVENT
n/a
Y
Both
EditCellStarted
A bindable event property that can be triggered when you begin to edit a cell value. This is only active when the IsEditable parameter is set.
You can use this event to change the state of other widgets in the mashup on editing.
EVENT
n/a
Y
Both
EditCellCompleted
A bindable event property that can be triggered when you edit a cell and then either press ENTER, TAB, or anywhere outside the edited cell. Press ESC to leave the value unedited. When the grid is refreshed, the edited values appear.
Two uses for this event follow:
• It can be bound to an infotable update service so that edited values from the EditedTable infotable are persisted.
• It can be bound to a service that enables a Save button widget in the Mashup. The Save button can, in turn, be bound to an infotable update service so that updated values from the EditedTable infotable are persisted.
EVENT
n/a
Y
Both
EditStarted
This event is triggered when you click Edit in the grid tool bar.
EVENT
n/a
Y
Both
EditCompleted
This event is triggered when you click Save in the grid tool bar.
EVENT
n/a
Y
Both
EditCancelled
This event is triggered when you click Cancel in the grid tool bar.
EVENT
n/a
Y
Both
Z-index*
The ordering for layered widgets. A lower Z-index moves the grid widget behind another widget with a higher Z-index.
NUMBER
10
N
Both
Visible*
If set, the grid displays in run time. This property can be defined by a service bound to the grid. If a visible service is bound to the grid, a filled arrow appears:
If there is no visible service, appears.
BOOLEAN
True
Y
Both
SelectedRowsChanged*
A bindable event property that you can use to trigger another widget or service when you select or deselect one or more rows in the grid.
To use this event property, follow these steps:
• Set the RowSelection property to single or multi.
• Bind the SelectedRowsproperty to another entity (a widget or service).
• Bind the SeletedRowsChanged event to the other entity so that it is triggered when SelectedRows changes.
EVENT
n/a
Y
Both
* When a configuration service is bound to the grid, only the starred properties appear in the Properties panel of the Mashup Builder. All of the other properties are hidden from view because those parameters are passed in from the JSON service.
* 
Grid Styles take precedence over one another in the order listed below, with TableWrapperStyle having the lowest priority, and RowHoverStyle overriding all others.
1. TableWrapperStyle
2. RowBackground/RowAlternateBackgroundStyle
3. CellBorder/RowBorderStyle
4. FixedRowFormatter/State Definition
5. RowSelectedStyle
6. RowHoverStyle
Was this helpful?