diff --git a/docs/api/methods/js_kanban_parse_method.md b/docs/api/methods/js_kanban_parse_method.md index 0aee15c..4779b61 100644 --- a/docs/api/methods/js_kanban_parse_method.md +++ b/docs/api/methods/js_kanban_parse_method.md @@ -46,4 +46,4 @@ board.parse({ **Change log:** Starting from v1.1 you don't need to reset initial data in constructor before parsing new data -**Related articles:** [Working with Data](guides/working_with_data.md#loading-data-from-local-source) +**Related articles:** [Working with Data](guides/working_with_data.md#load-data-from-a-local-source) diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index 14ccffe..273906b 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -6,74 +6,43 @@ description: You can learn about the configuration in the documentation of the D # Configuration -You can configure the *Kanban* appearance and functionality via the corresponding API. The available parameters will allow you to: - -- configure the cards appearance via the [`cardShape`](api/config/js_kanban_cardshape_config.md) property -- configure the editor fields via the [`editorShape`](api/config/js_kanban_editorshape_config.md) property -- configure the editor behaviour via the [`editor`](api/config/js_kanban_editor_config.md) property -- configure rendering and scrolling via the [`renderType`](api/config/js_kanban_rendertype_config.md) and [`scrollType`](api/config/js_kanban_scrolltype_config.md) properties -- configure the Kanban history via the [`history`](api/config/js_kanban_history_config.md) property -- customize the card appearance via the [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md) property - - *Refer to the [**Customization**](guides/customization.md) section for details!* -- apply the desired locale via the [`locale`](api/config/js_kanban_locale_config.md) property - - *Refer to the [**Localization**](guides/localization.md) section for details!* -- load data for cards, columns, rows and links via the corresponding [`cards`](api/config/js_kanban_cards_config.md), [`columns`](api/config/js_kanban_columns_config.md), [`rows`](api/config/js_kanban_rows_config.md) and [`links`](api/config/js_kanban_links_config.md) properties - - *Refer to the [**Working with data**](guides/working_with_data.md) section for details!* +You can configure the Kanban appearance and functionality with the following properties: -## Cards - -The board of Kanban consists of the *cards* distributed into *columns* and *rows*. You can configure the cards appearance using the [`cardShape`](api/config/js_kanban_cardshape_config.md) configuration property. There are several predefined fields you can include (or exclude) into the card template, namely: - -- a card label via the `label: boolean` config -- a card description via the `description: boolean` config - - :::tip - You can manage the **label** and **description** fields of any card via the corresponding inputs of the Kanban editor. If you activate these fields, the corresponding inputs will be displayed in the editor automatically. To configure these inputs, you can use the [**text** and **textarea**](#text-and-textarea-types) types. - ::: - -- a card progress via the `progress: boolean` config - - :::tip - You can manage the **progress** field of any card via the corresponding control of the Kanban editor. If you activate this field, the corresponding control will be displayed in the editor automatically. To configure this control, you can use the [**progress**](#progress-type) type. - ::: - -- a start date via the `start_date: boolean` config -- an end date via the `end_date: boolean` config - - :::tip - You can manage the **start date** and **end date** fields of any card via the corresponding controls of the Kanban editor. If you activate these fields, the corresponding controls will be displayed in the editor automatically. To configure these controls, you can use the [**date**](#date-and-daterange-types) type. - ::: - -- a card context menu via the `menu: boolean` config -- a card attachment via the `attached: boolean` config - - :::tip - You can **attache files** to any card via the corresponding field of the Kanban editor. To configure this field, you can use the [**files**](#files-type) type. - ::: - -- a card color via the `color: boolean` config - - :::tip - You can manage the **top color line** of any card via the corresponding control of the Kanban editor. If you activate **color**, the corresponding control (*colorpicker*) will be displayed in the editor automatically. To configure this control, you can use the [**color**](#color-type) type. - ::: - -- a card cover (*preview image*) via the `cover: boolean` config -- a card comment(s) via the `comments: boolean` config -- a confirmation dialog to confirm or decline the card deletion via the `confirmDeletion: boolean` config -- a card vote(s) via the `votes: boolean | { show: boolean, clicable: true }` config -- a card assignment (users) via the `users: boolean | { show: boolean, values: object, maxCount: number | false }` config +- [`cardShape`](api/config/js_kanban_cardshape_config.md) — set up card appearance and built-in fields +- [`editorShape`](api/config/js_kanban_editorshape_config.md) — define editor fields +- [`editor`](api/config/js_kanban_editor_config.md) — control editor visibility, autosave, and placement +- [`renderType`](api/config/js_kanban_rendertype_config.md), [`scrollType`](api/config/js_kanban_scrolltype_config.md) — adjust card rendering and board scrolling +- [`history`](api/config/js_kanban_history_config.md) — manage history of card operations +- [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md) — customize card appearance (see the [Customization](guides/customization.md) section) +- [`locale`](api/config/js_kanban_locale_config.md) — apply a locale (see the [Localization](guides/localization.md) section) +- [`cards`](api/config/js_kanban_cards_config.md), [`columns`](api/config/js_kanban_columns_config.md), [`rows`](api/config/js_kanban_rows_config.md), [`links`](api/config/js_kanban_links_config.md) — load data for cards, columns, rows, and links (see the [Working with data](guides/working_with_data.md) section) - :::tip - You can assign one or several users to any card via the corresponding control of the Kanban editor. To configure the control for assigning a single user, use the [**combo** or **select**](#combo-select-and-multiselect-types) types of editor. To assign multiple users, use the [**multiselect**](#combo-select-and-multiselect-types) type. - ::: +## Cards -- a card priority via the `priority: boolean | { show: boolean, values: object }` config +The Kanban board consists of cards distributed into columns and rows. Use the [`cardShape`](api/config/js_kanban_cardshape_config.md) property to configure card appearance and built-in fields: + +- `label: boolean | { show }` — card label, edited with the [`text`](#text-and-textarea-types) type +- `description: boolean | { show }` — card description, edited with the [`textarea`](#text-and-textarea-types) type +- `progress: boolean | { show }` — card progress, edited with the [`progress`](#progress-type) type +- `start_date: boolean | { show, format }` — card start date, edited with the [`date`](#date-and-daterange-types) type +- `end_date: boolean | { show, format }` — card end date, edited with the [`date`](#date-and-daterange-types) type +- `menu: boolean | { show, items }` — card context menu +- `attached: boolean | { show }` — card attachment, edited with the [`files`](#files-type) type +- `color: boolean | { show, values }` — top color line of the card, edited with the [`color`](#color-type) type +- `cover: boolean | { show }` — card preview image +- `comments: boolean | { show }` — card comments +- `confirmDeletion: boolean | { show }` — confirmation dialog for card deletion +- `votes: boolean | { show, clickable }` — card votes +- `users: boolean | { show, values, maxCount }` — users assigned to the card, edited with the [`combo`, `select`, or `multiselect`](#combo-select-and-multiselect-types) types +- `priority: boolean | { show, values }` — card priority, edited with the [`combo` or `select`](#combo-select-and-multiselect-types) type +- `css: (card) => string` — function that returns a CSS class applied to a card conditionally +- `headerFields: [{ key, label, css }]` — custom card fields - :::tip - You can manage the **priority** of any card via the corresponding control of the Kanban editor. If you activate **priority**, the corresponding control will be displayed in the editor automatically. To configure this control, you can use the [**combo** or **select**](#combo-select-and-multiselect-types) types only. - ::: +:::tip +When you activate a field in `cardShape`, the editor displays the matching control automatically. Configure each control through the [`editorShape`](api/config/js_kanban_editorshape_config.md) property — see [Editor](#editor) for the available types. +::: -- *a custom field* via the `headerFields: [ { key: string, label: string, css: string } ]` config +The following code snippet configures cards with custom users, priorities, and a custom header field: ~~~jsx {12-35,42} const users = [ // users data @@ -122,36 +91,36 @@ new kanban.Kanban("#root", { ~~~ :::note -Unless you specify the card settings via the [`cardShape`](api/config/js_kanban_cardshape_config.md) property, the widget will apply a [**defaultCardShape**](api/config/js_kanban_cardshape_config.md#default-config) set of parameters! +If you do not specify card settings through the [`cardShape`](api/config/js_kanban_cardshape_config.md) property, the widget falls back to [`defaultCardShape`](api/config/js_kanban_cardshape_config.md#default-config). ::: ## Editor -:::info -You can display the Editor as the **sidebar** or **modal window** using the [`editor.placement`](api/config/js_kanban_editor_config.md) property! -::: +The Kanban editor contains fields for managing card data. Use the [`editorShape`](api/config/js_kanban_editorshape_config.md) property to configure editor fields. The following field types are available: -The *Editor* of Kanban consists of the fields for managing the cards data. To configure the editor fields (controls), you can use the [`editorShape`](api/config/js_kanban_editorshape_config.md) property. You can use the following types of editor fields: +- [`combo`, `select`, `multiselect`](#combo-select-and-multiselect-types) — dropdown options +- [`color`](#color-type) — color picker +- [`text`, `textarea`](#text-and-textarea-types) — text inputs +- [`progress`](#progress-type) — progress slider +- [`files`](#files-type) — file uploader +- [`date`, `dateRange`](#date-and-daterange-types) — single date or date range +- [`comments`](#comments-type) — card comments +- [`links`](#links-type) — card links -- [**combo**, **select**, and **multiselect**](#combo-select-and-multiselect-types) -- [**color**](#color-type) -- [**text** and **textarea**](#text-and-textarea-types) -- [**progress**](#progress-type) -- [**files**](#files-type) -- [**date** and **dataRange**](#date-and-daterange-types) -- [**comments**](#comments-type) -- [**links**](#links-type) +:::info +Display the editor as a sidebar or modal window with the [`editor.placement`](api/config/js_kanban_editor_config.md) property. +::: -### Combo, Select and Multiselect types +### Combo, select, and multiselect types -The editor fields of **combo**, **select**, and **multiselect** types can be set in the following way: +The following code snippet configures a dropdown for picking a card priority: ~~~jsx {3-12} new kanban.Kanban("#root", { editorShape: [ { type: "combo", // or "select" and "multiselect" - key: "priority", // the "priority" key is used when configuring the "cardShape" property + key: "priority", // use the "priority" key in the "cardShape" property label: "Priority", values: [ { id: 1, label: "high" }, @@ -159,19 +128,19 @@ new kanban.Kanban("#root", { { id: 3, label: "low" } ] }, - // settings of other fields + // settings for other fields ] }); ~~~ :::info -For the editor field of **"multiselect"** and **"combo"** types you can also specify a path to the preview image via the **avatar** property: +For `multiselect` and `combo` fields, set a path to the preview image through the `avatar` property: ~~~jsx {3,9,13} editorShape: [ { type: "multiselect", // or "combo" - key: "users", // the "users" key is used when configuring the "cardShape" property + key: "users", // use the "users" key in the "cardShape" property label: "Users", values: [ { @@ -184,7 +153,7 @@ editorShape: [ } ] }, - // settings of other fields + // settings for other fields ] ~~~ @@ -193,14 +162,14 @@ editorShape: [ ### Color type -The editor field of **color** type can be set in the following way: +The following code snippet configures the editor field for picking a card color: ~~~jsx {3-12} new kanban.Kanban("#root", { editorShape: [ { type: "color", - key: "color", // the "color" key is used when configuring the "cardShape" property + key: "color", // use the "color" key in the "cardShape" property label: "Card color", values: ["#65D3B3", "#FFC975", "#58C3FE"], config: { @@ -208,14 +177,14 @@ new kanban.Kanban("#root", { placeholder: "Select color" } }, - // settings of other fields + // settings for other fields ] }); ~~~ -### Text and Textarea types +### Text and textarea types -The editor fields of **text** and **textarea** types can be set in the following way: +The following code snippet configures the editor field for entering a card label: ~~~jsx {3-14} new kanban.Kanban("#root", { @@ -232,21 +201,21 @@ new kanban.Kanban("#root", { inputStyle: "height: 50px;" } }, - // settings of other fields + // settings for other fields ] }); ~~~ ### Progress type -The editor field of **progress** type can be set in the following way: +The following code snippet configures the editor field for setting card progress: ~~~jsx {3-12} new kanban.Kanban("#root", { editorShape: [ { type: "progress", - key: "progress", // the "progress" key is used when configuring the "cardShape" property + key: "progress", // use the "progress" key in the "cardShape" property label: "Progress", config: { min: 10, @@ -254,16 +223,18 @@ new kanban.Kanban("#root", { step: 5 } }, - // settings of other fields + // settings for other fields ] }); ~~~ ### Files type -The editor field of **files** type can be set in the following way: +Set the `uploadURL` parameter to a string for a basic upload, or to a function for a custom request. -#### Configuring Upload Url as String +#### Configure upload URL as string + +The following code snippet uses a string URL for the file uploader: ~~~jsx {4-15} const url = "https://docs.dhtmlx.com/kanban-backend"; @@ -271,9 +242,9 @@ new kanban.Kanban("#root", { editorShape: [ { type: "files", - key: "attached", // the "attached" key is used when configuring the "cardShape" property + key: "attached", // use the "attached" key in the "cardShape" property label: "Attachment", - uploadURL: url + "/uploads", // specify url as string + uploadURL: url + "/uploads", // set URL as string config: { accept: "image/*", // "video/*", "audio/*" disabled: false, @@ -281,12 +252,14 @@ new kanban.Kanban("#root", { folder: false } }, - // settings of other fields + // settings for other fields ] }); ~~~ -#### Configuring Upload Url as Function +#### Configure upload URL as function + +Pass a function to `uploadURL` to add custom headers, tokens, or response handling. The following code snippet sends each file with a bearer token: ~~~jsx {9-31} const url = "https://docs.dhtmlx.com/kanban-backend"; @@ -324,9 +297,9 @@ new kanban.Kanban("#root", { }); ~~~ -### Date and DateRange types +### Date and dateRange types -The editor field of **date** type can be set in the following way: +The following code snippet configures the editor field for a single date: ~~~jsx {3-8} new kanban.Kanban("#root", { @@ -337,12 +310,12 @@ new kanban.Kanban("#root", { label: "Start date", format: "%d/%m/%y" }, - // settings of other fields + // settings for other fields ] }); ~~~ -The editor field of **dateRange** type can be set in the following way: +The following code snippet configures the editor field for a start/end date range: ~~~jsx {3-11} new kanban.Kanban("#root", { @@ -356,14 +329,14 @@ new kanban.Kanban("#root", { label: "Date Range", format: "%d/%m/%y" }, - // settings of other fields + // settings for other fields ] }); ~~~ ### Comments type -The editor field of **comments** type can be set in the following way: +The following code snippet configures the comments field of the editor: ~~~jsx {3-13} new kanban.Kanban("#root", { @@ -379,14 +352,14 @@ new kanban.Kanban("#root", { confirmDeletion: true } }, - // settings of other fields + // settings for other fields ] }); ~~~ ### Links type -The editor field of **links** type can be set in the following way: +The following code snippet configures the links field of the editor: ~~~jsx {3-10} new kanban.Kanban("#root", { @@ -399,15 +372,16 @@ new kanban.Kanban("#root", { confirmDeletion: true } }, - // settings of other fields + // settings for other fields ] }); ~~~ -### Binding editor fields to card fields +### Bind editor fields to card fields -:::info -To link the editor field to the corresponding card field, you need to provide special **key** in the object of [`editorShape`](api/config/js_kanban_editorshape_config.md) property (`key: "editor_field_key"`). The value of this key needs to be set to *true* in the [`cardShape`](api/config/js_kanban_cardshape_config.md) property (for built-in card fields) or specified in the **headerFields** array (for custom card fields). You can provide the initial data of any field via this key as well. +Each editor field links to a card field through a shared `key`. Set the same `key` value in the [`editorShape`](api/config/js_kanban_editorshape_config.md) entry and in the [`cardShape`](api/config/js_kanban_cardshape_config.md) property. For built-in card fields, set the key to `true`. For custom fields, list the key in the `headerFields` array. The same key supplies initial card data. + +The following code snippet binds the `label` and `note` editor fields to the matching card fields: ~~~jsx {5,13,22,25,33-34,38-39,45-47} // editor settings @@ -431,10 +405,10 @@ const editorShape = [ ]; // cards settings const cardShape = { - label: true, // a key of built-in field + label: true, // built-in field key headerFields: [ { - key: "note", // a key of custom field + key: "note", // custom field key label: "Note" } ] @@ -461,18 +435,21 @@ new kanban.Kanban("#root", { // other configuration parameters }); ~~~ -::: :::note -Unless you specify the editor settings via the [`editorShape`](api/config/js_kanban_editorshape_config.md) property, the widget will apply a [**defaultEditorShape**](api/config/js_kanban_editorshape_config.md#default-config) set of parameters. In this case, the default controls and inputs will be displayed in editor only after activating the corresponding fields of cards via the [`cardShape`](api/config/js_kanban_cardshape_config.md) property. +If you do not specify editor settings through the [`editorShape`](api/config/js_kanban_editorshape_config.md) property, the widget falls back to [`defaultEditorShape`](api/config/js_kanban_editorshape_config.md#default-config). The default controls and inputs appear in the editor only after you activate the corresponding card fields through the [`cardShape`](api/config/js_kanban_cardshape_config.md) property. ::: -### Configuring the editor +### Configure editor behavior + +The [`editor`](api/config/js_kanban_editor_config.md) property controls editor visibility, autosave, and placement: -Using the [`editor`](api/config/js_kanban_editor_config.md) property, you can configure the editor in the following way: +- [`editor.show`](api/config/js_kanban_editor_config.md) — enable or disable the editor +- [`editor.placement`](api/config/js_kanban_editor_config.md) — display the editor as a `"sidebar"` or `"modal"` window +- [`editor.autoSave`](api/config/js_kanban_editor_config.md) — enable or disable autosave mode +- [`editor.debounce`](api/config/js_kanban_editor_config.md) — delay before autosaving (applies only with `autoSave: true`) -- enables/disables an autosave mode of the editor via the *`editor.autoSave`* property -- specify a delay time of autosaving data via the *`editor.debounce`* property (works with the ***autoSave: true*** parameter only) +The following code snippet enables autosave with a 2-second delay: ~~~jsx {6-9} // create Kanban @@ -488,9 +465,53 @@ new kanban.Kanban("#root", { }); ~~~ +## Rendering and scrolling + +The Kanban widget renders all cards and scrolls the entire board by default. For boards with many cards, switch to lazy rendering or per-column scrolling: + +- [`renderType`](api/config/js_kanban_rendertype_config.md) — set to `"lazy"` to render only the cards visible on the board +- [`scrollType`](api/config/js_kanban_scrolltype_config.md) — set to `"column"` to scroll each column independently + +The following code snippet enables lazy rendering and per-column scrolling: + +~~~jsx {5-7} +new kanban.Kanban("#root", { + columns, + cards, + rows, + renderType: "lazy", + scrollType: "column", + cardHeight: 150 +}); +~~~ + +:::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. +::: + +## History of changes + +Kanban tracks card operations and exposes undo and redo controls on the Toolbar. Use the [`history`](api/config/js_kanban_history_config.md) property to disable this behavior. + +The following code snippet disables history tracking: + +~~~jsx {4} +new kanban.Kanban("#root", { + columns, + cards, + history: false +}); +~~~ + +:::tip +To skip individual operations from history, pass the [`$meta`](api/common/js_kanban_meta_parameter.md) parameter to methods or events. +::: + ## Toolbar -**Toolbar** of Kanban consists of the searchbar for *searching cards* and controls for *sorting cards* and *adding new columns and rows*. To display Toolbar, you need to initialize it in a separate container using the **kanban.Toolbar()** constructor. +The Kanban Toolbar provides a searchbar, sort controls, and controls for adding columns and rows. Initialize the Toolbar in a separate container with the `kanban.Toolbar()` constructor. + +The following code snippet creates a Toolbar bound to the Kanban instance: ~~~jsx {13} // create Kanban @@ -508,7 +529,7 @@ const board = new kanban.Kanban("#root", { new kanban.Toolbar("#toolbar", { api: board.api }); ~~~ -You can manage (*hide/show/customize*) the Toolbar controls using the **items** property: +Use the [`items`](api/config/toolbar_items_config.md) property to show, hide, or customize Toolbar controls. The following code snippet sets a custom searchbar, undo and redo controls, a custom sort, and column and row controls: ~~~jsx {6-51} // create Kanban @@ -541,8 +562,8 @@ new kanban.Toolbar("#toolbar", { }) }, "spacer", // empty space - "undo", // control to undo the card operations in the history - "redo", // control to redo the card operations in the history + "undo", // undo card operations in the history + "redo", // redo card operations in the history { // custom sort control type: "sort", options: [ @@ -566,11 +587,11 @@ new kanban.Toolbar("#toolbar", { ~~~ :::tip -To hide some of the Toolbar controls, remove the corresponding string(s) from the **items** array. +Remove a control from the `items` array to hide that control. ::: ## Example -In this snippet you can see how to configure the **Cards**, **Editor** and **Toolbar** of Kanban: +The following snippet configures the cards, editor, and Toolbar of Kanban: diff --git a/docs/guides/customization.md b/docs/guides/customization.md index b2e14ea..be53591 100644 --- a/docs/guides/customization.md +++ b/docs/guides/customization.md @@ -6,37 +6,139 @@ description: You can learn about the customization in the documentation of the D # Customization -Besides configuring Kanban, you can customize its appearance and behaviour. The widget allows you to specify a custom template for cards, modify a context menu for cards, columns and rows, change the Toolbar structure and functionality, and apply custom css styles to Kanban. +You can customize the Kanban appearance and behavior with the following properties: + +- [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md) — render cards with a custom HTML template +- [`cardShape.menu`](api/config/js_kanban_cardshape_config.md), [`columnShape.menu`](api/config/js_kanban_columnshape_config.md), [`rowShape.menu`](api/config/js_kanban_rowshape_config.md) — modify the context menu for cards, columns, and rows +- [`columnShape.headerTemplate`](api/config/js_kanban_columnshape_config.md), [`columnShape.collapsedTemplate`](api/config/js_kanban_columnshape_config.md) — replace column header templates +- [`cardShape.css`](api/config/js_kanban_cardshape_config.md), [`columnShape.css`](api/config/js_kanban_columnshape_config.md), [`rowShape.css`](api/config/js_kanban_rowshape_config.md) — apply CSS classes conditionally +- [`items`](api/config/toolbar_items_config.md) — rearrange Toolbar structure and add custom controls +- CSS variables — adjust visual styles (see the [Stylization](guides/stylization.md) section) ## Custom cards -To display cards by a custom template, you can use the [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md) property. It is a callback function that allows you to define the desired styles and logic and apply it to Kanban. See the snippet below: +Use the [`cardTemplate`](api/config/js_kanban_cardtemplate_config.md) property to render cards with a custom HTML template. The callback returns the markup for each card. + +The callback receives an object with the following parameters: + +- `cardFields` — card data +- `selected` — whether the card is selected +- `dragging` — whether the card is being dragged +- `cardShape` — card configuration + +To embed a context menu trigger in a custom card template, wrap the menu icon in a `
` with the `data-menu-id=${cardFields.id}` attribute (the same structure as the built-in card). The widget binds the menu to the wrapper through this attribute. + +The following demo applies a custom card template: ## Custom context menu -To customize a context menu for cards, columns and rows, you can use the corresponding [`cardShape`](api/config/js_kanban_cardshape_config.md), [`columnShape`](api/config/js_kanban_columnshape_config.md) and [`rowShape`](api/config/js_kanban_rowshape_config.md) properties. See the snippet below: +Configure the context menu for cards, columns, and rows through the [`cardShape.menu`](api/config/js_kanban_cardshape_config.md), [`columnShape.menu`](api/config/js_kanban_columnshape_config.md), and [`rowShape.menu`](api/config/js_kanban_rowshape_config.md) properties. Each `menu.items` entry can use a built-in action ID to invoke a default operation, or define a custom `onClick` handler for any other behavior. - +### `cardShape.menu` + +By default the card menu shows **Duplicate** and **Delete** options. The **Edit** option appears only when card editing is enabled and selection is disabled. Available built-in action IDs: -## Custom toolbar +- `"duplicate-card"` — duplicate the card +- `"delete-card"` — delete the card +- `"set-edit"` — open the card editor (shown when editing is available) -To customize the Toolbar structure and its functionality, you can use the [`items`](api/config/toolbar_items_config.md) property. In the array of this config you can define controls you need, arrange them in the desired order as well as modify their behaviour. +### `columnShape.menu` -In the snippet below you can see how to customize the following: +- `"add-card"` — add a new card to the column +- `"set-edit"` — rename the column +- `"move-column:left"`, `"move-column:right"` — move the column left or right +- `"delete-column"` — delete the column + +### `rowShape.menu` + +- `"set-edit"` — rename the row +- `"move-row:up"`, `"move-row:down"` — move the row up or down +- `"delete-row"` — delete the row + +Set `menu.items` to a function to render a different menu per card, column, or row. Return `null` or `false` from the function to hide the menu for a specific item. + +The following demo applies a custom context menu: + + -- an order of controls arrangement -- a searchbar and its behaviour -- a sort control and its behaviour -- a custom control and its behaviour +## Custom column headers + +The [`columnShape`](api/config/js_kanban_columnshape_config.md) property provides templates and behavior for column headers: + +- [`columnShape.headerTemplate`](api/config/js_kanban_columnshape_config.md) — HTML template of the column header in the expanded state +- [`columnShape.collapsedTemplate`](api/config/js_kanban_columnshape_config.md) — HTML template of the column header in the collapsed state +- [`columnShape.fixedHeaders`](api/config/js_kanban_columnshape_config.md) — freeze column headers during vertical scroll (default: `true`) + +The following code snippet sets a custom header template with a collapse icon, label with card count, and menu trigger: + +~~~jsx {5-21} +new kanban.Kanban("#root", { + columns, + cards, + columnShape: { + headerTemplate: kanban.template(({ column, columnState }) => { + return `
+ +
+ ${!column.collapsed + ? `
+ ${column.label} (${columnState.cardsCount}) +
+
+ +
` + : ""}`; + }), + collapsedTemplate: kanban.template(({ column }) => `
${column.label}
`) + } +}); +~~~ + +:::tip +For `fixedHeaders` to take effect, set a fixed height on the Kanban container so the board scrolls vertically. +::: + +## Conditional CSS classes + +To apply a CSS class conditionally, pass a function to the `css` parameter of [`cardShape`](api/config/js_kanban_cardshape_config.md), [`columnShape`](api/config/js_kanban_columnshape_config.md), or [`rowShape`](api/config/js_kanban_rowshape_config.md). The function returns a class name based on the current data: + +- [`cardShape.css: (card) => string`](api/config/js_kanban_cardshape_config.md) — class applied to a card +- [`columnShape.css: (column, cards) => string`](api/config/js_kanban_columnshape_config.md) — class applied to a column +- [`rowShape.css: (row, cards) => string`](api/config/js_kanban_rowshape_config.md) — class applied to a row + +The following code snippet highlights overdue cards and underloaded columns: + +~~~jsx {5,8} +new kanban.Kanban("#root", { + columns, + cards, + cardShape: { + css: (card) => card.end_date < new Date() ? "overdue" : "" + }, + columnShape: { + css: (column, cards) => cards.length < 5 ? "low-load" : "" + } +}); +~~~ + +## Custom Toolbar + +Use the [`items`](api/config/toolbar_items_config.md) property to customize the Toolbar structure. The array defines which controls appear, their order, and their behavior. An entry can be: + +- a built-in control: `"search"`, `"sort"`, `"undo"`, `"redo"`, `"addColumn"`, `"addRow"`, `"spacer"` +- an object that overrides the searchbar or sort control with custom options +- a custom control passed as a string identifier or a function + +The following demo customizes the order of controls, the searchbar, the sort control, and a custom control: ## Custom styles -You can customize the appearance of Kanban by changing values of the corresponding *CSS variables*. Refer to the [**Stylization**](guides/stylization.md) section for details. +Change the values of CSS variables to customize the Kanban appearance. See the [Stylization](guides/stylization.md) section for the full list. -In this snippet you can see how to apply custom styles to Kanban: +The following snippet applies custom styles to Kanban: diff --git a/docs/guides/initialization.md b/docs/guides/initialization.md index 5b171fa..31481fa 100644 --- a/docs/guides/initialization.md +++ b/docs/guides/initialization.md @@ -6,49 +6,51 @@ description: You can learn about the initialization in the documentation of the # Initialization -This guide will give you detailed instructions on how to create Kanban on a page to enrich your application with features of the Kanban board. Take the following steps to get a ready-to-use component: +Create a Kanban widget on a page in three steps: -1. [Include the Kanban source files on a page](#including-source-files). -2. [Create a container for Kanban](#creating-container). -3. [Initialize Kanban with a constructor](#initializing-kanban). +1. [Include source files](#include-source-files). +2. [Create a container](#create-a-container). +3. [Initialize Kanban](#initialize-kanban). -## Including source files +## Include source files -[Download the package](https://dhtmlx.com/docs/products/dhtmlxKanban/download.shtml) and unpack it into a folder of your project. +[Download the package](https://dhtmlx.com/docs/products/dhtmlxKanban/download.shtml) and unpack the contents into a folder of your project. -To create Kanban, you need to include 2 source files on your page: +Include the following source files on your page: - *kanban.js* - *kanban.css* -Make sure that you set correct relative paths to the source files: +Set correct relative paths to both files: ~~~html title="index.html" ~~~ -## Creating container +## Create a container -Add a container for Kanban and give it an ID, for example *"root"*: +Add a container for Kanban and assign an ID, for example `root`: ~~~jsx title="index.html"
~~~ -If you want to create the widget along with its *Toolbar*, you need to add a separate container for it: +To create the widget with a Toolbar, add a separate container for the Toolbar: ~~~jsx {1} title="index.html"
// container for Toolbar
// container for Kanban ~~~ -## Initializing Kanban +## Initialize Kanban -Initialize Kanban with the **kanban.Kanban** constructor. It takes two parameters: +Initialize Kanban with the `kanban.Kanban` constructor. The constructor takes two parameters: -- an HTML container (the ID of the HTML container) -- an object with configuration properties. [See the full list here](#configuration-properties) +- a CSS selector for the HTML container (or the container element itself) +- a configuration object (see the [full list of properties](#configuration-properties)) + +The following code snippet creates a Kanban instance: ~~~jsx title="index.html" // create Kanban @@ -57,35 +59,33 @@ new kanban.Kanban("#root", { }); ~~~ -If you want to create the widget along with its *Toolbar*, you need to initialize it separately using the **kanban.Toolbar** constructor. It also takes two parameters: - -- an HTML container (the ID of the HTML container) -- an object with configuration properties +To create the widget with a Toolbar, initialize the Toolbar separately with the `kanban.Toolbar` constructor. The Toolbar controls operate on the Kanban instance through the [`api`](api/config/toolbar_api_config.md) parameter. Pass `board.api` to bind the Toolbar to the board: -~~~jsx {6-8} title="index.html" +~~~jsx {7} title="index.html" // create Kanban const board = new kanban.Kanban("#root", { // configuration properties }); new kanban.Toolbar("#toolbar", { - // configuration properties + api: board.api, // required: links Toolbar controls to the Kanban instance + // other configuration properties }); ~~~ :::info -To learn more about configuring the Toolbar of Kanban, read the [**Configuration**](guides/configuration.md/#toolbar) section +For details on configuring the Toolbar, read the [Configuration](guides/configuration.md#toolbar) section. ::: ### Configuration properties -:::note -The full list of properties to configure **Kanban** can be found [**here**](api/overview/properties_overview.md).
-The full list of properties to configure **Toolbar of Kanban** can be found [**here**](api/overview/toolbar_properties_overview.md). -::: +For the full configuration reference: + +- [Kanban properties overview](api/overview/properties_overview.md) — all Kanban configuration properties +- [Toolbar properties overview](api/overview/toolbar_properties_overview.md) — all Toolbar configuration properties ## Example -In this snippet you can see how to initialize **Kanban** with the initial data: +The following snippet initializes Kanban with sample data: diff --git a/docs/guides/integration.md b/docs/guides/integration.md index 8836790..bdbe99f 100644 --- a/docs/guides/integration.md +++ b/docs/guides/integration.md @@ -6,12 +6,20 @@ description: You can learn about the integration in the documentation of the DHT # Integration with DHTMLX widgets -You can integrate DHTMLX Kanban with other DHTMLX widgets (for instance, [Gantt](https://docs.dhtmlx.com/gantt/), [Scheduler](https://docs.dhtmlx.com/scheduler/), [To Do List](https://docs.dhtmlx.com/todolist/)). Check the examples below. +You can integrate DHTMLX Kanban with other DHTMLX widgets, including: -## Integration with DHTMLX Gantt and Scheduler +- [Gantt](https://docs.dhtmlx.com/gantt/) +- [Scheduler](https://docs.dhtmlx.com/scheduler/) +- [To Do List](https://docs.dhtmlx.com/todolist/) + +## Gantt and Scheduler + +The following demo embeds a Kanban board alongside Gantt and Scheduler views: -## Integration with DHTMLX To Do List +## To Do List + +The following demo embeds a Kanban board alongside a To Do List: diff --git a/docs/guides/integration_with_angular.md b/docs/guides/integration_with_angular.md index 2713fda..4fbff7c 100644 --- a/docs/guides/integration_with_angular.md +++ b/docs/guides/integration_with_angular.md @@ -7,79 +7,79 @@ description: You can learn about the integration with Angular in the documentati # Integration with Angular :::tip -You should be familiar with basic concepts and patterns of **Angular** before reading this documentation. To refresh your knowledge, please refer to the [**Angular documentation**](https://v17.angular.io/docs). +This guide assumes familiarity with Angular concepts and patterns. For background, see the [Angular documentation](https://v17.angular.io/docs). ::: -DHTMLX Kanban is compatible with **Angular**. We have prepared code examples on how to use DHTMLX Kanban with **Angular**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/angular-kanban-demo). +DHTMLX Kanban is compatible with Angular. The full code example is available on [GitHub](https://github.com/DHTMLX/angular-kanban-demo). -## Creating a project +## Create a project :::info -Before you start to create a new project, install [**Angular CLI**](https://v17.angular.io/cli) and [**Node.js**](https://nodejs.org/en/). +Install [Angular CLI](https://v17.angular.io/cli) and [Node.js](https://nodejs.org/en/) before creating the project. ::: -Create a new **my-angular-kanban-app** project using Angular CLI. Run the following command for this purpose: +The following command creates a new *my-angular-kanban-app* project with Angular CLI: ~~~json ng new my-angular-kanban-app ~~~ :::note -If you want to follow this guide, disable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering) when creating new Angular app! +Disable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering) when prompted, so the project matches this guide. ::: -The command above installs all the necessary tools, so you don't need to run any additional commands. +The command installs all the necessary tools. No additional commands are required. -### Installation of dependencies +### Install dependencies -Go to the new created app directory: +Move into the new app directory: ~~~json cd my-angular-kanban-app ~~~ -Install dependencies and start the dev server. For this, use the [**yarn**](https://yarnpkg.com/) package manager: +Install dependencies and start the dev server with the [yarn](https://yarnpkg.com/) package manager: ~~~json yarn yarn start ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app runs on a localhost address (for example, `http://localhost:3000`). -## Creating Kanban +## Create Kanban -Now you should get the DHTMLX Kanban source code. First of all, stop the app and proceed with installing the Kanban package. +Stop the dev server and install the Kanban package. -### Step 1. Package installation +### Step 1. Install the package -Download the [**trial Kanban package**](/how_to_start/#installing-kanban-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial Kanban is available 30 days only. - -### Step 2. Component creation +Download the [trial Kanban package](/how_to_start/#installing-kanban-via-npm-or-yarn) and follow the steps in the README file. The trial version is available for 30 days. -Now you need to create an Angular component, to add Kanban with Toolbar into the application. Create the **kanban** folder in the **src/app/** directory, add a new file into it and name it **kanban.component.ts**. +### Step 2. Create the component + +Create an Angular component that mounts Kanban and the Toolbar. Create the *src/app/kanban/* folder and add a *kanban.component.ts* file inside. #### Import source files -Open the **kanban.component.ts** file and import Kanban source files. Note that: +Open *kanban.component.ts* and import the Kanban source files. The import path depends on the package version: -- if you use PRO version and install the Kanban package from a local folder, the imported path looks like this: +- For the PRO version installed from a local folder: ~~~jsx import { Kanban, Toolbar } from 'dhx-kanban-package'; ~~~ -- if you use the trial version of Kanban, specify the following path: +- For the trial version: ~~~jsx import { Kanban, Toolbar } from '@dhx/trial-kanban'; ~~~ -In this tutorial you can see how to configure the **trial** version of Kanban. +This tutorial uses the trial version of Kanban. -#### Set containers and initialize the Kanban with Toolbar +#### Set up containers and initialize Kanban -To display Kanban with Toolbar on the page, you need to set containers for Kanban and Toolbar, and initialize these components using the corresponding constructors: +To display Kanban with the Toolbar, set up two containers and call the constructors. The following code snippet defines the component template, references the containers, and creates the instances: ~~~jsx {1,8-11,15-18,24-31} title="kanban.component.ts" import { Kanban, Toolbar } from '@dhx/trial-kanban'; @@ -87,7 +87,7 @@ import { Component, ElementRef, OnInit, ViewChild, OnDestroy, ViewEncapsulation} @Component({ encapsulation: ViewEncapsulation.None, - selector: "kanban", // a template name used in the "app.component.ts" file as + selector: "kanban", // template name used in "app.component.ts" as styleUrls: ["./kanban.component.css"], // include the css file template: `
@@ -116,15 +116,15 @@ export class KanbanComponent implements OnInit, OnDestroy { } ngOnDestroy(): void { - this._kanban.destructor(); // destruct Kanban - this._toolbar.destructor(); // destruct Toolbar + this._kanban.destructor(); // destroy Kanban + this._toolbar.destructor(); // destroy Toolbar } } ~~~ -#### Adding styles +#### Add styles -To display Kanban correctly, you need to provide the corresponding styles. For this purpose, you can create the **kanban.component.css** file in the **src/app/kanban/** directory and specify important styles for Kanban and its container: +Add styles for Kanban and the container. Create the *kanban.component.css* file in the *src/app/kanban/* directory: ~~~css title="kanban.component.css" /* import Kanban styles */ @@ -150,9 +150,9 @@ body{ } ~~~ -#### Loading data +#### Load data -To add data into Kanban, you need to provide a data set. You can create the **data.ts** file in the **src/app/kanban/** directory and add some data into it: +To populate Kanban, provide a data set. Create the *data.ts* file in the *src/app/kanban/* directory: ~~~jsx {2,14,37,48} title="data.ts" export function getData() { @@ -206,7 +206,7 @@ export function getData() { } ~~~ -Then open the ***kanban.component.ts*** file. Import the file with data and specify the corresponding data properties to the configuration object of Kanban within the `ngOnInit()` method, as shown below: +Open *kanban.component.ts*, import the dataset, and pass the data properties to the Kanban configuration object inside `ngOnInit()`: ~~~jsx {2,23,25-27} title="kanban.component.ts" import { Kanban, Toolbar } from '@dhx/trial-kanban'; @@ -253,7 +253,7 @@ export class KanbanComponent implements OnInit, OnDestroy { } ~~~ -You can also use the [`setConfig()`](/api/methods/js_kanban_setconfig_method/) or [`parse()`](/api/methods/js_kanban_parse_method/) method inside the `ngOnInit()` method of Angular to load data into Kanban. The `setConfig` or `parse()` method provides data reloading on each applied change. +As an alternative, load data after creating the instance with [`setConfig()`](/api/methods/js_kanban_setconfig_method/) or [`parse()`](/api/methods/js_kanban_parse_method/) inside `ngOnInit()`: ~~~jsx {2,23,37-42} title="kanban.component.ts" import { Kanban, Toolbar } from '@dhx/trial-kanban'; @@ -307,13 +307,13 @@ export class KanbanComponent implements OnInit, OnDestroy { } ~~~ -Now the Kanban component is ready to use. When the element will be added to the page, it will initialize the Kanban with data. You can provide necessary configuration settings as well. Visit our [Kanban API docs](/api/overview/properties_overview/) to check the full list of available properties. +The Kanban component is now ready. When the element renders, Kanban initializes with data. For the full list of supported configuration properties, see the [Kanban API reference](/api/overview/properties_overview/). -#### Handling events +#### Handle events -When a user makes some action in the Kanban, it invokes an event. You can use these events to detect the action and run the desired code for it. See the [full list of events](/api/overview/events_overview/). +User actions in Kanban trigger events. Listen to events to react to specific actions. For the complete list, see the [Kanban events reference](/api/overview/events_overview/). -Open the **kanban.component.ts** file and complete the `ngOnInit()` method in the following way: +Open *kanban.component.ts* and extend the `ngOnInit()` method: ~~~jsx {5-7} title="kanban.component.ts" // ... @@ -330,9 +330,9 @@ ngOnDestroy(): void { } ~~~ -### Step 3. Adding Kanban into the app +### Step 3. Add Kanban to the app -To add the ***KanbanComponent*** component into your app, open the ***src/app/app.component.ts*** file and replace the default code with the following one: +To register the `KanbanComponent` in the app, open *src/app/app.component.ts* and replace the default code: ~~~jsx {5} title="app.component.ts" import { Component } from "@angular/core"; @@ -346,7 +346,7 @@ export class AppComponent { } ~~~ -Then create the ***app.module.ts*** file in the ***src/app/*** directory and specify the *KanbanComponent* as shown below: +Create *app.module.ts* in the *src/app/* directory and declare the `KanbanComponent`: ~~~jsx {4-5,8} title="app.module.ts" import { NgModule } from "@angular/core"; @@ -363,7 +363,7 @@ import { KanbanComponent } from "./kanban/kanban.component"; export class AppModule {} ~~~ -The last step is to open the ***src/main.ts*** file and replace the existing code with the following one: +Open *src/main.ts* and replace the existing code: ~~~jsx title="main.ts" import { platformBrowserDynamic } from "@angular/platform-browser-dynamic"; @@ -373,7 +373,7 @@ platformBrowserDynamic() .catch((err) => console.error(err)); ~~~ -After that, you can start the app to see Kanban loaded with data on a page. +Run the app to view the populated Kanban board on the page. import trial from '@site/static/img/trial_kanban.png'; @@ -383,4 +383,4 @@ import trial from '@site/static/img/trial_kanban.png'; className="img_border" /> -Now you know how to integrate DHTMLX Kanban with Angular. You can customize the code according to your specific requirements. The final advanced example you can find on [**GitHub**](https://github.com/DHTMLX/angular-kanban-demo). +See the complete project on [GitHub](https://github.com/DHTMLX/angular-kanban-demo). diff --git a/docs/guides/integration_with_react.md b/docs/guides/integration_with_react.md index 02bf209..4f737a2 100644 --- a/docs/guides/integration_with_react.md +++ b/docs/guides/integration_with_react.md @@ -7,86 +7,86 @@ description: You can learn about the integration with React in the documentation # Integration with React :::tip -You should be familiar with the basic concepts and patterns of [**React**](https://react.dev) before reading this documentation. To refresh your knowledge, please refer to the [**React documentation**](https://react.dev/learn). +This guide assumes familiarity with [React](https://react.dev) concepts and patterns. For background, see the [React documentation](https://react.dev/learn). ::: -DHTMLX Kanban is compatible with **React**. We have prepared code examples on how to use DHTMLX Kanban with **React**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/react-kanban-demo). +DHTMLX Kanban is compatible with React. The full code example is available on [GitHub](https://github.com/DHTMLX/react-kanban-demo). -## Creating a project +## Create a project :::info -Before you start to create a new project, install [**Vite**](https://vite.dev/) (optional) and [**Node.js**](https://nodejs.org/en/). +Install [Vite](https://vite.dev/) (optional) and [Node.js](https://nodejs.org/en/) before creating the project. ::: -You can create a basic **React** project or use **React with Vite**. Let's name the project as **my-react-kanban-app**: +Create a basic React project (or React with Vite). Name the project *my-react-kanban-app*: ~~~json npx create-react-app my-react-kanban-app ~~~ -### Installation of dependencies +### Install dependencies -Go to the new created app directory: +Move into the new app directory: ~~~json cd my-react-kanban-app ~~~ -Install dependencies and start the dev server. For this, use a package manager: +Install dependencies and start the dev server with one of the package managers: -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: +- For [yarn](https://yarnpkg.com/): ~~~json yarn yarn start ~~~ -- if you use [**npm**](https://www.npmjs.com/), run the following commands: +- For [npm](https://www.npmjs.com/): ~~~json npm install npm run dev ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app runs on a localhost address (for example, `http://localhost:3000`). -## Creating Kanban +## Create Kanban -Now you should get the DHTMLX Kanban source code. First of all, stop the app and proceed with installing the Kanban package. +Stop the dev server and install the Kanban package. -### Step 1. Package installation +### Step 1. Install the package -Download the [**trial Kanban package**](/how_to_start/#installing-kanban-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial Kanban is available 30 days only. +Download the [trial Kanban package](/how_to_start/#installing-kanban-via-npm-or-yarn) and follow the steps in the README file. The trial version is available for 30 days. -### Step 2. Component creation +### Step 2. Create the component -Now you need to create a React component, to add a Kanban into the application. Create a new file in the ***src/*** directory and name it ***Kanban.jsx***. +Create a React component that adds Kanban to the application. Add a new file to the *src/* directory and name it *Kanban.jsx*. -#### Importing source files +#### Import source files -Open the ***Kanban.jsx*** file and import Kanban source files. Note that: +Open *Kanban.jsx* and import the Kanban source files. The import paths depend on the package version: -- if you use PRO version and install the Kanban package from a local folder, the import paths look like this: +- For the PRO version installed from a local folder: ~~~jsx title="Kanban.jsx" import { Kanban, Toolbar } from 'dhx-kanban-package'; import 'dhx-kanban-package/dist/kanban.css'; ~~~ -Note that depending on the used package, the source files can be minified. In this case make sure that you are importing the CSS file as ***kanban.min.css***. +If the package ships minified source files, import the CSS file as *kanban.min.css*. -- if you use the trial version of Kanban, specify the following paths: +- For the trial version: ~~~jsx title="Kanban.jsx" import { Kanban, Toolbar } from '@dhx/trial-kanban'; import "@dhx/trial-kanban/dist/kanban.css"; ~~~ -In this tutorial you can see how to configure the **trial** version of Kanban. +This tutorial uses the trial version of Kanban. -#### Setting containers and adding Kanban with Toolbar +#### Set up containers and initialize Kanban -To display Kanban with Toolbar on the page, you need to create containers for Kanban and Toolbar, and initialize these components using the corresponding constructors: +To display Kanban with the Toolbar, create two containers and call the constructors. The following code snippet wires up refs and instantiates the components inside `useEffect()`: ~~~jsx {2,6-7,10-11,13-17} title="Kanban.jsx" import { useEffect, useRef } from "react"; @@ -108,8 +108,8 @@ export default function KanbanComponent(props) { }); return () => { - kanban.destructor(); // destruct Kanban - toolbar.destructor(); // destruct Toolbar + kanban.destructor(); // destroy Kanban + toolbar.destructor(); // destroy Toolbar }; }, []); @@ -120,9 +120,9 @@ export default function KanbanComponent(props) { } ~~~ -#### Adding styles +#### Add styles -To display Kanban correctly, you need to specify important styles for Kanban and its container in the main css file of the project: +Add styles for Kanban and the container in the main CSS file: ~~~css title="index.css" /* specify styles for initial page */ @@ -146,9 +146,9 @@ body, } ~~~ -#### Loading data +#### Load data -To add data into the Kanban, you need to provide a data set. You can create the ***data.js*** file in the ***src/*** directory and add some data into it: +To populate Kanban, provide a data set. Create the *data.js* file in the *src/* directory: ~~~jsx {2,14,37,48} title="data.js" export function getData() { @@ -202,7 +202,7 @@ export function getData() { } ~~~ -Then open the ***App.js*** file and import data. After this you can pass data into the new created `` components as **props**: +Open *App.js*, import the dataset, and pass the values to the new `` component as props: ~~~jsx {2,5-6} title="App.js" import Kanban from "./Kanban"; @@ -216,7 +216,7 @@ function App() { export default App; ~~~ -Go to the ***Kanban.jsx*** file and apply the passed **props** to the Kanban configuration object: +Open *Kanban.jsx* and apply the props to the Kanban configuration object: ~~~jsx {5,11-13} title="Kanban.jsx" import { useEffect, useRef } from "react"; @@ -254,7 +254,7 @@ export default function KanbanComponent(props) { } ~~~ -You can also use the [`setConfig()`](/api/methods/js_kanban_setconfig_method/) or [`parse()`](/api/methods/js_kanban_parse_method/) method inside the `useEffect()` method of React to load data into Kanban. The `setConfig` or `parse()` method provides data reloading on each applied change. +As an alternative, load data after creating the instance with [`setConfig()`](/api/methods/js_kanban_setconfig_method/) or [`parse()`](/api/methods/js_kanban_parse_method/) inside `useEffect()`: ~~~jsx {9-11,27} title="Kanban.jsx" import { useEffect, useRef } from "react"; @@ -265,9 +265,9 @@ export default function KanbanComponent(props) { let kanban_container = useRef(); let toolbar_container = useRef(); - let columns = props.columns; // data for columns - let cards = props.cards; // data for cards - let rows = props.rows; // data for rows + let columns = props.columns; + let cards = props.cards; + let rows = props.rows; useEffect(() => { const kanban = new Kanban(kanban_container.current, { @@ -299,13 +299,13 @@ export default function KanbanComponent(props) { } ~~~ -Now the Kanban component is ready. When the element will be added to the page, it will initialize the Kanban with data. You can provide necessary configuration settings as well. Visit our [Kanban API docs](/api/overview/properties_overview/) to check the full list of available properties. +The Kanban component is now ready. When the element renders, Kanban initializes with data. For the full list of supported configuration properties, see the [Kanban API reference](/api/overview/properties_overview/). -#### Handling events +#### Handle events -When a user makes some action in the Kanban, it invokes an event. You can use these events to detect the action and run the desired code for it. See the [full list of events](/api/overview/events_overview/). +User actions in Kanban trigger events. Listen to events to react to specific actions. For the complete list, see the [Kanban events reference](/api/overview/events_overview/). -Open ***Kanban.jsx*** and complete the `useEffect()` method in the following way: +Open *Kanban.jsx* and extend the `useEffect()` call: ~~~jsx {5-7} title="Kanban.jsx" // ... @@ -323,7 +323,7 @@ useEffect(() => { // ... ~~~ -After that, you can start the app to see Kanban loaded with data on a page. +Run the app to view the populated Kanban board on the page. import trial from '@site/static/img/trial_kanban.png'; @@ -333,4 +333,4 @@ import trial from '@site/static/img/trial_kanban.png'; className="img_border" /> -Now you know how to integrate DHTMLX Kanban with React. You can customize the code according to your specific requirements. The final advanced example you can find on [**GitHub**](https://github.com/DHTMLX/react-kanban-demo). +See the complete project on [GitHub](https://github.com/DHTMLX/react-kanban-demo). diff --git a/docs/guides/integration_with_salesforce.md b/docs/guides/integration_with_salesforce.md index fdf0be0..a361576 100644 --- a/docs/guides/integration_with_salesforce.md +++ b/docs/guides/integration_with_salesforce.md @@ -1,5 +1,5 @@ --- -sidebar\_label: Integration with Salesforce +sidebar_label: Integration with Salesforce title: Integration with Salesforce description: Learn how to integrate DHTMLX Kanban into Salesforce. This guide explains the required HTML setup and environment configuration for smooth operation inside Salesforce Lightning components. --- @@ -7,57 +7,59 @@ description: Learn how to integrate DHTMLX Kanban into Salesforce. This guide ex # Integration with Salesforce :::tip -You should be familiar with the basic concepts and patterns of [**Salesforce**](https://www.salesforce.com/) before reading this documentation. To refresh your knowledge, please refer to the [**Salesforce documentation**](https://developer.salesforce.com/docs). +This guide assumes familiarity with [Salesforce](https://www.salesforce.com/) concepts and patterns. For background, see the [Salesforce documentation](https://developer.salesforce.com/docs). ::: -DHTMLX Kanban is compatible with [Salesforce](https://www.salesforce.com/) platform. We have prepared code examples on how to add DHTMLX Kanban into Salesforce environment. For more information, refer to the corresponding [Example on GitHub](https://github.com/DHTMLX/salesforce-lwc-demo). +DHTMLX Kanban is compatible with the [Salesforce](https://www.salesforce.com/) platform. The full code example is available on [GitHub](https://github.com/DHTMLX/salesforce-lwc-demo). :::note -The JavaScript Kanban widget automatically detects that it operates within a [**Salesforce**](https://www.salesforce.com/) environment and configures the integration logic internally. In most cases, you do not need to call any [**Salesforce-specific methods**](#salesforce-specific-methods) manually. +The Kanban widget detects the Salesforce environment and configures the integration logic internally. In most cases, you do not need to call any [Salesforce-specific methods](#salesforce-specific-methods) manually. ::: -## Preparing environment +## Prepare the environment -If you want to add Kanban into your Salesforce project, you need to mark the *root* container with the `data-wx-root="true"` HTML attribute. This attribute allows the library to locate the main node for mounting **Kanban** and **Toolbar** widgets. +To add Kanban to a Salesforce project, mark the *root* container with the `data-wx-root="true"` HTML attribute. The library uses this attribute to locate the main mount node for Kanban and the Toolbar: -```html title="kanban.html" +~~~html title="kanban.html" -``` +~~~ -Nested elements marked with the `data-wx-portal-root="1"` attribute serve as containers for DHTMLX components (for example, **Toolbar** and **Kanban**). +Nested elements marked with the `data-wx-portal-root="1"` attribute serve as containers for the DHTMLX components (Toolbar, Kanban). ## Salesforce environment API -The DHTMLX Kanban includes the `salesForceEnv` helper class that stores methods for manual control of the Salesforce environment. You can import the `salesForceEnv` helper class as follows: +DHTMLX Kanban exposes the `salesForceEnv` helper class with methods for manual control of the Salesforce environment. Import the helper as follows: -```jsx {4} +~~~jsx {4} import { Kanban, Toolbar, salesForceEnv } from "@dhx/trial-kanban"; -``` +~~~ :::note -Normally, salesforce-specific methods are not required, but they can be available only as a fallback in case automatic detection fails. +Salesforce-specific methods are typically not required. Use them as a fallback when automatic detection fails. ::: ### Salesforce-specific methods -You can use the following methods of the `salesForceEnv` helper class: +The `salesForceEnv` helper class exposes the following methods: | Method | Description | | :--------------------------------------------------------------- | :----------------------------------------------------------------------------- | -| `salesForceEnv.detect()` | Detects whether the Kanban is running inside Salesforce | +| `salesForceEnv.detect()` | Detects whether Kanban is running inside Salesforce | | `salesForceEnv.addGlobalEvent(eventName, handler, htmlElement)` | Attaches a global event to the first available HTML element | | `salesForceEnv.getTopNode()` | Returns the first available HTML element inside the Salesforce DOM hierarchy | -```jsx {4,7} +The following code snippet imports the helper and runs the detection check: + +~~~jsx {4,7} import { Kanban, Toolbar, @@ -65,7 +67,7 @@ import { } from "@dhx/trial-kanban"; salesForceEnv.detect(); -``` +~~~ ### Additional exported function @@ -73,7 +75,9 @@ salesForceEnv.detect(); | :------------------- | :-------------------------------------------------------------------------------- | | `enableSalesForce()` | Manually sets the Salesforce environment when automatic detection is unavailable | -```jsx {5,8} +The following code snippet imports `enableSalesForce()` and forces the Salesforce environment: + +~~~jsx {5,8} import { Kanban, Toolbar, @@ -82,18 +86,20 @@ import { } from "@dhx/trial-kanban"; enableSalesForce(); -``` +~~~ ## Workflow steps -1. Add the `data-wx-root="true"` attribute to your LWC container -2. Import and initialize DHTMLX Kanban and Toolbar (optionaly) -3. The JavaScript Kanban widget automatically detects the Salesforce context and applies internal configuration -4. You do not need to call the `enableSalesForce()` function or use `salesForceEnv` methods unless your app runs in a non-standard embedding scenario +1. Add the `data-wx-root="true"` attribute to your LWC container. +2. Import and initialize Kanban and the Toolbar (Toolbar is optional). +3. Kanban detects the Salesforce context and applies internal configuration automatically. +4. Skip the `enableSalesForce()` call and `salesForceEnv` methods unless the app runs in a non-standard embedding scenario. ### Example -```jsx title="kanban.js" +The following code snippet initializes Kanban and the Toolbar inside an LWC component: + +~~~jsx title="kanban.js" import { Kanban, Toolbar } from "@dhx/trial-kanban"; import "@dhx/trial-kanban/dist/kanban.css"; @@ -105,6 +111,6 @@ export default class KanbanLWC { const toolbar = new Toolbar(toolbar_container, { api: kanban.api }); } } -``` +~~~ -Now the DHTMLX Kanban component is fully integrated into your **Salesforce Lightning** environment. The widget automatically handles DOM hierarchy and event binding inside LWC. You can continue configuring Kanban through its standard API and customize Kanban appearance and logic according to your project needs. The final example you can find on [**GitHub**](https://github.com/DHTMLX/salesforce-lwc-demo). +DHTMLX Kanban is now integrated into the Salesforce Lightning environment. The widget handles the DOM hierarchy and event binding inside LWC. Continue configuring Kanban through its standard API to customize appearance and behavior. The full example is available on [GitHub](https://github.com/DHTMLX/salesforce-lwc-demo). diff --git a/docs/guides/integration_with_svelte.md b/docs/guides/integration_with_svelte.md index 1baa0fc..80630d0 100644 --- a/docs/guides/integration_with_svelte.md +++ b/docs/guides/integration_with_svelte.md @@ -7,74 +7,71 @@ description: You can learn about the integration with Svelte in the documentatio # Integration with Svelte :::tip -You should be familiar with the basic concepts and patterns of **Svelte** before reading this documentation. To refresh your knowledge, please refer to the [**Svelte documentation**](https://svelte.dev/docs/svelte/overview). +This guide assumes familiarity with Svelte concepts and patterns. For background, see the [Svelte documentation](https://svelte.dev/docs/svelte/overview). ::: -DHTMLX Kanban is compatible with **Svelte**. We have prepared code examples on how to use DHTMLX Kanban with **Svelte**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/svelte-kanban-demo). +DHTMLX Kanban is compatible with Svelte. The full code example is available on [GitHub](https://github.com/DHTMLX/svelte-kanban-demo). -## Creating a project +## Create a project :::info -Before you start to create a new project, install [**Vite**](https://vite.dev/) (optional) and [**Node.js**](https://nodejs.org/en/). +Install [Vite](https://vite.dev/) (optional) and [Node.js](https://nodejs.org/en/) before creating the project. ::: -There are several ways of creating a **Svelte** project: +Set up a Svelte project in one of two ways: -- you can use the [**SvelteKit**](https://kit.svelte.dev/) - -or - -- you can also use **Svelte with Vite** (but without SvelteKit): +- with [SvelteKit](https://kit.svelte.dev/) — recommended +- with Svelte and Vite (without SvelteKit) — run: ~~~json npm create vite@latest ~~~ -Check the details in the [related article](https://svelte.dev/docs/svelte/overview). +For details, see the [Svelte documentation](https://svelte.dev/docs/svelte/overview). -### Installation of dependencies +### Install dependencies -Let's name the project as **my-svelte-kanban-app** and go to the app directory: +Name the project *my-svelte-kanban-app*. Move into the app directory: ~~~json cd my-svelte-kanban-app ~~~ -Install dependencies and start the dev server. For this, use a package manager: +Install dependencies and start the dev server with one of the package managers: -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: +- For [yarn](https://yarnpkg.com/): ~~~json yarn yarn start ~~~ -- if you use [**npm**](https://www.npmjs.com/), run the following commands: +- For [npm](https://www.npmjs.com/): ~~~json npm install npm run dev ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app runs on a localhost address (for example, `http://localhost:3000`). -## Creating Kanban +## Create Kanban -Now you should get the DHTMLX Kanban source code. First of all, stop the app and proceed with installing the Kanban package. +Stop the dev server and install the Kanban package. -### Step 1. Package installation +### Step 1. Install the package -Download the [**trial Kanban package**](/how_to_start/#installing-kanban-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial Kanban is available 30 days only. +Download the [trial Kanban package](/how_to_start/#installing-kanban-via-npm-or-yarn) and follow the steps in the README file. The trial version is available for 30 days. -### Step 2. Component creation +### Step 2. Create the component -Now you need to create a Svelte component, to add a Kanban with Toolbar into the application. Let's create a new file in the ***src/*** directory and name it ***Kanban.svelte***. +Create a Svelte component that mounts Kanban and the Toolbar. Add a new *Kanban.svelte* file to the *src/* directory. -#### Importing source files +#### Import source files -Open the ***Kanban.svelte*** file and import Kanban source files. Note that: +Open *Kanban.svelte* and import the Kanban source files. The import paths depend on the package version: -- if you use PRO version and install the Kanban package from a local folder, the import paths look like this: +- For the PRO version installed from a local folder: ~~~html title="Kanban.svelte" ~~~ -Note that depending on the used package, the source files can be minified. In this case make sure that you are importing the CSS file as **kanban.min.css**. +If the package ships minified source files, import the CSS file as *kanban.min.css*. -- if you use the trial version of Kanban, specify the following paths: +- For the trial version: ~~~html title="Kanban.svelte" ~~~ -In this tutorial you can see how to configure the **trial** version of Kanban. +This tutorial uses the trial version of Kanban. -#### Setting containers and adding Kanban with Toolbar +#### Set up containers and initialize Kanban -To display Kanban with Toolbar on the page, you need to create containers for Kanban and Toolbar, and initialize these components using the corresponding constructors: +To display Kanban with the Toolbar, create two containers and call the constructors. The following code snippet binds the containers and instantiates the components inside `onMount()`: ~~~html {3,6,10-11,13-17,27-28} title="Kanban.svelte" @@ -132,9 +129,9 @@ onDestroy(() => {
~~~ -#### Loading data +#### Load data -To add data into the Kanban, we need to provide a data set. You can create the ***data.js*** file in the ***src/*** directory and add some data into it: +To populate Kanban, provide a data set. Create the *data.js* file in the *src/* directory: ~~~jsx {2,14,37,48} title="data.js" export function getData() { @@ -162,7 +159,7 @@ export function getData() { type: "feature", }, { - label: "Archive the cards/kanbans ", + label: "Archive the cards/boards", priority: 3, color: "#58C3FE", users: [4], @@ -188,7 +185,7 @@ export function getData() { } ~~~ -Then open the ***App.svelte*** file, import data, and pass it into the new created `` components as **props**: +Open *App.svelte*, import the dataset, and pass the values to the new `` component as props: ~~~html {3,5,8} title="App.svelte" ~~~ -After that, you can start the app to see Kanban loaded with data on a page. +Run the app to view the populated Kanban board on the page. import trial from '@site/static/img/trial_kanban.png'; @@ -342,4 +339,4 @@ import trial from '@site/static/img/trial_kanban.png'; className="img_border" /> -Now you know how to integrate DHTMLX Kanban with Svelte. You can customize the code according to your specific requirements. The final advanced example you can find on [**GitHub**](https://github.com/DHTMLX/svelte-kanban-demo). +See the complete project on [GitHub](https://github.com/DHTMLX/svelte-kanban-demo). diff --git a/docs/guides/integration_with_vue.md b/docs/guides/integration_with_vue.md index 6690b8b..69720f3 100644 --- a/docs/guides/integration_with_vue.md +++ b/docs/guides/integration_with_vue.md @@ -7,70 +7,70 @@ description: You can learn about the integration with Vue in the documentation o # Integration with Vue :::tip -You should be familiar with the basic concepts and patterns of [**Vue**](https://vuejs.org/) before reading this documentation. To refresh your knowledge, please refer to the [**Vue 3 documentation**](https://vuejs.org/guide/introduction.html#getting-started). +This guide assumes familiarity with [Vue](https://vuejs.org/) concepts and patterns. For background, see the [Vue 3 documentation](https://vuejs.org/guide/introduction.html#getting-started). ::: -DHTMLX Kanban is compatible with **Vue**. We have prepared code examples on how to use DHTMLX Kanban with **Vue 3**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/vue-kanban-demo). +DHTMLX Kanban is compatible with Vue. The full code example for Vue 3 is available on [GitHub](https://github.com/DHTMLX/vue-kanban-demo). -## Creating a project +## Create a project :::info -Before you start to create a new project, install [**Node.js**](https://nodejs.org/en/). +Install [Node.js](https://nodejs.org/en/) before creating the project. ::: -To create a **Vue** project, run the following command: +The following command creates a new Vue project: ~~~json npm create vue@latest ~~~ -This command installs and executes `create-vue`, the official **Vue** project scaffolding tool. Check the details in the [Vue.js Quick Start](https://vuejs.org/guide/quick-start.html#creating-a-vue-application). +The command runs `create-vue`, the official Vue project scaffolding tool. For details, see the [Vue.js Quick Start](https://vuejs.org/guide/quick-start.html#creating-a-vue-application). -Let's name the project as **my-vue-kanban-app**. +Name the project *my-vue-kanban-app*. -### Installation of dependencies +### Install dependencies -Go to the app directory: +Move into the app directory: ~~~json cd my-vue-kanban-app ~~~ -Install dependencies and start the dev server. For this, use a package manager: +Install dependencies and start the dev server with one of the package managers: -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: +- For [yarn](https://yarnpkg.com/): ~~~jsx yarn yarn start // or yarn dev ~~~ -- if you use [**npm**](https://www.npmjs.com/), run the following commands: +- For [npm](https://www.npmjs.com/): ~~~json npm install npm run dev ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app runs on a localhost address (for example, `http://localhost:3000`). -## Creating Kanban +## Create Kanban -Now you should get the DHTMLX Kanban source code. First of all, stop the app and proceed with installing the Kanban package. +Stop the dev server and install the Kanban package. -### Step 1. Package installation +### Step 1. Install the package -Download the [**trial Kanban package**](/how_to_start/#installing-kanban-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial Kanban is available 30 days only. +Download the [trial Kanban package](/how_to_start/#installing-kanban-via-npm-or-yarn) and follow the steps in the README file. The trial version is available for 30 days. -### Step 2. Component creation +### Step 2. Create the component -Now you need to create a Vue component, to add Kanban with Toolbar into the application. Create a new file in the ***src/components/*** directory and name it ***Kanban.vue***. +Create a Vue component that mounts Kanban and the Toolbar. Add a new *Kanban.vue* file to the *src/components/* directory. #### Import source files -Open the ***Kanban.vue*** file and import Kanban source files. Note that: +Open *Kanban.vue* and import the Kanban source files. The import paths depend on the package version: -- if you use PRO version and install the Kanban package from a local folder, the import paths look like this: +- For the PRO version installed from a local folder: ~~~html title="Kanban.vue" ~~~ -Note that depending on the used package, the source files can be minified. In this case make sure that you are importing the CSS file as **kanban.min.css**. +If the package ships minified source files, import the CSS file as *kanban.min.css*. -- if you use the trial version of Kanban, specify the following paths: +- For the trial version: ~~~html title="Kanban.vue" ~~~ -In this tutorial you can see how to configure the **trial** version of Kanban. +This tutorial uses the trial version of Kanban. -#### Setting containers and adding Kanban with Toolbar +#### Set up containers and initialize Kanban -To display Kanban with Toolbar on the page, you need to create containers for Kanban and Toolbar, and initialize these components using the corresponding constructors: +To display Kanban with the Toolbar, create two containers and call the constructors. The following code snippet wires up refs and instantiates the components inside `mounted()`: ~~~html {2,7-8,10-14} title="Kanban.vue" @@ -128,9 +128,9 @@ export default { ~~~ -#### Adding styles +#### Add styles -To display Kanban correctly, you need to specify important styles for Kanban and its container in the main css file of the project: +Add styles for Kanban and the container in the main CSS file: ~~~css title="main.css" /* specify styles for initial page */ @@ -154,9 +154,9 @@ body, } ~~~ -#### Loading data +#### Load data -To add data into the Kanban, you need to provide a data set. You can create the ***data.js*** file in the ***src/*** directory and add some data into it: +To populate Kanban, provide a data set. Create the *data.js* file in the *src/* directory: ~~~jsx {2,14,37,48} title="data.js" export function getData() { @@ -184,7 +184,7 @@ export function getData() { type: "feature", }, { - label: "Archive the cards/kanbans ", + label: "Archive the cards/boards", priority: 3, color: "#58C3FE", users: [4], @@ -210,7 +210,7 @@ export function getData() { } ~~~ -Then open the ***App.vue*** file, import data, and initialize it via the inner `data()` method. After this you can pass data into the new created `` component as **props**: +Open *App.vue* and import the dataset. Initialize the values through the inner `data()` method, then pass the values to the new `` component as props: ~~~html {3,8,10-12,19} title="App.vue"