diff --git a/docs/api/config/js_kanban_cardheight_config.md b/docs/api/config/js_kanban_cardheight_config.md index 8a36d1be..195da4a6 100644 --- a/docs/api/config/js_kanban_cardheight_config.md +++ b/docs/api/config/js_kanban_cardheight_config.md @@ -19,6 +19,8 @@ cardHeight?: number; // px :::important If you combine the [`renderType: "lazy"`](api/config/js_kanban_rendertype_config.md) and [`scrollType: "default"`](api/config/js_kanban_scrolltype_config.md) settings, don't forget to specify a static height for cards via the `cardHeight` property. Unless you specify it, the cards will not be displayed. When you use [`renderType: "lazy"`](api/config/js_kanban_rendertype_config.md) with [`scrollType: "column"`](api/config/js_kanban_scrolltype_config.md), you should also fix the height of cards via the `cardHeight` property. Although a variable height of cards is supported for this type of layout, it may not work in a stable manner with custom card content. + +If `cardHeight` is not specified, the widget falls back to an experimental approximation of card heights based on the visible fields declared in [`cardShape`](api/config/js_kanban_cardshape_config.md). With a custom [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md), this approximation does not apply — in that case, either set `cardHeight` explicitly or supply a custom [`getCardHeight`](api/config/js_kanban_getcardheight_config.md) function. ::: ### Example diff --git a/docs/api/config/js_kanban_getcardheight_config.md b/docs/api/config/js_kanban_getcardheight_config.md new file mode 100644 index 00000000..67706f99 --- /dev/null +++ b/docs/api/config/js_kanban_getcardheight_config.md @@ -0,0 +1,74 @@ +--- +sidebar_label: getCardHeight +title: getCardHeight Config +description: You can learn about the getCardHeight config in the documentation of the DHTMLX JavaScript Kanban library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Kanban. +--- + +# getCardHeight + +### Description + +@short: Optional. A function that returns an estimated height of a card + +The `getCardHeight` function is used by the widget to estimate card heights when the [`cardHeight`](api/config/js_kanban_cardheight_config.md) property is not set and the board is configured with [`renderType: "lazy"`](api/config/js_kanban_rendertype_config.md) and [`scrollType: "column"`](api/config/js_kanban_scrolltype_config.md). The estimated heights let the widget render the scrollbar correctly before the actual cards are measured in the DOM. + +:::info +If you set the [`cardHeight`](api/config/js_kanban_cardheight_config.md) property, the widget uses the fixed height and `getCardHeight` is not called. Setting `cardHeight` is the recommended way to combine `renderType: "lazy"` with `scrollType: "column"`. +::: + +### Usage + +~~~jsx {} +getCardHeight?: (cardShape: object, card: object, cardWidth: number) => number; +~~~ + +### Parameters + +The callback function takes the following arguments: + +- `cardShape` - the configuration object of the card (the [`cardShape`](api/config/js_kanban_cardshape_config.md) property) +- `card` - the data object of the card +- `cardWidth` - the current width of the card in pixels + +The function must return a number — the estimated height of the card in pixels. + +### Default config + +By default, the widget uses a built-in function that approximates card height based on the visible fields declared in [`cardShape`](api/config/js_kanban_cardshape_config.md) and the data stored in the card. This default works for boards that rely on the built-in card layout. + +If you provide a custom [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md), the built-in approximation can no longer predict the actual height of the rendered markup. In this case, specify a custom `getCardHeight` function that returns the height of the rendered template, or set a static [`cardHeight`](api/config/js_kanban_cardheight_config.md) instead. + +### Example + +The example below provides a custom `getCardHeight` function for a board with a custom card template: + +~~~jsx {15-22,27} +const cardTemplate = ({ cardFields }) => { + const { label, description } = cardFields; + return ` +
+
${label}
+
${description || ""}
+
+ `; +}; + +new kanban.Kanban("#root", { + cards, + columns, + renderType: "lazy", + scrollType: "column", + cardTemplate: kanban.template(card => cardTemplate(card)), + getCardHeight: (cardShape, card, cardWidth) => { + // estimate the height of the custom template + let height = 60; // base padding + label line + if (card.description) { + height += Math.ceil(card.description.length / 40) * 18; + } + return height; + }, + // other parameters +}); +~~~ + +**Related articles:** [Configuration](guides/configuration.md#rendering-and-scrolling) diff --git a/docs/api/config/js_kanban_rendertype_config.md b/docs/api/config/js_kanban_rendertype_config.md index a11280bd..9e18e756 100644 --- a/docs/api/config/js_kanban_rendertype_config.md +++ b/docs/api/config/js_kanban_rendertype_config.md @@ -23,6 +23,8 @@ renderType?: "default" | "lazy"; :::important If you combine the `renderType: "lazy"` and [`scrollType: "default"`](api/config/js_kanban_scrolltype_config.md) settings, don't forget to specify a static height for cards via the [`cardHeight`](api/config/js_kanban_cardheight_config.md) property. Unless you specify it, the cards will not be displayed correctly. When you use `renderType: "lazy"` with [`scrollType: "column"`](api/config/js_kanban_scrolltype_config.md), you should also fix the height of cards via the [`cardHeight`](api/config/js_kanban_cardheight_config.md) property. Although a variable height of cards is supported for this type of layout, it may not work in a stable manner with custom card content. + +If `cardHeight` is not set, the widget falls back to an experimental approximation of card heights based on [`cardShape`](api/config/js_kanban_cardshape_config.md). For boards with a custom [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md), supply a custom [`getCardHeight`](api/config/js_kanban_getcardheight_config.md) function instead. ::: ### Default config diff --git a/docs/api/config/js_kanban_scrolltype_config.md b/docs/api/config/js_kanban_scrolltype_config.md index 70eb10d8..36831280 100644 --- a/docs/api/config/js_kanban_scrolltype_config.md +++ b/docs/api/config/js_kanban_scrolltype_config.md @@ -29,6 +29,8 @@ scrollType: "default" :::important If you combine the [`renderType: "lazy"`](api/config/js_kanban_rendertype_config.md) and `scrollType: "default"` settings, don't forget to specify a static height for cards via the [`cardHeight`](api/config/js_kanban_cardheight_config.md) property. Unless you specify it, the cards will not be displayed. When you use [`renderType: "lazy"`](api/config/js_kanban_rendertype_config.md) with `scrollType: "column"`, you should also fix the height of cards via the [`cardHeight`](api/config/js_kanban_cardheight_config.md) property. Although a variable height of cards is supported for this type of layout, it may not work in a stable manner with custom card content. + +If `cardHeight` is not set, the widget falls back to an experimental approximation of card heights based on [`cardShape`](api/config/js_kanban_cardshape_config.md). For boards with a custom [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md), supply a custom [`getCardHeight`](api/config/js_kanban_getcardheight_config.md) function instead. ::: ### Example diff --git a/docs/api/overview/properties_overview.md b/docs/api/overview/properties_overview.md index 8aeddf7a..6add4207 100644 --- a/docs/api/overview/properties_overview.md +++ b/docs/api/overview/properties_overview.md @@ -20,6 +20,7 @@ To configure the **Kanban**, refer to the [Configuration](guides/configuration.m | [](api/config/js_kanban_currentuser_config.md) | @getshort(api/config/js_kanban_currentuser_config.md) | | [](api/config/js_kanban_editor_config.md) | @getshort(api/config/js_kanban_editor_config.md) | | [](api/config/js_kanban_editorshape_config.md) | @getshort(api/config/js_kanban_editorshape_config.md) | +| [](api/config/js_kanban_getcardheight_config.md) | @getshort(api/config/js_kanban_getcardheight_config.md) | | [](api/config/js_kanban_history_config.md) | @getshort(api/config/js_kanban_history_config.md) | | [](api/config/js_kanban_links_config.md) | @getshort(api/config/js_kanban_links_config.md) | | [](api/config/js_kanban_locale_config.md) | @getshort(api/config/js_kanban_locale_config.md) | diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index 273906b3..2f1b428a 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -487,6 +487,8 @@ new kanban.Kanban("#root", { :::important When you combine `renderType: "lazy"` with any `scrollType`, set a static height for cards through the [`cardHeight`](api/config/js_kanban_cardheight_config.md) property. Without `cardHeight`, lazy rendering does not display cards correctly. + +If `cardHeight` is omitted with `renderType: "lazy"` and `scrollType: "column"`, the widget falls back to an experimental approximation of card heights based on the visible fields in [`cardShape`](api/config/js_kanban_cardshape_config.md). For boards that use a custom [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md), the widget cannot predict the rendered height — supply a custom [`getCardHeight(cardShape, card, cardWidth)`](api/config/js_kanban_getcardheight_config.md) function that returns the estimated card height. ::: ## History of changes diff --git a/sidebars.js b/sidebars.js index 22f75196..2229a883 100644 --- a/sidebars.js +++ b/sidebars.js @@ -224,6 +224,8 @@ module.exports = { "api/config/js_kanban_editor_config", //"api/config/js_kanban_editorautosave_config", REMOVED "api/config/js_kanban_editorshape_config", + // G + "api/config/js_kanban_getcardheight_config", // H "api/config/js_kanban_history_config", // L