diff --git a/docs/grid/api/grid_autoheight_config.md b/docs/grid/api/grid_autoheight_config.md index 031e402d..4074bec0 100644 --- a/docs/grid/api/grid_autoheight_config.md +++ b/docs/grid/api/grid_autoheight_config.md @@ -54,6 +54,8 @@ const grid = new dhx.Grid("grid_container", { }); ~~~ +The autoheight of a zone is ignored when [`headerRowHeight`](grid/api/grid_headerrowheight_config.md)/[`footerRowHeight`](grid/api/grid_footerrowheight_config.md) is set as an array: in that case the height of each level is defined by the corresponding array item, and only the *"auto"* items fit their content. + #### Take into account the information below: - to optimize performance, you should specify `htmlEnable: true` in the configuration object of the column which contains HTML content @@ -63,8 +65,16 @@ const grid = new dhx.Grid("grid_container", { - note that if you decide to change the font type, its size and offsets, correct calculation of the cell's autoHeight can't be ensured -@changelog: added in v7.1 +@changelog: + +- Since v9.4, the autoheight of the header/footer is ignored when `headerRowHeight`/`footerRowHeight` is set as an array +- Added in v7.1 -[comment]: # (@relatedapi: grid/api/grid_data_config.md) +**Related API:** +- [`headerAutoHeight`](grid/api/grid_headerautoheight_config.md) +- [`footerAutoHeight`](grid/api/grid_footerautoheight_config.md) +- [`headerRowHeight`](grid/api/grid_headerrowheight_config.md) +- [`footerRowHeight`](grid/api/grid_footerrowheight_config.md) +- [`data`](grid/api/grid_data_config.md) -[comment]: # (@related: grid/initialization.md#initialize-grid grid/configuration.md#autoheight-for-rows) +**Related article**: [Autoheight for rows](grid/configuration.md#autoheight-for-rows) diff --git a/docs/grid/api/grid_exportconfig_config.md b/docs/grid/api/grid_exportconfig_config.md index 78b72a2a..beaf925b 100644 --- a/docs/grid/api/grid_exportconfig_config.md +++ b/docs/grid/api/grid_exportconfig_config.md @@ -46,6 +46,10 @@ and returns a configuration object with export parameters. The returned configur - `typeConfig` - (*object*) an object containing unique settings for the specific format (filenames, delimiters, themes) - **Grid properties** - any Grid property that should be overridden (e.g., `headerRowHeight`) set as a `key:value` pair, where the *key* is the property name and the *value* is the property value to be applied only to the exported state +:::note +In the callback, `config.headerRowHeight`/`config.footerRowHeight` can be a *number* or an *array*. Pass an array to keep individual level heights in the exported file, see [Header/footer height](grid/configuration.md#headerfooter-height). +::: + #### Examples - Example 1: Conditional filtering and formatting diff --git a/docs/grid/api/grid_footerautoheight_config.md b/docs/grid/api/grid_footerautoheight_config.md index 7be6839f..35eabc03 100644 --- a/docs/grid/api/grid_footerautoheight_config.md +++ b/docs/grid/api/grid_footerautoheight_config.md @@ -17,7 +17,7 @@ This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) pac @default: false @example: -const grid = new dhx.Grid("grid", { +const grid = new dhx.Grid("grid_container", { columns: [ // columns config ], @@ -32,6 +32,11 @@ const grid = new dhx.Grid("grid", { Redefines the [autoHeight](grid/api/grid_autoheight_config.md) config for the footer. -@changelog: added in v8.3 +Ignored when [`footerRowHeight`](grid/api/grid_footerrowheight_config.md) is set as an array: in that case the height of each level of the footer is defined by the corresponding array item, and only the *"auto"* items fit their content. + +@changelog: + +- Since v9.4, ignored when `footerRowHeight` is set as an array +- Added in v8.3 diff --git a/docs/grid/api/grid_footerrowheight_config.md b/docs/grid/api/grid_footerrowheight_config.md index 6b713bd4..9504b314 100644 --- a/docs/grid/api/grid_footerrowheight_config.md +++ b/docs/grid/api/grid_footerrowheight_config.md @@ -8,20 +8,108 @@ description: You can explore the footerRowHeight config of Grid in the documenta @short: Optional. Sets the height of rows in the footer -@signature: {'footerRowHeight?: number;'} +### Usage -@default: 40 +~~~jsx +footerRowHeight?: number | (number | "auto")[]; +~~~ -@example: +:::tip pro version only +The "auto" value is a PRO feature. Measuring the content is available in the PRO version of the DHTMLX Grid (or DHTMLX Suite) package only, exactly like the [`headerAutoHeight`](grid/api/grid_headerautoheight_config.md), [`footerAutoHeight`](grid/api/grid_footerautoheight_config.md) and [`autoHeight`](grid/api/grid_autoheight_config.md) properties. +::: + +### Default config + +~~~jsx +footerRowHeight: 40 +~~~ + +### Example +~~~jsx const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { + id: "country", width: 200, + header: [{ text: "Location", colspan: 2 }, { text: "Country" }, { text: "ISO code" }], + footer: [{ text: "Total" }, { text: "The number of the listed countries" }], + }, + { + id: "region", width: 200, + header: ["", { text: "Region" }, { text: "Subregion of the world" }], + footer: [{ text: "Unique" }, { text: "The number of the distinct regions" }], + }, ], - footerRowHeight: 50 + // level 0 -> 40px, level 1 -> adjusts to its content + footerRowHeight: [40, "auto"], + data: dataset }); +~~~ + +### Footer levels and their height + +Grid renders the footer as a stack of **levels** (rows). The number of levels is defined by the longest `footer` array among the columns: + +~~~jsx +columns: [ + { id: "country", footer: [{ text: "Total" }, { text: "The number of the listed countries" }] }, // 2 levels + { id: "region", footer: [{ text: "Unique" }, { text: "The number of the distinct regions" }] } +] +~~~ + +The `footerRowHeight` property defines the height of those levels. You can set it in two ways: + +- as a **number** - the same height, in pixels, is applied to every level of the footer: + +~~~jsx +footerRowHeight: 56 // the height of both levels is 56px +~~~ + +- as an **array** - the levels are sized individually. The item at index *i* describes level *i*, counting from the topmost one. An item can be either a height in pixels or the *"auto"* keyword (**PRO version only**), which adjusts the level height to its content: + +~~~jsx +// level 0 -> 40px, level 1 -> adjusts to its content +footerRowHeight: [40, "auto"] +~~~ + +:::info +In the GPL version, the array form still works: individual pixel heights per level are fully supported. An *"auto"* item is accepted without an error, but it has no effect: the level gets the default height of 40px and its text is not wrapped. Use explicit pixel values instead. +::: + +### Height resolution rules + +| `footerRowHeight` | Level | Height | Text wrapping | +| -------- | ----- | ------ | ------------- | +| *number* | any | the number | no | +| *array* | a *number* item | the item | no | +| *array* | an *"auto"* item (**PRO version only**) | fits the content, at least 40px | yes | +| *array* | beyond the array length | 40px | no | + +Extra array items are ignored: an array longer than the actual number of levels does not add levels. A non-positive or non-numeric item falls back to the default 40px. -@descr: - The height of the footer is calculated as a sum of all row heights in it. -[comment]: # (@related: grid/initialization.md#initialize-grid grid/configuration.md#headerfooter-height) +### Relation to `footerAutoHeight` + +The [`footerAutoHeight`](grid/api/grid_footerautoheight_config.md) config, as well as [`autoHeight`](grid/api/grid_autoheight_config.md), which turns it on for the whole component, makes **every** level of the footer fit its content. The array form of `footerRowHeight` defines the height of each level explicitly, therefore it takes precedence over `footerAutoHeight`: + +- if `footerRowHeight` is set as an **array**, `footerAutoHeight` is ignored for the footer entirely, including the levels which the array does not cover. Use the *"auto"* items to opt individual levels in +- if `footerRowHeight` is set as a **number**, `footerAutoHeight` works as before: every level fits its content but is never shorter than `footerRowHeight` + +### Level heights in the export + +The per-level heights are carried over to the [export](grid/usage.md#exporting-data): the XLSX header and footer rows keep their individual heights, and the PDF/PNG snapshot uses the correct total height of the zone. + +**Change log**: +- the array value with individual level heights and the *"auto"* keyword were added in v9.4 + +**Related API:** +- [`headerRowHeight`](grid/api/grid_headerrowheight_config.md) +- [`footerAutoHeight`](grid/api/grid_footerautoheight_config.md) +- [`autoHeight`](grid/api/grid_autoheight_config.md) +- [`rowHeight`](grid/api/grid_rowheight_config.md) + +**Related article**: [Header/footer height](grid/configuration.md#headerfooter-height) + +**Related samples**: +- [Grid. Header, footer and rows height](https://snippet.dhtmlx.com/wjcjl80i) +- [Grid. Individual height of the header/footer rows](https://snippet.dhtmlx.com/1hf173dk) diff --git a/docs/grid/api/grid_headerautoheight_config.md b/docs/grid/api/grid_headerautoheight_config.md index 8e2536a4..f055f8a8 100644 --- a/docs/grid/api/grid_headerautoheight_config.md +++ b/docs/grid/api/grid_headerautoheight_config.md @@ -17,7 +17,7 @@ This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) pac @default: false @example: -const grid = new dhx.Grid("grid", { +const grid = new dhx.Grid("grid_container", { columns: [ // columns config ], @@ -32,4 +32,9 @@ const grid = new dhx.Grid("grid", { Redefines the [autoHeight](grid/api/grid_autoheight_config.md) config for the header. -@changelog: added in v8.3 +Ignored when [`headerRowHeight`](grid/api/grid_headerrowheight_config.md) is set as an array: in that case the height of each level of the header is defined by the corresponding array item, and only the *"auto"* items fit their content. + +@changelog: + +- Since v9.4, ignored when `headerRowHeight` is set as an array +- Added in v8.3 diff --git a/docs/grid/api/grid_headerrowheight_config.md b/docs/grid/api/grid_headerrowheight_config.md index 98ed5184..5661e0a2 100644 --- a/docs/grid/api/grid_headerrowheight_config.md +++ b/docs/grid/api/grid_headerrowheight_config.md @@ -8,22 +8,106 @@ description: You can explore the headerRowHeight config of Grid in the documenta @short: Optional. Sets the height of rows in the header -@signature: {'headerRowHeight?: number;'} +### Usage -@default: 40 +~~~jsx +headerRowHeight?: number | (number | "auto")[]; +~~~ -@example: +:::tip pro version only +The "auto" value is a PRO feature. Measuring the content is available in the PRO version of the DHTMLX Grid (or DHTMLX Suite) package only, exactly like the [`headerAutoHeight`](grid/api/grid_headerautoheight_config.md), [`footerAutoHeight`](grid/api/grid_footerautoheight_config.md) and [`autoHeight`](grid/api/grid_autoheight_config.md) properties. +::: + +### Default config + +~~~jsx +headerRowHeight: 40 +~~~ + +### Example +~~~jsx const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { + id: "country", width: 200, + header: [{ text: "Location", colspan: 2 }, { text: "Country" }, { text: "ISO code" }], + }, + { + id: "region", width: 200, + header: ["", { text: "Region" }, { text: "Subregion of the world" }], + }, ], - headerRowHeight: 50 + // level 0 -> 56px, level 1 -> adjusts to its content, level 2 -> 32px + headerRowHeight: [56, "auto", 32], + data: dataset }); +~~~ + +### Header levels and their height + +Grid renders the header as a stack of **levels** (rows). The number of levels is defined by the longest `header` array among the columns: + +~~~jsx +columns: [ + { id: "country", header: [{ text: "Location", colspan: 2 }, { text: "Country" }, { text: "ISO code" }] }, // 3 levels + { id: "region", header: ["", { text: "Region" }, { text: "Subregion of the world" }] } +] +~~~ + +The `headerRowHeight` property defines the height of those levels. You can set it in two ways: + +- as a **number** - the same height, in pixels, is applied to every level of the header: + +~~~jsx +headerRowHeight: 56 // the height of all the three levels is 56px +~~~ + +- as an **array** - the levels are sized individually. The item at index *i* describes level *i*, counting from the topmost one. An item can be either a height in pixels or the *"auto"* keyword (**PRO version only**), which adjusts the level height to its content: + +~~~jsx +// level 0 -> 56px, level 1 -> adjusts to its content, level 2 -> 32px +headerRowHeight: [56, "auto", 32] +~~~ -@descr: +:::info +In the GPL version, the array form still works: individual pixel heights per level are fully supported. An *"auto"* item is accepted without an error, but it has no effect: the level gets the default height of 40px and its text is not wrapped. Use explicit pixel values instead. +::: -**Related sample**: [Grid. Header, footer and rows height](https://snippet.dhtmlx.com/wjcjl80i) +### Height resolution rules + +| `headerRowHeight` | Level | Height | Text wrapping | +| -------- | ----- | ------ | ------------- | +| *number* | any | the number | no | +| *array* | a *number* item | the item | no | +| *array* | an *"auto"* item (**PRO version only**) | fits the content, at least 40px | yes | +| *array* | beyond the array length | 40px | no | + +Extra array items are ignored: an array longer than the actual number of levels does not add levels. A non-positive or non-numeric item falls back to the default 40px. The height of the header is calculated as a sum of all row heights in it. -[comment]: # (@related: grid/initialization.md#initialize-grid grid/configuration.md#headerfooter-height) +### Relation to `headerAutoHeight` + +The [`headerAutoHeight`](grid/api/grid_headerautoheight_config.md) config, as well as [`autoHeight`](grid/api/grid_autoheight_config.md), which turns it on for the whole component, makes **every** level of the header fit its content. The array form of `headerRowHeight` defines the height of each level explicitly, therefore it takes precedence over `headerAutoHeight`: + +- if `headerRowHeight` is set as an **array**, `headerAutoHeight` is ignored for the header entirely, including the levels which the array does not cover. Use the *"auto"* items to opt individual levels in +- if `headerRowHeight` is set as a **number**, `headerAutoHeight` works as before: every level fits its content but is never shorter than `headerRowHeight` + +### Level heights in the export + +The per-level heights are carried over to the [export](grid/usage.md#exporting-data): the XLSX header and footer rows keep their individual heights, and the PDF/PNG snapshot uses the correct total height of the zone. + +**Change log**: +- the array value with individual level heights and the *"auto"* keyword were added in v9.4 + +**Related API:** +- [`footerRowHeight`](grid/api/grid_footerrowheight_config.md) +- [`headerAutoHeight`](grid/api/grid_headerautoheight_config.md) +- [`autoHeight`](grid/api/grid_autoheight_config.md) +- [`rowHeight`](grid/api/grid_rowheight_config.md) + +**Related article**: [Header/footer height](grid/configuration.md#headerfooter-height) + +**Related samples**: +- [Grid. Header, footer and rows height](https://snippet.dhtmlx.com/wjcjl80i) +- [Grid. Individual height of the header/footer rows](https://snippet.dhtmlx.com/1hf173dk) diff --git a/docs/grid/configuration.md b/docs/grid/configuration.md index 59a04076..b4de65ce 100644 --- a/docs/grid/configuration.md +++ b/docs/grid/configuration.md @@ -1572,20 +1572,80 @@ You can change the height of the header/footer in one of the following ways: 1. Specify the necessary height of the rows in the header/footer via the related API options -The height of the header/footer of Grid is calculated as a sum of rows which are included into it. To set the height of a row inside the header/footer, use the [`headerRowHeight`](grid/api/grid_headerrowheight_config.md)/[`footerRowHeight`](grid/api/grid_footerrowheight_config.md) -properties, correspondingly. The default value of the mentioned properties is 40. +Grid renders the header and the footer as a stack of levels (rows). The number of levels is defined by the longest `header`/`footer` array among the columns: ~~~jsx +columns: [ + { + id: "country", + header: [{ text: "Location", colspan: 2 }, { text: "Country" }, { text: "ISO code" }], // 3 levels in the header + footer: [{ text: "Total" }, { text: "The number of the listed countries" }] // 2 levels in the footer + }, + { + id: "region", + header: ["", { text: "Region" }, { text: "Subregion of the world" }], + footer: [{ text: "Unique" }, { text: "The number of the distinct regions" }] + } +] +~~~ + +The height of the header/footer of Grid is calculated as a sum of rows which are included into it. To set the height of a row inside the header/footer, use the [`headerRowHeight`](grid/api/grid_headerrowheight_config.md)/[`footerRowHeight`](grid/api/grid_footerrowheight_config.md) properties, correspondingly. Each of them can be set either as a **number**, which is applied to every level of the zone, or as an **array**, which sizes the levels individually. + +The default value of the mentioned properties is 40. + +~~~jsx +// the same height for all the levels of the header/footer +headerRowHeight: 50, +footerRowHeight: 50 +~~~ + +When the property is set as an array, the item at index *i* describes level *i*, counting from the topmost one. An item can be either a height in pixels or the *"auto"* keyword (**PRO version only**), which adjusts the level height to its content: + +~~~jsx +// individual height for each level of the header/footer const grid = new dhx.Grid("grid_container", { columns: [ - // columns config + { + id: "country", width: 200, + header: [{ text: "Location", colspan: 2 }, { text: "Country" }, { text: "ISO code" }], + footer: [{ text: "Total" }, { text: "The number of the listed countries" }], + }, + { + id: "region", width: 200, + header: ["", { text: "Region" }, { text: "Subregion of the world" }], + footer: [{ text: "Unique" }, { text: "The number of the distinct regions" }], + }, ], - footerRowHeight:50 - headerRowHeight: 50 + // level 0 -> 56px, level 1 -> adjusts to its content, level 2 -> 32px + headerRowHeight: [56, "auto", 32], + // level 0 -> 40px, level 1 -> adjusts to its content + footerRowHeight: [40, "auto"], + data: dataset }); ~~~ -**Related sample**: [Grid. Header, footer and rows height](https://snippet.dhtmlx.com/wjcjl80i) +:::tip pro version only +Measuring the content is available in the PRO version of the DHTMLX Grid (or DHTMLX Suite) package only, exactly like the [`headerAutoHeight`](grid/api/grid_headerautoheight_config.md), [`footerAutoHeight`](grid/api/grid_footerautoheight_config.md) and [`autoHeight`](grid/api/grid_autoheight_config.md) properties. + +In the GPL version, the array form still works: individual pixel heights per level are fully supported. An *"auto"* item is accepted without an error, but it has no effect: the level gets the default height of 40px and its text is not wrapped. Use explicit pixel values instead. +::: + +The height of a level is resolved as follows: + +| `headerRowHeight` / `footerRowHeight` | Level | Height | Text wrapping | +| -------- | ----- | ------ | ------------- | +| *number* | any | the number | no | +| *array* | a *number* item | the item | no | +| *array* | an *"auto"* item (**PRO version only**) | fits the content, at least 40px | yes | +| *array* | beyond the array length | 40px | no | + +Extra array items are ignored: an array longer than the actual number of levels does not add levels. A non-positive or non-numeric item falls back to the default 40px. + +The per-level heights are carried over to the [export](grid/usage.md#exporting-data): the XLSX header and footer rows keep their individual heights, and the PDF/PNG snapshot uses the correct total height of the zone. + +**Related samples**: +- [Grid. Header, footer and rows height](https://snippet.dhtmlx.com/wjcjl80i) +- [Grid. Individual height of the header/footer rows](https://snippet.dhtmlx.com/1hf173dk) 2. Provide the automatic adjustment of the header/footer height for the content to fit in @@ -1593,7 +1653,7 @@ Use the [](grid/api/grid_headerautoheight_config.md) and [](grid/api/grid_footer ~~~jsx // enabling autoheight only in the content -const grid1 = new dhx.Grid("grid", { +const grid1 = new dhx.Grid("grid_container", { columns: [ // columns config ], @@ -1604,7 +1664,7 @@ const grid1 = new dhx.Grid("grid", { }); // enabling autoheight only in the header -const grid2 = new dhx.Grid("grid", { +const grid2 = new dhx.Grid("grid_container", { columns: [ // columns config ], @@ -1616,6 +1676,13 @@ const grid2 = new dhx.Grid("grid", { **Related sample**: [Grid. Header/footer autoHeight mode](https://snippet.dhtmlx.com/jwz9k66d?tag=grid) +Both configuration options make **every** level of the zone fit its content. The array form of `headerRowHeight`/`footerRowHeight` defines the height of each level explicitly, therefore it takes precedence over `headerAutoHeight`/`footerAutoHeight`: + +- if `headerRowHeight` is set as an **array**, `headerAutoHeight` is ignored for the header entirely, including the levels which the array does not cover. Use the *"auto"* items to opt individual levels in +- if `headerRowHeight` is set as a **number**, `headerAutoHeight` works as before: every level fits its content but is never shorter than `headerRowHeight` + +The same pair of rules applies to `footerRowHeight` and `footerAutoHeight`. + ### Footer position :::tip pro version only @@ -1747,7 +1814,7 @@ Please note that the `autoHeight` option does not adjust the height of the cells The option just makes their text split into multiple lines, but the height of the cells will remain the same. To set the height of the rows in the header/footer, you can: -- use the [](grid/api/grid_headerrowheight_config.md) and [](grid/api/grid_footerrowheight_config.md) configuration options of Grid to set specific values for the header/footer rows height +- use the [](grid/api/grid_headerrowheight_config.md) and [](grid/api/grid_footerrowheight_config.md) configuration options of Grid to set specific values for the header/footer rows height, either the same one for all the rows (levels) or an individual one for each of them - use the [](grid/api/grid_headerautoheight_config.md) and [](grid/api/grid_footerautoheight_config.md) configuration options of Grid (**PRO version only**) to enable autoheight for the header/footer rows ### Automatic adding of empty row into Grid diff --git a/docs/grid/usage.md b/docs/grid/usage.md index 67984238..b27c5bc6 100644 --- a/docs/grid/usage.md +++ b/docs/grid/usage.md @@ -601,6 +601,10 @@ The returned configuration object may contain the following properties: - `typeConfig` - (*object*) an object containing unique settings for the specific format (filenames, delimiters, themes) - **Grid properties** - any Grid property that should be overridden (e.g., `headerRowHeight`) set as a `key:value` pair, where the *key* is the property name and the *value* is the property value to be applied only to the exported state +:::note +You can override `headerRowHeight`/`footerRowHeight` with an array, so that the individual level heights differ in the exported file, see [Header/footer height](grid/configuration.md#headerfooter-height). The callback receives `config.headerRowHeight`/`config.footerRowHeight` either as a *number* or as an *array*. +::: + #### Example 1: Conditional filtering and formatting In this example, sensitive data is excluded for all formats, while for PDF/PNG the headers are converted to the uppercase and HTML templates are disabled: