Dynamic Tree Grid Control API

The Dynamic Tree Grid Control is available in Effectivity Services. This section describes the API. The Dynamic Tree Grid control is inherited from the TreeGrid component and has all its public methods, fields, and events.

Table 5 describes two parameters that the constructor supports.

Constructor-supported parameters

DynamicTreeGrid does not have its own public fields. It uses the base TreeGrid component public fields.

You can add and remove Events using the “on” and “off” public methods.

Each event listener callback accepts a single parameter: an event object of the type “CustomEvent” containing a “detail” property with specific event information.

Event fired after each row is added to the grid when adding rows using the “addRows” or “loadData” methods.

Property details for addRow

Event fired after all rows are added using the “addRows” or “loadData” methods.

Property details for addRows

Event fired after deleting a row from the grid using the “removeRow” method.

Property details for removeRow

Event fired after deleting all rows from the grid using the “removeAllRows” method.

Property details for removeRows

Event fired after adding a new column using the “addColumn” or “loadData” methods.

Property details for addColumn

Event fired after deleting a column using the “removeColumn” method.

Property details for removeColumn

This section describes common objects frequently used in the DynamicTreeGrid public methods.

A Metadata object is an object that contains additional information about a cell that is required for the grid editors and formatters to render the cell properly.

A Metadata object can have the following properties:

• formatter – optional property.

The formatter name used to display cell content. If you do not specify a “formatter” property, the formatter type is determined by the grid based on the cell value. E.g., if the cell value is a string the ‘text’ formatter will be used, and if the cell value is boolean the ‘boolean’ formatter will be used.

• editor – optional property.

The name of the editor used to display cell content when the cell is in the edit state. If you do not specify an “editor” property, the editor type will be determined by the grid.

• Other properties that can be used in the formatter and editor functions from the “metadata” parameter.

Example:

{

formatter: ‘select’,

editor: ‘select’, 

options: [

{label: ‘Red’, value: ‘id1'}, 

{label: ‘Green’, value: ‘id2'}, 

{label: ‘Blue’, value: ‘id3'}

]

}

The Column settings object contains additional settings applicable to the corresponding column. If a grid is not editable/resizable/sortable, then you cannot edit/resize/sort columns. However, if the grid is editable/resizable/sortable you can adjust these columns. The Column setting does not change when the corresponding grid setting is changed. The Column settings object can have the following optional properties:

• resizable enables you to decide whether to resize a column. The default value is obtained from grid settings when adding a new column.
• editable enables you to decide whether to edit cells in this column. The default value is obtained from grid settings when adding a new column. This setting value will be used as a default value for the cell’s editability setting when adding new rows. You can also use the “setCellEditability” and “getCellEditability” methods to set/get cell editability.
• sortable enables you to decide whether to sort by this column. The default value is obtained from the grid settings when adding a new column.
• visible enables you to decide if the column should be visible or not. The Default value is true when adding a new column.

Example:

{

resizable: false,

sortable: true,

editable: false,

visible: true

}

The Column object is used in the “loadData” and “addColumn” methods. It can contain the following properties:

• name – required property. Column name.
• label – optional property. The column name is used as the label if the “label” property is not set.
• width – optional property. The width is calculated automatically based on the column label if the “width” property is not set.
• metadata – optional property. It contains a metadata object for all cells in this column. Column metadata is used only for cells without their own metadata.
• settings – optional property containing settings that are applied to the corresponding column.

Example:

{

label: ‘Column 1’,

width: 100,

name: ‘property1,

metadata: {

formatter: ‘boolean’

},

settings: {

resizable: false,

editable: false

}

}

The Row object is used in the “loadData” and “addRows” methods. It can contain different properties. If the row object property name matches the column name, then its value is used as a cell value. The Row object property is updated automatically when the corresponding grid cell value is changed. Example:

{

property1: ‘value 1’,

property2: ‘value 2’,

someOtherProperties: ‘additional property’

}

Initializes the grid with specified rows and columns. If the “columns” parameter is not specified, the columns will be obtained automatically from the “rows” parameter. Each unique property of the row object will represent a column with the same name. If both the “rows” and “columns” parameters are not specified, the method removes all existing rows and columns.

Optional Input parameters for loadData

Return value Array – an array that contains the IDs of the added rows. Example of the “rows” array parameter:

[

{

property1: ‘row 1’,

property2: ‘value2’,

someOtherProperties: ‘additional property’

},

{

property1: ‘row 2’

}

]

Example of the “columns” array parameter:

 [

{

label: ‘Column 1’,

width: 55,

name: ‘property1,

metadata: {

formatter: ‘select’,

editor: ‘select’, 

options: [

{label: ‘Red’, value: ‘id1'}, 

{label: ‘Green’, value: ‘id2'}, 

{label: ‘Blue’, value: ‘id3'}

]

}

},

{

name: ‘property2’,

settings: {

resizable: false,

sortable: true,

editable: false

}

}

]

obtainRowID is an overridable handler which should return a unique row id for the given row object when adding new rows using the “loadData” or “addRows” methods. It returns null by default. The Unique row id will be generated automatically if the handler returns a falsy value, e.g., false, empty string, null or undefined. If the handler returns a truthy value which is not a string or grid that already contains a row with the same id, an error will be thrown in the “loadData” or “addRows” methods. Input parameters for obtainRowID

Return value String—row ID. Example:

dynamicTreeGrid.obtainRowId = function(rowObj, parentId) {

 return rowObj.id_property;

};

Adds rows to the specified position in the grid. Input parameters for addRows

Return value Array—array which contains IDs of the added rows.

Removes the row with the specified ID from the grid and grid rows collection. Input parameters for removeRows

Removes all rows from the grid and the grid rows collection.

Selects the row with the specified ID. Otherwise, the specified row becomes selected, and all previously selected rows stay selected. Input parameters for selectRow

Cancels the selection of the specified row. Input parameters for deselectRow

Adds a column to the grid. Input parameters for addColumn

Removes the specified column from the grid and the grid columns collection. Input parameters for removeColumn

Returns an Array containing the child row IDs for the specified parent row. This method returns the IDs of the root rows if the “parentId” parameter is null or undefined. Input parameters for getChildRowIds

Return value Array—array with child row IDs or an empty array if there are no children.

Gets user data stored by the specified row and key. Input parameters for getRowUserData

Return value Anything—user data stored by the specified row and key. Example:

let itemtype = grid.getRowUserData(rowId, ‘itemtype’);

Sets user data for the specified row and key. Input parameters for setRowUserData

Example:

grid.setRowUserData(rowId, ‘itemtype’, ‘Part’);

Sets cell edit availability. Input parameters for setCellEditability

Returns true if the specified cell is editable, otherwise it returns false. Input parameters for getCellEditability

Return value Boolean—is cell editable or not.

Sets cell value and updates the corresponding property in the user row object. Input parameters for setCellValue

Gets the cell value. Input parameters for getCellValue

Return value Anything—cell value.

Gets a count of all columns (visible and invisible). Return value Number

Gets a count of visible columns. Return value Number

Gets a column index by the column name. Returns -1 if the column is not found or is invisible. Input parameters for getColumnIndex

Return value Number—column index

Gets the column name using the column index. Input parameters for getColumnName

Return value String—column name

Gets Array with the names of visible columns in the same order as they are displayed in the grid. Return value Array

Gets Array with the names of all columns in the order they are added to the grid. Return value Array

Gets the ID of the parent row for the specified row. Returns null if the specified row is root and has no parent. Input parameters for getParentId

Return value String—parent row ID.

Returns true if the grid has a row with the specified ID in the rows collection, otherwise it returns false. Input parameters for containsRow

Return value Boolean

Returns true if the grid has a column with the specified name in the columns collection, otherwise it returns false. Input parameters for containsColumn

Return value Boolean

Expands all rows with their descendants.

Collapses all rows with their descendants.

Returns true if the specified row is expanded, otherwise it returns false. Input parameters for isRowExpanded

Return value Boolean

Returns true if the specified row is visible, otherwise it returns false. Input parameters for isRowVisible

Return value Boolean

Gets the number of visible rows that can be displayed in the grid.

Return value Number

Gets the number of all rows (visible and invisible) contained in the rows collection. Return value Number

Gets the Array with the IDs of visible rows displayed in the grid. Return value Array

Gets the Array with the IDs of all rows contained in the rows collection. Return value Array

Gets the row ID by the row index. Input parameters for getRowId

Return value String—row ID.

Gets the row index using the row ID. The method returns -1 if the row is not found or not visible. Input parameters for getRowIndex

Return value Number—row index.

Moves a column to the specified position. Input parameters for moveColumn

Sets settings for the specified column. Input parameters for setColumnSettings

Gets settings for the specified column. Input parameters for getColumnSettings

Return value Object—column settings object described in section Column settings object.

Sets metadata for the specified column that will be used by the column cells without their own metadata. Input parameters for setColumnMetadata

Gets metadata for the specified column. Returns null if the column has no metadata. Input parameters for getColumnMetadata

Return value Object—metadata object described in section 10.4.1.

Sets column visibility. Input parameters for setColumnVisibility

Returns true if the specified column is visible, otherwise it returns false. Input parameters for getColumnVisibility

Return value Boolean

Sets the label for the specified column. Input parameters for setColumnLabel

Gets the label for the specified column. Input parameters for getColumnLabel

Return value String—column label.

Sets the width for the specified column. Input parameters for setColumnWidth

Gets the width for the specified column. Input parameters for getColumnWidth

Return value Number—column width.

Sets metadata for the specified cell. Input parameters for setCellMetadata

Gets metadata for the specified cell. Returns null if the cell has no metadata (even if the column has metadata). Input parameters for getCellMetadataOnly

Return value Object—metadata object described in section 10.4.1.