Skip to main content

spans

Optional. Describes the configuration of cols/rows spans

spans?: object[];

Example

const grid = new dhx.Grid("grid_container", {
    columns: [ 
        // columns config
    ],
    spans: [
        {row:"0", column:"a", rowspan:5 },
        {row:"0", column:"b", rowspan:9, text:"<h2>Some content here</h2>"},
        {row:"0", column:"c", colspan:2, text:"Some content"},
        {row:"10", column:"a", colspan:4, text:"Some header", css:"myCustomColspan"}
    ],
    data: dataset
});

Related sample: Grid. Grouped headers (spans)

Each object in the spans array contains the following properties:

  • row - (string | number) obligatory, the id of a row
  • column - (string|number) obligatory, the id of a column
  • rowspan - (number) optional, the number of rows in a span
  • colspan - (number) optional, the number of columns in a span
  • text - (string|number) optional, the content of a span. You can specify the text of the column span via the text property. It can be set either as a string or a callback function which is called with the following parameter:
    • content - an object with the content of the span tooltip that contains the calculated values of the summary property, set as key:value pairs where:
      • the key is either the key defined in the list or the functor name
      • the value can be a string, number or null

The counted values are taken either from the summary config option of the component or the summary config option of a column.

note

In case key names in the summary configs are the same, values are taken from the column's configuration option.

important

If the value of a spanned cell is initialized with the text property set as a callback function, the cell content can't be edited.

const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 200, id: "country", header: [{ text: "Country" }] },
        { 
            width: 150, 
            id: "population", 
            header: [{ text: "Population" }],
            summary: "count"
        }
    ],
    summary: { totalPopulation: ["population", "sum"] },
    spans: [
        {
            row: "rowid",
            column: "population",
            rowspan: 9,
            text: ({ count }) => ("Count population:" + count)
        },
    ],
    data: dataset
});
  • css - (string) optional, the name of a CSS class applied to a span
  • tooltip - (boolean|object) optional, enables a tooltip on hovering over the content of a span, or sets the configuration object with the tooltip settings; true by default. When set as an object, the tooltip config can have the following properties:
    • force - (optional) forces opening of a tooltip; if set to true, the showDelay and hideDelay settings are ignored, false by default
    • showDelay - (optional) the time period that should pass before showing a tooltip, in ms
    • hideDelay - (optional) the time period that should pass before hiding a tooltip, in ms
    • margin - (optional) the margin between the node and tooltip
    • position - (optional) the position of a tooltip: "right", "bottom", "center", "left", "top"; "bottom" by default
    • css - (optional) the style of a tooltip box
  • tooltipTemplate - (function) sets a template for the span tooltip. The value of the tooltipTemplate property is a callback function which is called with the following parameters:
    • content - an object with the content of the span tooltip. Contains two properties which are available either from the component's or from the column's configuration:
      • value - the value rendered in a cell, including the applied templates
      • an object with the calculated values of the summary property, set as key:value pairs where:
        • the key is either the key defined in the list or the functor name
        • the value can be a string, number or null
    • span - the object of the column span
const grid = new dhx.Grid("grid_container", {
    columns: [
        { width: 200, id: "country", header: [{ text: "Country" }] },
        { 
            width: 150, 
            id: "population", 
            header: [{ text: "Population" }],
            summary: "count"
        }
    ],
    summary: { totalPopulation: ["population", "sum"] },
    spans: [
        {
            row: "rowid",
            column: "population",
            rowspan: 9,
            text: "Some text",
            toltipTemplate: ({ value, count }) => (`value: ${value}; count: ${count}`),
        },
    ],
    data: dataset
});

Note, that if both the spans and leftSplit properties are set in the Grid config, the following rules will be applied:

  • All necessary columns or rows will be in a span if the spans property is set for the columns located within the frozen area.
  • If the spans property is set for a number of columns or rows placed as in the frozen part as in the movable one, then the columns remained in the movable part only will be in a span.

Change log:

  • The tooltipTemplate property is added in v9.0
  • The ability to set the tooltip config as an object is added in v8.4
  • The tooltip property is added in v6.5.