Perspective - Table Scripting

This page details the various scripting, component, and extension functions available for Perspective's Table component.

Component Events

The Perspective Event Types Reference page describes all the possible component event types for Perspective components. Not all component events support each Perspective component. The Component Events and Actions page shows how to configure events and actions on a Perspective component. Component scripting is handled separately and can be accessed from the Component menubar or by right clicking on the component.

onEditCellCommit

This onEditCellCommit event is used with a runAction script on a table to take user entry and store it in the table or a database.

Provides a chance do something once a user has typed something into a cell. The user must commit the new value before the event will trigger. "Committing" a value depends on the type of value and how it's rendered. Numerical and text values can be committed by pressing "Enter" after typing a new value. Boolean values are typically committed via a click (such as in cases when the cell is rendered as a checkbox or toggle switches).

Additionally, the cell must first be editable (props.data.[rowNumber].[columnName].editable is set to true). The first cell in the default dataset on a newly created instance of the component demonstrates where the editable property must be positioned.

note

This component event is designed to be used in tandem with a script runAction. Within the script action, special properties and methods are available on the event object, which is passed to the script action as a parameter.

event.column

• Object Path

  • event.column

• Type

  • String

• Description

  • The name of the column under which the cell was edited.

event.row

• Object Path

  • event.row

• Type

  • Number

• Description

  • The unique row index as it is represented in the source data. Also known as the row ID.

event.value

• Object Path

  • event.value

• Type

  • Any

• Description

  • The value that was typed into the cell.

Example - Change the value in a cell

# This example will set the value of a cell, based on what the user typed into it.
 
# Get the value that was typed into the cell
valueToSet = event.value
 
# We need to set a value in a particular cell. The event object contains row and column properties
#  that report the position of the cell that was edited.
 
# If the data property contains an array, you would use the line below
self.props.data[event.row][event.column] = valueToSet
 
# If the data property contains a dataset, then you would want to use the following line instead
#self.props.data = system.dataset.setValue(self.props.data, event.row, event.column, valueToSet)

onSelectionChange

This onSelectionChange event will trigger when the selection in the chart changes.

note

The onSelectionChange event will fire on startup or mount if props do not equal the table components default selection config.

This component event is designed to be used in tandem with a script runAction. Within the script action, special properties and methods are available on the event object, which is passed to the script action as a parameter.

event.selectedColumn

• Object Path

  • event.selectedColumn

• Type

  • String or null

• Description

  • The name of the column that the selected cell is located under.

event.selectedRow

• Object Path

  • event.selectedRow

• Type

  • Number or null

• Description

  • The unique row index as it is represented in the source data. Also known as the row ID.

event.data

• Object Path

  • event.data

• Type

  • Array

• Description

  • Represents the currently selected entries. The contents of the array is based on the enabledRowSelection and enableColumnSelection properties as represented on the table below. The actual resulting value may include additional values if the selection mode on the table is set to "single interval" or "multiple interval".

Properties	Resulting return type	Output
enabledRowSelection: True enableColumnSelection: False	An array containing a number of JSON objects that each represent a single row. Each JSON object contains one key-value pair for each column on the table.	[{"city":"Folsom","country":"United States", "population":77271}]
enabledRowSelection: False enableColumnSelection: True	An array of JSON objects, where each object represents a separate row in the selected column. Each object contains a single key-value pair, where the key is the column name and the value is the value of the cell.	[{"city":"Folsom"}, {"city":"Helsinki"}, {"city":"Jakarta"},]
enabledRowSelection: True enableColumnSelection: True	An array containing a single JSON object, which can be treated like a Python dictionary.	[{"city":"Folsom"}]

onEditCellStart

This onEditCellStart event fires when the user starts editing a cell. For onEditCellStart, the value is the initial value before any edits.

note

This component event is designed to be used in tandem with a script runAction. Within the script action, special properties and methods are available on the event object, which is passed to the script action as a parameter.

event.column

• Object Path

  • event.column

• Type

  • String or number

• Description

  • The column the editing cell is positioned under.

event.row

• Object Path

  • event.row

• Type

  • Number

• Description

  • The unique row index as it is represented in the source data. Also known as the row ID.

event.rowIndex

• Object Path

  • event.rowIndex

• Type

  • Number

• Description

  • The row index as it is represented in the current visible data. Useful in cases where some of the rows are hidden, such as when filtering.

event.value

• Object Path

  • event.value

• Type

  • Any

• Description

  • The value of the cell before editing began.

onEditCellCancel

This onEditCellCancel event is fired when the user has canceled a cell edit and has exited editing mode by effectively pressing the escape key.

note

This component event is designed to be used in tandem with a script runAction. Within the script action, special properties and methods are available on the event object, which is passed to the script action as a parameter.

event.column

• Object Path

  • event.column

• Type

  • String

• Description

  • The column name of the cell being edited.

event.row

• Object Path

  • event.row

• Type

  • Number

• Description

  • The unique row index as it is represented in the source data. Also known as the row ID.

event.rowIndex

• Object Path

  • event.rowIndex

• Type

  • Number

• Description

  • The row index as it is represented in the current visible data. Useful in cases where some of the rows are hidden, such as when filtering.

event.value

• Object Path

  • event.value

• Type

  • Any

• Description

  • The value of the cell before editing began.

onRowClick

This onRowClick event is fired when a row in the table is clicked.

note

This component event is designed to be used in tandem with a script runAction. Within the script action, special properties and methods are available on the event object, which is passed to the script action as a parameter.

event.row

• Object Path

  • event.row

• Type

  • Number

• Description

  • The unique row index as it is represented in the source data. Also known as the row ID.

event.rowIndex

• Object Path

  • event.rowIndex

• Type

  • Number

• Description

  • The row index as it is represented in the current visible data. Useful in cases where some of the rows are hidden, such as when filtering.

event.value

• Object Path

  • event.value

• Type

  • PlainObject

• Description

  • The rows value as a JSON object.

onRowDoubleClick

This onRowDoubleClick event is triggered when a row in the table is double clicked.

note

This component event is designed to be used in tandem with a script runAction. Within the script action, special properties and methods are available on the event object, which is passed to the script action as a parameter.

event.row

• Object Path

  • event.row

• Type

  • Number

• Description

  • The unique row index as it is represented in the source data. Also known as the row ID.

event.rowIndex

• Object Path

  • event.rowIndex

• Type

  • Number

• Description

  • The row index as it is represented in the current visible data. Useful in cases where some of the rows are hidden, such as when filtering.

event.value

• Object Path

  • event.value

• Type

  • PlainObject

• Description

  • The rows value as a JSON object.

onSubviewExpand

This onSubviewExpand event is triggered when a row subview is expanded.

note

This component event is designed to be used in tandem with a script runAction. Within the script action, special properties and methods are available on the event object, which is passed to the script action as a parameter.

event.row

• Object Path

  • event.row

• Type

  • Number

• Description

  • The unique row index as it is represented in the source data. Also known as the row ID.

event.rowIndex

• Object Path

  • event.rowIndex

• Type

  • Number

• Description

  • The row index as it is represented in the current visible data. Useful in cases where some of the rows are hidden, such as when filtering.

event.value

• Object Path

  • event.value

• Type

  • PlainObject

• Description

  • The rows value as a JSON object.

onSubviewCollapse

This onSubviewCollapse event is triggered when a row subview is collapsed.

note

This component event is designed to be used in tandem with a script runAction. Within the script action, special properties and methods are available on the event object, which is passed to the script action as a parameter.

event.row

• Object Path

  • event.row

• Type

  • Number

• Description

  • The unique row index as it is represented in the source data. Also known as the row ID.

event.rowIndex

• Object Path

  • event.rowIndex

• Type

  • Number

• Description

  • The row index as it is represented in the current visible data. Useful in cases where some of the rows are hidden, such as when filtering.

event.value

• Object Path

  • event.value

• Type

  • PlainObject

• Description

  • The rows value as a JSON object.

Component Functions

.collapseSubviews()

New in 8.1.17

• Description

  • This function will collapse the specified row subviews. If no parameter is specified, this function will collapse all expanded subviews on the current page.

• Parameters

  • array rows - An optional array of indices of rows to collapse. Any argument that is not a list will throw an exception. A list of invalid indices will not throw an exception. Omitting this parameter will collapse all subviews.

• Return

  • Nothing

note

This function only operates on rows which are on the currently displayed page. For example, if you have a table that displays 25 rows per page and invoke self.collapseSubviews([100]) on page one, nothing will happen.

Changed in 8.1.28

Specifying a number of rows to collapse when using this function will now affect the actual number specified, instead of stopping at the end of the currently displayed page.

Additionally, there is a distinction between using row and rowIndex. Row refers to the true index of the row as it exists in the data, and is not affected by paging, sorting, or searching. RowIndex refers to the visual index of the row as it appears on the table and is affected by paging, sorting, and searching.

Example

# Collapse subviews for rows 1 and 3 if they exist. If the list does not match any indices that exist, nothing will happen.
self.getSibling('Table').collapseSubviews([1, 3])
 
# Collapse all expanded subviews.
self.getSibling('Table').collapseSubviews()
 
# The following lines are invalid and will throw an exception:
self.getSibling('Table').collapseSubviews(None)
self.getSibling('Table').collapseSubviews(3)

.expandSubviews()

New in 8.1.17

• Description

  • This function will expand the specified row subviews. This will only expand rows that are visible on the current page.

• Parameters

  • array rows - An array of indices of rows to expand. Any argument that is not a list will throw an exception. A list of invalid indices will not throw an exception. Omitting this parameter will expand all subviews.

• Return

  • Nothing

note

This function only operates on rows which are on the currently displayed page. For example, if you have a table that displays 25 rows per page and invoke self.expandSubviews([100]) on page one, nothing will happen.

Changed in 8.1.28

Specifying a number of rows to expand when using this function will now affect the actual number specified, instead of stopping at the end of the currently displayed page.

Additionally, there is a distinction between using row and rowIndex. Row refers to the true index of the row as it exists in the data, and is not affected by paging, sorting, or searching. RowIndex refers to the visual index of the row as it appears on the table and is affected by paging, sorting, and searching.

Example

# Expand subviews for rows 1 and 3 if they exist. If the list does not match any indices that exist, nothing will happen.
self.getSibling('Table').expandSubviews([1, 3])
 
# Expand all subviews.
self.getSibling('Table').expandSubviews()
 
# The following lines are invalid and will throw an exception:
self.getSibling('Table').expandSubviews(None)
self.getSibling('Table').expandSubviews(3)

Extension Functions

This component does not have extension functions associated with it.