diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md index d4be765..e81fc02 100644 --- a/docs/guides/configuration.md +++ b/docs/guides/configuration.md @@ -6,27 +6,31 @@ description: You can learn about the To Do List Configuration in the documentati # Configuration -You can adjust the settings of DHTMLX To Do List according to your needs. The available configuration options allow you: -- [to configure the appearance of the badge displaying the progress of task completion](#counter-of-completed-subtasks) -- [to configure the format of dates](#date-format) -- [to configure or disable drag-n-drop of tasks](#drag-n-drop) -- [to disable validation for due dates of tasks](#due-date-validation) -- [to change the mode used for marking tasks done](#mode-of-marking-tasks-complete) -- [to configure the appearance of the toolbar](#toolbar) - -You can also configure the mode of [hiding completed tasks](#mode-of-hiding-completed-tasks) as well as initialize To Do List in the [readonly](#read-only-mode) mode. +DHTMLX To Do List provides the following configuration options: + +- [Configure the subtask counter](#configure-the-subtask-counter) — set the progress display type for child tasks +- [Set the date format](#set-the-date-format) — define how dates appear in the list +- [Configure drag-n-drop](#configure-drag-n-drop) — control drag behavior or disable it +- [Configure due date validation](#configure-due-date-validation) — track task completion against due dates +- [Set the task completion mode](#set-the-task-completion-mode) — switch between auto and manual completion +- [Configure priority appearance](#configure-priority-appearance) — control priority cover and label visibility +- [Configure the toolbar](#toolbar) — customize toolbar controls and order +- [Hide completed tasks](#hide-completed-tasks) — remove completed tasks from view +- [Enable read-only mode](#enable-read-only-mode) — prevent task editing ## Tasks -### Counter of completed subtasks +Use the [`taskShape`](/api/configs/taskshape_config/) property to adjust task appearance and behavior. + +### Configure the subtask counter -You can change the type of the counter which renders the progress of completion of the child tasks. +Use the `counter` parameter of `taskShape` to configure the progress counter for child tasks. ![counter](/assets/counter.png) -By default, each parent task is equipped with the counter whose value is shown as a ratio of completed child tasks and the total number of the child tasks. +By default, the counter shows completed vs. total child tasks as a ratio. -If you want the value of the counter to be displayed as a percentage, specify the *type: "percentage"* attribute inside the **counter** parameter of the [`taskShape`](/api/configs/taskshape_config/) property: +To display progress as a percentage, set `type` to `"percentage"` in the `counter` parameter of [`taskShape`](/api/configs/taskshape_config/): ~~~js {5-9} const list = new ToDo("#root", { @@ -43,9 +47,9 @@ const list = new ToDo("#root", { **Related sample:** [To do list. Subtask counter and date format](https://snippet.dhtmlx.com/magidhw8) -### Date format +### Set the date format -By default, the To Do List displays dates in the "%d %M %Y" format (it looks like 09 Mar 2033). If you want to specify another format for dates, use the **date** parameter of the [`taskShape`](/api/configs/taskshape_config/) property: +By default, To Do List displays dates in the `"%d %M %Y"` format (for example, 09 Mar 2033). To specify another format, use the `date` parameter of [`taskShape`](/api/configs/taskshape_config/): ~~~js {5-10} const list = new ToDo("#root", { @@ -65,13 +69,15 @@ const list = new ToDo("#root", { Check [the list of available characters](/api/configs/taskshape_config/#list-of-characters). -### Drag-n-drop +### Configure drag-n-drop + +To Do List includes drag-n-drop by default. [Select one or several tasks](../../#selecting-tasks) and drag the tasks vertically. To copy the selected tasks, hold *Alt* during drag-n-drop. -The default configuration of To Do List includes the drag-n-drop functionality. You can [select one or several tasks](../../#selecting-tasks) and drag the selected tasks vertically at once. If you need to create a copy of the selected tasks, hold the *Alt* key during drag-n-drop. +Use the [`drag`](/api/configs/drag_config/) property to configure drag-n-drop behavior. -There is the [`drag`](/api/configs/drag_config/) property which allows you: +#### Prevent collapsed task expansion -- to configure the behavior of the collapsed tasks so that they don't expand when you hover them over during drag-n-drop: +To prevent collapsed tasks from expanding when hovered during drag-n-drop, set `expand` to `false`: ~~~js {7} const list = new ToDo("#root", { @@ -85,7 +91,9 @@ const list = new ToDo("#root", { }); ~~~ -- to disable drag-n-drop: +#### Disable drag-n-drop + +To disable drag-n-drop entirely, set `drag` to `false`: ~~~js {6} const list = new ToDo("#root", { @@ -97,19 +105,17 @@ const list = new ToDo("#root", { }); ~~~ -### Due date validation +### Configure due date validation -If you specify a [due date](/api/configs/tasks_config/) for a task, the due date validation will track the completion of the task. The due date of the task has green color until the task becomes Overdue. +If you specify a [due date](/api/configs/tasks_config/) for a task, due date validation tracks whether the task is completed on time. The due date appears green until the task becomes overdue. ![due_date](/assets/due_date.png) -The dates of the tasks which have not been completed on the due date are highlighted in red. +The widget highlights overdue task dates in red. ![due_date](/assets/overdue_task.png) -This validation works by default. - -In case you want to disable this functionality, specify the **validate** setting inside the *date* parameter of the [`taskShape`](/api/configs/taskshape_config/) property to *false*: +Validation is active by default. To disable it, set `validate` to `false` in the `date` parameter of [`taskShape`](/api/configs/taskshape_config/): ~~~js {5-10} const list = new ToDo("#root", { @@ -125,18 +131,24 @@ const list = new ToDo("#root", { }); ~~~ -In this configuration, the due dates will be colored grey. +In this configuration, due dates appear grey. -### Mode of marking tasks complete +### Set the task completion mode -By default, the process of checking/unchecking tasks is implemented in the "auto" mode, namely: +Use the `completed` parameter of [`taskShape`](/api/configs/taskshape_config/) to control how marking tasks done affects parent and child tasks. -- If you mark all children of a task as completed, the parent task automatically becomes marked as completed -- If you mark the parent task as completed, all its child automatically become marked as completed -- If you mark at least one child of a completed task as uncompleted, the task automatically becomes marked as uncompleted -- If you mark the parent task as uncompleted, all its child automatically become uncompleted +#### Auto mode -You can disable this behavior and activate the "manual" mode. For that, apply the **behavior: "manual"** setting of the **completed** parameter of the [`taskShape`](/api/configs/taskshape_config/) property: +By default, task completion uses the `"auto"` mode: + +- If you mark all child tasks as completed, the parent task becomes completed. +- If you mark the parent task as completed, all its children become completed. +- If you mark at least one child as uncompleted, the parent task becomes uncompleted. +- If you mark the parent task as uncompleted, all its children become uncompleted. + +#### Manual mode + +To activate the `"manual"` mode, set `behavior` to `"manual"` in the `completed` parameter of [`taskShape`](/api/configs/taskshape_config/): ~~~js {5-9} const list = new ToDo("#root", { @@ -153,11 +165,31 @@ const list = new ToDo("#root", { **Related sample:** [To do list. Two variants of marking a parent task done](https://snippet.dhtmlx.com/5892fcr2) +### Configure priority appearance + +Use the `priority` parameter of the [`taskShape`](/api/configs/taskshape_config/) property to control how task priorities appear in the list. + +~~~js {5-10} +const list = new ToDo("#root", { + tasks, + users, + projects, + taskShape: { + priority: { + cover: true, // show priority color cover + label: true // show priority label + } + } +}); +~~~ + ## Toolbar -The toolbar is a top part of To Do List which is [initialized](/guides/initialization/#initialize-toolbar) and [configured](/category/toolbar-properties.md) separately from To Do List. +The Toolbar is the top part of To Do List. Initialize and configure it [separately](/guides/initialization/#initialize-toolbar) from the main component. -To change the default structure of the toolbar, use the [`items`](/api/toolbar_api/configs/items_config/) configuration property of the Toolbar component. +The `items` property accepts the following built-in controls: `"combo"`, `"search"`, `"menu"`, `"undo"`, and `"redo"`. You can also pass a custom string or function to add a custom control. + +To change the toolbar structure, use the [`items`](/api/toolbar_api/configs/items_config/) property of the Toolbar component: ~~~js const toolbar = new Toolbar("#toolbar", { @@ -166,12 +198,27 @@ const toolbar = new Toolbar("#toolbar", { }); ~~~ -The property allows you to define which controls should be shown or hidden. Besides, you can enumerate the controls in the **items** array in the order you want to show them in the toolbar. +Use `items` to define which controls appear and in what order. + +## Hide completed tasks -## Mode of hiding completed tasks +To hide completed tasks by default on initialization, set `taskHide` to `true` in the `completed` parameter of [`taskShape`](/api/configs/taskshape_config/): + +~~~js {5-9} +const list = new ToDo("#root", { + tasks, + users, + projects, + taskShape: { + completed: { + taskHide: true // false by default + } + } +}); +~~~ -Read the details on how to hide completed tasks from To Do List in the [related section](/guides/hide_completed_tasks/). +Read the details on advanced options for hiding completed tasks in the [related section](/guides/hide_completed_tasks/). -## Read-only mode +## Enable read-only mode Read the details on how to make the To Do List read-only in the [related section](/guides/readonly_mode/). diff --git a/docs/guides/customization.md b/docs/guides/customization.md index 4679cfb..55f9be0 100644 --- a/docs/guides/customization.md +++ b/docs/guides/customization.md @@ -6,19 +6,18 @@ description: You can learn about the To Do List Customization in the documentati # Customization -## Toolbar +## Customize the toolbar -It is possible to customize the appearance of the toolbar. You can hide some default controls, add custom ones, and place them in the necessary order. To do that, use the [`items`](/api/toolbar_api/configs/items_config/) property of the Toolbar component. +Use the [`items`](/api/toolbar_api/configs/items_config/) property of the Toolbar component to hide default controls, add custom ones, and reorder them. -You can customize your toolbar as in: +The following example shows a customized toolbar with hidden and reordered controls: -## Styling To Do List +## Style To Do List -You can change the look and feel of To Do List by changing values of the [**CSS variables provided by the library**](/guides/stylization/). +Change the look and feel of To Do List with the [CSS variables provided by the library](/guides/stylization/). -Check the example: +The following example shows To Do List with custom CSS variable values: - diff --git a/docs/guides/hide_completed_tasks.md b/docs/guides/hide_completed_tasks.md index a975b8e..73c983f 100644 --- a/docs/guides/hide_completed_tasks.md +++ b/docs/guides/hide_completed_tasks.md @@ -1,19 +1,19 @@ --- -sidebar_label: Hiding completed tasks +sidebar_label: Hide completed tasks title: Show/hide completed tasks description: You can learn about how to hide or show completed tasks in the documentation of the DHTMLX JavaScript To Do List library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX To Do List. --- # Show/hide completed tasks -## Initial mode +## Set the initial mode -There are two modes of displaying tasks in To Do List: +To Do List supports two display modes: -- when all tasks are shown on the page (*default*) -- when completed tasks are hidden from the page +- all tasks are visible (default) +- completed tasks are hidden -You may initialize To Do List in the mode when all completed tasks will be hidden from the page. It will let you focus only on those tasks which yet need to be done. For that, you need to enable the **taskHide** setting of the **completed** parameter of the [`taskShape`](/api/configs/taskshape_config/) property, as in: +To initialize To Do List with completed tasks hidden, set `taskHide` to `true` in the `completed` parameter of [`taskShape`](/api/configs/taskshape_config/): ~~~js {6} const list = new ToDo("#root", { @@ -27,16 +27,31 @@ const list = new ToDo("#root", { }); ~~~ -## Switching between modes +## Switch between modes -You may easily switch between these two modes after initialization of To Do List in two ways: +Switch between modes after initialization in two ways: -- via the **Completed tasks -> Show/Hide** option of the [Toolbar menu](../../#toolbar) +- Select **Completed tasks → Show/Hide** in the [Toolbar menu](../../#toolbar). +- Use the [`hideCompletedTasks()`](/api/methods/hidecompletedtasks_method/) and [`showCompletedTasks()`](/api/methods/showcompletedtasks_method/) methods to switch programmatically. -- via the related [`hideCompletedTasks()`](/api/methods/hidecompletedtasks_method/) and [`showCompletedTasks()`](/api/methods/showcompletedtasks_method/) methods: +The following code snippet demonstrates switching modes programmatically: ~~~js -list.hideCompletedTasks(); +list.hideCompletedTasks(); // or -list.showCompletedTasks(); -~~~ \ No newline at end of file +list.showCompletedTasks(); +~~~ + +## React to mode changes + +Use the `hide-completed-tasks` and `show-completed-tasks` events to track when the display mode changes: + +~~~js +list.api.on("hide-completed-tasks", () => { + console.log("Completed tasks are now hidden"); +}); + +list.api.on("show-completed-tasks", () => { + console.log("Completed tasks are now visible"); +}); +~~~ diff --git a/docs/guides/initialization.md b/docs/guides/initialization.md index c002697..06c5b3c 100644 --- a/docs/guides/initialization.md +++ b/docs/guides/initialization.md @@ -6,8 +6,7 @@ description: You can learn about initialization of the DHTMLX JavaScript To Do L # Initialization - -To create or, in other words, to display To Do List on the page, you need to take the following steps: +To display To Do List on the page, follow these steps: 1\. [Include the To Do List source files on a page](#include-source-files) @@ -17,14 +16,14 @@ To create or, in other words, to display To Do List on the page, you need to tak ## Include source files -[Download the To Do List package](https://dhtmlx.com/docs/products/dhtmlxTodo/download.shtml) and unpack it into a folder of your project. +[Download the To Do List package](https://dhtmlx.com/docs/products/dhtmlxTodo/download.shtml) and unpack it into your project folder. -To create To Do List, you need to include 2 source files on your page: +Add the following two source files to your page: - *todo.js* - *todo.css* -Make sure that you set correct relative paths to the source files: +The following snippet includes the source files using relative paths to the *dist* folder: ~~~html title="index.html" @@ -33,27 +32,30 @@ Make sure that you set correct relative paths to the source files: ## Create containers -The To Do List widget consists of two separate components: a List and a Toolbar. - -Thus, create **two containers** to place a List and Toolbar into and give them IDs, for instance, **"root"** and **"toolbar"**: +To Do List consists of two components: a List and a Toolbar. +Create two containers with IDs, for example `"root"` and `"toolbar"`: ~~~html title="index.html" -
// the container for Toolbar (if you need to create To Do List with its Toolbar) -
// the container for List +
// Toolbar container (optional) +
// List container ~~~ ## Initialize To Do List +Initialize the List and Toolbar using their respective constructors. + ### Initialize List -After that, initialize List with the **new ToDo()** constructor. It takes two parameters: +Initialize the List with the `ToDo()` constructor. The constructor takes two parameters: + +- a container for the List (created in the previous step) +- an object with [configuration properties](/api/overview/configs_overview/) -- a container to place a List into. The one we have created at the previous step -- an object with configuration properties. [See the full list here](/api/overview/configs_overview/) +The following code snippet initializes the List: ~~~js title="index.js" -const { ToDo, Toolbar } = todo; // apply the object destructuring +const { ToDo, Toolbar } = todo; // unpack the todo global object // create List const list = new ToDo("#root", { @@ -63,17 +65,19 @@ const list = new ToDo("#root", { ### Initialize Toolbar -Next, initialize Toolbar with the **new Toolbar()** constructor. The constructor also takes two parameters: +Initialize the Toolbar with the `Toolbar()` constructor, passing `list.api` as the required `api` property. The constructor takes two parameters: -- a container to place a Toolbar into. The one we have created at the previous step -- an object with configuration properties. [See the full list here](/category/toolbar-properties/) +- a container for the Toolbar (created in the previous step) +- an object with [configuration properties](/category/toolbar-properties/) :::info -Initialization of the Toolbar is optional. You can skip this step if you don't need the Toolbar in your application +Toolbar initialization is optional. Skip this step if you do not need the Toolbar. ::: +The following code snippet initializes List and Toolbar: + ~~~js {9-11} title="index.js" -const { ToDo, Toolbar } = todo; // apply the object destructuring +const { ToDo, Toolbar } = todo; // unpack the todo global object // create List const list = new ToDo("#root", { @@ -87,16 +91,17 @@ const toolbar = new Toolbar("#toolbar", { ~~~ :::note -You should apply the object destructuring to "unpack" the **todo** global object into two variables: ToDo and Toolbar. +Apply object destructuring to unpack the `todo` global object into `ToDo` and `Toolbar` variables. -You don't need this step if you will use the **new todo.ToDo()** and **new todo.Toolbar()** constructors. +Skip this step if you use the `todo.ToDo()` and `todo.Toolbar()` constructors directly. ::: -## Loading data into To Do List +## Load data -Detailed information on loading data into DHTMLX To Do is given in the [Data loading](/guides/loading_data/) article. +See the [Data loading](/guides/loading_data/) guide for details. ## Example - +The example below demonstrates a basic To Do List initialization with List and Toolbar. + diff --git a/docs/guides/inline_editing.md b/docs/guides/inline_editing.md index a2e4d5f..fe3dfa8 100644 --- a/docs/guides/inline_editing.md +++ b/docs/guides/inline_editing.md @@ -6,54 +6,56 @@ description: You can learn about inline editing in the documentation of the DHTM # Inline editing -Inline editing lets you edit the content of a task/project directly by double-clicking on it. The functionality is enabled by default. +Inline editing lets you edit task and project content directly by double-clicking. The feature is enabled by default. :::tip -When you enable the [**readonly**](/api/configs/readonly_config/) mode of To Do List, inline editing becomes unavailable. +If you enable [`readonly`](/api/configs/readonly_config/) mode, inline editing becomes unavailable. ::: -## Supported formats of data +## Supported data formats -It is possible to type and edit the following data via the inline editor: +Edit the following types of data in the inline editor: -1\. **Text, numbers** +### Text and numbers -2\. **Hashtags** +Type plain text or numeric values directly into the editor. -Use hashtags to categorize tasks and make them more searchable. Here are some simple rules to know: +### Hashtags -- Hashtag is a combination of the `#` symbol and any letters, numbers (for instance, **#sport**) -- To create a hashtag, enter `#` and at least one symbol after it (for instance, **#t**), and press Enter -- You can use unlimited number of hashtags in To Do List. Separate the tags by spaces (for instance, **#tag #tag1**) -- All created hashtags are accessible in all projects -- To view the list of all hashtags you've already created, enter the `#` symbol. Click the necessary hashtag to add it to the task -- To activate strict filtering, click a hashtag or enter it in the search bar in the toolbar +Use hashtags to categorize tasks and make them searchable: + +- A hashtag combines the `#` symbol with letters and numbers (for example, `#sport`). +- To create a hashtag, type `#` followed by at least one character (for example, `#t`) and press Enter. +- Use any number of hashtags, separated by spaces (for example, `#tag #tag1`). +- Hashtags are available across all projects. +- To view all existing hashtags, type `#`. Click a hashtag to add it to the task. +- To filter tasks by a hashtag, click it or enter it in the toolbar search bar. :::info -You can create a default list of tags via the [`tags`](/api/configs/tags_config/) property +Use the [`tags`](/api/configs/tags_config/) property to set a default list of tags. ::: -3\. **Dates** +### Dates + +To enter a date, type `!` in the inline editor. The built-in date picker appears. -To enter a date via the inline editor, type the `!` symbol and the built-in date picker will appear on the page. - -You can also wrap some text in the special symbols - `!()` - for instance, **!(Enter Booking date)**, and press Enter to close the editor. In the future, clicking on this text will open the date picker. +Wrap text in `!()` — for example, `!(Enter Booking date)` — and press Enter to close the editor. Clicking the text later opens the date picker. :::info -The appearance of the added dates depends on the specified [**locale**](/api/configs/locale_config/) and [**date format**](/api/configs/taskshape_config/) +Date appearance depends on the configured [`locale`](/api/configs/locale_config/) and [`date format`](/api/configs/taskshape_config/). ::: -## Working with editor +## Work with the editor -You can manage the editor by using the API: +Use the following methods to open and close the inline editor programmatically. -To open the editor for a particular task/project, use the [`openInlineEditor()`](/api/methods/openinlineeditor_method/) method: +To open the editor for a task, pass the task ID to [`openInlineEditor()`](/api/methods/openinlineeditor_method/). Pass `"project"` as the optional `type` parameter to open the editor for a project instead of a task: ~~~js list.openInlineEditor({ id: "1.1.1" }); ~~~ -To close the editor after finishing the editing of the item and save the changes made, pass the ID of the item to the [`closeInlineEditor()`](/api/methods/closeinlineeditor_method/) method: +To close the editor and save changes, pass the item ID to [`closeInlineEditor()`](/api/methods/closeinlineeditor_method/): ~~~js list.closeInlineEditor({ @@ -61,12 +63,25 @@ list.closeInlineEditor({ }); ~~~ -If you don't need to save the changes after closing the editor, set the second **save** parameter of the method to *false*: +To discard changes on close, set `save` to `false`: ~~~js list.closeInlineEditor({ id: "1.1.1", save: false }); -~~~~ +~~~ + +## Track editor state + +Use the `open-inline-editor` and `close-inline-editor` events to react when the inline editor opens or closes: + +~~~js +list.api.on("open-inline-editor", ({id, type}) => { + console.log("Editor opened for", type, "with ID:", id); +}); +list.api.on("close-inline-editor", ({id, save}) => { + console.log("Editor closed for item", id, "saved:", save); +}); +~~~ diff --git a/docs/guides/integration.md b/docs/guides/integration.md index 191eee9..bd5d84d 100644 --- a/docs/guides/integration.md +++ b/docs/guides/integration.md @@ -6,26 +6,38 @@ description: You can learn about integration with other widgets in the documenta # Integration with DHTMLX widgets -You can integrate DHTMLX To Do List with other DHTMLX widgets (for instance, [Gantt](https://docs.dhtmlx.com/gantt/), [Scheduler](https://docs.dhtmlx.com/scheduler/), [Kanban](https://docs.dhtmlx.com/kanban/), [Grid](https://docs.dhtmlx.com/suite/grid/)). Check the examples below. +Integrate DHTMLX To Do List with other DHTMLX widgets such as [Gantt](https://docs.dhtmlx.com/gantt/), [Scheduler](https://docs.dhtmlx.com/scheduler/), [Kanban](https://docs.dhtmlx.com/kanban/), and [Grid](https://docs.dhtmlx.com/suite/grid/). The following examples demonstrate these integrations. ## Integration with DHTMLX Gantt - + +The following example shows To Do List integrated with DHTMLX Gantt: + ## Integration with DHTMLX Kanban +The following example shows To Do List integrated with DHTMLX Kanban: + ## Integration with DHTMLX Scheduler +To Do List can be integrated with DHTMLX Scheduler with or without the projects feature. + ### Example without projects +The following example shows To Do List integrated with DHTMLX Scheduler without projects: + ### Example with projects +The following example shows To Do List integrated with DHTMLX Scheduler with projects enabled: + ## Integration with DHTMLX DataGrid - \ No newline at end of file +The following example shows To Do List integrated with DHTMLX DataGrid: + + diff --git a/docs/guides/integration_with_angular.md b/docs/guides/integration_with_angular.md index 5aea5f3..2bdfceb 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). +Familiarize yourself with basic Angular concepts and patterns before reading this guide. Refer to the [Angular documentation](https://v17.angular.io/docs) to refresh your knowledge. ::: -DHTMLX To Do List is compatible with **Angular**. We prepared code examples on how to use DHTMLX To Do List with **Angular**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/angular-todolist-demo). +DHTMLX To Do List is compatible with Angular. For a complete example, see the [demo on GitHub](https://github.com/DHTMLX/angular-todolist-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/). +Before creating a new project, install [Angular CLI](https://v17.angular.io/cli) and [Node.js](https://nodejs.org/en/). ::: -Create a new **my-angular-todo-app** project using Angular CLI. For this purpose, run the following command: +Create a new `my-angular-todo-app` project using Angular CLI: ~~~json ng new my-angular-todo-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! +To follow this guide, disable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering) when creating the Angular app. ::: -The command above installs all the necessary tools, so you don't need to run any additional commands. +The command installs all necessary tools. -### Installation of dependencies +### Install dependencies -Go to the new created app directory: +Navigate to the new app directory: ~~~json cd my-angular-todo-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 using [yarn](https://yarnpkg.com/): ~~~json yarn yarn start ~~~ -The app should run on a localhost (for instance `http://localhost:3000`). +The app runs on a local server (for example, `http://localhost:3000`). -## Creating To Do List +## Create To Do List -Now you should get the DHTMLX To Do List source code. First of all, stop the app and proceed with installing the To Do List package. +Stop the app and install the To Do List package. -### Step 1. Package installation +### Step 1. Install the package -Download the [**trial To Do List package**](/how_to_start/#installing-to-do-list-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial To Do List is available 30 days only. - -### Step 2. Component creation +Download the [trial To Do List package](/how_to_start/#installing-to-do-list-via-npm-or-yarn) and follow the README instructions. The trial is available for 30 days. -Now you need to create an Angular component, to add To Do List with Toolbar into the application. Create the **todo** folder in the **src/app/** directory, add a new file into it and name it **todo.component.ts**. +### Step 2. Create the component + +Create the *todo* folder in *src/app/*, then add a new file named *todo.component.ts*. #### Import source files -Open the **todo.component.ts** file and import To Do List source files. Note that: +Open *todo.component.ts* and import To Do List source files. The import path depends on the version you use: -- if you use PRO version and install the To Do List package from a local folder, the imported path looks like this: +- For the PRO version installed from a local folder, use this import path: ~~~jsx title="todo.components.ts" import { ToDo, Toolbar } from 'dhx-todolist-package'; ~~~ -- if you use the trial version of To Do List, specify the following path: +- For the trial version, use this import path: ~~~jsx title="todo.components.ts" import { ToDo, Toolbar } from '@dhx/trial-todolist'; ~~~ -In this tutorial you can see how to configure the **trial** version of To Do List. +This guide uses the trial version. -#### Set containers and initialize the To Do List with Toolbar +#### Set containers and initialize To Do List -To display To Do List with Toolbar on the page, you need to set containers for To Do List and Toolbar, and initialize these components using the corresponding constructors: +The following code snippet sets up the component template and initializes To Do List and Toolbar in `ngOnInit()`: ~~~jsx {1,8-11,15-18,24-31} title="todo.component.ts" import { ToDo, Toolbar } from '@dhx/trial-todolist'; @@ -87,8 +87,8 @@ import { Component, ElementRef, OnInit, ViewChild, OnDestroy, ViewEncapsulation} @Component({ encapsulation: ViewEncapsulation.None, - selector: "todo", // a template name used in the "app.component.ts" file as - styleUrls: ["./todo.component.css"], // include the css file + selector: "todo", // selector used in app.component.ts as + styleUrls: ["./todo.component.css"], // include CSS file template: `
@@ -97,19 +97,19 @@ import { Component, ElementRef, OnInit, ViewChild, OnDestroy, ViewEncapsulation} }) export class ToDoComponent implements OnInit, OnDestroy { - // initialize container for Toolbar + // container for Toolbar @ViewChild("toolbar_container", { static: true }) toolbar_container!: ElementRef; - // initialize container for To Do List + // container for To Do List @ViewChild("todo_container", { static: true }) todo_container!: ElementRef; private _todo!: ToDo; private _toolbar!: Toolbar; ngOnInit() { - // initialize the To Do List component + // initialize To Do List this._todo = new ToDo(this.todo_container.nativeElement, {}); - // initialize the Toolbar component + // initialize Toolbar this._toolbar = new Toolbar(this.toolbar_container.nativeElement, { api: this._todo.api, // other configuration properties @@ -117,15 +117,15 @@ export class ToDoComponent implements OnInit, OnDestroy { } ngOnDestroy(): void { - this._todo.destructor(); // destruct To Do List - this._toolbar.destructor(); // destruct Toolbar + this._todo.destructor(); // remove To Do List + this._toolbar.destructor(); // remove Toolbar } } ~~~ -#### Adding styles +#### Add styles -To display To Do List correctly, you need to provide the corresponding styles. For this purpose, you can create the **todo.component.css** file in the **src/app/todo/** directory and specify important styles for To Do List and its container: +Create *todo.component.css* in *src/app/todo/* and add styles for To Do List and its container: ~~~css title="todo.component.css" /* import To Do List styles */ @@ -153,9 +153,9 @@ body{ } ~~~ -#### Loading data +#### Load data -To add data into To Do List, you need to provide a data set. You can create the **data.ts** file in the **src/app/todo/** directory and add some data into it: +Create *data.ts* in *src/app/todo/* with sample data: ~~~jsx {2,19,28,38} title="data.ts" export function getData() { @@ -199,7 +199,7 @@ export function getData() { } ~~~ -Then open the ***todo.component.ts*** file. Import the file with data and specify the corresponding data properties to the configuration object of To Do List within the `ngOnInit()` method, as shown below: +Open *todo.component.ts*, import the data file, and pass data properties to the To Do List constructor in `ngOnInit()`: ~~~jsx {2,23,25-27} title="todo.component.ts" import { ToDo, Toolbar } from '@dhx/trial-todolist'; @@ -224,7 +224,7 @@ export class ToDoComponent implements OnInit, OnDestroy { private _toolbar!: Toolbar; ngOnInit() { - const { users, tasks, projects } = getData(); // initialize data properties + const { users, tasks, projects } = getData(); // get data this._todo = new ToDo(this.todo_container.nativeElement, { users, // apply user data tasks, // apply task data @@ -245,7 +245,7 @@ export class ToDoComponent implements OnInit, OnDestroy { } ~~~ -You can also use the [`parse()`](/api/methods/parse_method/) method inside the `ngOnInit()` method of Angular to load data into To Do List. +Use the [`parse()`](/api/methods/parse_method/) method inside `ngOnInit()` to load data instead: ~~~jsx {2,23,31-36} title="todo.component.ts" import { ToDo, Toolbar } from '@dhx/trial-todolist'; @@ -270,7 +270,7 @@ export class ToDoComponent implements OnInit, OnDestroy { private _toolbar!: Toolbar; ngOnInit() { - const { users, tasks, projects } = getData(); // initialize data properties + const { users, tasks, projects } = getData(); // get data this._todo = new ToDo(this.todo_container.nativeElement, {}); this._toolbar = new Toolbar(this.toolbar_container.nativeElement, { @@ -278,7 +278,7 @@ export class ToDoComponent implements OnInit, OnDestroy { // other configuration properties }); - // apply the data via the parse() method + // load data with parse() this._todo.parse({ users, tasks, @@ -293,22 +293,22 @@ export class ToDoComponent implements OnInit, OnDestroy { } ~~~ -The `parse(data)` method provides data reloading on each applied change. +Call `parse()` again at any point to reload data with new values. -Now the To Do List component is ready to use. When the element will be added to the page, it will initialize the To Do List with data. You can provide necessary configuration settings as well. Visit our [To Do List API docs](/api/overview/configs_overview/) to check the full list of available properties. +The component is ready. When added to the page, the component initializes To Do List with data. See the [API docs](/api/overview/configs_overview/) for the full list of configuration properties. -#### Handling events +#### Handle events -When a user makes some action in the To Do List, 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/). +To Do List fires an event on each user action. Use these events to react to changes. See the [full list of events](/api/overview/events_overview/). -Open the **todo.component.ts** file and complete the `ngOnInit()` method in the following way: +The following code snippet handles the `add-task` event inside `ngOnInit()`: ~~~jsx {5-7} title="todo.component.ts" // ... ngOnInit() { this._todo = new ToDo(this.todo_container.nativeElement, {}); - this._todo.events.on("add-task", (obj) => { + this._todo.api.on("add-task", (obj) => { console.log("A new task is added", obj); }); } @@ -318,23 +318,23 @@ ngOnDestroy(): void { } ~~~ -### Step 3. Adding To Do List into the app +### Step 3. Add To Do List to the app -To add the ***ToDoComponent*** component into the app, open the ***src/app/app.component.ts*** file and replace the default code with the following one: +Open *src/app/app.component.ts* and replace the default code: ~~~jsx {5} title="app.component.ts" import { Component } from "@angular/core"; @Component({ selector: "app-root", - template: `` // a template created in the "todo.component.ts" file + template: `` // template defined in todo.component.ts }) export class AppComponent { name = ""; } ~~~ -Then create the ***app.module.ts*** file in the ***src/app/*** directory and specify the *ToDoComponent* as shown below: +Create *app.module.ts* in *src/app/* and register the components: ~~~jsx {4-5,8} title="app.module.ts" import { NgModule } from "@angular/core"; @@ -351,7 +351,7 @@ import { ToDoComponent } from "./todo/todo.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 to bootstrap the application: ~~~jsx title="main.ts" import { platformBrowserDynamic } from "@angular/platform-browser-dynamic"; @@ -361,8 +361,8 @@ platformBrowserDynamic() .catch((err) => console.error(err)); ~~~ -After that, you can start the app to see To Do List loaded with data on a page. +Start the app to see To Do List loaded with data. ![To Do List initialization](/assets/trial_todolist.png) -Now you know how to integrate DHTMLX To Do List with Angular. You can customize the code according to your specific requirements. The final example you can find on [**GitHub**](https://github.com/DHTMLX/angular-todolist-demo). +Customize the code to fit your requirements. Find the complete example on [GitHub](https://github.com/DHTMLX/angular-todolist-demo). diff --git a/docs/guides/integration_with_react.md b/docs/guides/integration_with_react.md index 76d1e20..34ac671 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). +Familiarize yourself with basic React concepts and patterns before reading this guide. Refer to the [React documentation](https://react.dev/learn) to refresh your knowledge. ::: -DHTMLX To Do List is compatible with **React**. We have prepared code examples on how to use DHTMLX To Do List with **React**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/react-todolist-demo). +DHTMLX To Do List is compatible with React. For a complete example, see the [demo on GitHub](https://github.com/DHTMLX/react-todolist-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/). +Before creating a new project, install [Vite](https://vite.dev/) (optional) and [Node.js](https://nodejs.org/en/). ::: -You can create a basic **React** project or use **React with Vite**. Let's name the project as **my-react-todo-app**: +Create a new `my-react-todo-app` project. You can use plain React or React with Vite: ~~~json npx create-react-app my-react-todo-app ~~~ -### Installation of dependencies +### Install dependencies -Go to the new created app directory: +Navigate to the new app directory: ~~~json cd my-react-todo-app ~~~ -Install dependencies and start the dev server. For this, use a package manager: +Install dependencies and start the dev server using your package manager: -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: +- With [yarn](https://yarnpkg.com/): ~~~json yarn yarn start ~~~ -- if you use [**npm**](https://www.npmjs.com/), run the following commands: +- With [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 local server (for example, `http://localhost:3000`). -## Creating To Do List +## Create To Do List -Now you should get the DHTMLX To Do List source code. First of all, stop the app and proceed with installing the To Do List package. +Stop the app and install the To Do List package. -### Step 1. Package installation +### Step 1. Install the package -Download the [**trial To Do List package**](/how_to_start/#installing-to-do-list-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial To Do List is available 30 days only. +Download the [trial To Do List package](/how_to_start/#installing-to-do-list-via-npm-or-yarn) and follow the README instructions. The trial 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 To Do List with Toolbar into the application. Create a new file in the ***src/*** directory and name it ***ToDo.jsx***. +Create a new file in *src/* and name it *ToDo.jsx*. #### Import source files -Open the ***ToDo.jsx*** file and import To Do List source files. Note that: +Open *ToDo.jsx* and import To Do List source files. The import path depends on the version you use: -- if you use PRO version and install the To Do List package from a local folder, the import paths look like this: +- For the PRO version installed from a local folder, use these import paths: ~~~jsx title="ToDo.jsx" import { ToDo, Toolbar } from 'dhx-todolist-package'; import 'dhx-todolist-package/dist/todo.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 ***todo.min.css***. +If the package is minified, import *todo.min.css* instead. -- if you use the trial version of To Do List, specify the following paths: +- For the trial version, use these import paths: ~~~jsx title="ToDo.jsx" import { ToDo, Toolbar } from '@dhx/trial-todolist'; import "@dhx/trial-todolist/dist/todo.css"; ~~~ -In this tutorial you can see how to configure the **trial** version of To Do List. +This guide uses the trial version. -#### Setting containers and adding To Do List with Toolbar +#### Set containers and initialize To Do List -To display To Do List with Toolbar on the page, you need to create containers for To Do List and Toolbar, and initialize these components using the corresponding constructors: +The following code snippet sets up the component and initializes To Do List and Toolbar inside `useEffect()`: ~~~jsx {2,6-7,10-11,13-17} title="ToDo.jsx" import { useEffect, useRef } from "react"; @@ -94,22 +94,22 @@ import { ToDo, Toolbar } from "@dhx/trial-todolist"; import "@dhx/trial-todolist/dist/todo.css"; // include To Do List styles export default function ToDoComponent(props) { - let toolbar_container = useRef(); // initialize container for Toolbar - let todo_container = useRef(); // initialize container for To Do List + let toolbar_container = useRef(); // container for Toolbar + let todo_container = useRef(); // container for To Do List useEffect(() => { - // initialize the To Do List component + // initialize To Do List const todo = new ToDo(todo_container.current, {}); - // initialize the Toolbar component + // initialize Toolbar const toolbar = new Toolbar(toolbar_container.current, { - api: todo.api, // provide To Do List inner API + api: todo.api, // connect To Do List to Toolbar // other configuration properties }); return () => { - todo.destructor(); // destruct To Do List - toolbar.destructor(); // destruct Toolbar + todo.destructor(); // remove To Do List + toolbar.destructor(); // remove Toolbar }; }, []); @@ -120,9 +120,9 @@ export default function ToDoComponent(props) { } ~~~ -#### Adding styles +#### Add styles -To display To Do List correctly, you need to provide the corresponding styles. You can use the **index.css** file to specify important styles for To Do List and its containers: +Add styles for To Do List and its containers to *index.css*: ~~~css title="index.css" /* specify styles for initial page */ @@ -148,9 +148,9 @@ body, } ~~~ -#### Loading data +#### Load data -To add data into the To Do List, you need to provide a data set. You can create the ***data.js*** file in the ***src/*** directory and add some data into it: +Create *data.js* in *src/* with sample data: ~~~jsx {2,19,28,38} title="data.js" export function getData() { @@ -194,7 +194,7 @@ export function getData() { } ~~~ -Then open the ***App.js*** file and import data. After this you can pass data into the `` component as **props**: +Open *App.js*, import the data, and pass the data to the `` component as props: ~~~jsx {2,5-6} title="App.js" import ToDo from "./ToDo"; @@ -208,7 +208,7 @@ function App() { export default App; ~~~ -Go to the ***ToDo.jsx*** file and apply the passed **props** to the To Do List configuration object: +Open *ToDo.jsx* and apply the props to the To Do List configuration: ~~~jsx {5,11-13} title="ToDo.jsx" import { useEffect, useRef } from "react"; @@ -245,7 +245,7 @@ export default function ToDoComponent(props) { } ~~~ -You can also use the [`parse()`](/api/methods/parse_method/) method inside the `useEffect()` method of React to load data into To Do List: +Use the [`parse()`](/api/methods/parse_method/) method inside `useEffect()` to load data instead: ~~~jsx {9-11,21} title="ToDo.jsx" import { useEffect, useRef } from "react"; @@ -258,7 +258,7 @@ export default function ToDoComponent(props) { let tasks = props.tasks; let users = props.users; - let projects = props.users; + let projects = props.projects; useEffect(() => { const todo = new ToDo(todo_container.current, {}); @@ -283,15 +283,15 @@ export default function ToDoComponent(props) { } ~~~ -The `parse(data)` method provides data reloading on each applied change. +Call `parse()` again at any point to reload data with new values. -Now the To Do List component is ready to use. When the element will be added to the page, it will initialize the To Do List with data. You can provide necessary configuration settings as well. Visit our [To Do List API docs](/api/overview/configs_overview/) to check the full list of available properties. +The component is ready. When added to the page, the component initializes To Do List with data. See the [API docs](/api/overview/configs_overview/) for the full list of configuration properties. -#### Handling events +#### Handle events -When a user makes some action in the To Do List, 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/). +To Do List fires an event on each user action. Use these events to react to changes. See the [full list of events](/api/overview/events_overview/). -Open ***ToDo.jsx*** and complete the `useEffect()` method in the following way: +The following code snippet handles the `add-task` event inside `useEffect()`: ~~~jsx {5-7} title="ToDo.jsx" // ... @@ -309,9 +309,9 @@ useEffect(() => { // ... ~~~ -### Step 3. Adding To Do List into the app +### Step 3. Add To Do List to the app -To add the component into the app, open the ***App.js*** file and replace the default code with the following one: +Open *App.js* and replace the default code: ~~~jsx title="App.js" import ToDo from "./ToDo"; @@ -325,8 +325,8 @@ function App() { export default App; ~~~ -After that, you can start the app to see To Do List loaded with data on a page. +Start the app to see To Do List loaded with data. ![To Do List initialization](/assets/trial_todolist.png) -Now you know how to integrate DHTMLX To Do List with React. You can customize the code according to your specific requirements. The final example you can find on [**GitHub**](https://github.com/DHTMLX/react-todolist-demo). +Customize the code to fit your requirements. Find the complete example on [GitHub](https://github.com/DHTMLX/react-todolist-demo). diff --git a/docs/guides/integration_with_svelte.md b/docs/guides/integration_with_svelte.md index a8df02f..0b8b349 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). +Familiarize yourself with basic Svelte concepts and patterns before reading this guide. Refer to the [Svelte documentation](https://svelte.dev/docs/svelte/overview) to refresh your knowledge. ::: -DHTMLX To Do List is compatible with **Svelte**. We have prepared code examples on how to use DHTMLX To Do List with **Svelte**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/svelte-todolist-demo). +DHTMLX To Do List is compatible with Svelte. For a complete example, see the [demo on GitHub](https://github.com/DHTMLX/svelte-todolist-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/). +Before creating a new project, install [Vite](https://vite.dev/) (optional) and [Node.js](https://nodejs.org/en/). ::: -There are several ways of creating a **Svelte** project: +Create a Svelte project using one of these options: -- you can use the [**SvelteKit**](https://kit.svelte.dev/) - -or - -- you can also use **Svelte with Vite** (but without SvelteKit): +- [SvelteKit](https://kit.svelte.dev/) +- Svelte with Vite (without SvelteKit): ~~~json npm create vite@latest ~~~ -Check the details in the [related article](https://svelte.dev/docs/svelte/overview). +See the [Svelte documentation](https://svelte.dev/docs/svelte/overview) for details. -### Installation of dependencies +### Install dependencies -Let's name the project as **my-svelte-todo-app** and go to the app directory: +Name the project `my-svelte-todo-app` and navigate to the app directory: ~~~json cd my-svelte-todo-app ~~~ -Install dependencies and start the dev server. For this, use a package manager: +Install dependencies and start the dev server using your package manager: -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: +- With [yarn](https://yarnpkg.com/): ~~~json yarn yarn start ~~~ -- if you use [**npm**](https://www.npmjs.com/), run the following commands: +- With [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 local server (for example, `http://localhost:3000`). -## Creating To Do List +## Create To Do List -Now you should get the DHTMLX To Do List source code. First of all, stop the app and proceed with installing the To Do List package. +Stop the app and install the To Do List package. -### Step 1. Package installation +### Step 1. Install the package -Download the [**trial To Do List package**](/how_to_start/#installing-to-do-list-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial To Do List is available 30 days only. +Download the [trial To Do List package](/how_to_start/#installing-to-do-list-via-npm-or-yarn) and follow the README instructions. The trial is available for 30 days. -### Step 2. Component creation +### Step 2. Create the component -Now you need to create a Svelte component, to add To Do List with Toolbar into the application. Let's create a new file in the ***src/*** directory and name it ***ToDo.svelte***. +Create a new file in *src/* and name it *ToDo.svelte*. -#### Import source file +#### Import source files -Open the ***ToDo.svelte*** file and import To Do List source files. Note that: +Open *ToDo.svelte* and import To Do List source files. The import path depends on the version you use: -- if you use PRO version and install the To Do List package from a local folder, the import paths look like this: +- For the PRO version installed from a local folder, use these import paths: ~~~html title="ToDo.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 **todo.min.css**. +If the package is minified, import *todo.min.css* instead. -- if you use the trial version of To Do List, specify the following paths: +- For the trial version, use these import paths: ~~~html title="ToDo.svelte" ~~~ -In this tutorial you can see how to configure the **trial** version of To Do List. +This guide uses the trial version. -#### Setting containers and adding To Do List with Toolbar +#### Set containers and initialize To Do List -To display To Do List with Toolbar on the page, you need to create containers for To Do List and Toolbar, and initialize these components using the corresponding constructors: +The following code snippet sets up the component and initializes To Do List and Toolbar in `onMount()`: ~~~html {3,6,10-11,13-17,27-28} title="ToDo.svelte" @@ -132,9 +129,31 @@ onDestroy(() => { ~~~ -#### Loading data +#### Add styles + +Add global styles for To Do List and its containers to your stylesheet (for example, *src/app.css*): + +~~~css +/* specify styles for the initial page */ +html, +body { + height: 100%; + padding: 0; + margin: 0; + background-color: #f7f7f7; +} + +/* specify styles for To Do List and Toolbar container */ +.component_container { + height: 100%; + max-width: 800px; + margin: 0 auto; +} +~~~ + +#### Load data -To add data into the To Do List, we need to provide a data set. You can create the ***data.js*** file in the ***src/*** directory and add some data into it: +Create *data.js* in *src/* with sample data: ~~~jsx {2,19,28,38} title="data.js" export function getData() { @@ -178,7 +197,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 data, and pass the data to `` as props: ~~~html {3,5,8} title="App.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 **todo.min.css**. +If the package is minified, import *todo.min.css* instead. -- if you use the trial version of To Do List, specify the following paths: +- For the trial version, use these import paths: ~~~html title="ToDo.vue" ~~~ -In this tutorial you can see how to configure the **trial** version of To Do List. +This guide uses the trial version. -#### Setting containers and adding To Do List with Toolbar +#### Set containers and initialize To Do List -To display To Do List with Toolbar on the page, you need to create containers for To Do List and Toolbar, and initialize these components using the corresponding constructors: +The following code snippet sets up the component and initializes To Do List and Toolbar in `mounted()`: ~~~html {2,7-8,10-14} title="ToDo.vue" @@ -128,9 +128,31 @@ export default { ~~~ -#### Loading data +#### Add styles -To add data into the To Do List, you need to provide a data set. You can create the ***data.js*** file in the ***src/*** directory and add some data into it: +Add global styles for To Do List and its containers to your stylesheet (for example, *src/assets/main.css*): + +~~~css +/* specify styles for the initial page */ +html, +body { + height: 100%; + padding: 0; + margin: 0; + background-color: #f7f7f7; +} + +/* specify styles for To Do List and Toolbar container */ +.component_container { + height: 100%; + max-width: 800px; + margin: 0 auto; +} +~~~ + +#### Load data + +Create *data.js* in *src/* with sample data: ~~~jsx {2,19,28,38} title="data.js" export function getData() { @@ -174,7 +196,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*, import the data, and pass the data to `` as props: ~~~html {3,7-14,19} title="App.vue" ~~~ -And apply the object destructuring: +Apply object destructuring to extract the data: ~~~js title="index.js" const { tasks, users, projects, priorities } = getData(); ~~~ -## Loading from local source +## Load from a local source -### Loading data on initialization +### Load data on initialization -You can load [a predefined data](#preparing-data-to-load) into To Do List on the initialization stage in the following way: +The following code snippet passes [predefined data](#prepare-data-to-load) to the constructor on initialization: ~~~js {2,5-8} title="index.js" const { ToDo } = todo; @@ -192,9 +192,9 @@ const list = new ToDo("#root", { }); ~~~ -### Loading data after initialization +### Load data after initialization -To load data from a local data source after initialization of the To Do List, use the [`parse()`](/api/methods/parse_method/) method: +Use the [`parse()`](/api/methods/parse_method/) method to load data after initialization: ~~~js {3,5,12-17} title="index.js" const { ToDo, Toolbar } = todo; @@ -207,7 +207,7 @@ const toolbar = new Toolbar("#toolbar", { api: list.api, }); -// parse data into the component +// load data into To Do List list.parse({ tasks, users, @@ -216,9 +216,9 @@ list.parse({ }); ~~~ -## Saving and restoring state +## Save and restore state -To save the current state of a To Do, use the [`serialize()`](/api/methods/serialize_method/) method. It converts the data of the To Do List into a JSON object. +Use the [`serialize()`](/api/methods/serialize_method/) method to save the current state. The method converts To Do List data into a JSON object: ~~~js const state = list.serialize(); @@ -226,18 +226,17 @@ const state = list.serialize(); // tasks: [{...}, {...}, ...], // users: [{...}, {...}, ...], // projects: [{...}, {...}, ...], -// priorities: [{...}, {...}, ...], // tags: [], // activeProject: string, // } ~~~ -Then you can parse the data stored in the saved state array to a different To Do List. For example: +The following code snippet loads the saved state into a new To Do List instance: ~~~js -// creating a new To Do +// create a new To Do List const list2 = new ToDo("#root2", {}); -// parsing the state of To Do List into another To Do List +// load the saved state into the new list list2.parse(state); -~~~ \ No newline at end of file +~~~ diff --git a/docs/guides/localization.md b/docs/guides/localization.md index ce2889d..546a307 100644 --- a/docs/guides/localization.md +++ b/docs/guides/localization.md @@ -6,13 +6,15 @@ description: You can learn about the To Do List localization in the documentatio # Localization -You can present the interface of DHTMLX To Do List in any language. The library provides a number of predefined locales and gives the ability to create custom ones. By default, DHTMLX To Do List uses [English locale](#default-locale). +Present the To Do List interface in any language. The library includes predefined locales and supports custom ones. By default, To Do List uses the [English locale](#default-locale). ## Default locale +The following code snippet defines the default English locale with all available labels: + ~~~js const en = { - calendar:{ // translations and settings of the calendar + calendar:{ // calendar translations and settings monthFull: [ "January", "February", "March", "April", "May", "June", @@ -108,9 +110,9 @@ const en = { ## Custom locale -To initialize the To Do List component in non-English language, you need to: +To use a non-English locale: -- define necessary language settings: provide translations for all text labels (it can be any language you need) +- Define the language settings and provide translations for all text labels: ~~~js const de = { @@ -124,11 +126,11 @@ const de = { ~~~ :::tip -To create a custom locale, you can make a copy of the default ([English](#default-locale)) locale, and translate text labels from it into the required language. +To create a custom locale, copy the [default English locale](#default-locale) and translate the labels. ::: :::info -You can download [**a repository from GitHub**](https://github.com/web-widgets/wx-todo-locales/tree/master/locales) which includes locales of the To Do List for the following languages: +Download a [locale repository from GitHub](https://github.com/web-widgets/wx-todo-locales/tree/master/locales) with ready-made translations for the following languages: - Chinese (**cn**) - French (**fr**) @@ -140,10 +142,10 @@ You can download [**a repository from GitHub**](https://github.com/web-widgets/w - Russian (**ru**) - Spanish (**es**) -*The files don't include translations for the Calendar labels, therefore you will need to add them yourself.* +The files do not include Calendar label translations — add them manually. ::: -- apply the necessary locale to the To Do List component and its Toolbar via the corresponding **locale** properties: +- Apply the `locale` property to both To Do List and Toolbar: ~~~js {8,13} const { ToDo, Toolbar} = todo; @@ -163,11 +165,16 @@ const toolbar = new Toolbar("#toolbar", { ~~~ :::tip -To change the locale dynamically, use the related `setLocale()` methods of the [To Do List](/api/methods/setlocale_method/) and [Toolbar](/api/toolbar_api/methods/setlocale_method/) +To change the locale dynamically, call [`setLocale()`](/api/methods/setlocale_method/) on both To Do List and Toolbar. Note that `setLocale()` reinitializes the component. Pass `list.api` as the second argument to the Toolbar method: + +~~~js +list.setLocale(de); +toolbar.setLocale(de, list.api); +~~~ ::: ## Example -In this snippet you can see how to switch between the EN and DE locales: +The following example demonstrates switching between English and German locales: diff --git a/docs/guides/multiselection.md b/docs/guides/multiselection.md index d908088..875c399 100644 --- a/docs/guides/multiselection.md +++ b/docs/guides/multiselection.md @@ -8,19 +8,15 @@ description: You can learn about selection of multiple tasks in the documentatio The To Do List library allows you to select multiple tasks and manage them at once. -In this article we'll discuss the details on how to initialize To Do List with selected tasks, how to select one or several tasks after the initialization stage, how to get IDs of all selected tasks. - -We'll consider how to perform bulk operations over the selected tasks and provide you with a list of available operations. And, finally, we'll show you the ways of resetting selection. - ![Multiselection](/assets/multiselection.png) :::info -Learn how to [select](../../#selecting-tasks) and [manage multiple tasks](../../#managing-multiple-tasks) via UI +Learn how to [select](../../#selecting-tasks) and [manage multiple tasks](../../#managing-multiple-tasks) via the UI. ::: -## Initially selected tasks +## Set initially selected tasks -If you want to create a To Do List with initially selected tasks, use the [`selected`](/api/configs/selected_config/) configuration property of To Do List: +Use the [`selected`](/api/configs/selected_config/) configuration property to specify tasks that are selected on initialization: ~~~js {12} const list = new ToDo("#root", { @@ -40,18 +36,18 @@ const list = new ToDo("#root", { console.log(list.getSelection()); // ["1.1", "1.2", "2.2"] ~~~ -## Selecting tasks +## Select tasks -The library provides you with the [`selectTask()`](/api/methods/selecttask_method/) method which lets you select tasks after To Do List initialization. The method has two parameters: +Use the [`selectTask()`](/api/methods/selecttask_method/) method to select tasks after initialization. The method takes two parameters: -- `id` - the ID of the task to select -- `join` - defines whether To Do List should join the specified task to the previously selected tasks +- `id` — ID of the task to select +- `join` — if `true`, adds the task to the current selection without resetting previously selected tasks -### Selecting one task +### Select one task -By default, the value of the **join** parameter is set to *false*. It means, that the method will select only the specified task without saving IDs of the previously selected tasks. +By default, `join` is `false`. The method selects only the specified task and clears the previous selection. -Take a look at the following code snippet: +The following code snippet selects a single task, clearing the previous selection: ~~~js {19} const list = new ToDo("#root", { @@ -78,11 +74,11 @@ list.selectTask({ console.log(list.getSelection()) // ["2.1"] ~~~ -### Selecting multiple tasks +### Select multiple tasks -In order to select multiple tasks, you need to set the value of the **join** parameter to *true*. In this case, the `selectTask()` method will select the specified task and will not reset selection of earlier selected tasks. +To select multiple tasks, set `join` to `true`. The `selectTask()` method adds the task to the current selection without resetting previously selected tasks. -The most convenient way to select several tasks at once is shown below: +The following code snippet uses `selectTask()` with `join: true` to select multiple tasks at once: ~~~js {14-18} const list = new ToDo("#root", { @@ -107,7 +103,7 @@ for (id of selected) { console.log(list.getSelection()) // ["1.1", "1.2", "2.2"] ~~~ -And here is an example of how you can select one more task: +The following code snippet adds one more task to the current selection: ~~~js {3} console.log(list.getSelection()) // ["1.1", "1.2", "2.2"] @@ -117,7 +113,7 @@ list.selectTask({ id: "2.1", join: true }); console.log(list.getSelection()) // ["1.1", "1.2", "2.2", "2.1"] ~~~ -## Getting all selected tasks +## Get all selected tasks To get all tasks that are currently selected, use the [`getSelection()`](/api/methods/getselection_method/) method: @@ -129,15 +125,15 @@ list.getSelection({ sorted: false }); // ["1.2", "1.1", "2.2", "2.1"] list.getSelection({ sorted: true }); // ["1.1", "1.2", "2.1", "2.2"] ~~~ -Enable the **sorted** parameter if you need to get IDs of the selected tasks in the order they are displayed in List. +Enable `sorted` to get IDs in the order they appear in the list. -## Managing selected tasks +## Manage selected tasks -After you have selected multiple tasks, you may apply different operations to them at once. +Apply bulk operations to all selected tasks at once. -For this purpose, the library includes the [`eachSelected()`](/api/methods/eachselected_method/) method that allows iterating over all selected tasks. The additional parameters of the method - **sorted** and **reversed** - let you define whether the tasks should be sorted or not and specify the direction of iteration. +Use the [`eachSelected()`](/api/methods/eachselected_method/) method to iterate over all selected tasks. The `sorted` and `reversed` parameters control the sort order and iteration direction. -For example, you can apply the method to delete all selected tasks: +For example, the following code snippet deletes all selected tasks: ~~~js list.eachSelected(id => { @@ -149,35 +145,44 @@ Check the full list of available operations you can perform over multiple tasks ### List of available operations -Here is the full list of bulk operations you can perform over multiple selected tasks via API methods: +Use the following methods to perform bulk operations on selected tasks: -- copying tasks via the [`copyTask()`](/api/methods/copytask_method/) method -- pasting tasks via the [`pasteTask()`](/api/methods/pastetask_method/) method -- moving tasks via the [`moveTask()`](/api/methods/movetask_method/) method -- deleting tasks via the [`deleteTask()`](/api/methods/deletetask_method/) method -- marking tasks complete/incomplete via the [`checkTask()`](/api/methods/checktask_method/) and [`uncheckTask()`](/api/methods/unchecktask_method/) methods -- demoting and promoting the nesting level of tasks via the [`indentTask()`](/api/methods/indenttask_method/) and [`unindentTask()`](/api/methods/unindenttask_method/) methods +- [`copyTask()`](/api/methods/copytask_method/) — copy selected tasks +- [`pasteTask()`](/api/methods/pastetask_method/) — paste copied tasks +- [`moveTask()`](/api/methods/movetask_method/) — move selected tasks +- [`deleteTask()`](/api/methods/deletetask_method/) — delete selected tasks +- [`checkTask()`](/api/methods/checktask_method/), [`uncheckTask()`](/api/methods/unchecktask_method/) — mark selected tasks complete or incomplete +- [`indentTask()`](/api/methods/indenttask_method/), [`unindentTask()`](/api/methods/unindenttask_method/) — change the nesting level of selected tasks -## Resetting selection +## Reset selection -### Unselecting one task +### Unselect one task -To remove selection from one selected task, pass the ID of the task as a parameter to the [`unselectTask()`](/api/methods/unselecttask_method/) method: +To unselect a specific task, pass the task ID to the [`unselectTask()`](/api/methods/unselecttask_method/) method: ~~~js list.unselectTask({ id: "1.1" }); ~~~ -### Unselecting all tasks +### Unselect all tasks -To unselect all currently selected tasks, pass **id: null** to the [`unselectTask()`](/api/methods/unselecttask_method/) method: +To unselect all selected tasks, pass `id: null` to [`unselectTask()`](/api/methods/unselecttask_method/): ~~~js list.unselectTask({ id: null }); ~~~ +## React to selection changes +To Do List fires events when you select or unselect tasks. Use these events to react to changes. +- [`select-task`](/api/events/selecttask_event/) — fires when a task is selected +- [`unselect-task`](/api/events/unselecttask_event/) — fires when a task is unselected +The following code snippet handles the `select-task` event: - +~~~js +list.api.on("select-task", ({ id, join }) => { + console.log("Selected task:", id); +}); +~~~ diff --git a/docs/guides/project_index.md b/docs/guides/project_index.md index 25878cd..9e7519a 100644 --- a/docs/guides/project_index.md +++ b/docs/guides/project_index.md @@ -1,22 +1,22 @@ --- -sidebar_label: Managing projects -title: Managing projects +sidebar_label: Manage projects +title: Manage projects description: You can learn how to manage projects in the documentation of the DHTMLX JavaScript To Do List library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX To Do List. --- -# Managing projects +# Manage projects :::info To configure projects, use the [`projects`](/api/configs/projects_config/) property of To Do List. -To define what project a task will belong to, you need to pass the id of the necessary project to the **project** parameter of the related [`task`](/api/configs/tasks_config/) object +To define what project a task belongs to, pass the project ID to the `project` parameter of the related [`task`](/api/configs/tasks_config/) object. -To make a certain project active on initialization of To Do List, use the [`activeProject`](/api/configs/activeproject_config/) property. +To make a certain project active on initialization, use the [`activeProject`](/api/configs/activeproject_config/) property. ::: -The next guides will teach you how to work with the object of a project and how to implement basic operations with the projects via API. +The following guides cover project object structure and basic project operations via API. import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; diff --git a/docs/guides/project_object_operations.md b/docs/guides/project_object_operations.md index ef6eaed..46bc46e 100644 --- a/docs/guides/project_object_operations.md +++ b/docs/guides/project_object_operations.md @@ -6,9 +6,9 @@ description: You can learn about project object in the documentation of the DHTM # Project object -## Getting a project object +## Get a project object -To get a project object, use the [`getProject()`](/api/methods/getproject_method/) method: +Use the [`getProject()`](/api/methods/getproject_method/) method to retrieve a project object by ID: ~~~js {13} const projects = [ @@ -26,9 +26,9 @@ const toolbar = new Toolbar("#toolbar", { list.getProject({ id: "first" }); // -> {id: 'first', label: 'First project'} ~~~ -## Checking if a project exists +## Check if a project exists -To check whether a project exists or not, use the [`existsProject()`](/api/methods/existsproject_method/) method: +Use the [`existsProject()`](/api/methods/existsproject_method/) method to check whether a project with the given ID exists: ~~~js {13-14} const projects = [ @@ -45,4 +45,4 @@ const toolbar = new Toolbar("#toolbar", { list.existsProject({ id: 1 }); // -> false list.existsProject({ id: "first" }); // -> true -~~~ \ No newline at end of file +~~~ diff --git a/docs/guides/project_operations.md b/docs/guides/project_operations.md index 0b3fb52..aa008c7 100644 --- a/docs/guides/project_operations.md +++ b/docs/guides/project_operations.md @@ -6,9 +6,9 @@ description: You can learn about operations with projects in the documentation o # Operations with projects -## Changing the active project +## Change the active project -It is possible to change the currently active project via the [`setProject()`](/api/methods/setproject_method/) method. It takes the id of a project as a parameter: +Change the active project with the [`setProject()`](/api/methods/setproject_method/) method, passing the project ID as a parameter: ~~~js {9,16} const projects = [ @@ -29,9 +29,9 @@ const toolbar = new Toolbar("#toolbar", { list.setProject({ id: "first" }); ~~~ -## Adding a new project +## Add a new project -You may create a new project via the [`addProject()`](/api/methods/addproject_method/) method: +Add a new project with the [`addProject()`](/api/methods/addproject_method/) method: ~~~js {13-18} const projects = [ @@ -54,9 +54,9 @@ list.addProject({ }); ~~~ -## Updating a project +## Update a project -To dynamically update parameters of a project, apply the [`updateProject()`](/api/methods/updateproject_method/) method. For instance, you can update the label of the project: +To update project parameters, use the [`updateProject()`](/api/methods/updateproject_method/) method. The following example updates the project label: ~~~js {13-18} const projects = [ @@ -79,9 +79,9 @@ list.updateProject({ }); ~~~ -## Deleting a project +## Delete a project -To remove an unnecessary project, apply the [`deleteProject()`](/api/methods/deleteproject_method/) method: +To delete a project, use the [`deleteProject()`](/api/methods/deleteproject_method/) method: ~~~js {17} const projects = [ @@ -104,9 +104,9 @@ list.deleteProject({ id: "first" }); ~~~ :::note -The tasks linked to the project won't be removed. They will be moved to the *"No project"* section +The tasks linked to the deleted project are not removed. The widget moves the tasks to the *"No project"* section. ~~~js console.log(list.getTask({id: "1"})); // -> {id: '1', text: 'Task 1', project: null} ~~~ -::: \ No newline at end of file +::: diff --git a/docs/guides/readonly_mode.md b/docs/guides/readonly_mode.md index f7c0c35..eec05f6 100644 --- a/docs/guides/readonly_mode.md +++ b/docs/guides/readonly_mode.md @@ -6,12 +6,12 @@ description: You can learn about the read-only mode in the documentation of the # Read-only mode -To make the To Do List read-only, set the [`readonly`](/api/configs/readonly_config/) configuration property to *true*. +To make To Do List read-only, set the [`readonly`](/api/configs/readonly_config/) property to `true`: ~~~js {8} const { ToDo, Toolbar } = todo; -// create To do list +// create To Do List const list = new ToDo("#root", { tasks, users, @@ -25,9 +25,11 @@ const toolbar = new Toolbar("#toolbar", { ~~~ :::info -In this mode, the tasks are non-editable. You will be able only to select a task and mark it as complete or incomplete. +In this mode, tasks are non-editable. You can only select a task and mark it as complete or incomplete. ::: ## Example +The example below demonstrates the read-only mode. + \ No newline at end of file diff --git a/docs/guides/sorting_filtering_tasks.md b/docs/guides/sorting_filtering_tasks.md index aa4ece7..56f5473 100644 --- a/docs/guides/sorting_filtering_tasks.md +++ b/docs/guides/sorting_filtering_tasks.md @@ -1,18 +1,18 @@ --- -sidebar_label: Sorting and filtering tasks -title: Sorting and filtering tasks +sidebar_label: Sort and filter tasks +title: Sort and filter tasks description: You can learn about sorting and filtering of tasks in the documentation of the DHTMLX JavaScript To Do List library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX To Do List. --- -# Sorting and filtering tasks +# Sort and filter tasks -## Sorting tasks +## Sort tasks -The library allows you to sort tasks in the list after initialization of To Do List. There are two ways to view the tasks in the sorted order: +Sort tasks in the list with one of the following options: -- via the **Sort by** option of the [Toolbar menu](../../#toolbar). You may sort tasks by *text*, *due date*, *completion date*, *creation date*, or *editing date* +- through the **Sort by** option in the [Toolbar menu](../../#toolbar) — sort by *text*, *due date*, *completion date*, *creation date*, or *editing date* -- via the [`setSort()`](/api/methods/setsort_method/) method. You may specify your own search function or implement sorting by a [task attribute](/api/configs/tasks_config/#parameters). For instance: +- with the [`setSort()`](/api/methods/setsort_method/) method — specify a custom sort function or sort by a [task attribute](/api/configs/tasks_config/#parameters): ~~~js list.setSort({ @@ -22,13 +22,13 @@ list.setSort({ }); ~~~ -## Filtering tasks +## Filter tasks -You can find the tasks that match the specified criteria in 2 ways: +Find tasks that match specified criteria with one of the following options: -- via the [search bar](../../#toolbar) of Toolbar +- through the [search bar](../../#toolbar) in the Toolbar -- through the [`setFilter()`](/api/methods/setfilter_method/) method. The method supports the *strict* mode of filtering that allows you to filter tasks by the exact match. +- with the [`setFilter()`](/api/methods/setfilter_method/) method — supports `strict` mode to match tasks by exact value: ~~~js // filter data by the specified rules @@ -44,4 +44,4 @@ To reset filtering, call the method without parameters: ~~~js // reset filtering list.setFilter({}); -~~~ \ No newline at end of file +~~~ diff --git a/docs/guides/stylization.md b/docs/guides/stylization.md index f0dac4b..03596ad 100644 --- a/docs/guides/stylization.md +++ b/docs/guides/stylization.md @@ -6,15 +6,17 @@ description: You can learn about the To Do List Stylization in the documentation # Stylization -You can stylize any part of the interface of DHTMLX To Do List to meet your project requirements. For this, the library provides a wide range of CSS variables. Note, that To Do List includes **two** types of CSS variables: +Stylize any part of the DHTMLX To Do List interface with CSS variables. The library provides two types of CSS variables: - variables related to To Do List style - variables related to the WX library style (font, icons, checkboxes, etc) ## Default style +The following CSS variables define the default appearance of To Do List. + :::tip Note -New versions of the To Do List can bring some changes for the variables and their names. So, please, do not forget to check the names after updating to the newest version and promptly modify them in your code to avoid problems with display of the component +New versions of To Do List may change variable names. Check variable names after updating to avoid display issues. ::: ~~~html @@ -95,9 +97,9 @@ New versions of the To Do List can bring some changes for the variables and thei ## Custom style -To customize the appearance of To Do List, just change the values of the necessary CSS variables. +To customize the appearance of To Do List, change the values of the CSS variables. -In this snippet you can see how to apply a custom style to To Do List: +The example below applies a custom style to To Do List: diff --git a/docs/guides/task_index.md b/docs/guides/task_index.md index bd83624..e2d5c73 100644 --- a/docs/guides/task_index.md +++ b/docs/guides/task_index.md @@ -1,16 +1,16 @@ --- -sidebar_label: Managing tasks -title: Managing tasks +sidebar_label: Manage tasks +title: Manage tasks description: You can learn about managing tasks in the documentation of the DHTMLX JavaScript To Do List library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX To Do List. --- -# Managing tasks +# Manage tasks :::info -To configure tasks, use the [`tasks`](/api/configs/tasks_config/) property of To Do List +To configure tasks, use the [`tasks`](/api/configs/tasks_config/) property of To Do List. ::: -In the next guides you will find information related to the API of To Do List intended for work with tasks. You will learn how to get the object of a task, how to work with parents and children of a task, how to perform different operations over tasks (such as adding, deleting, updating, copying, moving a task, etc), how to select multiple tasks and manage them at once, and more. +The following guides cover the API for working with tasks: accessing task objects, navigating parent-child relationships, performing operations (add, delete, update, copy, move), selecting multiple tasks, and more. import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; diff --git a/docs/guides/task_object.md b/docs/guides/task_object.md index 85d8a46..99bf4b9 100644 --- a/docs/guides/task_object.md +++ b/docs/guides/task_object.md @@ -4,9 +4,9 @@ title: Task object/ID description: You can learn about task object and task id in the documentation of the DHTMLX JavaScript To Do List library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX To Do List. --- -# Task object/Id +# Task object/ID -## Getting a task object +## Get a task object To get a task object, use the [`getTask()`](/api/methods/gettask_method/) method: @@ -22,9 +22,9 @@ const list = new ToDo("#root", { tasks }); list.getTask({ id: "1.2" }); // -> {id: '1.2', text: 'Task 1.2', parent: '1'} ~~~ -## Checking if a task exists +## Check if a task exists -To check whether a task exists or not, use the [`existsTask()`](/api/methods/existstask_method/) method: +To check whether a task exists, use the [`existsTask()`](/api/methods/existstask_method/) method: ~~~js const tasks = [ @@ -39,7 +39,7 @@ list.existsTask({ id: "2" }); // -> false list.existsTask({ id: "1.2" }); // -> true ~~~ -## Getting child Ids +## Get child IDs To get the children of a task, use the [`getChildrenIds()`](/api/methods/getchildrenids_method/) method: @@ -55,7 +55,7 @@ console.log(list.getChildrenIds({ id: "1" })); // ['1.1', '1.1.1', '1.2'] console.log(list.getChildrenIds({ id: "1", tree: false })); // ['1.1', '1.2'] ~~~ -If you apply filtering, some tasks can become invisible on the page. The **filtered** parameter of the method gives you the ability to define whether the filtered (hidden) tasks must be included into the result (*filtered: false* by default) or not (*filtered: true*): +If you apply filtering, some tasks become hidden. Set `filtered: false` (default) to include hidden tasks in the result, or `filtered: true` to exclude them: ~~~js // filter the tasks @@ -68,14 +68,14 @@ console.log(list.getChildrenIds({ id: "1", filtered: false })); // -> ['1.1', '1 console.log(list.getChildrenIds({ id: "1", filtered: true })); // -> ['1.1', '1.1.1'] ~~~ -The **tree** parameter of the method allows you to get the IDs only for the first-level children of the task. For that, set the parameter to *false*: +Set `tree` to `false` to get IDs only for first-level children: ~~~js console.log(list.getChildrenIds({ id: "1", filtered: true, tree: false })); // -> ['1.1'] console.log(list.getChildrenIds({ id: "1", filtered: false, tree: false })); // -> ['1.1', '1.2'] ~~~ -The **hideCompleted** parameter of the method lets you get the IDs only of those children tasks which yet need to be done, excluding the completed ones. For that, set the parameter to *true*: +Set `hideCompleted` to `true` to exclude completed tasks from the result: ~~~js {4,11,18,21} const tasks = [ @@ -101,9 +101,9 @@ console.log(list.getChildrenIds({ id: "1", filtered: false, tree: true, hideComp console.log(list.getChildrenIds({ id: "1", filtered: false, tree: true, hideCompleted: true})); // -> ['1.1', '1.2'] ~~~ -## Checking if a task has children +## Check if a task has children -To check whether a task has child tasks, apply the [`hasChildren()`](/api/methods/haschildren_method/) method: +To check whether a task has child tasks, use the [`hasChildren()`](/api/methods/haschildren_method/) method: ~~~js const tasks = [ @@ -117,7 +117,7 @@ const tasks = [ console.log(list.hasChildren({ id: "1.1" })); // -> true ~~~ -If you apply filtering, some tasks can become invisible on the page. The **filtered** parameter of the method gives you the ability to define whether the filtered (hidden) tasks must be included into the result (*filtered: false* by default) or not (*filtered: true*): +If you apply filtering, some tasks become hidden. Set `filtered: false` (default) to include hidden tasks in the result, or `filtered: true` to exclude them: ~~~js // filter the tasks @@ -128,7 +128,7 @@ console.log(list.hasChildren({ id: "1.1" })); // -> true console.log(list.hasChildren({ id: "1.1", filtered: true })); // -> false ~~~ -The **hideCompleted** parameter of the method lets you exclude completed tasks from the result. For that, set the parameter to *true*: +Set `hideCompleted` to `true` to exclude completed tasks from the result: ~~~js {4,9} const tasks = [ @@ -142,7 +142,7 @@ console.log(list.hasChildren({ id: "1.1" })); // -> true console.log(list.hasChildren({ id: "1.1", hideCompleted: true })); // -> false ~~~ -## Getting parent Ids +## Get parent IDs To get the parents of a task, use the [`getParentIds()`](/api/methods/getparentids_method/) method: @@ -159,7 +159,7 @@ const list = new ToDo("#root", { tasks }); console.log(list.getParentIds({ id: "1.1.1" })); // ['1.1', '1'] ~~~ -## Getting Ids of selected tasks +## Get IDs of selected tasks To get IDs of all currently selected tasks, use the [`getSelection()`](/api/methods/getselection_method/) method: @@ -181,5 +181,5 @@ list.selectTask({ join: true }); -console.log(list.getSelection( sorted: false )); // -> ["1.1", "1.2", "1.1.1"] -~~~ \ No newline at end of file +console.log(list.getSelection({ sorted: false })); // -> ["1.1", "1.2", "1.1.1"] +~~~ diff --git a/docs/guides/task_operations.md b/docs/guides/task_operations.md index 3b7d659..7b3b612 100644 --- a/docs/guides/task_operations.md +++ b/docs/guides/task_operations.md @@ -6,7 +6,7 @@ description: You can learn about operations with tasks in the documentation of t # Operations with tasks -## Adding a new task +## Add a new task To add a new task to the list, use the [`addTask()`](/api/methods/addtask_method/) method: @@ -23,30 +23,31 @@ list.addTask({ }); ~~~ -## Copying/pasting a task +## Copy and paste a task ### Copy and paste -The quickest way to copy and paste a task is use the [`copyTask()`](/api/methods/copytask_method/) method. For that, it is necessary to pass the following parameters to the method: -- the ID of the task that you want to copy and paste -- the ID of the future project (if it exists) -- the ID of the target task where the copied task should be pasted +Use the [`copyTask()`](/api/methods/copytask_method/) method to copy and paste a task. Pass the following parameters to the method: + +- the ID of the task to copy and paste +- the ID of the target project (if it exists) +- the ID of the target task where the copied task is pasted - other parameters are optional ~~~js list.copyTask({ id: "1.1", // ID of the task to copy join: false, // resets copies of other tasks and copies only this task - project: "p_2", // ID of the future project (if exists) - parent: "2.1", // ID of the future parent + project: "p_2", // ID of the target project (if exists) + parent: "2.1", // ID of the target parent targetId: "2.1.2", // ID of the target task - reverse: true // the task will be pasted before the target one + reverse: true // the task is pasted before the target one }); ~~~ ### Copy to the clipboard -To copy a necessary task to the clipboard without its further pasting, pass the ID of the task to the [`copyTask()`](/api/methods/copytask_method/) method: +To copy a task to the clipboard without pasting, pass the task ID to the [`copyTask()`](/api/methods/copytask_method/) method: ~~~js list.copyTask({ @@ -54,15 +55,15 @@ list.copyTask({ }); ~~~ -### Saving IDs of other copies +### Save IDs of other copies :::info -If you want to copy the task and save other previously copied tasks, you need to pass the **join: true** parameter to the [`copyTask()`](/api/methods/copytask_method/) method. Otherwise, only the specified task will be copied, all others copies created earlier will be reset. +To copy a task and keep other previously copied tasks, pass `join: true` to the [`copyTask()`](/api/methods/copytask_method/) method. If you do not pass this parameter, only the specified task is copied and earlier copies are reset. ::: ### Paste from the clipboard -You can paste the copied task from the clipboard to the necessary place via the [`pasteTask()`](/api/methods/pastetask_method/) method: +Paste the copied task from the clipboard with the [`pasteTask()`](/api/methods/pastetask_method/) method: ~~~js list.pasteTask({ @@ -71,9 +72,9 @@ list.pasteTask({ }); ~~~ -## Updating a task +## Update a task -To dynamically update parameters of a task, apply the [`updateTask()`](/api/methods/updatetask_method/) method: +To update parameters of a task, use the [`updateTask()`](/api/methods/updatetask_method/) method: ~~~js list.updateTask({ @@ -84,25 +85,25 @@ list.updateTask({ }); ~~~ -## Moving a task +## Move a task To move a task to another position, use the [`moveTask()`](/api/methods/movetask_method/) method: ~~~js list.moveTask({ id: "1.1", // ID of the task to move - project:"p_2", // ID of the future project (if exists) - parent: "2", // ID of the future parent + project:"p_2", // ID of the target project (if exists) + parent: "2", // ID of the target parent targetId: "2.1", // ID of the target task - reverse: true // the task will be placed before the target one + reverse: true // the task is placed before the target one }); ~~~ :::note -If you move a parent task, it will be moved together with its subtasks. +A parent task moves together with its subtasks. ::: -## Deleting a task +## Delete a task To delete a task, use the [`deleteTask()`](/api/methods/deletetask_method/) method: @@ -111,10 +112,10 @@ list.deleteTask({ id: "1.2" }); ~~~ :::note -The method removes the task with all its child tasks +The method removes the task with all its child tasks. ::: -## Expanding/collapsing a task +## Expand and collapse tasks To collapse a task, use the [`collapseTask()`](/api/methods/collapsetask_method/) method. The method takes the ID of the task as a parameter: @@ -129,9 +130,9 @@ To expand a collapsed task by its ID, use the [`expandTask()`](/api/methods/expa list.expandTask({ id: "1.1" }); ~~~ -## Marking a task complete/incomplete +## Mark a task complete or incomplete -You may mark the necessary task as complete/incomplete via the corresponding [`checkTask()`](/api/methods/checktask_method/) and [`uncheckTask()`](/api/methods/unchecktask_method/) methods: +Mark a task complete or incomplete with the [`checkTask()`](/api/methods/checktask_method/) and [`uncheckTask()`](/api/methods/unchecktask_method/) methods: ~~~js list.checkTask({ @@ -145,9 +146,9 @@ list.uncheckTask({ }); ~~~ -When `manual: false` is set, the result of applying the method depends on the value which is specified for the **behavior** attribute of the **completed** parameter of the [`taskShape`](/api/configs/taskshape_config/) property. +When `manual: false` is set, the result depends on the `behavior` attribute of the `completed` parameter in [`taskShape`](/api/configs/taskshape_config/). -If the "auto" mode is specified via the **taskShape** property but you need to check/uncheck the task in the "manual" mode, set the **manual** parameter of the [`checkTask()`](/api/methods/checktask_method/) or [`uncheckTask()`](/api/methods/unchecktask_method/) method to *true*: +If `taskShape` uses the `"auto"` mode but you need to check or uncheck the task manually, set the `manual` parameter of [`checkTask()`](/api/methods/checktask_method/) or [`uncheckTask()`](/api/methods/unchecktask_method/) to `true`: ~~~js list.checkTask({ @@ -161,11 +162,11 @@ list.uncheckTask({ }); ~~~ -## Changing the indent level of a task +## Change the indent level of a task -To change the nesting level of a task dynamically, use the following two methods: +To change the nesting level of a task, use the following methods: -- [`indentTask()`](/api/methods/indenttask_method/) - to demote the nesting level of a task to one lower level +- [`indentTask()`](/api/methods/indenttask_method/) — demote a task's nesting level by one ~~~js const list = new ToDo("#root", { @@ -182,7 +183,7 @@ list.indentTask({ id: "1.2" }); console.log(list.getParentIds({ id: "1.2" })); // ['1.1', '1'] ~~~ -- [`unindentTask()`](/api/methods/unindenttask_method/) - to promote the nesting level of the task to one higher level +- [`unindentTask()`](/api/methods/unindenttask_method/) — promote a task's nesting level by one ~~~js const list = new ToDo("#root", { @@ -200,12 +201,12 @@ console.log(list.getParentIds({ id: "1.2" })); // [] ~~~ :::info -The result of applying the methods depends on the structure of the list +The result depends on the structure of the list. ::: -## Filtering tasks +## Filter tasks -You can find the tasks that match the specified criteria with the help of the [`setFilter()`](/api/methods/setfilter_method/) method. The method supports the *strict* mode of filtering that allows you to filter tasks by the exact match. +Use the [`setFilter()`](/api/methods/setfilter_method/) method to find tasks that match specified criteria. The method supports the `strict` mode of filtering to match tasks by exact value. ~~~js // filter data by the specified rules @@ -221,4 +222,4 @@ To reset filtering, call the method without parameters: ~~~js // reset filtering list.setFilter({}); -~~~ \ No newline at end of file +~~~ diff --git a/docs/guides/task_users.md b/docs/guides/task_users.md index 1f45d1f..3a676fe 100644 --- a/docs/guides/task_users.md +++ b/docs/guides/task_users.md @@ -8,9 +8,9 @@ description: You can learn about task assignees in the documentation of the DHTM You can delegate tasks to one or several people. -## Configuring task assignees +## Configure task assignees -The list of assignees is specified via the [`users`](/api/configs/users_config/) configuration property of To Do List. +Specify the list of assignees with the [`users`](/api/configs/users_config/) configuration property: ~~~js const users = [ @@ -23,9 +23,9 @@ const users = [ const list = new ToDo("#root", { users }); ~~~ -## Setting assignees on initialization stage +## Set assignees on initialization -To assign people to the necessary task on the initialization stage, pass the id(s) of the assignees to the **assigned** parameter of the related [`task`](/api/configs/tasks_config/) object: +To assign people to a task on initialization, pass the user IDs to the `assigned` parameter of the [`task`](/api/configs/tasks_config/) object: ~~~js {11} const users = [ @@ -48,18 +48,18 @@ const list = new ToDo("#root", { }); ~~~ -As a result, the assigned people will be displayed to the right of the task. +The assigned people appear to the right of the task. ![users](/assets/users.png) -To view the list of people assigned to a task, click on the people avatars. To close the opened list, click outside it. +To view the list of people assigned to a task, click the avatars. To close the list, click outside the list. -## Changing task assignees +## Change task assignees -You can re-assign or remove a task assignee after initialization of To Do List in the following ways: +Re-assign or remove a task assignee in the following ways: -- via the **Assign to** option of the task menu -- via the corresponding [`assignUser()`](/api/methods/assignuser_method/) and [`unassignUser()`](/api/methods/unassignuser_method/) methods, for example: +- through the **Assign to** option in the task menu +- with the [`assignUser()`](/api/methods/assignuser_method/) and [`unassignUser()`](/api/methods/unassignuser_method/) methods: ~~~js // assign a person to the task diff --git a/docs/guides/working_with_server.md b/docs/guides/working_with_server.md index 136ec7c..e7de86d 100644 --- a/docs/guides/working_with_server.md +++ b/docs/guides/working_with_server.md @@ -1,54 +1,57 @@ --- -sidebar_label: Working with server -title: Working with server +sidebar_label: Work with server +title: Work with server description: You can learn about working with server in the documentation of the DHTMLX JavaScript To Do List library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX To Do List. --- -# Working with server -DHTMLX To Do List allows working both with the client and server data. The widget doesn't have any special requirements for the backend. It can be easily connected with any backend platform which supports the REST API (RESTful API). +# Work with server + +To Do List works with both client-side and server-side data. The widget has no special backend requirements and connects to any backend platform that supports REST API. :::info -By default, the widget comes with the built-in [**Go**](https://github.com/web-widgets/todo-go) and [**Node**](https://github.com/web-widgets/todo-node) backend. But you can use your custom server scripts as well. +By default, the widget comes with the built-in [**Go**](https://github.com/web-widgets/todo-go) and [**Node**](https://github.com/web-widgets/todo-node) backend. You can also use custom server scripts. ::: + ## RestDataProvider -The To Do List has the **RestDataProvider** service that completely supports REST API for dealing with the backend. It allows interacting with the server and perform the following data operations: - -- **"add-task"** -- **"update-task"** -- **"delete-task"** -- **"add-project"** -- **"update-project"** -- **"delete-project"** -- **"set-project"** -- **"move-task"** -- **"clone-task"** +The `RestDataProvider` service fully supports REST API for backend communication and handles the following data operations: + +- `"add-task"` +- `"update-task"` +- `"delete-task"` +- `"add-project"` +- `"update-project"` +- `"delete-project"` +- `"set-project"` +- `"move-task"` +- `"clone-task"` + ## REST methods -The **RestDataProvider** service includes the special REST methods for dynamic data loading: +The `RestDataProvider` service provides the following REST methods for dynamic data loading: -- [`getProjects()`](/api/rest_api/methods/getprojects_method/) - gets a promise with the **projects data** -- [`getProjectTasks()`](/api/rest_api/methods/getprojecttasks_method/) - gets a promise with the **tasks data** of the specified **project** -- [`getTags()`](/api/rest_api/methods/gettags_method/) - gets a promise with a list of **default tags** -- [`getTasks()`](/api/rest_api/methods/gettasks_method/) - gets a promise with the **tasks data** -- [`getUsers()`](/api/rest_api/methods/getusers_method/) - gets a promise with the **users data** -- [`setAPI()`](/api/rest_api/methods/setapi_method/) - sets API of the To Do List component into RestDataProvider -- [`send()`](/api/rest_api/methods/send_method/) - sends a necessary request to the server and gets a promise with or without data depending on the request +- [`getProjects()`](/api/rest_api/methods/getprojects_method/) — get projects data +- [`getProjectTasks()`](/api/rest_api/methods/getprojecttasks_method/) — get tasks data for a specified project +- [`getTags()`](/api/rest_api/methods/gettags_method/) — get a list of default tags +- [`getTasks()`](/api/rest_api/methods/gettasks_method/) — get tasks data +- [`getUsers()`](/api/rest_api/methods/getusers_method/) — get users data +- [`setAPI()`](/api/rest_api/methods/setapi_method/) — set the To Do List API in RestDataProvider +- [`send()`](/api/rest_api/methods/send_method/) — send a request to the server and get a promise with or without data -## Interacting with backend +## Connect to a backend -To interact with the server, you need to connect **RestDataProvider** to the corresponding server scripts. If you want to use the built-in backend, you can find the needed scripts in the following repositories: +Connect `RestDataProvider` to the server scripts. To use the built-in backend, find the scripts in the following repositories: - [**Go**](https://github.com/web-widgets/todo-go) backend - [**Node**](https://github.com/web-widgets/todo-node) backend -or you can create a custom one. +You can also create a custom backend. :::tip -If you use custom backend, refer to the [**REST API routes**](/api/rest_api/routes/rest_routes_overview/) topic for more information! +To use a custom backend, see the [**REST API routes**](/api/rest_api/routes/rest_routes_overview/) topic for details. ::: -To connect **RestDataProvider** to the backend, you need to call the **new RestDataProvider()** constructor by passing the corresponding **URL** as a parameter. +Connect `RestDataProvider` to the backend with the `new RestDataProvider()` constructor, passing the server URL: ~~~js {4-5,23-24} const { ToDo, Toolbar, RestDataProvider } = todo; @@ -79,20 +82,20 @@ Promise.all([ ~~~ :::info -You need to include **RestDataProvider** into the **Event Bus** order via the [`api.setNext()`](/api/internal/setnext_method/) method to perform operations with data (*adding, deleting,* etc) and send the corresponding requests to the server +Include `RestDataProvider` in the Event Bus with the [`api.setNext()`](/api/internal/setnext_method/) method to perform data operations (adding, deleting, etc.) and send requests to the server. ::: ### Example -The snippet below shows you how to connect **RestDataProvider** to the backend and load server data dynamically: +The snippet below connects `RestDataProvider` to the backend and loads server data: ## Multiuser backend -Task management tools, such as our To Do List, are highly sought after by businesses of all sizes. Considering this, it is crucial to provide a seamless user experience for all users, regardless of the number. Our new feature allows multiple users to efficiently manage the same tasks on the list in real-time, without the need for page reloads. As a result, users can collaborate and stay up-to-date with one another's actions, enhancing productivity and overall user satisfaction. +To Do List supports real-time collaboration, letting multiple users manage the same tasks without page reloads. -To implement a multiuser backend, you need to get authorization on the server before the To Do List initialization. For this, you can create the `login()` function: +To implement a multiuser backend, authenticate with the server before To Do List initialization. Create a `login()` function to handle authentication: ~~~js {} const login = (url) => { @@ -109,7 +112,7 @@ const login = (url) => { } ~~~ -The `login()` function returns the server token that is crucial for all subsequent interactions with the server. The token is included in each request as the value of the **Remote-Token** header in the following way: +The `login()` function returns a server token used for all subsequent requests. Include the token in each request as the `Remote-Token` header value: ~~~js {} login(url).then(token => { @@ -119,7 +122,7 @@ login(url).then(token => { }); ~~~ -After the initialization, you need to add WebSocket aimed to listen for events from the server. It can be done in the following way: +After initialization, add a WebSocket listener to receive server events: ~~~js {14-16,18-24} Promise.all([ @@ -149,17 +152,17 @@ Promise.all([ }); ~~~ -After integrating the multiuser backend into your app, you can simplify collaboration between users and enable them to keep track of any changes via the UI in a real time. +With the multiuser backend in place, users can track each other's changes in the UI in real time. ### Example -The snippet below shows how to configure the multiuser backend to track changes of other users in a real time: +The snippet below configures the multiuser backend to track changes in real time: -## Customization of server events +## Customize server events -You can define your own logic for handling server events. For this purpose, you need to pass the **handlers** object to the `RemoteEvents.on(handlers)` method. The **handlers** object should have the following structure: +Define custom logic for server events by passing a `handlers` object to the `RemoteEvents.on(handlers)` method. The `handlers` object uses the following structure: ~~~js {} { @@ -168,14 +171,14 @@ You can define your own logic for handling server events. For this purpose, you } ~~~ -When any change occurs on the server, it returns the name of the modified element. These names can vary depending on the server logic. +When any change occurs, the server returns the name of the modified element. Names vary depending on the server logic. -The data updated on the client side will be placed in the **obj** argument of the `function(obj: any)` function. To specify an operation, there is a `type: string` field. It can take the following values: +Client-side data updates appear in the `obj` argument of the `function(obj: any)` function. Use the `type: string` field to specify the operation. The field accepts the following values: - For **tasks**: `"add-task"`, `"update-task"`, `"delete-task"`, `"move-task"`, `"clone-task"` - For **projects**: `"add-project"`, `"update-project"`, `"delete-project"`, `"move-project"`, `"clone-project"` -In the following code snippet you can see the implementation details: +The following code snippet implements custom server event handling: ~~~js {} const todoInstance = new todo.ToDo("#root", config); @@ -226,11 +229,11 @@ const remoteEvents = new todo.RemoteEvents(remoteEventsURL, token); remoteEvents.on(handlers); ~~~ -The `RestDataProvider.getIDResolver()` method returns a function that is necessary to synchronize client IDs with server IDs. When a new object (*task/project*) is created on the client side, the received object will have a temporary ID and its corresponding server ID in `RestDataProvider`. The `idResolver()` function allows synchronizing the client ID with the server ID. This function has the following format: `idResolver(id: TID, type: number)` +The `RestDataProvider.getIDResolver()` method returns a function that synchronizes client IDs with server IDs. When a new task or project is created on the client side, the object has a temporary ID with a corresponding server ID in `RestDataProvider`. Use `idResolver()` to synchronize client and server IDs. The function uses the following format: `idResolver(id: TID, type: number)`. -The `type` argument is the type of model that takes the following values: +The `type` argument accepts the following values: -- `TaskID` - 1 -- `ProjID` - 2 +- `TaskID` — 1 +- `ProjID` — 2 -To prevent the request from being sent to the server, you need to use the `skipProvider: true` flag when calling the `todoInstance.api.exec()` method. +To prevent sending a request to the server, set `skipProvider: true` when calling `todoInstance.api.exec()`.