Initializing help system before first use

vdl-treegrid

The VDL Tree grid component is a VDL Extension that provides an interface for users to visualize nested data in table format. The data must be structured in a certain way in order to build a table with nested data. To have child rows, it is necessary to provide an array of child data objects to the rows with the "_children" property. However, this property can be configured by using the children-field attribute. Tree grid table requires data to be passed via the data attribute.

Add the compact class to the parent vdl-page to render the Tree Grid with compact style.

since 5.2

Example

<script>
    const nestedData = [
        {id:1, name:"Grandparent", prop1:"60", 
            "_children":[
                {id:2, name:"Parent one", prop1:"45"}, //child rows nested under Grandparent
                {id:3, name:"Parent two", prop1:"42"},
                {id:4, name:"Parent three", prop1:"40", 
                    "_children":[
                        {id:5, name:"Child one", prop1:"16"}, //child rows nested under Parent three
                        {id:6, name:"Child two", prop1:"12"},
            ]},
        ]},
        {id:7, name:"Parent one", prop1:"45"},
        {id:8, name:"Parent two", prop1:"42", 
            "_children":[
                {id:9, name:"Child one", prop1:"10"}, //child row nested under Parent two
        ]},
        {id:10, name:"Parent three", prop1:"40"}
    ]
</script>

<vdl-treegrid   
            column-definition="auto"
            data="=nestedData">
</vdl-treegrid>

Attributes

always-show-selection Whether to display selection on inactive grids. Set to true to keep selection on a grid when it becomes inactive. since 5.2
cell-render A custom cell render function or expression that is applied to all cells in the datagrid. This affects the rendered output of the cell only, sorting and filtering are unaffected. The cell-render function should return either the original data unchanged, some new data to display in the cell or a new HTML element to insert into the cell. In addition to returning the original or modified cell data it can also modify the HTML cellElement that is passed in. If a cell-render function is provided on vdl-datagrid and a child vdl-datagrid-column has a render function, then the vdl-datagrid-column render function will take precedence.
Variable Type Description
data (string|boolean|number) The value of the cell being rendered. Its data type will match that of the array elements in this column. The cell value will be HTML escaped to avoid XSS security issues.
type string The type call data requested - this will currently always be display.
rowData Array.<(string|boolean|number)> The values from each cell in the current row. The order of the row data reflects the underlying order of the array indices rather than the display order.
columnDefinition ColumnDefinition The ColumnDefinition object representing the configuration of the cell's column. See the ColumnDefinition object describe in the column-definition attribute.You can use columndefinition.parentColumn to iterate over nested columns headers to work out the location of the cell.
cellElement HTMLElement The cell HTML element. This can be modified or appended to, affecting the display of the cell.
treeParentRow (RowDefinition|false) The parent row definition if there is one, else "false". See the RowDefinition object describe in the column-definition attribute.You can use treeParentRow to iterate through the tree structure and determine the location of the cell.
since 5.3 requires expression
children-field Default behavior of vdl-treegrid is to display nested data based on the _children property in the hierarchical source data, however this behavior may be overridden by passing different values to the property. since 5.2 accepts expression
class Space-separated list of the classes of the element. since 5.2
column-definition Specify how columns are defined. This attribute can only be used in combination with the "data" attribute.

Allowed values are:

column-definition="auto" - Generates columns from the data (default)

column-definition="labels" - Uses the "label" and "value" properties on an object. Data will be reduced to one row.

column-definition="=[{ field: "name" }, { field: "age" }]" - An array of objects defining the column properties.

When using column properties, you should supply a column definition object for each column you require and each object must have a property named 'field'. The value of the field property must reference a property on the data.

Below is an example showing how columns, and even individual cells can be made editable. This also shows how dropdown options can be supplied with labels:

Note: Any expandable cells (has children-field present) will not be editable.

data =
[
   { name: "John Doe", gender: "MALE", age: 30, isStaff: false },
   { name: "Jane Doe", gender: "FEMALE", age: 25, isStaff: true }
]

Callback to determine if a cell is editable:
/* ColumnDefinition
{
   field: string,
   title: string,
   editable: boolean | ((details: VdlDatagridCellDetails) => boolean),
   parentColumn: false | ColumnDefinition,
}
*/

/* RowDefinition
{
   rowData: (string|number|boolean|null|undefined)[] | Record
      
       ,
       
   treeParentRow: false | RowDefinition,
       
}
       
*/
       

       
/* VdlDatagridCellDetails
       
{
       
   cellValue: (string|number|boolean|null|undefined),
       
   columnDefinition: ColumnDefinition,
       
   rowData: (string|number|boolean|null|undefined)[] | Record
       
        ,
        
   treeParentRow: false | RowDefinition,
        
   tableData: (string|number|boolean|null|undefined)[][],
        
}
        
*/
        

        
function isNameEditable(cellDetails: VdlDatagridCellDetails) {
        
   /* Make use of the cellDetails to determine if a cell is editable... */
        
   return true;
        
}

Callback to construct gender options:
function constructGenderOptions(cellValue: (string|boolean|number), rowData: {[key: string]: (string|boolean|number)}) {
   return [
       { key: "OTHER", value: "Prefer not to say" },
       { key: "MALE", value: "Male" },
       { key: "FEMALE", value: "Female" }
   ];
}

column-definition =
[
   { field: "name", title: "Full Name", editable: isNameEditable },
   { field: "gender", editable: true, editorOptions: constructGenderOptions },
   { field: "age", headerSortStartingDir: "desc", editable: true },
   { field: "isStaff" }
]

Object passed to the cell-event handler:
/* ColumnDefinition
{
   field: string,
   title: string,
   editable: boolean | ((details: VdlDatagridCellDetails) => boolean),
   parentColumn: false | ColumnDefinition,
}
*/

/* RowDefinition
{
   rowData: (string|number|boolean|null|undefined)[] | Record
      
       ,
       
   treeParentRow: false | RowDefinition,
       
}
       
*/
       

       
/* VdlDatagridCellEditDetails
       
{
       
   cellValue: (string|number|boolean|null|undefined),
       
   cellInitialValue: (string|number|boolean|null|undefined),
       
   cellOldValue: (string|number|boolean|null|undefined),
       
   columnDefinition: ColumnDefinition,
       
   rowData: (string|number|boolean|null|undefined)[] | Record
       
        ,
        
   treeParentRow: false | RowDefinition,
        
   tableData: (string|number|boolean|null|undefined)[][]
        
}
        
*/
Handling the cell-edit event:
<script>
function handler(cellEditDetails: VdlDatagridCellEditDetails) {
   /* cell-edit event handler code */
}
</script>

<vdl-datagrid vdl-event="cell-edit: handler" [...] >

Callback to validate a cell:
/* VdlDatagridCellDetails
{
   cellValue: (string|number|boolean|null|undefined),
   columnDefinition: ColumnDefinition,
   rowData: (string|number|boolean|null|undefined)[] | Record
      
       ,
       
   treeParentRow: false | RowDefinition,
       
   tableData: (string|number|boolean|null|undefined)[][],
       
}
       
*/
       

       
function isValidBool(cellDetails: VdlDatagridCellDetails) {
       
   return true;
       
}
       
function isValidObject(cellDetails: VdlDatagridCellDetails) {
       
   return {
       
      isValid: true,
       
      errorMessage: "wrong value",
       
      allowSave:false
       
   };
       
}

Custom sorter:
<script>
function customSorter(valueA, valueB, rowA, rowB, columnElement, sortDirection) {
   return valueA > valueB ? 1 : -1;
}
const columnDefinitions = [{ field: "name", title: "Full Name", sorter: customSorter }]
</script>


Column definition objects accept the following configuration properties:
Variable Type Description
field string The name of the objects property which holds the columns value.
title string The displayed title of the column.
width number|string The width of the column, either as a number in pixels, for example 200, or a percentage string such as: '50%'.
headerSortStartingDir "asc" | "desc" The header sort starting direction.
cssClass string Space seperated class names.
editable boolean | (details: VdlDatagridCellDetails) => boolean Optional boolean, or callback which determines if an individual cell can be edited. The callback is invoked when a cell is clicked and is provided with an VdlDatagridCellDetails object to help a decision be made. Note: Any expandable cell (has children-field present) will not be editable.
dataType "string" | "number" | "boolean" Optionally specify the data type for the column. If not provided, type will automatically be inferred from the first row of data.
editorOptions Array.<(string|boolean|number)> | Object.<string, string> | Array.<{key: (string|boolean|number), value: string}> Optional editor options array, the presence of which will cause a dropdown of the provided options to appear instead of the usual string, number or checkbox editor.
editorValidate (details: VdlDatagridCellDetails) => boolean | InsightValidationResult Optional callback which validate the values in the column's cells. The callback is provided with a VdlDatagridCellDetails.
sorter (valueA: "string" | "number" | "boolean", valueB: "string" | "number" | "boolean", rowA: RowDefinition, rowB: RowDefinition, columnDefinition: ColumnDefinition, sortDirection: "asc" | "desc") => number Custom sorter function for the column. The function should return a number less than 0 if valueA is less than valueB, 0 if they are equal, and a number greater than 0 if valueA is greater than valueB.
since 5.2 accepts expression
column-filter Set this to true to enable the column filters. This will show a header row with filter inputs for each column. since 5.2
data Use this attribute to pass data directly to vdl-treegrid. Supported formats is; Array of objects: [{... prop: 1}]. since 5.2 requires expression
defer-column-filter Set this to true to defer column filters from applying until the input loses focus. since 5.3 accepts expression
freeze-columns The number of columns to freeze in the table starting from the left hand column. Works best when vdl-treegrid is in a fixed width container. since 5.2
header-tooltip-render A custom render function or expression that is called for each column header in the treegrid and defines how to display the header's tooltip. It should return either a string or HTML content to display inside the tooltip, a DOM node to replace the tooltip or an undefined/nullish value to hide the tooltip.
Variable Type Description
title string The title text of the column header the tooltip is being generated for.
columnDefinition ColumnDefinition The ColumnDefinition object representing the configuration of the tooltip header's column. See the ColumnDefinition object describe in the column-definition attribute.
headerElement HTMLElement The tooltip's header HTML element.
since 5.7 requires expression
height Grid height, When page-mode is set to scrolling you can set the height of the grid to something other than the default. since 5.2
id Specify an element id for the grid. Useful if you later want to target the grid using a selector. If not given then an id will be generated. since 5.2
page-mode By default the grid will show all rows in scrolling mode. Set this attribute to paged to enable grid pagination. since 5.2
page-size The number of rows to show per-page in paged mode. Defaults to 50. since 5.2
save-state Set this to false to disable grid state saving. By default grid state is stored in the user's browser session so that user settings (e.g. page, sorting and search) are preserved if grid data is reloaded. since 5.2
start-expanded By default all nodes on the tree will start collapsed, you can customize the initial expansion state of the tree using this attribute since 5.2 accepts expression
tooltip-render A custom render function or expression that is called for each cell in the treegrid and defines how to display the cell's tooltip.It should return either a string or HTML content to display inside the tooltip, a DOM node to replace the tooltip or an undefined/nullish value to hide the tooltip.The tooltip is not displayed on the bottom-calc row's cells.
Variable Type Description
data (string|boolean|number) The value of the cell the tooltip is being generated for. Its data type will match that of the array elements in this column. The cell value will be HTML escaped to avoid XSS security issues.
type string The type cell data requested - this will currently always be display.
rowData Array.<(string|boolean|number)> The values from each cell in the current row. The order of the row data reflects the underlying order of the array indices rather than the display order.
columnDefinition ColumnDefinition The ColumnDefinition object representing the configuration of the tooltip cell's column. See the ColumnDefinition object describe in the column-definition attribute.
cellElement HTMLElement The tooltip's cell HTML element.
treeParentRow (RowDefinition|false) The parent row definition if there is one, else "false". See the RowDefinition object describe in the column-definition attribute.You can use treeParentRow to iterate through the tree structure and determine the location of the tooltip's cell.
since 5.3 requires expression
width Set the grid to a fixed width, in pixels. Accepts an integer value. If set to the string custom then the grid width is calculated by adding up all the widths of the columns in the grid. If a column doesn't have a width specified then it is given a default value of 100px. since 5.2
Parent Topic VDL 5 Reference

© 2001-2025 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.