ptcs-grid¶

Overview¶

The ptcs-grid component displays data in tabular format. Each data item is represented by a grid row that contains one or more cells. You can customize the content of each cell. In a typical configuration, the data item is a JavaScript object and each cell corresponds to a field in that object. Additional objects types are also supported.

The grid component can manage large data sets that contain 100,000 data items. Larger data sets with up to one million data items were tested and are manageable, with some operations such as sorting taking more time.

Data Manager¶

The grid component reads its data from a data manager, which is used to perform all operations on the data, such as:

filtering,
sorting,
selections,
grouping,
hierarchical items (tree grid),
creating, updating, deleting,
exporting,
lazy loading,

and more.

The data manager must provide information about the number of items it contains, and return any item when a request is sent.

If the data manager has dynamic content or dynamic views, it must send updates about any changes using change events. For example, the data manager must send a change event when data is filtered, sorted, or grouped.

View Configurator¶

The grid displays each item using configurations from a view configurator.

The view configurator provides two types of view configurations:

The column header, which defines the grid layout.
Row configurations, which defines a row configuration for a specific data item. The row configuration defines the user interface controls that should be used for the various cells in the data row.

Usage Examples¶

Basic Usage¶

<ptcs-grid data="[[dataMgr]]" view="[[viewCfg]]"></ptcs-grid>

Component API¶

Properties¶

Property	Type	Description
data	Data Manager	Specifies the data manager. Refer to the detailed section about the data manager below.
disabled	Boolean	Disables the grid
disableRow	Function or String	A function that specifies if a row should be disabled. The function is called as `disableRow(item, baseIndex, dataManager)`. If the function returns `true`, the row that corresponds to the item is disabled. As syntactic sugar, `disableRow` can also be supplied as a string. In that case the grid creates the following function: `item => item[disableRow]`. That is, if `disableRow` is a string it specifies a field in the row object that in turn specifies if the item is disabled or not.
filterHintText	String	The hint text to display in the quick filter box
filterString	String	The string for the filter query
showFilter	Boolean	Shows or hides the grid filter (a.k.a. simple / quick filter)
filterWidth	Number	Sets a specific width in pixels for the quick filter box, although actual width may be limited by CSS `min-width` on part `filter-field`
quickFilterMinWidth	Number	Read-only property returning the quick filter's min-width, if any
hideHeader	Boolean	Enables you to hide the grid header
items	Array	A simpler interface for specifying data: if `items` is assigned, the array is forwarded to `data` - if `data` is an instance of the default data manager. If `data` is unassigned, the grid instantiates a default data manager and assign `items` to it.
label	String	Enables you to specify the grid title
labelVariant	String	Specifies the variant of the grid title
labelAlignment	String	Enables you to set the title alignment to the "left", "center", or "right".
filterLabel	String	Enables you to specify a title for the grid filter
clearFilteredSelection	Boolean	Clears the selected rows when filtering the grid data.
selectedIndexes	Array	Array of selected items indexes. The indexes are base indexes, not row indexes. This property can be used both for selecting items and for checking which items are selected. It is automatically updated when the user selects or unselects rows. Note that `selectedIndexes` is an array even if `selectMethod` is `'single'`.
selectedItemText	String	The text to display next to the filter label when a single item is selected (default value: 'Selected Item').
selectedItemsText	String	The text to display next to the filter label when two or more items are selected (default value: 'Selected Items').
hideMessage	Boolean	Hide the grid message? (Ignore bindDataText, noDataToDisplayText, noResultsText, noMatchesText?)
bindDataText	String	Prompt to bind data to the grid, shown in the message area (default value: 'Bind data to the grid')
noDataToDisplayText	String	Alternative text shown in the message area when there is no data binding (default value: 'There is no data to display.')
noResultsText	String	Text shown in the message area when there is bound data but no rows to show (default value: 'No Results.')
noMatchesText	String	Text shown in the message area when data filtering causes all rows to be filtered out (default value: 'No matches found.')
selectMethod	String	Sets the selection method of `data`.
selectRow	Boolean	Allow users to select grid rows using the mouse or the keyboard.
view	View Configurator	Sets the View Configurator. Refer to the detailed section about the view configurator below.
cacheRuntimeChanges	Boolean	Should we store user interactions in browser local storage? (effective only when gridId is defined)
preserveRowExpansion	Boolean	Should we store expanded rows in browser local storage? (effective only when gridId is defined and cacheRuntimeChanges is true)
gridId	String	Associated unique ID for saving the grid's client configurations (sort, order, widths, visibility, expanded) in browser local storage.
dataLoading	Boolean	Set to `true` to show the "data loading" indicator when starting to load data, and to `false` to hide the indicator
loadingIndicatorSize	Number	Container size in pixels (same height / width) for the data loading indicator (default: 200)
loadingIndicatorDelay	Number	Delay before displaying the loading indicator, in ms (default: 1000)
loadingIndicatorImage	String	The url of a custom loading indicator image, that replaces the default indeterminate progress bar load indicator. If the image load fails, the default loading indicator is used as fallback.
showResetButton	Boolean	Shows a button that resets the grid back to its default configuration when changes are made at run time.
resizeColumns	Boolean	Enables to adjust the width of grid columns by dragging the divider lines.
reorderColumns	Boolean	Allows the user to reorder columns in runtime using drag and drop.
rowEditFormTitle	String	Title for the Row Edit form when it edits an existing row..
rowEditFormAddTitle	String	Title for the Row Edit form when it adds a new row.
updateButtonText	String	Label for Save button in Row Edit Form when it edits an existing row.
addButtonText	String	Label for Save button in Row Edit Form when it adds a new row.
applyButtonText	String	Label for Apply button in Column Reorder Form.
cancelButtonText	String	Label for Cancel button in Column Reorder Form and Row Edit Form.
isEditable	Boolean	Specifies the editing mode. If `true`, then any editable cells can be edited. Otherwise the grid is read-only. If `showEditButton` is `true`, the default value for `isEditable` is `false` and it will not become `true` until the `Edit` button is clicked.
edit	String	Specifies inline editing mode: `'cell'` for cell editing or `'row'` for row editing. All changes will be submitted as soon as they are valid. If `edit` has the value `grid`, the grid uses `cell` editing, but doesn't submit the changes until the user presses the `Save` button or the method `commitUpdates` is called.
showEditButton	Boolean	When this property is `true`, buttons are displayed on the grid toolbar that enable you to turn editing mode on or off. Initially, only the `Edit` button is displayed. When the `edit level` is set to `grid` and `Edit` is clicked, the `edit-started` event is triggered and the `Edit` button is replaced by `Save` and `Cancel` buttons. When the `Save` button is clicked, the `edit-completed` event is triggered and the editing mode is stopped. When the `Cancel` button is clicked, the `edit-cancelled` event is triggered and the editing mode is stopped. The save and cancel buttons are only available when editing on a grid level. Grid-level editing enables you to save all modifications to grid cells at the same time. Cell level and row level editing will immediately save the edits to a cell or a row. When the edit mode is stopped, the `Save` and `Cancel` buttons are hidden and the `Edit` button is displayed again.
editButtonText	String	Label for the `Edit` toolbar button (only visible if `showEditButton` is on). Default: `'Edit'`.
saveEditButtonText	String	Label for the `Save` toolbar button (only visible if `showEditButton` is on). Default: `'Save'`.
cancelEditButtonText	String	Label for the `Cancel` toolbar button (only visible if `showEditButton` is on). Default: `'Cancel'`.
editControlVisibility	String	Specifies how to show the edit control in `'cell'` edit mode: `'hover'` (default), `'always'`, or `'never'`. Note that the `'never'` option effectively disables editing, unless `inlineEditing` is `true`.
inlineEditing	Boolean	Enable inline editing? Ignored unless `edit` is `'cell'` or `'grid'` and `editControlVisibility` is `'never'`.
showDeleteRowButton	Boolean	Show a Delete Row button in the grid toolbar that allows the user to delete the selected rows?
deleteRowButtonText	String	Label for the Delete Row toolbar button. Default: `'Delete'`
showAddRowButton	Boolean	Show an Add Row button in the grid toolbar that allows the user to add new rows?
addRowButtonText	String	Label for Add Row toolbar button. Default: `'Add'`.
editControl	String	Specifies the edit control. The edit controls the edit activator, that the user can click on to edit a cell or row. Supported values: `'icon'` (default), `'link'`, or `'none'` (= disable editing)
editControlLabel	String	Specifies the label for the `'link'` edit control.
editControlIcon	String	Specifies the icon for the `'icon'` edit control.
highlightDrafts	Boolean	Highlight cells that contains a value that has been changed by grid inline editing.
highlightNewRows	Boolean	Highlight newly added rows with a "change badge" marker.
columnsMenuOptions	String	Enables user to show and hide specific columns using a check box, and change the order of the columns by dragging.
columnsMenuVisibleItems	Number	Sets the number of items to display initially when the columns configuration menu is opened.
columnsMenuReorderTooltip	String	Tooltip for the reorder icon in the columns configuration menu.
columnsMenuVisibilityTooltip	String	Tooltip for the column visibility checkbox in the columns configuration menu.
navigation	String	Specifies the focus navigation method. Possible values: `'row-first'` (default), `cell-first`, `cell-only`
preventFocusRowWrap	Boolean	Prevents the left and right arrow keys from navigating to next or previous row. Default: false
selectFollowsFocus	Boolean	In single selection mode, automatically selects the focused row. Default: false
autoScroll	Boolean	Keeps selected rows visible by scrolling automatically when the grid is updated or resized.
footerData	Array	A JS object that contains data for the grid footer. Refer to the detailed section about the grid footer.
showFooter	Boolean	Adds a footer area to the grid.
showHeaderRowInFooter	Boolean	Shows the header row within the grid footer.
deleteRowsConfirmation	Boolean	Prevents the `deleteSelectedRows` method from being executed after pressing the `delete` button. It can be used together with the `delete-row-clicked` event to add a custom confirmation step before calling the `deleteSelectedRows` manually.
customActions	Action[]	Actions to display on the grid toolbar.
customActionsPosition	String	Position of the toolbar actions relative to the edit, add, and delete buttons on the grid. Possible values: `'after'` (default), `'before'`, `'none'`.
preventDoubleClickedEvent	Boolean	Prevents text selection on double click.

Additional properties for the Tree Grid¶

Property	Type	Description
subItems	String	For tree grids: specifies a field name in the data item that contains sub-items
alwaysExpanded	Boolean	If true, then all sub-items will always be visible and the tree toggle icons are automatically hidden.
showExpandAll	Boolean	If true, the grid displays a button in the toolbar that allows the user to expand or collsapse all sub-items.
expandAllText	String	The label of the `showExpandAll` button when it expands all sub-nodes. Default: `'Expand All'`
collapseAllText	String	The label of the `showExpandAll` button when it collapses all sub-nodes. Default: `'Collapse All'`
disableChildRows	Boolean	Works together with `disableRow`. If `disableChildRows` is true, items will be disabled if any ancestor item is disabled.

Using the Data Manager Interface¶

To use a data manager with the grid, it should have the following methods and properties:

data.observe(cbObj)

The method registers cbOoj as an observer to state changes in the data manager.

Each change event corresponds to a function name. If the object cbObj has a corresponding function, the event is sent to that function.

In ThingWorx, 9.2, the grid component monitors the following events:

dmView() - Triggered when the data view is updated through sorting, filtering, or grouping.
dmItem(index) - Triggered when data item with index index is updated.
dmInserted([[index, count], ...]) - Triggered when count items are inserted, starting at the index. Note that several segments can be inserted at the same time.
dmRemoved([[index, count], ...]) - Triggered when count items are removed, starting at index. Note that several segments can be removed at the same time.
dmSelected(baseIndex, selected) - Triggered when an item with the base index baseIndex is selected (selected is true) or unselected (selected is false).

The baseIndex persists to a specific data item, including when the data is sorted, filtered, grouped, and more. However, some operations such as adding or removing items can affect the baseIndex persistence.

data.unobserve(cbObj);

Use the unobserve() method to stop the cbObj observer from listening to the data manager events.

data.length

Returns the number of data items in the data manager.

data.item(index)

Returns the data item that corresponds at a specific index number.

The index is a zero-based index with a value between 0 and data.length - 1.

Note: The item is used as an input for methods in the view configurator and it is not interpreted by the grid.

data.isSelected(index)

Returns true if a data item at a specific index number is selected, and false in any other case. The grid uses the returned value to set or unset the selected attribute on the corresponding row element.

data.selectMethod

The property (or get function) specifies the data selection mode using one of the following options:

none - disable selection
single - select one item at a time
multiple - select multiple items at the same time

data.baseIndex(index)

Converts the current index into a persistent base index that is not affected by changes to the view. When index does not correspond to an item, such as a virtual grouping item, the method returns -1.

The base indexes are used to maintain the selection when the data view is changed by sorting, filtering, or any additional changes to the data projection.

data.setSelected(selected, directSelection)

Set the selected items. The directSelection argument indicates whether the unselection was direct or non-direct.

data.select(baseIndex, selected, directSelection)

Controls the selection of the item using the index number and based on the value of the selected variable. The item is selected when selected is True unselected when False. When selected is set to undefined, the method toggles the selected state of the item. The directSelection argument indicates whether the unselection was direct or non-direct.

data.selectAllItems(directSelection)

Selects all items. The directSelection argument indicates whether the selection was direct or non-direct.

data.unselectAllItems(directSelection)

Unselects all items. The directSelection argument indicates whether the unselection was direct or non-direct.

data.directSelection

Returns true if the row or rows selection was direct, and undefined or false if triggered from other data service. A direct selection is when a user selects grid rows using the mouse or the keyboard.

View Configurator interface¶

The grid expects that the view configurator has the following methods or properties:

view.singleLineHeader

Displays each column label on the grid header as a single line of text.

view.maxHeightHeader

Sets the maximum height of the grid header when it is displayed across multiple lines.

view.singleLineRows

Use this property to display the grid rows on a single line.

view.maxHeightRow

Sets the maximum height of the grid rows when each row is displayed across multiple lines.

view.minHeightRow

Sets the grid minimum height of each row on the grid.

view.sortSelectionColumn

Adds a sort button to the row selection column.

view.externalSort

Controls whether an internal sort function is applied or an external sort is used when you click to sort a column.

view.getSortExpression()

Gets the current sort expression based on column names and sort orders.

view.setSortExpression(expr, dataManager, opt)

Applies a sort expression to the grid. Set opt.noOrder to true to reset only the sort icons. Set opt.reset to true to reset current sort order.

view.getOrderExpression()

Get the current columns order.

view.getWidthsExpression()

Get the current widths expression based on column names and widths.

view.getVisibilityExpression()

Get the current visibility expression based on column names and its hidden property.

view.observe(cbObj);

Registers cbOoj as an observer to any state changes in the view configurator.

Each change event corresponds to a function name. If the object cbObj has a corresponding function, the event is sent to that function.

In ThingWorx, 9.2, the grid component observes one event:

dvChanged() - Triggers when the view configuration changes, which allows the grid to refresh the current view.

view.unobserve(cbObj);

Stops the cbObj observer from observing the view configurator events.

view.columns

The columns property (or get function) contains an array that defines the grid columns. Each array item is an object that contains the following fields:

col.name¶

Specifies the identifier of the column. Optional. Required only if you want to show a footer data for this column.

In order to not interfere with the internal view expression syntax (used to capture e.g. column widths, order, or visibility), ASCII colon or comma appearing in column names will internally be replaced by other strings within such expressions.

col.label¶

Specifies the title in the column header. It is either a string or a function. If it is a string it will be displayed using a ptcs-label component. If it is a function, it returns a single element which may contain sub-elements, that is used as the column header.

col.width¶

Sets the column width. For variable widths, set the value using fractions or percentage (fr) units.

col.minWidth¶

Sets the minimum column width, width when the col.width property contains is a variable width.

col.maxWidth¶

Sets the maximum column width, width when the col.width property contains is a variable width.

col.headerHAlign¶

Sets the horizontal alignment of the column header label to one of the following options:

'left'
'center'
'right'

col.headerVAlign¶

Sets the vertical alignment of the column header label to one of the following options:

'top'
'center'
'bottom'

col.halign¶

Sets the horizontal alignment of content within the column cells to one of the following options:

'left'
'center'
'right'

col.valign¶

Sets the vertical alignment of content within the column cells to one of the following options:

'top'
'center'
'bottom'

col.resizable¶

Returns a True value when column can be resized by the user using mouse or keyboard interaction (not implemented yet).

col.hidden¶

Returns a True value if the column is hidden.

view.getRowDef(item);

Returns the row configuration of an item. The row configuration is an array, where each array item defines a specific cell. It is an object with these fields:

row.create¶

row.create is a function that creates the cell content. It is called with a single parameter: the cell element where the result is placed. This allows the create function to mark the cell with extra styling or attributes, giving it control over the whole cell area.

Note that the returned element is not yet bound to a data item. The element may be reused for many items, which can improve performance.

row.select¶

Retrieves the cell data from a data item. The function is called with two parameters:

row.select(item, index);

item - the data item from the data manager
index - the index number of the item

The returned value is assigned as a value property to the cell element, which makes the cell available for state formatting, and also sent to row.assign().

row.assign¶

Binds an element that is created by the row.create() function to a data item. The function is executed with four parameters:

row.assign(element, value, index, dataManager);

element - the element created by the row.create()
value - the value selected by row.select()
index - the index of the corresponding data item
dataManager - the data manager that contains the data item

The two latter arguments is mainly intended for inline cell editing, which allows the editor to send any changes to the data manager.

row.halign¶

row.halign sets the horizontal alignment of the cell to one of the following options:

'left'
'center'
'right'

row.valign¶

row.valign specifies the vertical alignment of the cell to one of the following options:

'top'
'center'
'bottom'

See the example of the grid footer object. When you create your own footer data you should ensure same field names in the footer data as are used in the actual grid data.

grid.footerData = [
    {
        avatar:     'Footer Area',
        title:      '#cspan',
        name:       'Total Count: {#stat_count}, text-align:right;',
        department: '#cspan',
        linkedin:   '#cspan',
        born:       'Average Age:, text-align:right;',
        age:        '{#stat_average}',
        desc:       '#cspan'
    }
];

{#stat_count} - Counts the number of rows.

{#stat_max} - Calculates the maximum client-side value for the values in the column. Limited for numbers and dates only.

{#stat_min} - Calculates the minimum client-side value for the values in the column. Limited for numbers and dates only.

{#stat_average} - Calculates the average client-side value for the values in the column. Limited for numbers only.

{#stat_total} - Calculates the total client-side value for the values in the column. Limited to numbers only.

{#cspan} - Span columns.

You can align data in the footer using #cspan and text alignment settings text-align:left or text-align:right. Use HTML escape characters for comma in text, and the text following the comma is the alignment setting in the configuration, which is by default text-align:left.

Events¶

Name	Event.detail	Description
edit-started		Generated when the user clicks on the `Edit` button.
edit-completed		Generated when the user clicks on the `Save` button.
edit-cancelled		Generated when the user clicks on the `Cancel` button.
add-row		Generated when the user clicks on the `Add Row` button.
edit-item-started	{item, field, baseIndex}	Generated when the user begins inline editing: `item` is the edited item. `field` is the edited field, if `edit` mode is `'cell'` (otherwise `field` is undefined). `baseIndex` is the base index of the edited item. If a new item is being created, only `baseIndex` is present, with the value `-1`.
edit-item-cancelled	{baseIndex, field, item}	Generated when the user stops inline editing without making any changes.
edit-item-completed	{baseIndex, field, item, update, validation}	Generated when the user has completed an inline change. `item` contains the updated item and `update` contains the actual changes. `validation` contains any validation errors for the changes.
reset-to-default		Generated when the user clicks on the `Reset` button.
row-click	{ value: row index }	Generated when the user clicks on a row.
row-double-click	{ value: row index }	Generated when the user double clicks on a row.
delete-row-clicked	{rowsIndex: rows indexes}	Generated when the user clicks on the `Delete` button (row deletion).
custom-actions-activated	{ action, value }	Event generated from the toolbar custom actions. It's triggered when the user clicks on a `button` or `link`.
custom-actions-value-changed	{ action, value }	Event generated from the toolbar custom actions. It's triggered when the value of a `toggle` or `dropdown` changes.

NOTE: The data manager and view configurator also generates various events.

Methods¶

Name	Argument	Type	Description
isIndexSelected	index	Number	Returns true if the item with the base index `index` is selected.
isRowSelected	index	Number	Returns true if the item on the row at index `index` is selected.
selectIndex	index	Number	Base index for item
	select	Boolean	`false`: unselect item. `true`: select item. `undefined`: toggle item selection state.
selectRowIndex	index	Number	Row index for item (dependent on filtering, sorting, ...)
	select	Boolean	`false`: unselect item. `true`: select item. `undefined`: toggle item selection state.
scrollTo	index	Number	Scrolls the item with the specified index number into the current view.
getSortExpression			Returns the value of getSortExpression() from the view configurator
setSortExpression	sortExpression, opt		Forwards the call to setSortExpression() in the view configurator
getOrderExpression			Returns the value of getSortExpression() from the view configurator
getWidthsExpression			Returns the value of getSortExpression() from the view configurator
getVisibilityExpression			Returns the value of getSortExpression() from the view configurator
rollbackUpdates			Rollback all unsubmitted changes made by the grid inline editing
commitUpdates			Submit all changes made by the grid inline editing - including invalid changes.
deleteSelectedRows			Removes the selected rows from the grid.
modifyCustomAction	actionId, value, updateType	String, , String	Modifies the toolbar according to the updateType (`'value'`/`'disabled'`/`'visible'`)

Styling¶

Parts¶

Part	Description
body-cell	A data cell
header-cell	A header cell
header	The grid header row
header-label	The column label in header cell
row	A data row
cell-link	A link in a cell

States¶

Attribute	Description	Part
disabled	Indicates whether the grid is disabled	:host

Subcomponents¶

The grid has subcomponent ptcs-quick-filter with following parts:

Part	Description
label	The filter label
filter-field	The filter textfield
filter-label	Displays the number of selected rows when the grid selection mode is `multiple`

The grid has subcomponent ptcs-data-load-bar with following parts:

Part	Description
bar-container	The container for the indeterminate progress bar or custom image
track	The default progress bar (a horizontal track with a moving slider)
slider	The moving part within the track
image	The custom image that replaces the default progress bar

TODO¶

rows spanning multiple columns
resize columns with mouse interaction
drag and drop reordering of columns
drag and drop reordering of rows (or?)
pinned rows and columns (the row / column stays in place regardless of scrolling)
allow runtime user to dynamically show / hide columns
keyboard interaction for resizing columns
keyboard interaction for moving columns
keyboard interaction for moving rows (or?)
pagination
tile / card layout
ARIA attributes