Merge pull request #104 from DHTMLX/next

Fixed missing information and typos

Author: serhiipylypchuk1991

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

docs/api/config/js_kanban_columnshape_config.md

@@ -30,10 +30,10 @@ columnShape?: {
     },
     fixedHeaders?: boolean,
     css?: (column, cards) => string,
-    headerTemplate?: template(column => {
+    headerTemplate?: template(props => {
         return "The HTML template of the column header in the expanded state";
     }),
-    collapsedTemplate?: template(column => {
+    collapsedTemplate?: template(props => {
         return "The HTML template of the column header in the collapsed state";
     }),
     confirmDeletion?: boolean
@@ -94,8 +94,28 @@ To configure the columns appearance, in the **columnShape** object you can speci
 
 - `fixedHeaders` - (optional) freezes column headers during vertical scroll (*true* by default). Scroll must be enabled in Kanban itself (height must be limited)
 - `css` - (optional) a function that returns a css class that applies to columns conditionally
-- `headerTemplate` - (optional) the HTML template of the column header in the expanded state
-- `collapsedTemplate` - (optional) the HTML template of the column header in the collapsed state
+- `headerTemplate` - (optional) the HTML template of the column header in the expanded state. The function receives a `props` object with the following properties:
+    - `column` - (object) the column data (see [`columns`](api/config/js_kanban_columns_config.md) for the structure)
+    - `columnState` - (object) the current state of the column. It always includes:
+        - ***columnId*** - (string | number) the ID of the column
+        - ***column*** - (object) the column data (same as `props.column`)
+        - ***cardsCount*** - (number) the number of cards in the column
+        - ***noFreeSpace*** - (boolean) ***true*** when the column cannot accept more cards
+
+        When the [`columns[i].limit`](api/config/js_kanban_columns_config.md) parameter is enabled, it also includes:
+        - ***totalLimit*** - (number) the configured cards limit
+        - ***isOverLimit*** - (boolean) ***true*** when the number of cards exceeds the limit
+
+        When the column belongs to a swimlane (row), it also includes:
+        - ***rowId*** - (string | number) the ID of the row
+        - ***row*** - (object) the row data (see [`rows`](api/config/js_kanban_rows_config.md) for the structure)
+        - ***height*** - (number) the height of the area
+    - `isMenuVisible` - (boolean) ***true*** when the menu should be shown for this column header
+    - `renaming` - (boolean) ***true*** when the input for editing the column name is active
+    - `readonly` - (boolean) ***true*** when column editing is disabled (equivalent of `!readonly.edit`, see the [`readonly`](api/config/js_kanban_readonly_config.md) property)
+- `collapsedTemplate` - (optional) the HTML template of the column header in the collapsed state. The function receives a `props` object with the following properties:
+    - `column` - (object) the column data (see [`columns`](api/config/js_kanban_columns_config.md))
+    - `columnState` - (object) the current state of the column. The shape is the same as `columnState` in the [`headerTemplate`](#parameters) parameter above
 - `confirmDeletion` - (optional) shows/hides the **confirmation dialog** that allows users to confirm or decline the column deletion
 
 ### Default config
@@ -160,30 +180,30 @@ const columnShape = {
     },
     fixedHeaders: false,
     css: (column, cards) => column.id == "inprogress" && cards.length < 5 ? "green" : "red",
-    headerTemplate: template(column => {
+    headerTemplate: template(props => {
         return `<div class="wx-collapse-icon" data-action=${"collapse"}>
-                    <i class=${column.column.collapsed ? "wxi-angle-right" : "wxi-angle-left"}></i>
+                    <i class=${props.column.collapsed ? "wxi-angle-right" : "wxi-angle-left"}></i>
                 </div>
                 ${
-                    !column.column.collapsed
+                    !props.column.collapsed
                         ?   `<div class="wx-label" data-action="rename">
-                                ${escapeHTML(column.column.label)}
-                                (${column.columnState.cardsCount})
+                                ${escapeHTML(props.column.label)}
+                                (${props.columnState.cardsCount})
                             </div>`
                         : ""
                 }
                 ${
-                    !column.column.collapsed
-                        ?   `<div class="wx-menu" data-menu-id=${column.id}>
+                    !props.column.collapsed
+                        ?   `<div class="wx-menu" data-menu-id=${props.column.id}>
                                 <i class="wxi-dots-h"></i>
                             </div>`
                         : ""
                 }`;
     }),
-    collapsedTemplate: template(column => {
+    collapsedTemplate: template(props => {
         return `<div class="wx-collapsed-label">
-                    <div class="wx-label-text">${escapeHTML(column.column.label)} (${
-                        column.columnState?.cardsCount
+                    <div class="wx-label-text">${escapeHTML(props.column.label)} (${
+                        props.columnState?.cardsCount
                     })</div>
                 </div>`;
     }),

docs/api/config/js_kanban_editorshape_config.md

@@ -19,6 +19,7 @@ editorShape?: [
         type: string, 
         key: string, 
         label?: string, 
+        modalSection?: "left" | "right",
 
         // for the "dateRange" type only
         key: {
@@ -182,6 +183,9 @@ In the Kanban editor you can use the following types of fields: **dateRange**, *
 ~~~
 
 - `label` - (optional) an editor field label
+- `modalSection` - (optional) defines in which column of the modal editor the field is placed. Applied only when the editor is shown as a modal window via the [`editor.placement: "modal"`](api/config/js_kanban_editor_config.md) property. The possible values are:
+    - `"left"` - the field is placed in the left column
+    - `"right"` - the field is placed in the right column (default)
 
 #### - Parameters for a "dateRange" type
 
@@ -466,6 +470,7 @@ new kanban.Kanban("#root", {
 
 - The ***dateRange*** type was added in v1.3
 - The ***comments*** and ***links*** types of editor, and ***format*** parameters were added in v1.4
+- The ***modalSection*** parameter was added in v1.6
 - The ***clearButton*** parameter was replaced with the ***clear*** parameter
 
 **Related articles:** [Configuration](guides/configuration.md/#editor)

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 `
+        <div class="custom-card" style="padding:20px">
+            <div class="custom-label">${label}</div>
+            <div class="custom-description">${description || ""}</div>
+        </div>
+    `;
+};
+
+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)

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

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

docs/api/config/toolbar_items_config.md

@@ -26,8 +26,8 @@ items?: [
                 }
             }, {...}
         ],
-        resultTemplate?: template(searchResult => {
-            return "The HTML template of the search result";
+        resultTemplate?: template(({ result }) => {
+            return `HTML template using ${result.label}`;
         }) 
     },
     "sort" | {
@@ -66,7 +66,7 @@ In the **items** array you can specify the following parameters:
         - ***card*** - an object of the card data
         - ***value*** - a searched value, specified in the search bar
         - ***by*** - a key of card field, by which the cards will be searched
-- `searchResult` - (optional) a template for displaying the custom search result
+- `resultTemplate` - (optional) a template for displaying the custom search result
 
 ~~~jsx
 items: [
@@ -93,10 +93,10 @@ items: [
                 }
             }
         ],
-        resultTemplate: kanban.template(searchResult => {
+        resultTemplate: kanban.template(({ result }) => {
             return `<div class="list-item">
-                <div class="list-item-text">${searchResult.result.label}</div>
-                ${searchResult.result.description ? `<div class="list-item-text item-description">${searchResult.result.description}</div>` : ""}
+                <div class="list-item-text">${result.label}</div>
+                ${result.description ? `<div class="list-item-text item-description">${result.description}</div>` : ""}
             </div>`
         })
     },
@@ -161,10 +161,10 @@ new kanban.Toolbar("#toolbar", {
     items: [
         {
             type: "search",
-            resultTemplate: kanban.template(searchResult => {
+            resultTemplate: kanban.template(({ result }) => {
                 return `<div class="list-item">
-                            <div class="list-item-text">${searchResult.result.label}</div>
-                            ${searchResult.result.description ? `<div class="list-item-text item-description">${searchResult.result.description}</div>` : ""}
+                            <div class="list-item-text">${result.label}</div>
+                            ${result.description ? `<div class="list-item-text item-description">${result.description}</div>` : ""}
                         </div>`
             })
         },
@@ -182,7 +182,7 @@ new kanban.Toolbar("#toolbar", {
 
 - The *"Undo"* and *"Redo"* controls were added in v1.3
 - The ***items.options[0].label*** parameter of the **sort** control was replaced by the ***items.options[0].text*** parameter in v1.4
-- The ***items.searchResult*** parameter of the **"search"** control was added in v1.6
+- The ***items.resultTemplate*** parameter of the **"search"** control was added in v1.6
 
 **Related articles:** [Configuration](guides/configuration.md#toolbar) and [Customization](guides/customization.md#custom-toolbar)
 

docs/api/overview/internal_rest_overview.md

@@ -6,11 +6,15 @@ description: You can have an Internal RestDataProvider methods overview of JavaS
 
 # RestDataProvider methods
 
-| Name                                                         | Description                                                        |
-| ------------------------------------------------------------ | ------------------------------------------------------------------ |
-| [](api/provider/rest_methods/js_kanban_getcards_method.md)    | @getshort(api/provider/rest_methods/js_kanban_getcards_method.md)   |
-| [](api/provider/rest_methods/js_kanban_getcolumns_method.md)  | @getshort(api/provider/rest_methods/js_kanban_getcolumns_method.md) |
-| [](api/provider/rest_methods/js_kanban_getlinks_method.md)    | @getshort(api/provider/rest_methods/js_kanban_getlinks_method.md)   |
-| [](api/provider/rest_methods/js_kanban_getrows_method.md)     | @getshort(api/provider/rest_methods/js_kanban_getrows_method.md)    |
-| [](api/provider/rest_methods/js_kanban_getusers_method.md)    | @getshort(api/provider/rest_methods/js_kanban_getusers_method.md)   |
-| [](api/provider/rest_methods/js_kanban_send_method.md)        | @getshort(api/provider/rest_methods/js_kanban_send_method.md)       |
+| Name                                                            | Description                                                           |
+| --------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [](api/provider/rest_methods/js_kanban_getcards_method.md)      | @getshort(api/provider/rest_methods/js_kanban_getcards_method.md)     |
+| [](api/provider/rest_methods/js_kanban_getcolumns_method.md)    | @getshort(api/provider/rest_methods/js_kanban_getcolumns_method.md)   |
+| [](api/provider/rest_methods/js_kanban_gethandlers_method.md)   | @getshort(api/provider/rest_methods/js_kanban_gethandlers_method.md)  |
+| [](api/provider/rest_methods/js_kanban_getidresolver_method.md) | @getshort(api/provider/rest_methods/js_kanban_getidresolver_method.md)|
+| [](api/provider/rest_methods/js_kanban_getlinks_method.md)      | @getshort(api/provider/rest_methods/js_kanban_getlinks_method.md)     |
+| [](api/provider/rest_methods/js_kanban_getqueue_method.md)      | @getshort(api/provider/rest_methods/js_kanban_getqueue_method.md)     |
+| [](api/provider/rest_methods/js_kanban_getrows_method.md)       | @getshort(api/provider/rest_methods/js_kanban_getrows_method.md)      |
+| [](api/provider/rest_methods/js_kanban_getusers_method.md)      | @getshort(api/provider/rest_methods/js_kanban_getusers_method.md)     |
+| [](api/provider/rest_methods/js_kanban_send_method.md)          | @getshort(api/provider/rest_methods/js_kanban_send_method.md)         |
+| [](api/provider/rest_methods/js_kanban_setheaders_method.md)    | @getshort(api/provider/rest_methods/js_kanban_setheaders_method.md)   |

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)         |