From 111fddfdbd71466a3daebb689838a59615628996 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Tue, 21 Jan 2025 17:44:33 +0300 Subject: [PATCH 01/14] [add] guides on working with data collection --- .../api/datacollection_changeid_method.md | 2 +- .../api/datacollection_group_method.md | 2 +- docs/grid/usage.md | 4 +- docs/guides/datacollection/editing_data.md | 108 ++++++++++ docs/guides/datacollection/grouping_data.md | 184 ++++++++++++++++++ docs/guides/datacollection/loading_data.md | 75 +++++++ .../datacollection/saving_restoring_data.md | 79 ++++++++ .../datacollection/sorting_filtering_data.md | 103 ++++++++++ docs/guides/datacollection_guide.md | 30 +-- sidebars.js | 17 +- 10 files changed, 574 insertions(+), 30 deletions(-) create mode 100644 docs/guides/datacollection/editing_data.md create mode 100644 docs/guides/datacollection/grouping_data.md create mode 100644 docs/guides/datacollection/loading_data.md create mode 100644 docs/guides/datacollection/saving_restoring_data.md create mode 100644 docs/guides/datacollection/sorting_filtering_data.md diff --git a/docs/data_collection/api/datacollection_changeid_method.md b/docs/data_collection/api/datacollection_changeid_method.md index 2ab6f173..f3468f45 100644 --- a/docs/data_collection/api/datacollection_changeid_method.md +++ b/docs/data_collection/api/datacollection_changeid_method.md @@ -13,7 +13,7 @@ description: You can explore the changeId method of DataCollection in the docume @params: - `id: string | number` - the old id of an item - `newId: string | number` - optional, the new id; auto-generated if not set -- `silent: boolean` - true, to prevent changing the id; otherwise, false +- `silent: boolean` - optional, *true*, to prevent changing the id; otherwise, *false* @example: component.data.changeId("1", "22"); diff --git a/docs/data_collection/api/datacollection_group_method.md b/docs/data_collection/api/datacollection_group_method.md index ffd99064..f263ae58 100644 --- a/docs/data_collection/api/datacollection_group_method.md +++ b/docs/data_collection/api/datacollection_group_method.md @@ -45,7 +45,7 @@ group(order: TGroupOrder[], config?: IGroupConfig): void; - an `IGroupOrder` object that has the following properties: - `by` - the field name or a function for user-defined grouping - `map` - (optional) an object for data aggregation in a group, where the keys are field names, and the values can be: - - a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the `dhx.methods` helper + - a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the [`dhx.methods`](helpers/data_calculation_functions.md) helper - a user-defined aggregation function `(i: IDataItem[]) => string | number` - `summary` - (optional) specifies where the total row is rendered - at the `top` or at the `bottom` of the group - `config` - (optional) the configuration of data grouping diff --git a/docs/grid/usage.md b/docs/grid/usage.md index 270b10e3..c3f23d6c 100644 --- a/docs/grid/usage.md +++ b/docs/grid/usage.md @@ -263,7 +263,7 @@ grid.removeSpan("10", "a"); ### Filtering data -You can filter grid data by the specified criteria with the help of the `filter()` method of [DataCollection](data_collection.md). The method takes as a parameter an object with the properties described below: +You can filter grid data by the specified criteria with the help of the `filter()` method of [DataCollection](data_collection.md). The method takes two parameters: @@ -969,7 +969,7 @@ The method takes the following parameters: - an `IGroupOrder` object that has the following properties: - `by` - the field name or a function for user-defined grouping - `map` - (optional) an object for data aggregation in a group, where the keys are field names, and the values can be: - - a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the `dhx.methods` helper + - a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the [`dhx.methods`](helpers/data_calculation_functions.md) helper - a user-defined aggregation function `(i: IDataItem[]) => string | number` - `summary` - (optional) specifies where the total row is rendered - at the `top` or at the `bottom` of the group - `config` - (optional) the configuration of data grouping diff --git a/docs/guides/datacollection/editing_data.md b/docs/guides/datacollection/editing_data.md new file mode 100644 index 00000000..93b3a0a5 --- /dev/null +++ b/docs/guides/datacollection/editing_data.md @@ -0,0 +1,108 @@ +--- +sidebar_label: Editing data +title: JavaScript Guides - Editing data +description: You can learn how to edit data with DataCollection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Editing data + +You can edit the data items of a component via DataCollection API. It allows adding new items, removing particular items or all items at once, updating the necessary configuration options of the item, creating a copy of an item at the defined position, changing the id of an item. + +## Adding items + +To add new items into a component, use the [`add()`](data_collection/api/datacollection_add_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: + +- `new_item: object | array` - the object of a new item or an array of item objects +- `index: number` - optional, the index of the position starting from which new items will be added + +and returns either the item's id or an array with the ids of items. + +~~~jsx +// adding a new item into the beginning of a data collection +component.data.add({"value": 57.44787660011765, "id": "u1565340894584"},0); + +// adding an array of new items into a data collection +component.data.add([ + { + "value": 57.44787660011765, + "id": "u1565340894584" + }, + { + "value": 14.612810637958095, + "id": "u1565340894585" + }, + { + "value": 83.9707181117741, + "id": "u1565340894586" + }, + { + "value": 59.01285878162044, + "id": "u1565340894587" + } +]); +~~~ + +**Related sample**: [Data. Add](https://snippet.dhtmlx.com/ktd8ks0m) + +## Removing items + +To delete the specified item from the component, use the [`remove()`](data_collection/api/datacollection_remove_method.md) method. The method takes the following parameter: + +- `id: string | string[]` - the ids of the items that should be deleted + +~~~jsx +component.data.remove("2"); +//or +component.data.remove(["2", "4"]); +~~~ + +**Related sample**: [Data. Remove](https://snippet.dhtmlx.com/ugdlqgp5) + +To delete all items from the component, use the [`removeAll()`](data_collection/api/datacollection_removeall_method.md) method. + +~~~jsx +component.data.removeAll(); +~~~ + +**Related sample**: [Data. Remove all](https://snippet.dhtmlx.com/ykk2ne82) + +## Updating items + +You can update the properties of the item with the help of the [`update()`](data_collection/api/datacollection_update_method.md) method. The method takes two parameters: + +- `id: string | number` - the id of the item which needs to be updated +- `newItem: object` - a hash of properties which need to be updated + +~~~jsx +component.data.update(123, { text:"New text" }); +~~~ + +**Related sample**: [Data. Update](https://snippet.dhtmlx.com/4g90gi6b) + +## Copying items + +The [`copy()`](data_collection/api/datacollection_copy_method.md) method will help you to create a copy of an item at the defined position. The method takes the following parameters: + +- `id: (string | number) | (string | number)[]` - the id of an item or an array with ids of items to copy +- `index: number` - the index to create a copy at +- `target: object` - optional, the target data collection object + +and returns the item's id or an array with ids of items. + +~~~jsx +component.data.copy("4",5); // copies the item with id:4 to the position with index 5 +~~~ + +**Related sample**: [Data. Copy](https://snippet.dhtmlx.com/9rws8r05) + +## Changing the id of an item + +You can change the id of the necessary element of a data collection, using the [`changeId()`](data_collection/api/datacollection_changeid_method.md) method. The method takes the following parameters: + +- `id: string | number` - the old id of an item +- `newId: string | number` - optional, the new id; auto-generated if not set +- `silent: boolean` - optional, *true* to prevent changing the id; otherwise, *false* + +~~~jsx +component.data.changeId("1", "22"); +~~~ \ No newline at end of file diff --git a/docs/guides/datacollection/grouping_data.md b/docs/guides/datacollection/grouping_data.md new file mode 100644 index 00000000..6e6f907a --- /dev/null +++ b/docs/guides/datacollection/grouping_data.md @@ -0,0 +1,184 @@ +--- +sidebar_label: Grouping data +title: JavaScript Guides - Grouping data +description: You can learn how to group data with DataCollection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Grouping data + +You can group the data of a component, ungroup data and check whether data in a collection is grouped via the DataCollection API. + +:::info important +Data grouping isn't intended for working with [`lazyDataProxy`](helpers.md/lazydataproxy/) +::: + +:::note +Grouped data can be serialized. After serialization data is available for rendering and editing as a plain tree-like structure +::: + +The DataCollection API can be used for working with [data grouping in Grid](grid/usage.md/#grouping-data). + +## Enabling data grouping + +To use the [row data grouping functionality](grid/usage.md/#grouping-data) in Grid, you need to apply the [`group`](grid/api/grid_group_config.md) configuration property of Grid. You can set the `group` property to *true* to enable grouping, or to specify it as a configuration object to [configure data grouping ](grid/usage.md/#configuring-data-grouping). + +~~~jsx {5} +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + group: true, // enabling grouping in a grid + groupable: true + data: dataset +}); +~~~ + +You can also specify what Grid data will be used for grouping using the `groupable` properties of Grid and of a column. + +The [`groupable`](grid/api/grid_groupable_config.md) **property of Grid** enables grouping data by the values in all columns: + +~~~jsx {6} +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + group: true, + groupable: true // allowing grouping row data by the values of all columns + data: dataset +}); +~~~ + +:::note +The `groupable` property works only with the [`group`](grid/api/grid_group_config.md) panel. +::: + +**Related sample:** [Grid. Grouping](https://snippet.dhtmlx.com/dvqy4ewe) + +The [`groupable`](grid/api/api_gridcolumn_properties.md) **property of a column** allows grouping data by the values of a certain column: + +~~~jsx {3} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "country", header: [{ text: "Country" }], groupable: true }, + { id: "population", header: [{ text: "Population" }] }, + { id: "area", header: [{ text: "Land Area (Km²)" }] } + ], + group: true, + data: dataset +}); +~~~ + +In the above snippet rows will be grouped by the "country" column values, as the `groupable: true` property is specified in its configuration. + +## Grouping data + +The [`group()`](data_collection/api/datacollection_group_method.md) method groups data in a collection that has a plain tree-like structure according to the specified order and additional configuration. The method takes the following parameters: + +- `order` - an array that defines the order and configuration for data grouping. Each element in the array can be: + - a string that represents a grouping field + - a function `(i: IDataItem) => string` for dynamic defining of a group + - an `IGroupOrder` object that has the following properties: + - `by` - the field name or a function for user-defined grouping + - `map` - (optional) an object for data aggregation in a group, where the keys are field names, and the values can be: + - a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the [`dhx.methods`](helpers/data_calculation_functions.md) helper + - a user-defined aggregation function `(i: IDataItem[]) => string | number` + - `summary` - (optional) specifies where the total row is rendered - at the `top` or at the `bottom` of the group +- `config` - (optional) the configuration of data grouping + - `showMissed` - (optional) specifies whether the elements that don't have the field for grouping should be displayed, *true* by default + - if set to *true*, the rows that don't have values for grouping are rendered row by row after all the data + - if a *string* value is set, e.g. "Missed", the rows that don't have values for grouping are rendered as a separate group the name of which will have the specified string value. This group will be rendered as the last one + - if set to *false*, the rows that don't suit the grouping criteria won't be rendered + - `field` - (optional) the group field name, *"group"* by default + +There are several examples of grouping Grid data via the `group()` method of DataCollection: + +- simple grouping with the use of a callback function and a string field value + +~~~jsx {12-19} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "salary", header: [{ text: "Salary" }] }, + { id: "experience", header: [{ text: "Experience (years)" }] }, + { id: "city", header: [{ text: "City" }] } + ], + group: true, + groupable: true, + data: dataset +}); + +grid.data.group([ + function(row) { + if (row.salary < 30000) return "Low income"; + if (row.salary >= 30000 && row.salary < 70000) return "Medium income"; + return "High income"; + }, + "city" +]); +~~~ + +- grouping with the use of a configuration object and aggregation settings + +~~~jsx {12-23} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "department", header: [{ text: "Department" }] }, + { id: "employees", header: [{ text: "Number of Employees" }] }, + { id: "location", header: [{ text: "Location" }] } + ], + group: true, + groupable: true, + data: dataset +}); + +grid.data.group([{ + by: "department", // grouping by the `department` field + map: { + employees: ["employees", "sum"], // aggregation: sums up the number of employees + location: (rows) => { + // a custom function for calculating unique locations + const uniqueLocations = [...new Set(rows.map(r => r.location))]; + return uniqueLocations.join(", "); + } + }, + summary: "top" // the total row is rendered at the top of the group +}]); +~~~ + +- grouping with the use of the `showMissed` property + +~~~jsx {12-16} +const grid = new dhx.Grid("grid_container", { + columns: [ + { id: "name", header: [{ text: "Name" }] }, + { id: "age", header: [{ text: "Age" }] }, + { id: "city", header: [{ text: "City" }] } + ], + group: true, + groupable: true, + data: dataset +}); + +grid.data.group(["city"], { + // the group elements that don't have the "city" value + // will be rendered in the "Unknown City" group + showMissed: "Unknown City" +}); +~~~ + +## Ungrouping data + +To ungroup the data of a component, use the [`ungroup()`](data_collection/api/datacollection_ungroup_method.md) method of DataCollection. + +~~~jsx +grid.data.ungroup(); +~~~ + +## Checking whether data is grouped + +To check whether the data of a component is grouped at the moment, use the [`isGrouped()`](data_collection/api/datacollection_isgrouped_method.md) method of DataCollection. The method returns *true* if the data in a collection is grouped at the moment and *false* if it isn't grouped. + +~~~jsx +if (component.data.isGrouped()) { + console.log("The data is currently grouped"); +} +~~~ \ No newline at end of file diff --git a/docs/guides/datacollection/loading_data.md b/docs/guides/datacollection/loading_data.md new file mode 100644 index 00000000..8bdf520f --- /dev/null +++ b/docs/guides/datacollection/loading_data.md @@ -0,0 +1,75 @@ +--- +sidebar_label: Loading data +title: JavaScript Guides - Loading data +description: You can learn how to load data with DataCollection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Loading data + +You can load data into a component from an external file or from a local data source via the DataCollection API. + +:::info +Please note that if you specify the `id` fields in the loaded data collection, their values should be **unique**. You can also omit the `id` fields in the data collection. In this case they will be generated automatically. +::: + +## Loading data from an external file + +To load data into a component from an external file, make use of the [load()](data_collection/api/datacollection_load_method.md) method of [DataCollection](data_collection.md). It takes as parameters the URL of the file with data and, optionally, DataDriver or the type of data ("json" (default), "csv", "xml"). For example: + +~~~jsx +component.data.load("../common/data.xml", "xml"); +~~~ + +**Related sample**: [Data. Load](https://snippet.dhtmlx.com/dyykcnxi) + +The component will make an AJAX call and expect the remote URL to provide valid JSON data. + +Data loading is asynchronous, so you need to wrap any after-loading code into a promise: + +~~~jsx +component.data.load(url).then(function(){ + // do something after load +}); +~~~ + +or + +~~~jsx +component.data.load(url); +component.data.loadData.then(function(){ + // do something after load +}); +// loadData executes a callback function after an asynchronous +// data loading has completed +~~~ + +## Loading data from a local data source + +To load data into a component from a local data source, use the [parse()](data_collection/api/datacollection_parse_method.md) method of [DataCollection](data_collection.md). The method takes as parameters a predefined data set and, optionally, DataDriver or the type of data ("json" (default), "csv", "xml"). For example: + +~~~jsx +const dataset = [ + { + "value": "Ben", + "short": "Ben is a very cautious 5-year-old Siberian Husky.", + "thumbnailName": "01.jpg" + }, + { + "value": "Izzy", + "short": "This is our most beloved kingfisher bird Izzy.", + "thumbnailName": "02.jpg" + }, + { + "value": "Momo", + "short": "Momo is a 25-year-old elephant with a big heart.", + "thumbnailName": "03.jpg" + } +] + +const dataview = new dhx.DataView("dataview_container"); + +// loads data into the dataview from the JSON array +dataview.data.parse(dataset); +~~~ + +**Related sample**: [Data. Parse](https://snippet.dhtmlx.com/0zrxtmvi) \ No newline at end of file diff --git a/docs/guides/datacollection/saving_restoring_data.md b/docs/guides/datacollection/saving_restoring_data.md new file mode 100644 index 00000000..f86ca2f3 --- /dev/null +++ b/docs/guides/datacollection/saving_restoring_data.md @@ -0,0 +1,79 @@ +--- +sidebar_label: Saving and restoring data +title: JavaScript Guides - Saving and restoring data +description: You can learn how to save and restore data with DataCollection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Saving and restoring data + +You can use the DataCollection API to save the state of a component and send it to a different component or to the server. + +## Saving the state of a component + +To save the current state of a component, use the [`serialize()`](data_collection/api/datacollection_serialize_method.md) method of Data Collection. The method is used to serialize data into the JSON, XML or CSV format. It takes the following parameter: + +- `driver: string` - optional, the format that the data will be serialized into ("json" (default), "csv", "xml") + +and returns serialized data for each item of the component either as an array of JSON objects or as a CSV/XML string. + +For example: + +~~~jsx +const state = grid1.data.serialize(); +~~~ + +**Related sample**: [Data. Serialize](https://snippet.dhtmlx.com/7c35n4uf) + +## Restoring the state of a component + +### Sending saved data to a new component + +After you've saved a component's state, you can send the data stored in the saved state to a new component using the [`parse()`](data_collection/api/datacollection_parse_method.md) method of Data Collection: + +~~~jsx +// creating a new grid +const grid2 = new dhx.Grid(document.body); +// parsing the state of grid1 into grid2 +grid2.data.parse(state); +~~~ + +### Saving data changes to the server side + +You can also save changes made in the data to the server side using the [`save()`](data_collection/api/datacollection_save_method.md) method of Data Collection. The method takes the following parameter: + +- `url: string | IDataProxy` - the URL of a server side or DataProxy with the URL configured + +For example: + +~~~jsx +grid.data.save("http://userurl/"); + +//or +grid.data.save(new DataProxy({url:"http://userurl/"})); +~~~ + +Each time the user changes data of the component, the `save()` method will make an AJAX call and expect the remote URL to save data changes. The method will send one of the following requests to the back-end: + +- `POST` - after adding new data into the component +- `PUT` - after editing data of the component +- `DELETE` - after deleting data + +Data saving is asynchronous, so you need to return a promise - the result of the saving operation. To do this, use the `saveData` property that returns a "promise" object: + +~~~jsx +const data = new DataCollection(); +data.save(loader); +return data.saveData.then(function(){ + // now your data is saved +}); +~~~ + +Use the [`isSaved()`](data_collection/api/datacollection_issaved_method.md) method to check whether the changes are saved. The method returns *true*, if the changes are saved, otherwise, *false*. + +~~~jsx +grid.data.saveData.then(function(){ + console.log(grid.data.isSaved()); +}); +~~~ + + diff --git a/docs/guides/datacollection/sorting_filtering_data.md b/docs/guides/datacollection/sorting_filtering_data.md new file mode 100644 index 00000000..437dc480 --- /dev/null +++ b/docs/guides/datacollection/sorting_filtering_data.md @@ -0,0 +1,103 @@ +--- +sidebar_label: Sorting and filtering data +title: JavaScript Guides - Sorting and filtering data +description: You can learn how to sort and filter data with DataCollection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Sorting and filtering data + +When working with data you may need to sort or filter it. You can sort or filter the data of a component via the DataCollection API. + +## Sorting data + +To sort data items in a component, use the [`sort()`](data_collection/api/datacollection_sort_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: + +- `rule: object` - an object with parameters for sorting. The object has the following attributes: + - `by: string | number` - the id of a data field (a column of Grid) + - `dir: string` - the direction of sorting: "asc" or "desc" + - `as: function` - a function that specifies the type to sort data as + - `rule: function` - optional, a sorting rule; the function must have two parameters and return a number (-1,0,1) +- `config: object` - defines the parameter of sorting. It may contain one property: + - `smartSorting: boolean` - specifies whether a sorting rule should be applied each time after changing the data set + +~~~jsx +grid.data.sort({ + by:"a", + dir:"desc", + as: function(item){ + return item.toUpperCase(); + }, + { + smartSorting: true + } +}); + +// cancels the applied sorting rules +grid.data.sort(); +~~~ + +**Related sample**: [Data. Sorting](https://snippet.dhtmlx.com/lz351u47) + +:::note +Calling the method without parameters will discard all the applied sorting rules. +::: + +### Custom sorting + +To set a custom function for sorting, you need to specify the `rule` attribute in a passed object. For example: + +~~~jsx +grid.data.sort({ + rule: (a, b) => a.id > b.id ? 1 : (a.id < b.id ? -1 : 0) +}); +~~~ + +## Filtering data + +To filter data items in a component, use the [`filter()`](data_collection/api/datacollection_filter_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: + +- `rule: function | object` - the filtering criteria + - If set as a *function*, filtering will be applied by the rule specified in the function. The function takes an object of a data item as a parameter and returns *true/false* + - If set as an *object*, the parameter has the following attributes: + - `by: string | number` - mandatory, the id of a data field (the column of Grid) + - `match: string` - mandatory, a pattern to match + - `compare: function` - optional, a function for extended filtering that takes three parameters: + - `value` - the value to compare (e.g. a column in a row for Grid) + - `match` - a pattern to match + - `item` - a data item the values of which should be compared (e.g. a row) +- `config: object` - optional, defines the parameters of filtering. It may contain the following properties: + - `id: string` - optional, the id of the filter + - `add: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (true), or to the initial data (false, default) + - `permanent: boolean` - optional, *true* to make the current filter permanent. It will be applied even if the next filtering doesn't have the `add:true` property in its configuration object. Such a filter can be removed just with the [resetFilter()](data_collection/api/datacollection_resetfilter_method.md) method + +The `filter()` method returns the id of the filter. + +~~~jsx +// filtering data by a function +grid.data.filter(function (item) { + return item.a > 0 && item.b !== "Apple"; +}); + +// or +grid.data.filter(function (item) { + return item.a > 0 && item.b !== "Apple"; +}, { + add: true, +}); + +// filtering data by the column +grid.data.filter({ + by: "a", + match: "Orange", + compare: function (value, match, item) { + if (item.a !== "Some") { + return val === "New"; + } + return false; + } +}, { + add: true, +}); +~~~ + +**Related sample**: [Data. Filter](https://snippet.dhtmlx.com/csiwq3kj) diff --git a/docs/guides/datacollection_guide.md b/docs/guides/datacollection_guide.md index 61bc5138..3da0605f 100644 --- a/docs/guides/datacollection_guide.md +++ b/docs/guides/datacollection_guide.md @@ -42,31 +42,11 @@ where: The methods of DataCollection are useful for: -- Loading data -- Sorting and filtering data -- Editing data -- Saving and restoring -- Grouping data - -#### Loading data - -To load data into the component use the `load()` or `parse()` methods. The `load()` method is used to load data from an external file, the `parse()` method is used to load data from a local data source. - -#### Sorting and filtering data - -When working with data you may need to sort or filter it. Use the `sort()` method and the `filter()` one for this purpose. - -#### Editing data - -You can add new items into the initialized component via the `add()` method, remove particular items by the `remove()` method or remove all items at once via the `removeAll()` method. The `update()` method allows you to update the necessary configuration options of the item by its id while the `changeId()` method lets you change the id of the element. - -#### Saving and restoring - -The `serialize()` method is used to serialize data into JSON, XML or CSV format. You can send the serialized data to a new component or server. The `copy()` method will help you to create a copy of an item at the defined position. Use the `save()` method to save changes made in the data to the server side. - -#### Grouping data - -You can group the data of a component using the `group()` method and remove data groups via the `ungroup()` method. The `isGrouped()` method allows you to check whether a data collection is grouped. +- [Loading data](guides/datacollection/loading_data.md) +- [Sorting and filtering data](guides/datacollection/sorting_filtering_data.md) +- [Editing data](guides/datacollection/editing_data.md) +- [Saving and restoring data](guides/datacollection/saving_restoring_data.md) +- [Grouping data](guides/datacollection/grouping_data.md) Check all the [methods](data_collection.md/#methods) of DataCollection. diff --git a/sidebars.js b/sidebars.js index bb1439de..3b3c512d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -4913,7 +4913,22 @@ module.exports = { }, items: [ "guides/events_guide", - "guides/datacollection_guide", + { + type: "category", + label: "How to work with DataCollection", + link: { + type: 'doc', + id:"guides/datacollection_guide" + }, + items: [ + "guides/datacollection/loading_data", + "guides/datacollection/sorting_filtering_data", + "guides/datacollection/editing_data", + "guides/datacollection/saving_restoring_data", + "guides/datacollection/grouping_data", + ], + }, + //"guides/datacollection_guide", ], }, // end Guides From 7fd6f3c1aba0a5b58ee4a2927e822862d98167cb Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Fri, 31 Jan 2025 16:45:58 +0300 Subject: [PATCH 02/14] [update] guides on working with data collection --- .../api/datacollection_filter_method.md | 2 +- .../api/datacollection_find_method.md | 2 +- .../api/datacollection_getfilters_method.md | 4 +- .../api/datacollection_getitem_method.md | 2 +- .../api/datacollection_getlength_method.md | 2 +- .../api/datacollection_isdataloaded_method.md | 4 +- .../api/datacollection_map_method.md | 4 +- .../api/datacollection_maprange_method.md | 2 +- .../api/datacollection_reduce_method.md | 2 +- .../api/datacollection_resetfilter_method.md | 4 +- docs/grid/data_loading.md | 4 +- docs/grid/treegrid_mode.md | 4 +- docs/guides/datacollection/editing_data.md | 11 - docs/guides/datacollection/grouping_data.md | 4 + docs/guides/datacollection/loading_data.md | 23 +- .../datacollection/sorting_filtering_data.md | 39 +++- .../datacollection/working_with_data_items.md | 216 ++++++++++++++++++ docs/guides/datacollection_guide.md | 5 +- sidebars.js | 1 + 19 files changed, 302 insertions(+), 33 deletions(-) create mode 100644 docs/guides/datacollection/working_with_data_items.md diff --git a/docs/data_collection/api/datacollection_filter_method.md b/docs/data_collection/api/datacollection_filter_method.md index 6e4b2afb..88796c5b 100644 --- a/docs/data_collection/api/datacollection_filter_method.md +++ b/docs/data_collection/api/datacollection_filter_method.md @@ -22,7 +22,7 @@ description: You can explore the filter method of DataCollection in the document - `item` - a data item the values of which should be compared (e.g. a row) - `config: object` - optional, defines the parameters of filtering. It may contain the following properties: - `id: string` - optional, the id of the filter - - `add: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (true), or to the initial data (false, default) + - `add: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (*true*), or to the initial data (*false*, default) - `permanent: boolean` - optional, *true* to make the current filter permanent. It will be applied even if the next filtering doesn't have the `add:true` property in its configuration object. Such a filter can be removed just with the [resetFilter()](data_collection/api/datacollection_resetfilter_method.md) method @returns: diff --git a/docs/data_collection/api/datacollection_find_method.md b/docs/data_collection/api/datacollection_find_method.md index abd7c741..bb404f1f 100644 --- a/docs/data_collection/api/datacollection_find_method.md +++ b/docs/data_collection/api/datacollection_find_method.md @@ -21,7 +21,7 @@ description: You can explore the find method of DataCollection in the documentat - `array` - (optional) an array with items @returns: -An object of the matching item. +The object of the matching item. @example: //searching for an item by the function diff --git a/docs/data_collection/api/datacollection_getfilters_method.md b/docs/data_collection/api/datacollection_getfilters_method.md index b5b22f8d..3d7d598d 100644 --- a/docs/data_collection/api/datacollection_getfilters_method.md +++ b/docs/data_collection/api/datacollection_getfilters_method.md @@ -12,10 +12,10 @@ description: You can explore the getFilters method of DataCollection in the docu @params: -- `permanent: boolean` - optional, false by default. Allows getting the list of permanent filters +- `permanent: boolean` - optional, *false* by default. Allows getting the list of permanent filters @returns: -- `filters: object` - an object with the applied filters, where the key is the id of a filter and the value is an object with the [**rule** and **config** properties](data_collection/api/datacollection_filter_method.md) +- `filters: object` - an object with the applied filters, where the key is the id of a filter and the value is an object with the [`rule` and `config` properties](data_collection/api/datacollection_filter_method.md) @example: const filters = grid.data.getFilters(); diff --git a/docs/data_collection/api/datacollection_getitem_method.md b/docs/data_collection/api/datacollection_getitem_method.md index 2ae9b158..abaa217c 100644 --- a/docs/data_collection/api/datacollection_getitem_method.md +++ b/docs/data_collection/api/datacollection_getitem_method.md @@ -26,7 +26,7 @@ const item = component.data.getItem(123); You can access the original properties of an item like this: -~~~js +~~~jsx const item = component.data.getItem(123); const text = item.text; ~~~ diff --git a/docs/data_collection/api/datacollection_getlength_method.md b/docs/data_collection/api/datacollection_getlength_method.md index 68ab517d..b0f3d3f2 100644 --- a/docs/data_collection/api/datacollection_getlength_method.md +++ b/docs/data_collection/api/datacollection_getlength_method.md @@ -14,7 +14,7 @@ description: You can explore the getLength method of DataCollection in the docum The number of elements of a data collection. @example: -component.data.getLength(); +const items = component.data.getLength(); @descr: diff --git a/docs/data_collection/api/datacollection_isdataloaded_method.md b/docs/data_collection/api/datacollection_isdataloaded_method.md index 813d5da4..96fce0a3 100644 --- a/docs/data_collection/api/datacollection_isdataloaded_method.md +++ b/docs/data_collection/api/datacollection_isdataloaded_method.md @@ -6,7 +6,9 @@ description: You can explore the isDataLoaded method of DataCollection in the do # isDataLoaded() -{{pronote This functionality is available in the PRO edition only.}} +:::tip pro version only +This functionality is available in the PRO edition only. +::: @short: checks whether the specified data range is loaded from the server diff --git a/docs/data_collection/api/datacollection_map_method.md b/docs/data_collection/api/datacollection_map_method.md index c835e789..c964845e 100644 --- a/docs/data_collection/api/datacollection_map_method.md +++ b/docs/data_collection/api/datacollection_map_method.md @@ -6,7 +6,7 @@ description: You can explore the map method of DataCollection in the documentati # map() -@short: iterates through all items of the component +@short: iterates through all the items of the component @signature: {'map(callback: function): object[];'} @@ -17,7 +17,7 @@ description: You can explore the map method of DataCollection in the documentati A new array of items where each item is the result of the callback function. @example: -//getting ids of all items of the component +// getting the ids of all the items of the component component.data.map(function(item){ return item; }); diff --git a/docs/data_collection/api/datacollection_maprange_method.md b/docs/data_collection/api/datacollection_maprange_method.md index 3e9f38df..9ea9f7cf 100644 --- a/docs/data_collection/api/datacollection_maprange_method.md +++ b/docs/data_collection/api/datacollection_maprange_method.md @@ -6,7 +6,7 @@ description: You can explore the mapRange method of DataCollection in the docume # mapRange() -@short: returns a new array of the items correspond to the specified parameters +@short: returns a new array of the items corresponding to the specified parameters @signature: {'mapRange(from: number, to: number, callback: function): object[];'} diff --git a/docs/data_collection/api/datacollection_reduce_method.md b/docs/data_collection/api/datacollection_reduce_method.md index 5e3c39ef..6ea42a1f 100644 --- a/docs/data_collection/api/datacollection_reduce_method.md +++ b/docs/data_collection/api/datacollection_reduce_method.md @@ -13,7 +13,7 @@ description: You can explore the reduce method of DataCollection in the document @params: - `callback: function` - a function that will be called for each item in the array. The function takes two parameters: - - `acc` - the initialValue, or the previously returned value of the function + - `acc` - the *initialValue*, or the previously returned value of the function - `item` - the current item of a data collection - `acc: any` - a value to be passed to the function as the initial value diff --git a/docs/data_collection/api/datacollection_resetfilter_method.md b/docs/data_collection/api/datacollection_resetfilter_method.md index 4a55a9da..ea933eb9 100644 --- a/docs/data_collection/api/datacollection_resetfilter_method.md +++ b/docs/data_collection/api/datacollection_resetfilter_method.md @@ -11,9 +11,9 @@ description: You can explore the resetFilter method of DataCollection in the doc @signature: {'resetFilter(config?: object): boolean;'} @params: -- `config: object` - optional, specifies the parameters of resetting the active filters. If the config isn't specified or it is empty, all the filters except for those that have the **permanent** property in the configuration object will be reset. Can contain the following properties: +- `config: object` - optional, specifies the parameters of resetting the active filters. If the config isn't specified or it is empty, all the filters except for those that have the `permanent` property in the configuration object will be reset. Can contain the following properties: - `id: string` - optional, the id of the filter to reset - - `permanent: boolean` - optional, *true* to reset all the active filters, including those that have the **permanent:true** property in their config + - `permanent: boolean` - optional, *true* to reset all the active filters, including those that have the `permanent:true` property in their config @returns: - `result: boolean` - *true*, if all the filters, including the permanent ones, have been reset; otherwise *false* diff --git a/docs/grid/data_loading.md b/docs/grid/data_loading.md index de7e5717..1b69dec4 100644 --- a/docs/grid/data_loading.md +++ b/docs/grid/data_loading.md @@ -166,7 +166,9 @@ grid2.data.parse(state); ## Dynamic loading -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: To enable dynamic data loading in Grid you need to: diff --git a/docs/grid/treegrid_mode.md b/docs/grid/treegrid_mode.md index 57c44067..14464a9e 100644 --- a/docs/grid/treegrid_mode.md +++ b/docs/grid/treegrid_mode.md @@ -6,9 +6,9 @@ description: You can explore how to work with Grid in the documentation of the D # TreeGrid mode -{{pronote +:::tip pro version only The TreeGrid mode of the Grid component is available in the **PRO** version only. -}} +::: TreeGrid mode of the Grid component allows showing the nested tabular data. diff --git a/docs/guides/datacollection/editing_data.md b/docs/guides/datacollection/editing_data.md index 93b3a0a5..537d0734 100644 --- a/docs/guides/datacollection/editing_data.md +++ b/docs/guides/datacollection/editing_data.md @@ -95,14 +95,3 @@ component.data.copy("4",5); // copies the item with id:4 to the position with in **Related sample**: [Data. Copy](https://snippet.dhtmlx.com/9rws8r05) -## Changing the id of an item - -You can change the id of the necessary element of a data collection, using the [`changeId()`](data_collection/api/datacollection_changeid_method.md) method. The method takes the following parameters: - -- `id: string | number` - the old id of an item -- `newId: string | number` - optional, the new id; auto-generated if not set -- `silent: boolean` - optional, *true* to prevent changing the id; otherwise, *false* - -~~~jsx -component.data.changeId("1", "22"); -~~~ \ No newline at end of file diff --git a/docs/guides/datacollection/grouping_data.md b/docs/guides/datacollection/grouping_data.md index 6e6f907a..80ecf845 100644 --- a/docs/guides/datacollection/grouping_data.md +++ b/docs/guides/datacollection/grouping_data.md @@ -8,6 +8,10 @@ description: You can learn how to group data with DataCollection in the document You can group the data of a component, ungroup data and check whether data in a collection is grouped via the DataCollection API. +:::tip pro version only +The described functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + :::info important Data grouping isn't intended for working with [`lazyDataProxy`](helpers.md/lazydataproxy/) ::: diff --git a/docs/guides/datacollection/loading_data.md b/docs/guides/datacollection/loading_data.md index 8bdf520f..3ff0e553 100644 --- a/docs/guides/datacollection/loading_data.md +++ b/docs/guides/datacollection/loading_data.md @@ -14,7 +14,7 @@ Please note that if you specify the `id` fields in the loaded data collection, t ## Loading data from an external file -To load data into a component from an external file, make use of the [load()](data_collection/api/datacollection_load_method.md) method of [DataCollection](data_collection.md). It takes as parameters the URL of the file with data and, optionally, DataDriver or the type of data ("json" (default), "csv", "xml"). For example: +To load data into a component from an external file, make use of the [`load()`](data_collection/api/datacollection_load_method.md) method of [DataCollection](data_collection.md). It takes as parameters the URL of the file with data and, optionally, DataDriver or the type of data ("json" (default), "csv", "xml"). For example: ~~~jsx component.data.load("../common/data.xml", "xml"); @@ -45,7 +45,7 @@ component.data.loadData.then(function(){ ## Loading data from a local data source -To load data into a component from a local data source, use the [parse()](data_collection/api/datacollection_parse_method.md) method of [DataCollection](data_collection.md). The method takes as parameters a predefined data set and, optionally, DataDriver or the type of data ("json" (default), "csv", "xml"). For example: +To load data into a component from a local data source, use the [`parse()`](data_collection/api/datacollection_parse_method.md) method of [DataCollection](data_collection.md). The method takes as parameters a predefined data set and, optionally, DataDriver or the type of data ("json" (default), "csv", "xml"). For example: ~~~jsx const dataset = [ @@ -72,4 +72,21 @@ const dataview = new dhx.DataView("dataview_container"); dataview.data.parse(dataset); ~~~ -**Related sample**: [Data. Parse](https://snippet.dhtmlx.com/0zrxtmvi) \ No newline at end of file +**Related sample**: [Data. Parse](https://snippet.dhtmlx.com/0zrxtmvi) + +## Checking whether data is loaded + +:::tip pro version only +This functionality is available in the PRO edition only. +::: + +You can check whether the specified data range is loaded from the server using the [`isDataLoaded()`](data_collection/api/datacollection_isdataloaded_method.md) method of [DataCollection](data_collection.md). The method takes the following parameters: + +- `from: number` - optional, the index of the first element of the data range to be checked +- `to: number` - optional, the index of the last element of the data range to be checked + +and returns `true`, if a range of data is loaded; otherwise, `false`. + +~~~jsx +component.data.isDataLoaded(); +~~~ diff --git a/docs/guides/datacollection/sorting_filtering_data.md b/docs/guides/datacollection/sorting_filtering_data.md index 437dc480..24f5f8c2 100644 --- a/docs/guides/datacollection/sorting_filtering_data.md +++ b/docs/guides/datacollection/sorting_filtering_data.md @@ -67,7 +67,7 @@ To filter data items in a component, use the [`filter()`](data_collection/api/da - `item` - a data item the values of which should be compared (e.g. a row) - `config: object` - optional, defines the parameters of filtering. It may contain the following properties: - `id: string` - optional, the id of the filter - - `add: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (true), or to the initial data (false, default) + - `add: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (*true*), or to the initial data (*false*, default) - `permanent: boolean` - optional, *true* to make the current filter permanent. It will be applied even if the next filtering doesn't have the `add:true` property in its configuration object. Such a filter can be removed just with the [resetFilter()](data_collection/api/datacollection_resetfilter_method.md) method The `filter()` method returns the id of the filter. @@ -101,3 +101,40 @@ grid.data.filter({ ~~~ **Related sample**: [Data. Filter](https://snippet.dhtmlx.com/csiwq3kj) + +### Getting filters + +You can get filters applied to the data of a component using the [`getFilters()`](data_collection/api/datacollection_getfilters_method.md) method. The method takes the following parameter: + +- `permanent: boolean` - optional, *false* by default. Allows getting the list of permanent filters + +and returns an object with the applied filters, where the key is the id of a filter and the value is an object with the [`rule` and `config` properties](data_collection/api/datacollection_filter_method.md). + +~~~jsx +const filters = grid.data.getFilters(); +~~~ + +### Resetting filters + +You can reset a certain filter or all the active filters using the [`resetFilter()`](data_collection/api/datacollection_resetfilter_method.md) method. It takes the following parameter: + +- `config: object` - optional, specifies the parameters of resetting the active filters. If the config isn't specified or it is empty, all the filters except for those that have the `permanent` property in the configuration object will be reset. Can contain the following properties: + - `id: string` - optional, the id of the filter to reset + - `permanent: boolean` - optional, *true* to reset all the active filters, including those that have the `permanent:true` property in their config + +The method returns *true*, if all the filters, including the permanent ones, have been reset; otherwise *false*. + +~~~jsx +// resets all the filters, except for those that have the "permanent" property in the config +component.data.resetFilter(); + +// resets all the filters, including those that have the "permanent" property in the config +component.data.resetFilter({ permanent: true }); + +// resets the filter with the specified id +component.data.resetFilter({ id: "filter_id" }); +~~~ + +**Related samples**: +- [Data. ResetFilter](https://snippet.dhtmlx.com/jg8wxfvc) +- [Grid. ResetFilter](https://snippet.dhtmlx.com/15trblk2) diff --git a/docs/guides/datacollection/working_with_data_items.md b/docs/guides/datacollection/working_with_data_items.md new file mode 100644 index 00000000..5f526742 --- /dev/null +++ b/docs/guides/datacollection/working_with_data_items.md @@ -0,0 +1,216 @@ +--- +sidebar_label: Working with data items +title: JavaScript Guides - Working with data items +description: You can learn how to work with DataCollection items in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +--- + +# Working with data items + +Besides [basic editing API of DataCollection](guides/datacollection/editing_data.md) that allows adding, copying, updating and deleting data items, there is a set of more specific methods for manipulating data items. For example, you can check the existence of an item, find necessary items, iterate over items, get the id/index of an item or get an item object by its id, etc. + +## Checking existence of an item + +You can check whether the specified item exists in the component via the [`exists()`](data_collection/api/datacollection_exists_method.md) method of DataCollection. The method takes the following parameter: + +- `id: string | number` - the id of the item in question + +and returns *true*, if the item exists; otherwise, *false*. + +~~~jsx +const item = component.data.exists("1"); +~~~ + +**Related sample**: [Data. Exists](https://snippet.dhtmlx.com/2ekntrbk) + +## Changing the id of an item + +You can change the id of the necessary element of a data collection, using the [`changeId()`](data_collection/api/datacollection_changeid_method.md) method. The method takes the following parameters: + +- `id: string | number` - the old id of an item +- `newId: string | number` - optional, the new id; auto-generated if not set +- `silent: boolean` - optional, *true* to prevent changing the id; otherwise, *false* + +~~~jsx +component.data.changeId("1", "22"); +~~~ + +## Searching for certain data items + +You can find data items that match some criteria. The DataCollection API allows searching for a particular item or all the matching items. + +The [`find()`](data_collection/api/datacollection_find_method.md) method finds the item that corresponds to the specified rule. It takes the following parameter: + +- `rule: object | function` - the search criteria: + - if set as an *object*, the parameter contains the following attributes: + - `by: string | function` - the search criterion (either the key of the item attribute or a search function) + - `match: string` - the value of the item attribute + - if set as a *function*, the search will be applied by the rule specified in the function. The function may take three parameters: + - `item` - (required) the object of an item + - `index` - (optional) the index of an item + - `array` - (optional) an array with items + +The method returns the object of the matching item. + +~~~jsx +//searching for an item by the function +const item = component.data.find(function(item){ + if(item.text==="Manager"||item.text==="Marketer"){return true} +}); + +//searching for an item by the attribute key +const item = component.data.find({by:"text",match:"Manager"}); +~~~ + +**Related sample**: [Data. Find](https://snippet.dhtmlx.com/fpxhdc46) + +The [`findAll()`](data_collection/api/datacollection_findall_method.md) method finds all the items that correspond to the specified rule. It takes the following parameter: + +- `rule: object | function` - the search criteria: + - if set as an *object*, the parameter contains the following attributes: + - `by: string | function` - the search criterion (either the key of the item attribute or a search function) + - `match: string` - the value of the item attribute + - if set as a *function*, the search will be applied by the rule specified in the function. The function may take three parameters: + - `item` - (required) the object of an item + - `index` - (optional) the index of an item + - `array` - (optional) an array with items + +The method returns an array of matching item objects. + +~~~js +//searching for items by the function +const items = component.data.findAll(function(items){ + if(items.text==="Manager"||items.text==="Marketer"){return true} +}); + +//searching for items by the attribute key +const items = component.data.findAll({by:"text",match:"Manager"}); +~~~ + +**Related sample**: [Data. Find all](https://snippet.dhtmlx.com/kvemrz93) + +## Iterating items + +You can iterate through the items of a data collection, the items of a component and a specified range of items. + +The [`forEach()`](data_collection/api/datacollection_foreach_method.md) method iterates through all the items of a data collection. It takes as a parameter a callback function that will iterate over items of a data collection and may take three parameters: + - `item` - (required) the object of an item + - `index` - (optional) the index of an item + - `array` - (optional) an array with items + +~~~jsx +component.data.forEach(function(item, index, array) { + console.log("This is an item of dataCollection: ", item); + console.log("This is an index of the element: ", index); + console.log("This is an array of the elements: ", array); +}); +~~~ + +**Related sample**: [Data. ForEach](https://snippet.dhtmlx.com/wa6tcmtn) + +The [`map()`](data_collection/api/datacollection_map_method.md) method iterates through all the items of the component. As a parameter it takes a callback function that will be called for each item of a component and returns a new array of items where each item is the result of the callback function. + +~~~jsx +// getting the ids of all the items of the component +component.data.map(function(item){ + return item; +}); +~~~ + +**Related sample**: [Data. Map](https://snippet.dhtmlx.com/louctp61) + +The [`mapRange()`](data_collection/api/datacollection_maprange_method.md) method returns a new array of the items corresponding to the specified parameters. The method takes the following parameters: + +- `from: number` - the initial position of an item in the range +- `to: number` - the final position of an item in the range +- `callback: function` - a function that will be called for each item from the specified range + +and returns a new array of matching item objects. + +~~~jsx +const result = component.data.mapRange(0, 20, function(item, index) { + console.log(item.id, index); +}); +~~~ + +## Getting the id of an item + +You can get the id of an item by using the [`getId()`](data_collection/api/datacollection_getid_method.md) method of DataCollection. As a parameter, the method takes the index of the item. + +~~~jsx +const id = component.data.getId(0); // -> returns "1" +~~~ + +**Related sample**: [Data. Get Id](https://snippet.dhtmlx.com/8e02xliz) + +## Getting the index of an item + +To get the index of an item, make use of the [`getIndex()`](data_collection/api/datacollection_getindex_method.md) method of DataCollection. The method takes the id of the item as a parameter. + +~~~jsx +const index = component.data.getIndex("1"); // -> returns 0 +~~~ + +**Related sample**: [Data. Get index](https://snippet.dhtmlx.com/1ottirdt) + +## Getting the object of an item + +You can get the object of an item with the help of the [`getItem()`](data_collection/api/datacollection_getitem_method.md) method of DataCollection. As a parameter the method takes the id of a selected item. + +~~~jsx +const item = component.data.getItem(123); +~~~ + +It is possible to get access to the original properties of an item using the `getItem()` method. For example: + +~~~jsx +const item = component.data.getItem(123); +const text = item.text; +~~~ + +**Related sample**: [Data. Get item](https://snippet.dhtmlx.com/wz2sscrm) + + +## Getting the number of items + +You can get the number of items in a data collection via the [`getLength()`](data_collection/api/datacollection_getlength_method.md) method. + +~~~jsx +const items = component.data.getLength(); +~~~ + +**Related sample**: [Data. Get length](https://snippet.dhtmlx.com/4weiba8i) + +## Moving items + +You can move an item/items to the defined position using the [`move()`](data_collection/api/datacollection_move_method.md) method. It takes the following parameters: + +- `id: string | string[]` - the ids of items to move +- `index: number` - the index to move items to +- `target: object` - optional, the target data collection object + +The method returns either an item's id or an array with the ids of items. + +~~~jsx +component.data.move("4",5); // moves the item with id:4 to the position with index 5 +~~~ + +**Related sample**: [Data. Move](https://snippet.dhtmlx.com/fi66bi8h) + +## Reducing an array of items + +You can reduce an array of items to a single value with the [`reduce()`](data_collection/api/datacollection_reduce_method.md) method. It takes the following parameters: + +- `callback: function` - a function that will be called for each item in the array. The function takes two parameters: + - `acc` - the *initialValue*, or the previously returned value of the function + - `item` - the current item of a data collection +- `acc: any` - a value to be passed to the function as the initial value + +and returns a single output value. + +~~~jsx +const total = component.data.reduce(function(acc, item) { + return acc + item.value; +}, 0); +~~~ + +**Related sample**: [Data. Reduce](https://snippet.dhtmlx.com/pv7hewc7) diff --git a/docs/guides/datacollection_guide.md b/docs/guides/datacollection_guide.md index 3da0605f..2aca5041 100644 --- a/docs/guides/datacollection_guide.md +++ b/docs/guides/datacollection_guide.md @@ -43,10 +43,11 @@ where: The methods of DataCollection are useful for: - [Loading data](guides/datacollection/loading_data.md) -- [Sorting and filtering data](guides/datacollection/sorting_filtering_data.md) - [Editing data](guides/datacollection/editing_data.md) -- [Saving and restoring data](guides/datacollection/saving_restoring_data.md) +- [Working with data items](guides/datacollection/work_with_data_items.md) +- [Sorting and filtering data](guides/datacollection/sorting_filtering_data.md) - [Grouping data](guides/datacollection/grouping_data.md) +- [Saving and restoring data](guides/datacollection/saving_restoring_data.md) Check all the [methods](data_collection.md/#methods) of DataCollection. diff --git a/sidebars.js b/sidebars.js index 3b3c512d..abe58af4 100644 --- a/sidebars.js +++ b/sidebars.js @@ -4926,6 +4926,7 @@ module.exports = { "guides/datacollection/editing_data", "guides/datacollection/saving_restoring_data", "guides/datacollection/grouping_data", + "guides/datacollection/working_with_data_items", ], }, //"guides/datacollection_guide", From 4cbdc04454ce1fd5d583a3360863b1840040c6f2 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Thu, 6 Mar 2025 16:47:00 +0300 Subject: [PATCH 03/14] [update] complete data collection guides --- .../api/datacollection_isdataloaded_method.md | 2 +- .../api/datacollection_remove_method.md | 2 +- docs/grid/usage.md | 4 +- docs/guides/datacollection/editing_data.md | 8 +- docs/guides/datacollection/grouping_data.md | 47 ++---------- docs/guides/datacollection/loading_data.md | 76 +++++++++++++++++-- .../datacollection/sorting_filtering_data.md | 70 +++++++++++++---- .../datacollection/working_with_data_items.md | 6 +- docs/guides/datacollection_guide.md | 53 ++++++------- sidebars.js | 6 +- 10 files changed, 170 insertions(+), 104 deletions(-) diff --git a/docs/data_collection/api/datacollection_isdataloaded_method.md b/docs/data_collection/api/datacollection_isdataloaded_method.md index 96fce0a3..4764316b 100644 --- a/docs/data_collection/api/datacollection_isdataloaded_method.md +++ b/docs/data_collection/api/datacollection_isdataloaded_method.md @@ -7,7 +7,7 @@ description: You can explore the isDataLoaded method of DataCollection in the do # isDataLoaded() :::tip pro version only -This functionality is available in the PRO edition only. +The method works with the [Dynamic loading](helpers/lazydataproxy.md) functionality which is available in the PRO edition only. ::: @short: checks whether the specified data range is loaded from the server diff --git a/docs/data_collection/api/datacollection_remove_method.md b/docs/data_collection/api/datacollection_remove_method.md index 9c940ff6..c54c3ffe 100644 --- a/docs/data_collection/api/datacollection_remove_method.md +++ b/docs/data_collection/api/datacollection_remove_method.md @@ -16,7 +16,7 @@ description: You can explore the remove method of DataCollection in the document @example: component.data.remove("2"); //or -component.data.remove(["2", "4"]); +component.data.remove([ "2", "4" ]); @descr: diff --git a/docs/grid/usage.md b/docs/grid/usage.md index 98a9dc0f..a8f6bd27 100644 --- a/docs/grid/usage.md +++ b/docs/grid/usage.md @@ -426,7 +426,7 @@ To get the current state of sorting data in Grid, use the [`getSortingStates()`] ~~~jsx const state = grid.data.getSortingStates(); -// -> [{by: "country", dir: "desc"}, {by: "population", dir: "desc"}] +// -> [{ by: "country", dir: "desc" }, { by: "population", dir: "desc" }] ~~~ @@ -547,7 +547,7 @@ It is possible to [set a predefined Grid configuration](#configuring-data-groupi ### Enabling data grouping -To use the row data grouping functionality in Grid, you need to apply the [`group`](grid/api/grid_group_config.md) configuration property of Grid. You can set the `group` property to *true* to enable grouping, or to specify it as a configuration object to [configure data grouping ](#configuring-data-grouping). +To use the row data grouping functionality in Grid, you need to apply the [`group`](grid/api/grid_group_config.md) configuration property of Grid. You can set the `group` property to *true* to enable grouping, or specify it as a configuration object to [configure data grouping](#configuring-data-grouping). ~~~jsx {5} const grid = new dhx.Grid("grid_container", { diff --git a/docs/guides/datacollection/editing_data.md b/docs/guides/datacollection/editing_data.md index 537d0734..a8e3f92c 100644 --- a/docs/guides/datacollection/editing_data.md +++ b/docs/guides/datacollection/editing_data.md @@ -6,7 +6,7 @@ description: You can learn how to edit data with DataCollection in the documenta # Editing data -You can edit the data items of a component via DataCollection API. It allows adding new items, removing particular items or all items at once, updating the necessary configuration options of the item, creating a copy of an item at the defined position, changing the id of an item. +You can edit the data items of a component via the DataCollection API. It allows adding new items, removing particular items or all items at once, updating the necessary configuration options of the item, creating a copy of an item at the defined position. ## Adding items @@ -19,7 +19,7 @@ and returns either the item's id or an array with the ids of items. ~~~jsx // adding a new item into the beginning of a data collection -component.data.add({"value": 57.44787660011765, "id": "u1565340894584"},0); +component.data.add({ "value": 57.44787660011765, "id": "u1565340894584" }, 0); // adding an array of new items into a data collection component.data.add([ @@ -53,7 +53,7 @@ To delete the specified item from the component, use the [`remove()`](data_colle ~~~jsx component.data.remove("2"); //or -component.data.remove(["2", "4"]); +component.data.remove([ "2", "4" ]); ~~~ **Related sample**: [Data. Remove](https://snippet.dhtmlx.com/ugdlqgp5) @@ -90,7 +90,7 @@ The [`copy()`](data_collection/api/datacollection_copy_method.md) method will he and returns the item's id or an array with ids of items. ~~~jsx -component.data.copy("4",5); // copies the item with id:4 to the position with index 5 +component.data.copy("4", 5); // copies the item with id:4 to the position with index 5 ~~~ **Related sample**: [Data. Copy](https://snippet.dhtmlx.com/9rws8r05) diff --git a/docs/guides/datacollection/grouping_data.md b/docs/guides/datacollection/grouping_data.md index 80ecf845..69a05a06 100644 --- a/docs/guides/datacollection/grouping_data.md +++ b/docs/guides/datacollection/grouping_data.md @@ -6,25 +6,21 @@ description: You can learn how to group data with DataCollection in the document # Grouping data -You can group the data of a component, ungroup data and check whether data in a collection is grouped via the DataCollection API. - :::tip pro version only The described functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. ::: +You can group the data of a component, ungroup data and check whether data in a collection is grouped via the DataCollection API. + :::info important Data grouping isn't intended for working with [`lazyDataProxy`](helpers.md/lazydataproxy/) ::: -:::note -Grouped data can be serialized. After serialization data is available for rendering and editing as a plain tree-like structure -::: - The DataCollection API can be used for working with [data grouping in Grid](grid/usage.md/#grouping-data). ## Enabling data grouping -To use the [row data grouping functionality](grid/usage.md/#grouping-data) in Grid, you need to apply the [`group`](grid/api/grid_group_config.md) configuration property of Grid. You can set the `group` property to *true* to enable grouping, or to specify it as a configuration object to [configure data grouping ](grid/usage.md/#configuring-data-grouping). +To use the [row data grouping functionality](grid/usage.md/#grouping-data) in Grid, you need to apply the [`group`](grid/api/grid_group_config.md) configuration property of Grid. You can set the `group` property to *true* to enable grouping, or specify it as a configuration object to [configure data grouping](grid/usage.md/#configuring-data-grouping). ~~~jsx {5} const grid = new dhx.Grid("grid_container", { @@ -37,46 +33,13 @@ const grid = new dhx.Grid("grid_container", { }); ~~~ -You can also specify what Grid data will be used for grouping using the `groupable` properties of Grid and of a column. - -The [`groupable`](grid/api/grid_groupable_config.md) **property of Grid** enables grouping data by the values in all columns: - -~~~jsx {6} -const grid = new dhx.Grid("grid_container", { - columns: [ - // columns config - ], - group: true, - groupable: true // allowing grouping row data by the values of all columns - data: dataset -}); -~~~ - :::note -The `groupable` property works only with the [`group`](grid/api/grid_group_config.md) panel. +Grouped data can be serialized. After serialization data is available for rendering and editing as a plain tree-like structure ::: -**Related sample:** [Grid. Grouping](https://snippet.dhtmlx.com/dvqy4ewe) - -The [`groupable`](grid/api/api_gridcolumn_properties.md) **property of a column** allows grouping data by the values of a certain column: - -~~~jsx {3} -const grid = new dhx.Grid("grid_container", { - columns: [ - { id: "country", header: [{ text: "Country" }], groupable: true }, - { id: "population", header: [{ text: "Population" }] }, - { id: "area", header: [{ text: "Land Area (Km²)" }] } - ], - group: true, - data: dataset -}); -~~~ - -In the above snippet rows will be grouped by the "country" column values, as the `groupable: true` property is specified in its configuration. - ## Grouping data -The [`group()`](data_collection/api/datacollection_group_method.md) method groups data in a collection that has a plain tree-like structure according to the specified order and additional configuration. The method takes the following parameters: +The [`group()`](data_collection/api/datacollection_group_method.md) method of DataCollection groups data in a collection that has a plain tree-like structure according to the specified order and additional configuration. The method takes the following parameters: - `order` - an array that defines the order and configuration for data grouping. Each element in the array can be: - a string that represents a grouping field diff --git a/docs/guides/datacollection/loading_data.md b/docs/guides/datacollection/loading_data.md index 3ff0e553..88d2a8a5 100644 --- a/docs/guides/datacollection/loading_data.md +++ b/docs/guides/datacollection/loading_data.md @@ -1,12 +1,12 @@ --- -sidebar_label: Loading data -title: JavaScript Guides - Loading data -description: You can learn how to load data with DataCollection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. +sidebar_label: Loading and saving data +title: JavaScript Guides - Loading and saving data +description: You can learn how to load and save data with DataCollection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. --- -# Loading data +# Loading and saving data -You can load data into a component from an external file or from a local data source via the DataCollection API. +You can load data into a component from an external file or from a local data source via the DataCollection API. It also allows saving the state of a component and sending it to a different component, as well as saving changes made in the data to the server side. :::info Please note that if you specify the `id` fields in the loaded data collection, their values should be **unique**. You can also omit the `id` fields in the data collection. In this case they will be generated automatically. @@ -77,7 +77,7 @@ dataview.data.parse(dataset); ## Checking whether data is loaded :::tip pro version only -This functionality is available in the PRO edition only. +The method works with the [Dynamic loading](helpers/lazydataproxy.md) functionality which is available in the PRO edition only. ::: You can check whether the specified data range is loaded from the server using the [`isDataLoaded()`](data_collection/api/datacollection_isdataloaded_method.md) method of [DataCollection](data_collection.md). The method takes the following parameters: @@ -90,3 +90,67 @@ and returns `true`, if a range of data is loaded; otherwise, `false`. ~~~jsx component.data.isDataLoaded(); ~~~ + +## Saving and restoring the state of a component + +To save the current state of a component, use the [`serialize()`](data_collection/api/datacollection_serialize_method.md) method of Data Collection. The method is used to serialize data into the JSON, XML or CSV format. It takes the following parameter: + +- `driver: string` - optional, the format that the data will be serialized into ("json" (default), "csv", "xml") + +and returns serialized data for each item of the component either as an array of JSON objects or as a CSV/XML string. + +For example: + +~~~jsx +const state = grid1.data.serialize(); +~~~ + +**Related sample**: [Data. Serialize](https://snippet.dhtmlx.com/7c35n4uf) + +After you've saved a component's state, you can send the data stored in the saved state to a new component using the [`parse()`](data_collection/api/datacollection_parse_method.md) method of Data Collection: + +~~~jsx +// creating a new grid +const grid2 = new dhx.Grid(document.body); +// parsing the state of grid1 into grid2 +grid2.data.parse(state); +~~~ + +## Saving data changes to the server side + +You can save changes made in the data to the server side using the [`save()`](data_collection/api/datacollection_save_method.md) method of Data Collection. The method takes the following parameter: + +- `url: string | IDataProxy` - the URL of a server side or DataProxy with the URL configured + +For example: + +~~~jsx +grid.data.save("http://userurl/"); + +//or +grid.data.save(new DataProxy({ url:"http://userurl/" })); +~~~ + +Each time the user changes data of the component, the `save()` method will make an AJAX call and expect the remote URL to save data changes. The method will send one of the following requests to the back-end: + +- `POST` - after adding new data into the component +- `PUT` - after editing data of the component +- `DELETE` - after deleting data + +Data saving is asynchronous, so you need to return a promise - the result of the saving operation. To do this, use the `saveData` property that returns a "promise" object: + +~~~jsx +const data = new DataCollection(); +data.save(loader); +return data.saveData.then(function(){ + // now your data is saved +}); +~~~ + +Use the [`isSaved()`](data_collection/api/datacollection_issaved_method.md) method to check whether the changes are saved. The method returns *true*, if the changes are saved, otherwise, *false*. + +~~~jsx +grid.data.saveData.then(function(){ + console.log(grid.data.isSaved()); +}); +~~~ \ No newline at end of file diff --git a/docs/guides/datacollection/sorting_filtering_data.md b/docs/guides/datacollection/sorting_filtering_data.md index 24f5f8c2..e4984123 100644 --- a/docs/guides/datacollection/sorting_filtering_data.md +++ b/docs/guides/datacollection/sorting_filtering_data.md @@ -13,7 +13,7 @@ When working with data you may need to sort or filter it. You can sort or filter To sort data items in a component, use the [`sort()`](data_collection/api/datacollection_sort_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: - `rule: object` - an object with parameters for sorting. The object has the following attributes: - - `by: string | number` - the id of a data field (a column of Grid) + - `by: string | number` - the id of a data field - `dir: string` - the direction of sorting: "asc" or "desc" - `as: function` - a function that specifies the type to sort data as - `rule: function` - optional, a sorting rule; the function must have two parameters and return a number (-1,0,1) @@ -21,16 +21,14 @@ To sort data items in a component, use the [`sort()`](data_collection/api/dataco - `smartSorting: boolean` - specifies whether a sorting rule should be applied each time after changing the data set ~~~jsx -grid.data.sort({ - by:"a", - dir:"desc", - as: function(item){ - return item.toUpperCase(); - }, +grid.data.sort( { - smartSorting: true - } -}); + by:"a", + dir:"desc", + as: item => (item.toUpperCase()) + }, + { smartSorting: true } +); // cancels the applied sorting rules grid.data.sort(); @@ -44,7 +42,7 @@ Calling the method without parameters will discard all the applied sorting rules ### Custom sorting -To set a custom function for sorting, you need to specify the `rule` attribute in a passed object. For example: +You can also specify the `rule` attribute in a passed object instead of the default one and set a custom function for sorting. For example: ~~~jsx grid.data.sort({ @@ -52,6 +50,40 @@ grid.data.sort({ }); ~~~ +### Getting the sorting state + +To get the current state of sorting data in Grid, use the [`getSortingStates()`](data_collection/api/datacollection_getsortingstates_method.md) method of DataCollection. The method allows getting the result of sorting data by multiple columns and returns an array of objects with the following properties: + +
+ + + + + + + + + + + + + + + + + + + + + + +
by(string | number) the id of a data field to sort by
dir(string) the direction of sorting: "asc" or "desc"
as(function) a custom function of converting values before comparing
rule(function) a custom sorting function
smartSorting(boolean) (if applied) specifies whether a sorting rule should be applied each time after changing the data set
+ +~~~jsx +const state = grid.data.getSortingStates(); +// -> [{ by: "country", dir: "desc" }, { by: "population", dir: "desc" }] +~~~ + ## Filtering data To filter data items in a component, use the [`filter()`](data_collection/api/datacollection_filter_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: @@ -59,12 +91,12 @@ To filter data items in a component, use the [`filter()`](data_collection/api/da - `rule: function | object` - the filtering criteria - If set as a *function*, filtering will be applied by the rule specified in the function. The function takes an object of a data item as a parameter and returns *true/false* - If set as an *object*, the parameter has the following attributes: - - `by: string | number` - mandatory, the id of a data field (the column of Grid) + - `by: string | number` - mandatory, the id of a data field - `match: string` - mandatory, a pattern to match - `compare: function` - optional, a function for extended filtering that takes three parameters: - - `value` - the value to compare (e.g. a column in a row for Grid) + - `value` - the value to compare - `match` - a pattern to match - - `item` - a data item the values of which should be compared (e.g. a row) + - `item` - a data item the values of which should be compared - `config: object` - optional, defines the parameters of filtering. It may contain the following properties: - `id: string` - optional, the id of the filter - `add: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (*true*), or to the initial data (*false*, default) @@ -138,3 +170,13 @@ component.data.resetFilter({ id: "filter_id" }); **Related samples**: - [Data. ResetFilter](https://snippet.dhtmlx.com/jg8wxfvc) - [Grid. ResetFilter](https://snippet.dhtmlx.com/15trblk2) + +## Getting the initial data + +You can get the initial values of the items of a widget initialized in a data collection using the [`getInitialData()`](data_collection/api/datacollection_getinitialdata_method.md) method. It returns an array of item objects with initial values. + +~~~jsx +const startingData = component.data.getInitialData(); +~~~ + +**Related sample**: [Data. Get initial data](https://snippet.dhtmlx.com/l6wun9j4) diff --git a/docs/guides/datacollection/working_with_data_items.md b/docs/guides/datacollection/working_with_data_items.md index 5f526742..657fa8aa 100644 --- a/docs/guides/datacollection/working_with_data_items.md +++ b/docs/guides/datacollection/working_with_data_items.md @@ -6,7 +6,7 @@ description: You can learn how to work with DataCollection items in the document # Working with data items -Besides [basic editing API of DataCollection](guides/datacollection/editing_data.md) that allows adding, copying, updating and deleting data items, there is a set of more specific methods for manipulating data items. For example, you can check the existence of an item, find necessary items, iterate over items, get the id/index of an item or get an item object by its id, etc. +Besides [basic editing API of DataCollection](guides/datacollection/editing_data.md) that allows adding, copying, updating and deleting data items, there is a set of more specific methods for manipulating data items. For example, you can check the existence of an item, find necessary items, iterate over items, get the id/index of an item or get the item object by its id, etc. ## Checking existence of an item @@ -58,7 +58,7 @@ const item = component.data.find(function(item){ }); //searching for an item by the attribute key -const item = component.data.find({by:"text",match:"Manager"}); +const item = component.data.find({ by:"text",match:"Manager" }); ~~~ **Related sample**: [Data. Find](https://snippet.dhtmlx.com/fpxhdc46) @@ -83,7 +83,7 @@ const items = component.data.findAll(function(items){ }); //searching for items by the attribute key -const items = component.data.findAll({by:"text",match:"Manager"}); +const items = component.data.findAll({ by:"text",match:"Manager" }); ~~~ **Related sample**: [Data. Find all](https://snippet.dhtmlx.com/kvemrz93) diff --git a/docs/guides/datacollection_guide.md b/docs/guides/datacollection_guide.md index 2aca5041..7441e153 100644 --- a/docs/guides/datacollection_guide.md +++ b/docs/guides/datacollection_guide.md @@ -13,7 +13,7 @@ The DHTMLX library includes two invisible components (in other words, helpers) t API methods and events of DataCollection and TreeCollection let you work with data items, namely to load, process, and edit the items. -The helpers allow using the same data set in different components. For instance, you can prepare one data set and load it into DataView, Grid, and List with the help of the [](../data_collection/api/datacollection_load_method.md) method of DataCollection. +The helpers allow using the same data set in different components. For instance, you can prepare one data set and load it into DataView, Grid, and List with the help of the [`load()`](data_collection/api/datacollection_load_method.md) method of DataCollection. :::info Please note that if you specify the `id` fields in the data collection, their values should be **unique**. You can also omit the `id` fields in the data collection. In this case they will be generated automatically. @@ -21,15 +21,11 @@ Please note that if you specify the `id` fields in the data collection, their va In this article we will consider how to work with DataCollection. -Check all the methods and events of [Data Collection API](data_collection.md/). +Check all the methods and events of the [Data Collection API](data_collection.md/). -## Common features of DataCollection +## DataCollection methods -Here you will find some common features to understand how DataCollection works. - -### DataCollection methods - -The syntax of the DataCollection method: +The syntax of a DataCollection method is the following: ~~~jsx component.data.method(); @@ -37,23 +33,14 @@ component.data.method(); where: -- **component** is the name of the applicable component (chart, combobox, dataview, grid, list) +- **component** is the name of the applicable component (Chart, Combobox, Dataview, Grid, List) - **method** is the method of DataCollection -The methods of DataCollection are useful for: - -- [Loading data](guides/datacollection/loading_data.md) -- [Editing data](guides/datacollection/editing_data.md) -- [Working with data items](guides/datacollection/work_with_data_items.md) -- [Sorting and filtering data](guides/datacollection/sorting_filtering_data.md) -- [Grouping data](guides/datacollection/grouping_data.md) -- [Saving and restoring data](guides/datacollection/saving_restoring_data.md) - Check all the [methods](data_collection.md/#methods) of DataCollection. -### DataCollection events +## DataCollection events -The syntax of the DataCollection event: +The syntax of a DataCollection event is the following: ~~~jsx component.data.events.on("event", function(){}); @@ -61,7 +48,7 @@ component.data.events.on("event", function(){}); where: -- **component** is the name of the applicable component (chart, combobox, dataview, grid, list) +- **component** is the name of the applicable component (Chart, Combobox, Dataview, Grid, List) - **event** is the event of DataCollection Events of DataCollection are helpful when you need to configure a system response to the changes made in data. @@ -70,7 +57,17 @@ Check all the [events](data_collection.md/#events) of DataCollection. Check how to work with events in the [Events basic rules](guides/events_guide.md/) guide. -## The DataCollection usage sample +## Guides + +The following articles will help you to find out how to work with DataCollection. + +- [Loading data](guides/datacollection/loading_data.md) +- [Editing data](guides/datacollection/editing_data.md) +- [Working with data items](guides/datacollection/work_with_data_items.md) +- [Sorting and filtering data](guides/datacollection/sorting_filtering_data.md) +- [Grouping data](guides/datacollection/grouping_data.md) + +## DataCollection usage sample Let's create a sample of DataCollection usage step by step. @@ -246,7 +243,7 @@ Please note that if you specify the `id` fields in the data set, their values sh ~~~ -- Then, to load the prepared data into the list we apply the [](../data_collection/api/datacollection_parse_method.md) method of DataCollection: +- Then, to load the prepared data into the list we apply the [`parse()`](data_collection/api/datacollection_parse_method.md) method of DataCollection: ~~~jsx list.data.parse(data); @@ -254,7 +251,7 @@ list.data.parse(data); As a result, the list of books is rendered on the page according to the specified template. We took a small part of the list just for a convenience sample, in real-life practice, the list can be very huge. -Now, let's add a new book to the list. To do that, we need to use the [](../data_collection/api/datacollection_add_method.md) method of DataCollection: +Now, let's add a new book to the list. To do that, we need to use the [`add()`](data_collection/api/datacollection_add_method.md) method of DataCollection: ~~~jsx list.data.add( @@ -277,13 +274,13 @@ list.data.add( Note, that we have added the new item into the list but not into the data set. -To save the current state of the list we will serialize the component data with the help of the [](../data_collection/api/datacollection_serialize_method.md) method of DataCollection. +To save the current state of the list we will serialize the component data with the help of the [`serialize()`](data_collection/api/datacollection_serialize_method.md) method of DataCollection. ~~~jsx const state = list.data.serialize(); ~~~ -After that, we can parse the serialized data to the new list. We will use the [](../data_collection/api/datacollection_parse_method.md) method for it. +After that, we can parse the serialized data to the new list. We will use the [`parse()`](data_collection/api/datacollection_parse_method.md) method for it. Do not forget to add a separate container for the new component. @@ -293,7 +290,7 @@ Do not forget to add a separate container for the new component. ~~~jsx //creating list2 - list2 = new dhx.List("list2", { +list2 = new dhx.List("list2", { css: "dhx_widget--bordered", template: template }); @@ -314,7 +311,7 @@ list.data.remove("book001-newedition"); Pay attention, the data in list now are different from the data in list2 because we have sent data to list2 before removing the item of list. -Now we can create one more list, send new data to it, save data to the server with the save() method, or add more items, etc. Check all the possibilities to work with data with the help of DataCollection. +Now we can create one more list, send new data to it, save data to the server with the `save()` method, or add more items, etc. [Check all the possibilities to work with data with the help of DataCollection](#guides). **Please, look at the example we have just created.** diff --git a/sidebars.js b/sidebars.js index 631ae95e..482ffaac 100644 --- a/sidebars.js +++ b/sidebars.js @@ -4924,11 +4924,11 @@ module.exports = { }, items: [ "guides/datacollection/loading_data", - "guides/datacollection/sorting_filtering_data", "guides/datacollection/editing_data", - "guides/datacollection/saving_restoring_data", - "guides/datacollection/grouping_data", "guides/datacollection/working_with_data_items", + "guides/datacollection/sorting_filtering_data", + "guides/datacollection/grouping_data", + ], }, //"guides/datacollection_guide", From eae88b208762f101d1b823330ea0adcbc64ac068 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Mon, 10 Mar 2025 10:56:26 +0300 Subject: [PATCH 04/14] [update] data collection guides, minor fixes in methods --- .../api/datacollection_add_method.md | 2 +- .../api/datacollection_find_method.md | 2 +- .../api/datacollection_findall_method.md | 2 +- .../api/datacollection_reduce_method.md | 2 +- .../api/datacollection_save_method.md | 8 +- .../api/datacollection_sort_method.md | 2 +- docs/guides/datacollection/grouping_data.md | 23 -- docs/guides/datacollection/loading_data.md | 6 +- .../datacollection/sorting_filtering_data.md | 4 +- .../datacollection/working_with_data_items.md | 242 ++++++++++++------ sidebars.js | 1 - 11 files changed, 184 insertions(+), 110 deletions(-) diff --git a/docs/data_collection/api/datacollection_add_method.md b/docs/data_collection/api/datacollection_add_method.md index 2ee3a3cd..907b1547 100644 --- a/docs/data_collection/api/datacollection_add_method.md +++ b/docs/data_collection/api/datacollection_add_method.md @@ -19,7 +19,7 @@ Either item's id or an array with ids of items. @example: // adding a new item into the beginning of a data collection -component.data.add({"value": 57.44787660011765, "id": "u1565340894584"},0); +component.data.add({ "value": 57.44787660011765, "id": "u1565340894584" }, 0); // adding an array of new items into a data collection component.data.add([ diff --git a/docs/data_collection/api/datacollection_find_method.md b/docs/data_collection/api/datacollection_find_method.md index bb404f1f..679da8a2 100644 --- a/docs/data_collection/api/datacollection_find_method.md +++ b/docs/data_collection/api/datacollection_find_method.md @@ -30,7 +30,7 @@ const item = component.data.find(function(item){ }); //searching for an item by the attribute key -const item = component.data.find({by:"text",match:"Manager"}); +const item = component.data.find({ by:"text",match:"Manager" }); @descr: diff --git a/docs/data_collection/api/datacollection_findall_method.md b/docs/data_collection/api/datacollection_findall_method.md index c9ee5f23..00dd0c72 100644 --- a/docs/data_collection/api/datacollection_findall_method.md +++ b/docs/data_collection/api/datacollection_findall_method.md @@ -30,7 +30,7 @@ const items = component.data.findAll(function(items){ }); //searching for items by the attribute key -const items = component.data.findAll({by:"text",match:"Manager"}); +const items = component.data.findAll({ by:"text",match:"Manager" }); @descr: diff --git a/docs/data_collection/api/datacollection_reduce_method.md b/docs/data_collection/api/datacollection_reduce_method.md index 6ea42a1f..0e66a0b9 100644 --- a/docs/data_collection/api/datacollection_reduce_method.md +++ b/docs/data_collection/api/datacollection_reduce_method.md @@ -12,7 +12,7 @@ description: You can explore the reduce method of DataCollection in the document @params: -- `callback: function` - a function that will be called for each item in the array. The function takes two parameters: +- `callback: function` - a function that will be called for each item in the array. The function is called with the following parameters: - `acc` - the *initialValue*, or the previously returned value of the function - `item` - the current item of a data collection - `acc: any` - a value to be passed to the function as the initial value diff --git a/docs/data_collection/api/datacollection_save_method.md b/docs/data_collection/api/datacollection_save_method.md index 0a8fc496..8c18ae42 100644 --- a/docs/data_collection/api/datacollection_save_method.md +++ b/docs/data_collection/api/datacollection_save_method.md @@ -8,20 +8,20 @@ description: You can explore the save method of DataCollection in the documentat @short: saves changes made in a data collection to the server side -@signature: {'save?: (url: string | IDataProxy) => void;'} +@signature: {'save(url: IDataProxy | string): void;'} @params: -- `url: string | IDataProxy` - the URL of a server side or DataProxy with the URL configured +- `url: IDataProxy | string` - the URL of a server side or DataProxy with the URL configured @example: grid.data.save("http://userurl/"); //or -grid.data.save(new DataProxy({url:"http://userurl/"})); +grid.data.save(new DataProxy({ url:"http://userurl/" })); @descr: -Each time the user changes data of the component, the **save()** method will make an AJAX call and expect the remote URL to save data changes. +Each time the user changes data of the component, the `save()` method will make an AJAX call and expect the remote URL to save data changes. The method will send one of the following requests to the backend: - `POST` - after adding new data into the component; diff --git a/docs/data_collection/api/datacollection_sort_method.md b/docs/data_collection/api/datacollection_sort_method.md index 593e9e3b..4da1446b 100644 --- a/docs/data_collection/api/datacollection_sort_method.md +++ b/docs/data_collection/api/datacollection_sort_method.md @@ -17,7 +17,7 @@ description: You can explore the sort method of DataCollection in the documentat - `as: function` - a function that specifies the type to sort data as - `rule: function` - optional, a sorting rule; the function must have two parameters and return a number (-1,0,1) - `config: object` - defines the parameter of sorting. It may contain one property: - - `smartSorting: boolean` - specifies whether a sorting rule should be applied each time after changing the data set + - `smartSorting: boolean` - optional, specifies whether a sorting rule should be applied each time after changing the data set @example: grid.data.sort( diff --git a/docs/guides/datacollection/grouping_data.md b/docs/guides/datacollection/grouping_data.md index 69a05a06..9107773a 100644 --- a/docs/guides/datacollection/grouping_data.md +++ b/docs/guides/datacollection/grouping_data.md @@ -6,10 +6,6 @@ description: You can learn how to group data with DataCollection in the document # Grouping data -:::tip pro version only -The described functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. -::: - You can group the data of a component, ungroup data and check whether data in a collection is grouped via the DataCollection API. :::info important @@ -18,25 +14,6 @@ Data grouping isn't intended for working with [`lazyDataProxy`](helpers.md/lazyd The DataCollection API can be used for working with [data grouping in Grid](grid/usage.md/#grouping-data). -## Enabling data grouping - -To use the [row data grouping functionality](grid/usage.md/#grouping-data) in Grid, you need to apply the [`group`](grid/api/grid_group_config.md) configuration property of Grid. You can set the `group` property to *true* to enable grouping, or specify it as a configuration object to [configure data grouping](grid/usage.md/#configuring-data-grouping). - -~~~jsx {5} -const grid = new dhx.Grid("grid_container", { - columns: [ - // columns config - ], - group: true, // enabling grouping in a grid - groupable: true - data: dataset -}); -~~~ - -:::note -Grouped data can be serialized. After serialization data is available for rendering and editing as a plain tree-like structure -::: - ## Grouping data The [`group()`](data_collection/api/datacollection_group_method.md) method of DataCollection groups data in a collection that has a plain tree-like structure according to the specified order and additional configuration. The method takes the following parameters: diff --git a/docs/guides/datacollection/loading_data.md b/docs/guides/datacollection/loading_data.md index 88d2a8a5..8b9cfab0 100644 --- a/docs/guides/datacollection/loading_data.md +++ b/docs/guides/datacollection/loading_data.md @@ -76,11 +76,13 @@ dataview.data.parse(dataset); ## Checking whether data is loaded +You can check whether the specified data range is loaded from the server using the [`isDataLoaded()`](data_collection/api/datacollection_isdataloaded_method.md) method of [DataCollection](data_collection.md). + :::tip pro version only The method works with the [Dynamic loading](helpers/lazydataproxy.md) functionality which is available in the PRO edition only. ::: -You can check whether the specified data range is loaded from the server using the [`isDataLoaded()`](data_collection/api/datacollection_isdataloaded_method.md) method of [DataCollection](data_collection.md). The method takes the following parameters: +The method takes the following parameters: - `from: number` - optional, the index of the first element of the data range to be checked - `to: number` - optional, the index of the last element of the data range to be checked @@ -120,7 +122,7 @@ grid2.data.parse(state); You can save changes made in the data to the server side using the [`save()`](data_collection/api/datacollection_save_method.md) method of Data Collection. The method takes the following parameter: -- `url: string | IDataProxy` - the URL of a server side or DataProxy with the URL configured +- `url: IDataProxy | string` - the URL of a server side or DataProxy with the URL configured For example: diff --git a/docs/guides/datacollection/sorting_filtering_data.md b/docs/guides/datacollection/sorting_filtering_data.md index e4984123..f6799dc7 100644 --- a/docs/guides/datacollection/sorting_filtering_data.md +++ b/docs/guides/datacollection/sorting_filtering_data.md @@ -18,7 +18,7 @@ To sort data items in a component, use the [`sort()`](data_collection/api/dataco - `as: function` - a function that specifies the type to sort data as - `rule: function` - optional, a sorting rule; the function must have two parameters and return a number (-1,0,1) - `config: object` - defines the parameter of sorting. It may contain one property: - - `smartSorting: boolean` - specifies whether a sorting rule should be applied each time after changing the data set + - `smartSorting: boolean` - optional, specifies whether a sorting rule should be applied each time after changing the data set ~~~jsx grid.data.sort( @@ -42,7 +42,7 @@ Calling the method without parameters will discard all the applied sorting rules ### Custom sorting -You can also specify the `rule` attribute in a passed object instead of the default one and set a custom function for sorting. For example: +You can also specify the `rule` attribute in a passed object to set a custom function for sorting. For example: ~~~jsx grid.data.sort({ diff --git a/docs/guides/datacollection/working_with_data_items.md b/docs/guides/datacollection/working_with_data_items.md index 657fa8aa..53ddb101 100644 --- a/docs/guides/datacollection/working_with_data_items.md +++ b/docs/guides/datacollection/working_with_data_items.md @@ -6,21 +6,147 @@ description: You can learn how to work with DataCollection items in the document # Working with data items -Besides [basic editing API of DataCollection](guides/datacollection/editing_data.md) that allows adding, copying, updating and deleting data items, there is a set of more specific methods for manipulating data items. For example, you can check the existence of an item, find necessary items, iterate over items, get the id/index of an item or get the item object by its id, etc. +The DataCollection API provides a wide set of methods for working with data items. You can get the id/index of an item, add, update, delete, copy, move data items, find necessary items, iterate over items, etc. -## Checking existence of an item +## Getting the id of an item -You can check whether the specified item exists in the component via the [`exists()`](data_collection/api/datacollection_exists_method.md) method of DataCollection. The method takes the following parameter: +You can get the id of an item by using the [`getId()`](data_collection/api/datacollection_getid_method.md) method of DataCollection. As a parameter, the method takes the index of the item. -- `id: string | number` - the id of the item in question +~~~jsx +const id = component.data.getId(0); // -> returns "1" +~~~ -and returns *true*, if the item exists; otherwise, *false*. +**Related sample**: [Data. Get Id](https://snippet.dhtmlx.com/8e02xliz) + +## Getting the index of an item + +To get the index of an item, make use of the [`getIndex()`](data_collection/api/datacollection_getindex_method.md) method of DataCollection. The method takes the id of the item as a parameter. ~~~jsx -const item = component.data.exists("1"); +const index = component.data.getIndex("1"); // -> returns 0 ~~~ -**Related sample**: [Data. Exists](https://snippet.dhtmlx.com/2ekntrbk) +**Related sample**: [Data. Get index](https://snippet.dhtmlx.com/1ottirdt) + +## Getting the object of an item + +You can get the object of an item with the help of the [`getItem()`](data_collection/api/datacollection_getitem_method.md) method of DataCollection. As a parameter the method takes the id of a selected item. + +~~~jsx +const item = component.data.getItem(123); +~~~ + +It is possible to get access to the original properties of an item using the `getItem()` method. For example: + +~~~jsx +const item = component.data.getItem(123); +const text = item.text; +~~~ + +**Related sample**: [Data. Get item](https://snippet.dhtmlx.com/wz2sscrm) + +## Adding items + +To add new items into a component, use the [`add()`](data_collection/api/datacollection_add_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: + +- `new_item: object | array` - the object of a new item or an array of item objects +- `index: number` - optional, the index of the position starting from which new items will be added + +and returns either the item's id or an array with the ids of items. + +~~~jsx +// adding a new item into the beginning of a data collection +component.data.add({ "value": 57.44787660011765, "id": "u1565340894584" }, 0); + +// adding an array of new items into a data collection +component.data.add([ + { + "value": 57.44787660011765, + "id": "u1565340894584" + }, + { + "value": 14.612810637958095, + "id": "u1565340894585" + }, + { + "value": 83.9707181117741, + "id": "u1565340894586" + }, + { + "value": 59.01285878162044, + "id": "u1565340894587" + } +]); +~~~ + +**Related sample**: [Data. Add](https://snippet.dhtmlx.com/ktd8ks0m) + +## Removing items + +To delete the specified item from the component, use the [`remove()`](data_collection/api/datacollection_remove_method.md) method. The method takes the following parameter: + +- `id: string | string[]` - the ids of the items that should be deleted + +~~~jsx +component.data.remove("2"); +//or +component.data.remove([ "2", "4" ]); +~~~ + +**Related sample**: [Data. Remove](https://snippet.dhtmlx.com/ugdlqgp5) + +To delete all items from the component, use the [`removeAll()`](data_collection/api/datacollection_removeall_method.md) method. + +~~~jsx +component.data.removeAll(); +~~~ + +**Related sample**: [Data. Remove all](https://snippet.dhtmlx.com/ykk2ne82) + +## Updating items + +You can update the properties of the item with the help of the [`update()`](data_collection/api/datacollection_update_method.md) method. The method takes two parameters: + +- `id: string | number` - the id of the item which needs to be updated +- `newItem: object` - a hash of properties which need to be updated + +~~~jsx +component.data.update(123, { text:"New text" }); +~~~ + +**Related sample**: [Data. Update](https://snippet.dhtmlx.com/4g90gi6b) + +## Copying items + +The [`copy()`](data_collection/api/datacollection_copy_method.md) method will help you to create a copy of an item at the defined position. The method takes the following parameters: + +- `id: (string | number) | (string | number)[]` - the id of an item or an array with ids of items to copy +- `index: number` - the index to create a copy at +- `target: object` - optional, the target data collection object + +and returns the item's id or an array with ids of items. + +~~~jsx +component.data.copy("4", 5); // copies the item with id:4 to the position with index 5 +~~~ + +**Related sample**: [Data. Copy](https://snippet.dhtmlx.com/9rws8r05) + +## Moving items + +You can move an item/items to the defined position using the [`move()`](data_collection/api/datacollection_move_method.md) method. It takes the following parameters: + +- `id: string | string[]` - the ids of items to move +- `index: number` - the index to move items to +- `target: object` - optional, the target data collection object + +The method returns either an item's id or an array with the ids of items. + +~~~jsx +component.data.move("4",5); // moves the item with id:4 to the position with index 5 +~~~ + +**Related sample**: [Data. Move](https://snippet.dhtmlx.com/fi66bi8h) ## Changing the id of an item @@ -34,10 +160,36 @@ You can change the id of the necessary element of a data collection, using the [ component.data.changeId("1", "22"); ~~~ +## Checking existence of an item + +You can check whether the specified item exists in the component via the [`exists()`](data_collection/api/datacollection_exists_method.md) method of DataCollection. The method takes the following parameter: + +- `id: string | number` - the id of the item in question + +and returns *true*, if the item exists; otherwise, *false*. + +~~~jsx +const item = component.data.exists("1"); +~~~ + +**Related sample**: [Data. Exists](https://snippet.dhtmlx.com/2ekntrbk) + +## Getting the number of items + +You can get the number of items in a data collection via the [`getLength()`](data_collection/api/datacollection_getlength_method.md) method. + +~~~jsx +const items = component.data.getLength(); +~~~ + +**Related sample**: [Data. Get length](https://snippet.dhtmlx.com/4weiba8i) + ## Searching for certain data items You can find data items that match some criteria. The DataCollection API allows searching for a particular item or all the matching items. +### Searching for a particular item + The [`find()`](data_collection/api/datacollection_find_method.md) method finds the item that corresponds to the specified rule. It takes the following parameter: - `rule: object | function` - the search criteria: @@ -63,6 +215,8 @@ const item = component.data.find({ by:"text",match:"Manager" }); **Related sample**: [Data. Find](https://snippet.dhtmlx.com/fpxhdc46) +### Searching for several items + The [`findAll()`](data_collection/api/datacollection_findall_method.md) method finds all the items that correspond to the specified rule. It takes the following parameter: - `rule: object | function` - the search criteria: @@ -92,7 +246,9 @@ const items = component.data.findAll({ by:"text",match:"Manager" }); You can iterate through the items of a data collection, the items of a component and a specified range of items. -The [`forEach()`](data_collection/api/datacollection_foreach_method.md) method iterates through all the items of a data collection. It takes as a parameter a callback function that will iterate over items of a data collection and may take three parameters: +### Iterating through the items of a data collection + +The [`forEach()`](data_collection/api/datacollection_foreach_method.md) method iterates through all the items of a data collection. It takes as a parameter a callback function that will iterate over items of a data collection and is called with the following parameters: - `item` - (required) the object of an item - `index` - (optional) the index of an item - `array` - (optional) an array with items @@ -107,6 +263,8 @@ component.data.forEach(function(item, index, array) { **Related sample**: [Data. ForEach](https://snippet.dhtmlx.com/wa6tcmtn) +### Iterating through the items of a component + The [`map()`](data_collection/api/datacollection_map_method.md) method iterates through all the items of the component. As a parameter it takes a callback function that will be called for each item of a component and returns a new array of items where each item is the result of the callback function. ~~~jsx @@ -118,6 +276,8 @@ component.data.map(function(item){ **Related sample**: [Data. Map](https://snippet.dhtmlx.com/louctp61) +### Iterating through the items of a specified range + The [`mapRange()`](data_collection/api/datacollection_maprange_method.md) method returns a new array of the items corresponding to the specified parameters. The method takes the following parameters: - `from: number` - the initial position of an item in the range @@ -132,75 +292,11 @@ const result = component.data.mapRange(0, 20, function(item, index) { }); ~~~ -## Getting the id of an item - -You can get the id of an item by using the [`getId()`](data_collection/api/datacollection_getid_method.md) method of DataCollection. As a parameter, the method takes the index of the item. - -~~~jsx -const id = component.data.getId(0); // -> returns "1" -~~~ - -**Related sample**: [Data. Get Id](https://snippet.dhtmlx.com/8e02xliz) - -## Getting the index of an item - -To get the index of an item, make use of the [`getIndex()`](data_collection/api/datacollection_getindex_method.md) method of DataCollection. The method takes the id of the item as a parameter. - -~~~jsx -const index = component.data.getIndex("1"); // -> returns 0 -~~~ - -**Related sample**: [Data. Get index](https://snippet.dhtmlx.com/1ottirdt) - -## Getting the object of an item - -You can get the object of an item with the help of the [`getItem()`](data_collection/api/datacollection_getitem_method.md) method of DataCollection. As a parameter the method takes the id of a selected item. - -~~~jsx -const item = component.data.getItem(123); -~~~ - -It is possible to get access to the original properties of an item using the `getItem()` method. For example: - -~~~jsx -const item = component.data.getItem(123); -const text = item.text; -~~~ - -**Related sample**: [Data. Get item](https://snippet.dhtmlx.com/wz2sscrm) - - -## Getting the number of items - -You can get the number of items in a data collection via the [`getLength()`](data_collection/api/datacollection_getlength_method.md) method. - -~~~jsx -const items = component.data.getLength(); -~~~ - -**Related sample**: [Data. Get length](https://snippet.dhtmlx.com/4weiba8i) - -## Moving items - -You can move an item/items to the defined position using the [`move()`](data_collection/api/datacollection_move_method.md) method. It takes the following parameters: - -- `id: string | string[]` - the ids of items to move -- `index: number` - the index to move items to -- `target: object` - optional, the target data collection object - -The method returns either an item's id or an array with the ids of items. - -~~~jsx -component.data.move("4",5); // moves the item with id:4 to the position with index 5 -~~~ - -**Related sample**: [Data. Move](https://snippet.dhtmlx.com/fi66bi8h) - ## Reducing an array of items You can reduce an array of items to a single value with the [`reduce()`](data_collection/api/datacollection_reduce_method.md) method. It takes the following parameters: -- `callback: function` - a function that will be called for each item in the array. The function takes two parameters: +- `callback: function` - a function that will be called for each item in the array. The function is called with the following parameters: - `acc` - the *initialValue*, or the previously returned value of the function - `item` - the current item of a data collection - `acc: any` - a value to be passed to the function as the initial value diff --git a/sidebars.js b/sidebars.js index 482ffaac..af18a797 100644 --- a/sidebars.js +++ b/sidebars.js @@ -4924,7 +4924,6 @@ module.exports = { }, items: [ "guides/datacollection/loading_data", - "guides/datacollection/editing_data", "guides/datacollection/working_with_data_items", "guides/datacollection/sorting_filtering_data", "guides/datacollection/grouping_data", From 5306d60edd371ab146909d652820439c1959bc22 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Mon, 10 Mar 2025 11:20:33 +0300 Subject: [PATCH 05/14] [update] remove unused data collection guides --- docs/guides/datacollection/editing_data.md | 97 ------------------- .../datacollection/saving_restoring_data.md | 79 --------------- 2 files changed, 176 deletions(-) delete mode 100644 docs/guides/datacollection/editing_data.md delete mode 100644 docs/guides/datacollection/saving_restoring_data.md diff --git a/docs/guides/datacollection/editing_data.md b/docs/guides/datacollection/editing_data.md deleted file mode 100644 index a8e3f92c..00000000 --- a/docs/guides/datacollection/editing_data.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -sidebar_label: Editing data -title: JavaScript Guides - Editing data -description: You can learn how to edit data with DataCollection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. ---- - -# Editing data - -You can edit the data items of a component via the DataCollection API. It allows adding new items, removing particular items or all items at once, updating the necessary configuration options of the item, creating a copy of an item at the defined position. - -## Adding items - -To add new items into a component, use the [`add()`](data_collection/api/datacollection_add_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: - -- `new_item: object | array` - the object of a new item or an array of item objects -- `index: number` - optional, the index of the position starting from which new items will be added - -and returns either the item's id or an array with the ids of items. - -~~~jsx -// adding a new item into the beginning of a data collection -component.data.add({ "value": 57.44787660011765, "id": "u1565340894584" }, 0); - -// adding an array of new items into a data collection -component.data.add([ - { - "value": 57.44787660011765, - "id": "u1565340894584" - }, - { - "value": 14.612810637958095, - "id": "u1565340894585" - }, - { - "value": 83.9707181117741, - "id": "u1565340894586" - }, - { - "value": 59.01285878162044, - "id": "u1565340894587" - } -]); -~~~ - -**Related sample**: [Data. Add](https://snippet.dhtmlx.com/ktd8ks0m) - -## Removing items - -To delete the specified item from the component, use the [`remove()`](data_collection/api/datacollection_remove_method.md) method. The method takes the following parameter: - -- `id: string | string[]` - the ids of the items that should be deleted - -~~~jsx -component.data.remove("2"); -//or -component.data.remove([ "2", "4" ]); -~~~ - -**Related sample**: [Data. Remove](https://snippet.dhtmlx.com/ugdlqgp5) - -To delete all items from the component, use the [`removeAll()`](data_collection/api/datacollection_removeall_method.md) method. - -~~~jsx -component.data.removeAll(); -~~~ - -**Related sample**: [Data. Remove all](https://snippet.dhtmlx.com/ykk2ne82) - -## Updating items - -You can update the properties of the item with the help of the [`update()`](data_collection/api/datacollection_update_method.md) method. The method takes two parameters: - -- `id: string | number` - the id of the item which needs to be updated -- `newItem: object` - a hash of properties which need to be updated - -~~~jsx -component.data.update(123, { text:"New text" }); -~~~ - -**Related sample**: [Data. Update](https://snippet.dhtmlx.com/4g90gi6b) - -## Copying items - -The [`copy()`](data_collection/api/datacollection_copy_method.md) method will help you to create a copy of an item at the defined position. The method takes the following parameters: - -- `id: (string | number) | (string | number)[]` - the id of an item or an array with ids of items to copy -- `index: number` - the index to create a copy at -- `target: object` - optional, the target data collection object - -and returns the item's id or an array with ids of items. - -~~~jsx -component.data.copy("4", 5); // copies the item with id:4 to the position with index 5 -~~~ - -**Related sample**: [Data. Copy](https://snippet.dhtmlx.com/9rws8r05) - diff --git a/docs/guides/datacollection/saving_restoring_data.md b/docs/guides/datacollection/saving_restoring_data.md deleted file mode 100644 index f86ca2f3..00000000 --- a/docs/guides/datacollection/saving_restoring_data.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -sidebar_label: Saving and restoring data -title: JavaScript Guides - Saving and restoring data -description: You can learn how to save and restore data with DataCollection in the documentation of the DHTMLX JavaScript UI library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Suite. ---- - -# Saving and restoring data - -You can use the DataCollection API to save the state of a component and send it to a different component or to the server. - -## Saving the state of a component - -To save the current state of a component, use the [`serialize()`](data_collection/api/datacollection_serialize_method.md) method of Data Collection. The method is used to serialize data into the JSON, XML or CSV format. It takes the following parameter: - -- `driver: string` - optional, the format that the data will be serialized into ("json" (default), "csv", "xml") - -and returns serialized data for each item of the component either as an array of JSON objects or as a CSV/XML string. - -For example: - -~~~jsx -const state = grid1.data.serialize(); -~~~ - -**Related sample**: [Data. Serialize](https://snippet.dhtmlx.com/7c35n4uf) - -## Restoring the state of a component - -### Sending saved data to a new component - -After you've saved a component's state, you can send the data stored in the saved state to a new component using the [`parse()`](data_collection/api/datacollection_parse_method.md) method of Data Collection: - -~~~jsx -// creating a new grid -const grid2 = new dhx.Grid(document.body); -// parsing the state of grid1 into grid2 -grid2.data.parse(state); -~~~ - -### Saving data changes to the server side - -You can also save changes made in the data to the server side using the [`save()`](data_collection/api/datacollection_save_method.md) method of Data Collection. The method takes the following parameter: - -- `url: string | IDataProxy` - the URL of a server side or DataProxy with the URL configured - -For example: - -~~~jsx -grid.data.save("http://userurl/"); - -//or -grid.data.save(new DataProxy({url:"http://userurl/"})); -~~~ - -Each time the user changes data of the component, the `save()` method will make an AJAX call and expect the remote URL to save data changes. The method will send one of the following requests to the back-end: - -- `POST` - after adding new data into the component -- `PUT` - after editing data of the component -- `DELETE` - after deleting data - -Data saving is asynchronous, so you need to return a promise - the result of the saving operation. To do this, use the `saveData` property that returns a "promise" object: - -~~~jsx -const data = new DataCollection(); -data.save(loader); -return data.saveData.then(function(){ - // now your data is saved -}); -~~~ - -Use the [`isSaved()`](data_collection/api/datacollection_issaved_method.md) method to check whether the changes are saved. The method returns *true*, if the changes are saved, otherwise, *false*. - -~~~jsx -grid.data.saveData.then(function(){ - console.log(grid.data.isSaved()); -}); -~~~ - - From 121166a002bde393adc498050faa535838e8b488 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Mon, 10 Mar 2025 12:42:54 +0300 Subject: [PATCH 06/14] [update] add index param for reduce() method of data collection --- docs/data_collection/api/datacollection_reduce_method.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/data_collection/api/datacollection_reduce_method.md b/docs/data_collection/api/datacollection_reduce_method.md index 0e66a0b9..3250a569 100644 --- a/docs/data_collection/api/datacollection_reduce_method.md +++ b/docs/data_collection/api/datacollection_reduce_method.md @@ -8,20 +8,21 @@ description: You can explore the reduce method of DataCollection in the document @short: reduces the array to a single value -@signature: {'reduce(callback: (acc: any, item: any) => any, acc: any): any;'} +@signature: {'reduce(callback: (acc: any, item: any, index?: number) => any, acc: any): any;'} @params: - `callback: function` - a function that will be called for each item in the array. The function is called with the following parameters: - `acc` - the *initialValue*, or the previously returned value of the function - `item` - the current item of a data collection + - `index` - the index of the item - `acc: any` - a value to be passed to the function as the initial value @returns: A single output value. @example: -const total = component.data.reduce(function(acc, item) { +const total = component.data.reduce(function(acc, item, index) { return acc + item.value; }, 0); From 895060ec257e3793fe1d61669015f0f6d804180c Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Mon, 10 Mar 2025 13:58:04 +0300 Subject: [PATCH 07/14] [update] minor updates in datacollection guides --- docs/guides/datacollection/working_with_data_items.md | 3 ++- docs/guides/datacollection_guide.md | 7 +++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guides/datacollection/working_with_data_items.md b/docs/guides/datacollection/working_with_data_items.md index 53ddb101..48d2d1bf 100644 --- a/docs/guides/datacollection/working_with_data_items.md +++ b/docs/guides/datacollection/working_with_data_items.md @@ -299,12 +299,13 @@ You can reduce an array of items to a single value with the [`reduce()`](data_co - `callback: function` - a function that will be called for each item in the array. The function is called with the following parameters: - `acc` - the *initialValue*, or the previously returned value of the function - `item` - the current item of a data collection + - `index` - the index of the item - `acc: any` - a value to be passed to the function as the initial value and returns a single output value. ~~~jsx -const total = component.data.reduce(function(acc, item) { +const total = component.data.reduce(function(acc, item, index) { return acc + item.value; }, 0); ~~~ diff --git a/docs/guides/datacollection_guide.md b/docs/guides/datacollection_guide.md index 7441e153..72d06335 100644 --- a/docs/guides/datacollection_guide.md +++ b/docs/guides/datacollection_guide.md @@ -62,7 +62,6 @@ Check how to work with events in the [Events basic rules](guides/events_guide.md The following articles will help you to find out how to work with DataCollection. - [Loading data](guides/datacollection/loading_data.md) -- [Editing data](guides/datacollection/editing_data.md) - [Working with data items](guides/datacollection/work_with_data_items.md) - [Sorting and filtering data](guides/datacollection/sorting_filtering_data.md) - [Grouping data](guides/datacollection/grouping_data.md) @@ -299,7 +298,7 @@ list2 = new dhx.List("list2", { list2.data.parse(state); ~~~ -Now we have two lists with the same data. Let's make some changes to **list**. For example, we can change the id of the first item using the `changeId()` method and, then, delete the item from the list via the `remove()` method, as in: +Now we have two lists with the same data. Let's make some changes to **list**. For example, we can change the id of the first item using the [`changeId()`](data_collection/api/datacollection_changeid_method.md) method and, then, delete the item from the list via the [`remove()`](data_collection/api/datacollection_remove_method.md) method, as in: ~~~jsx //changing the id of the element @@ -309,9 +308,9 @@ list.data.changeId("book001", "book001-newedition"); list.data.remove("book001-newedition"); ~~~ -Pay attention, the data in list now are different from the data in list2 because we have sent data to list2 before removing the item of list. +Pay attention, the data in **list** now are different from the data in **list2** because we have sent data to **list2** before removing the item of list. -Now we can create one more list, send new data to it, save data to the server with the `save()` method, or add more items, etc. [Check all the possibilities to work with data with the help of DataCollection](#guides). +Now we can create one more list, send new data to it, save data to the server with the [`save()`](data_collection/api/datacollection_save_method.md) method, or add more items, etc. [Check all the possibilities to work with data with the help of DataCollection](#guides). **Please, look at the example we have just created.** From 7ca54016f244683cafc00b6a10c8a69968f90af1 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Mon, 10 Mar 2025 15:59:47 +0300 Subject: [PATCH 08/14] [update] complete work with items guide for data collection --- .../datacollection/working_with_data_items.md | 24 ++++++++++++------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/guides/datacollection/working_with_data_items.md b/docs/guides/datacollection/working_with_data_items.md index 48d2d1bf..54347008 100644 --- a/docs/guides/datacollection/working_with_data_items.md +++ b/docs/guides/datacollection/working_with_data_items.md @@ -249,9 +249,9 @@ You can iterate through the items of a data collection, the items of a component ### Iterating through the items of a data collection The [`forEach()`](data_collection/api/datacollection_foreach_method.md) method iterates through all the items of a data collection. It takes as a parameter a callback function that will iterate over items of a data collection and is called with the following parameters: - - `item` - (required) the object of an item - - `index` - (optional) the index of an item - - `array` - (optional) an array with items + - `item` - the object of an item + - `index` - the index of an item + - `array` - an array with items ~~~jsx component.data.forEach(function(item, index, array) { @@ -265,12 +265,17 @@ component.data.forEach(function(item, index, array) { ### Iterating through the items of a component -The [`map()`](data_collection/api/datacollection_map_method.md) method iterates through all the items of the component. As a parameter it takes a callback function that will be called for each item of a component and returns a new array of items where each item is the result of the callback function. +The [`map()`](data_collection/api/datacollection_map_method.md) method iterates through all the items of the component. As a parameter it takes a callback function that will be called for each item of a component. The function is called with the following parameters: + - `item` - the object of an item + - `index` - the index of an item + - `array` - an array of items the method was called upon + +and returns a new array of items where each item is the result of the callback function. ~~~jsx // getting the ids of all the items of the component -component.data.map(function(item){ - return item; +component.data.map(function(item, index, array){ + return item.id; }); ~~~ @@ -282,12 +287,15 @@ The [`mapRange()`](data_collection/api/datacollection_maprange_method.md) method - `from: number` - the initial position of an item in the range - `to: number` - the final position of an item in the range -- `callback: function` - a function that will be called for each item from the specified range +- `callback: function` - a function that will be called for each item from the specified range. The function is called with the following parameters: + - `item` - the object of an item + - `index` - the index of an item + - `array` - an array of items the method was called upon and returns a new array of matching item objects. ~~~jsx -const result = component.data.mapRange(0, 20, function(item, index) { +const result = component.data.mapRange(0, 20, function(item, index, array) { console.log(item.id, index); }); ~~~ From d50686824553ee67bada0c374f0d2b04e22909ba Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Tue, 11 Mar 2025 11:17:36 +0300 Subject: [PATCH 09/14] [add] the "silent" parameter for filter(),resetFilter(), update() DataCollection methods --- docs/data_collection/api/datacollection_filter_method.md | 7 ++++++- .../api/datacollection_resetfilter_method.md | 7 ++++++- docs/data_collection/api/datacollection_update_method.md | 7 ++++++- 3 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/data_collection/api/datacollection_filter_method.md b/docs/data_collection/api/datacollection_filter_method.md index f71378d4..e9f12937 100644 --- a/docs/data_collection/api/datacollection_filter_method.md +++ b/docs/data_collection/api/datacollection_filter_method.md @@ -8,7 +8,7 @@ description: You can explore the filter method of DataCollection in the document @short: filters data items in a component -@signature: {'filter(rule?: function | object, config?: object): string;'} +@signature: {'filter(rule?: function | object, config?: object, silent?: boolean): string;'} @params: - `rule: function | object` - the filtering criteria @@ -24,6 +24,11 @@ description: You can explore the filter method of DataCollection in the document - `id: string` - optional, the id of the filter - `add: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (*true*), or to the initial data (*false*, default) - `permanent: boolean` - optional, *true* to make the current filter permanent. It will be applied even if the next filtering doesn't have the `add:true` property in its configuration object. Such a filter can be removed just with the [resetFilter()](data_collection/api/datacollection_resetfilter_method.md) method +- `silent: boolean` - optional, if *true*, the update of the DataCollection state won't trigger the component repainting, *false* by default + +:::info +Note that the use of the `silent` parameter may cause incorrect behavior of the method. +::: @returns: - `id: string` - the id of the filter diff --git a/docs/data_collection/api/datacollection_resetfilter_method.md b/docs/data_collection/api/datacollection_resetfilter_method.md index ea933eb9..30c98616 100644 --- a/docs/data_collection/api/datacollection_resetfilter_method.md +++ b/docs/data_collection/api/datacollection_resetfilter_method.md @@ -8,12 +8,17 @@ description: You can explore the resetFilter method of DataCollection in the doc @short: resets the active filters -@signature: {'resetFilter(config?: object): boolean;'} +@signature: {'resetFilter(config?: object, silent?: boolean): boolean;'} @params: - `config: object` - optional, specifies the parameters of resetting the active filters. If the config isn't specified or it is empty, all the filters except for those that have the `permanent` property in the configuration object will be reset. Can contain the following properties: - `id: string` - optional, the id of the filter to reset - `permanent: boolean` - optional, *true* to reset all the active filters, including those that have the `permanent:true` property in their config +- `silent: boolean` - optional, if *true*, the update of the DataCollection state won't trigger the component repainting, *false* by default + +:::info +Note that the use of the `silent` parameter may cause incorrect behavior of the method. +::: @returns: - `result: boolean` - *true*, if all the filters, including the permanent ones, have been reset; otherwise *false* diff --git a/docs/data_collection/api/datacollection_update_method.md b/docs/data_collection/api/datacollection_update_method.md index 441eeacc..75c1dabc 100644 --- a/docs/data_collection/api/datacollection_update_method.md +++ b/docs/data_collection/api/datacollection_update_method.md @@ -8,11 +8,16 @@ description: You can explore the update method of DataCollection in the document @short: updates properties of the item -@signature: {'update?: (id: string | number, newItem: object) => void;'} +@signature: {'update?: (id: string | number, newItem: object, silent?: boolean) => void;'} @params: - `id: string | number` - the id of the item which needs to be updated - `newItem: object` - a hash of properties which need to be updated +- `silent: boolean` - optional, if *true*, the update of the DataCollection state won't trigger the component repainting, *false* by default + +:::info +Note that the use of the `silent` parameter may cause incorrect behavior of the method. +::: @example: component.data.update(123, { text:"New text" }); From 4f3d1921d1c4adcf740541e3c95d03a72db42889 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Mon, 17 Mar 2025 13:35:14 +0300 Subject: [PATCH 10/14] [add] what's new for v9.1.2 --- docs/whatsnew.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/whatsnew.md b/docs/whatsnew.md index 5b7ec1dd..eb11ec8d 100644 --- a/docs/whatsnew.md +++ b/docs/whatsnew.md @@ -8,6 +8,21 @@ description: You can explore what's new in DHTMLX Suite and its release history Before updating DHTMLX to the latest version, please check the [Migration to Newer Versions](migration.md) guide to avoid possible breakdowns. +## Version 9.1.2 + +Released on February 17, 2025 + +### Fixes + +- Chart. The default CSS classes aren't applied to the series of the `splineArea` chart type +- Combobox. Incorrect calculation of the popup position on filtering options +- Grid. Impossibility to set the left border for the first cells +- Grid. Incorrect displaying of a row dragged by the frozen part +- Grid. The script error that occurred while hovering over a span in the "tree" mode +- TreeCollection. The `move` method doesn't move child elements of an item between collections +- TreeCollection. After moving elements in `_order` there are duplicates of moved elements + + ## Version 9.1.1 Released on February 24, 2025 From 9a126e0df6190e3515619d80a67fe2b12c3f349f Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Mon, 17 Mar 2025 13:37:38 +0300 Subject: [PATCH 11/14] [fix] the release date for v9.1.2 --- docs/whatsnew.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/whatsnew.md b/docs/whatsnew.md index eb11ec8d..e074c4fa 100644 --- a/docs/whatsnew.md +++ b/docs/whatsnew.md @@ -10,7 +10,7 @@ Before updating DHTMLX to the latest version, please check the [Migration to New ## Version 9.1.2 -Released on February 17, 2025 +Released on March 17, 2025 ### Fixes From 088a22642ba0eaaeb5827d35962beb3d08cb0131 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Wed, 26 Mar 2025 12:15:46 +0300 Subject: [PATCH 12/14] [update] datacollection api descriptions --- .../api/datacollection_add_method.md | 4 +-- .../api/datacollection_changeid_method.md | 4 +-- .../api/datacollection_copy_method.md | 4 +-- .../api/datacollection_filter_method.md | 36 +++++++++++-------- .../api/datacollection_find_method.md | 20 ++++++----- .../api/datacollection_findall_method.md | 18 +++++----- .../api/datacollection_foreach_method.md | 8 ++--- .../api/datacollection_getfilters_method.md | 2 +- .../api/datacollection_getitem_method.md | 2 +- .../api/datacollection_getlength_method.md | 2 +- .../datacollection_getsortingstates_method.md | 2 +- .../api/datacollection_group_method.md | 28 +++++++-------- .../api/datacollection_isdataloaded_method.md | 8 +++-- .../api/datacollection_load_method.md | 8 ++--- .../api/datacollection_map_method.md | 10 +++--- .../api/datacollection_maprange_method.md | 8 ++--- .../api/datacollection_move_method.md | 4 +-- .../api/datacollection_parse_method.md | 2 +- .../api/datacollection_reduce_method.md | 11 +++--- .../api/datacollection_resetfilter_method.md | 13 ++++--- .../api/datacollection_save_method.md | 16 ++++----- .../api/datacollection_serialize_method.md | 2 +- .../api/datacollection_sort_method.md | 18 +++++----- .../api/datacollection_update_method.md | 18 +++++++++- 24 files changed, 141 insertions(+), 107 deletions(-) diff --git a/docs/data_collection/api/datacollection_add_method.md b/docs/data_collection/api/datacollection_add_method.md index 2ee3a3cd..5fa3d42d 100644 --- a/docs/data_collection/api/datacollection_add_method.md +++ b/docs/data_collection/api/datacollection_add_method.md @@ -12,14 +12,14 @@ description: You can explore the add method of DataCollection in the documentati @params: - `new_item: object | array` - the object of a new item or an array of item objects -- `index: number` - optional, the index of the position starting from which new items will be added +- `index?: number` - optional, the index of the position starting from which new items will be added @returns: Either item's id or an array with ids of items. @example: // adding a new item into the beginning of a data collection -component.data.add({"value": 57.44787660011765, "id": "u1565340894584"},0); +component.data.add({ "value": 57.44787660011765, "id": "u1565340894584" }, 0); // adding an array of new items into a data collection component.data.add([ diff --git a/docs/data_collection/api/datacollection_changeid_method.md b/docs/data_collection/api/datacollection_changeid_method.md index 2ab6f173..6605e62b 100644 --- a/docs/data_collection/api/datacollection_changeid_method.md +++ b/docs/data_collection/api/datacollection_changeid_method.md @@ -12,8 +12,8 @@ description: You can explore the changeId method of DataCollection in the docume @params: - `id: string | number` - the old id of an item -- `newId: string | number` - optional, the new id; auto-generated if not set -- `silent: boolean` - true, to prevent changing the id; otherwise, false +- `newId?: string | number` - optional, the new id; auto-generated if not set +- `silent?: boolean` - optional, if set to *true*, the method will be called without triggering events; otherwise, *false* @example: component.data.changeId("1", "22"); diff --git a/docs/data_collection/api/datacollection_copy_method.md b/docs/data_collection/api/datacollection_copy_method.md index 49fba344..5ae63dd2 100644 --- a/docs/data_collection/api/datacollection_copy_method.md +++ b/docs/data_collection/api/datacollection_copy_method.md @@ -13,13 +13,13 @@ description: You can explore the copy method of DataCollection in the documentat @params: - `id: (string | number) | (string | number)[]` - the id of an item or an array with ids of items to copy - `index: number` - the index to create a copy at -- `target: object` - optional, the target data collection object +- `target?: object` - optional, the target data collection object @returns: The item's id or an array with ids of items. @example: -component.data.copy("4",5); // copies the item with id:4 to the position with index 5 +component.data.copy("4", 5); // copies the item with id:4 to the position with index 5 @descr: diff --git a/docs/data_collection/api/datacollection_filter_method.md b/docs/data_collection/api/datacollection_filter_method.md index c55122cf..5abcd69c 100644 --- a/docs/data_collection/api/datacollection_filter_method.md +++ b/docs/data_collection/api/datacollection_filter_method.md @@ -8,22 +8,30 @@ description: You can explore the filter method of DataCollection in the document @short: filters data items in a component -@signature: {'filter(rule?: function | object, config?: object): string;'} +@signature: {'filter(rule?: function | object, config?: object, silent?: boolean): string;'} @params: -- `rule: function | object` - the filtering criteria - - If set as a *function*, filtering will be applied by the rule specified in the function. The function takes an object of a data item as a parameter and returns *true/false* - - If set as an *object*, the parameter has the following attributes: - - `by: string | number` - mandatory, the id of a data field - - `match: string` - mandatory, a pattern to match - - `compare: function` - optional, a function for extended filtering that takes three parameters: - - `value` - the value to compare - - `match` - a pattern to match - - `item` - a data item the values of which should be compared -- `config: object` - optional, defines the parameters of filtering. It may contain the following properties: - - `id: string` - optional, the id of the filter - - `add: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (true), or to the initial data (false, default) - - `permanent: boolean` - optional, *true* to make the current filter permanent. It will be applied even if the next filtering doesn't have the `add:true` property in its configuration object. Such a filter can be removed just with the [resetFilter()](data_collection/api/datacollection_resetfilter_method.md) method + + + + + + + + + + + + + + + + +
rule(function | object) optional, the filtering criteria. It can be:
  • a filtering function. It takes as a parameter a data item and returns true/false
  • an object with the following attributes:
    • `by?: string | number` - optional, the id of a column
    • `match?: string` - optional, a pattern to match
    • `compare?: function` - optional, a function for extended filtering that takes the following parameters:
      • value - the value to compare
      • match - a pattern to match
      • item - a data item the values of which should be compared
config(object) optional, an object with the following properties:
  • `id?: string` - optional, the id of the filter
  • `add?: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (true), or to the initial data (false, default)
  • `permanent?: boolean` - optional, true to make the current filter permanent. It will be applied even if the next filtering doesn't have the `add:true` property in its configuration object. Such a filter can be removed just with the `resetFilter()` method
silent(boolean) optional, if set to true, the method will be called without triggering events, false by default
+ +:::info +Note that after calling the method with the `silent:true` parameter, you may need to repaint the component with the `paint()` method. +::: @returns: - `id: string` - the id of the filter diff --git a/docs/data_collection/api/datacollection_find_method.md b/docs/data_collection/api/datacollection_find_method.md index abd7c741..be37dbbe 100644 --- a/docs/data_collection/api/datacollection_find_method.md +++ b/docs/data_collection/api/datacollection_find_method.md @@ -16,21 +16,23 @@ description: You can explore the find method of DataCollection in the documentat - `by: string | function` - the search criterion (either the key of the item attribute or a search function) - `match: string` - the value of the item attribute - if set as a function, the search will be applied by the rule specified in the function. The function takes three parameters: - - `item` - (required) the object of an item - - `index` - (optional) the index of an item - - `array` - (optional) an array with items + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon @returns: -An object of the matching item. +The object of the matching item. @example: -//searching for an item by the function -const item = component.data.find(function(item){ - if(item.text==="Manager"||item.text==="Marketer"){return true} +// searching for an item by the function +const item = component.data.find(function (item) { + if (item.text === "Manager" || item.text === "Marketer") { + return true + } }); -//searching for an item by the attribute key -const item = component.data.find({by:"text",match:"Manager"}); +// searching for an item by the attribute key +const item = component.data.find({ by: "text", match: "Manager" }); @descr: diff --git a/docs/data_collection/api/datacollection_findall_method.md b/docs/data_collection/api/datacollection_findall_method.md index c9ee5f23..90a3fff5 100644 --- a/docs/data_collection/api/datacollection_findall_method.md +++ b/docs/data_collection/api/datacollection_findall_method.md @@ -16,21 +16,23 @@ description: You can explore the findAll method of DataCollection in the documen - `by: string | function` - the search criterion (either the key of the item attribute or a search function) - `match: string` - the value of the item attribute - if set as a function, the search will be applied by the rule specified in the function. The function takes three parameters: - - `item` - (required) the object of an item - - `index` - (optional) the index of an item - - `array` - (optional) an array with items + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon @returns: An array of matching item objects. @example: -//searching for items by the function -const items = component.data.findAll(function(items){ - if(items.text==="Manager"||items.text==="Marketer"){return true} +// searching for items by the function +const items = component.data.findAll(function (items) { + if (items.text === "Manager" || items.text === "Marketer") { + return true + } }); -//searching for items by the attribute key -const items = component.data.findAll({by:"text",match:"Manager"}); +// searching for items by the attribute key +const items = component.data.findAll({ by: "text", match: "Manager" }); @descr: diff --git a/docs/data_collection/api/datacollection_foreach_method.md b/docs/data_collection/api/datacollection_foreach_method.md index 7b27118f..f95575d8 100644 --- a/docs/data_collection/api/datacollection_foreach_method.md +++ b/docs/data_collection/api/datacollection_foreach_method.md @@ -12,12 +12,12 @@ description: You can explore the forEach method of DataCollection in the documen @params: - `callback: function` - a function that will iterate over items of a data collection. The function is called with the following parameters: - - `item` - the object of an item - - `index` - the index of an item - - `array` - an array of items the method was called upon + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon @example: -component.data.forEach(function(item, index, array) { +component.data.forEach(function (item, index, array) { console.log("This is an item of dataCollection: ", item); console.log("This is an index of the element: ", index); console.log("This is an array of the elements: ", array); diff --git a/docs/data_collection/api/datacollection_getfilters_method.md b/docs/data_collection/api/datacollection_getfilters_method.md index 347f5b52..cdccd497 100644 --- a/docs/data_collection/api/datacollection_getfilters_method.md +++ b/docs/data_collection/api/datacollection_getfilters_method.md @@ -12,7 +12,7 @@ description: You can explore the getFilters method of DataCollection in the docu @params: -- `permanent: boolean` - optional, false by default. Allows getting the list of permanent filters +- `permanent?: boolean` - optional, *false* by default. Allows getting the list of permanent filters @returns: - `filters: object` - an object with the applied filters, where the key is the id of a filter and the value is an object with the [`rule` and `config` properties](data_collection/api/datacollection_filter_method.md) diff --git a/docs/data_collection/api/datacollection_getitem_method.md b/docs/data_collection/api/datacollection_getitem_method.md index 2ae9b158..abaa217c 100644 --- a/docs/data_collection/api/datacollection_getitem_method.md +++ b/docs/data_collection/api/datacollection_getitem_method.md @@ -26,7 +26,7 @@ const item = component.data.getItem(123); You can access the original properties of an item like this: -~~~js +~~~jsx const item = component.data.getItem(123); const text = item.text; ~~~ diff --git a/docs/data_collection/api/datacollection_getlength_method.md b/docs/data_collection/api/datacollection_getlength_method.md index 68ab517d..680bb3b1 100644 --- a/docs/data_collection/api/datacollection_getlength_method.md +++ b/docs/data_collection/api/datacollection_getlength_method.md @@ -14,7 +14,7 @@ description: You can explore the getLength method of DataCollection in the docum The number of elements of a data collection. @example: -component.data.getLength(); +const dataLength = component.data.getLength(); @descr: diff --git a/docs/data_collection/api/datacollection_getsortingstates_method.md b/docs/data_collection/api/datacollection_getsortingstates_method.md index 9b9d9759..230d09dc 100644 --- a/docs/data_collection/api/datacollection_getsortingstates_method.md +++ b/docs/data_collection/api/datacollection_getsortingstates_method.md @@ -27,7 +27,7 @@ An array of objects with the current parameters of sorting applied to the data. @example: const state = grid.data.getSortingStates(); -// -> [{by: "country", dir: "desc"}, {by: "population", dir: "desc"}] +// -> [{ by: "country", dir: "desc" }, { by: "population", dir: "desc" }] @descr: The array returned by the method contains objects with the following properties: diff --git a/docs/data_collection/api/datacollection_group_method.md b/docs/data_collection/api/datacollection_group_method.md index ffd99064..eecb5e68 100644 --- a/docs/data_collection/api/datacollection_group_method.md +++ b/docs/data_collection/api/datacollection_group_method.md @@ -39,21 +39,19 @@ group(order: TGroupOrder[], config?: IGroupConfig): void; ## Parameters -- `order` - an array that defines the order and configuration for data grouping. Each element in the array can be: - - a string that represents a grouping field - - a function `(i: IDataItem) => string` for dynamic defining of a group - - an `IGroupOrder` object that has the following properties: - - `by` - the field name or a function for user-defined grouping - - `map` - (optional) an object for data aggregation in a group, where the keys are field names, and the values can be: - - a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the `dhx.methods` helper - - a user-defined aggregation function `(i: IDataItem[]) => string | number` - - `summary` - (optional) specifies where the total row is rendered - at the `top` or at the `bottom` of the group -- `config` - (optional) the configuration of data grouping - - `showMissed` - (optional) specifies whether the elements that don't have the field for grouping should be displayed, *true* by default - - if set to *true*, the rows that don't have values for grouping are rendered row by row after all the data - - if a *string* value is set, e.g. "Missed", the rows that don't have values for grouping are rendered as a separate group the name of which will have the specified string value. This group will be rendered as the last one - - if set to *false*, the rows that don't suit the grouping criteria won't be rendered - - `field` - (optional) the group field name, *"group"* by default + + + + + + + + + + + +
order (array) an array that defines the order and configuration for data grouping. Each element in the array can be:
  • a string that represents a grouping field
  • a function `(i: IDataItem) => string` for dynamic defining of a group
  • an `IGroupOrder` object that has the following properties:
    • `by: string | function` - the field name or a function for user-defined grouping
    • `map?: object` - optional, an object for data aggregation in a group, where the keys are field names, and the values can be: +
      • a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the `dhx.methods` helper
      • a user-defined aggregation function `(i: IDataItem[]) => string | number`
    • `summary?: string` - optional, specifies where the total row is rendered - at the `top` or at the `bottom` of the group
config(object) optional, the configuration of data grouping. The configuration object may include the following properties:
  • `showMissed?: boolean | string` - optional, specifies whether the elements that don't have the field for grouping should be displayed, *true* by default
    • if set to *true*, the rows that don't have values for grouping are rendered row by row after all the data
    • if a *string* value is set, e.g. "Missed", the rows that don't have values for grouping are rendered as a separate group the name of which will have the specified string value. This group will be rendered as the last one
    • if set to *false*, the rows that don't suit the grouping criteria won't be rendered
  • `field?: string` - optional, the group field name, *"group"* by default
## Examples diff --git a/docs/data_collection/api/datacollection_isdataloaded_method.md b/docs/data_collection/api/datacollection_isdataloaded_method.md index 813d5da4..f2bfad39 100644 --- a/docs/data_collection/api/datacollection_isdataloaded_method.md +++ b/docs/data_collection/api/datacollection_isdataloaded_method.md @@ -6,15 +6,17 @@ description: You can explore the isDataLoaded method of DataCollection in the do # isDataLoaded() -{{pronote This functionality is available in the PRO edition only.}} +:::tip pro version only +The method works with the [Dynamic loading](helpers/lazydataproxy.md) functionality which is available in the PRO edition only. +::: @short: checks whether the specified data range is loaded from the server @signature: {'isDataLoaded(from?: number, to?: number): boolean;'} @params: -- `from: number` - optional, the index of the first element of the data range to be checked -- `to: number` - optional, the index of the last element of the data range to be checked +- `from?: number` - optional, the index of the first element of the data range to be checked +- `to?: number` - optional, the index of the last element of the data range to be checked @returns: `true`, if a range of data is loaded; otherwise, `false`. diff --git a/docs/data_collection/api/datacollection_load_method.md b/docs/data_collection/api/datacollection_load_method.md index a41c53b3..4f4586ba 100644 --- a/docs/data_collection/api/datacollection_load_method.md +++ b/docs/data_collection/api/datacollection_load_method.md @@ -8,12 +8,12 @@ description: You can explore the load method of DataCollection in the documentat @short: loads data from an external file -@signature: {'load?(url: string | DataProxy, driver?: object | string): Promise;'} +@signature: {'load(url: string | DataProxy, driver?: object | string): Promise;'} @params: - `url: string | IDataProxy` - the URL of an external file or DataProxy with the URL configured -- `driver: object | string` - optional, DataDriver or type of data ("json", "csv", "xml"), "json" by default +- `driver?: object | string` - optional, DataDriver or type of data ("json", "csv", "xml"), "json" by default @returns: A promise of data loading. @@ -34,7 +34,7 @@ The component will make an AJAX call and expect the remote URL to provide valid Data loading is asynchronous, so you need to wrap any after-loading code into a promise: ~~~jsx -component.data.load(url).then(function(){ +component.data.load(url).then(function () { //do something after load; }); ~~~ @@ -43,7 +43,7 @@ or ~~~jsx component.data.load(url); -component.data.loadData.then(function(){ +component.data.loadData.then(function () { //do something after load; }); // loadData executes a callback function after an asynchronous diff --git a/docs/data_collection/api/datacollection_map_method.md b/docs/data_collection/api/datacollection_map_method.md index f507b336..f51f7cce 100644 --- a/docs/data_collection/api/datacollection_map_method.md +++ b/docs/data_collection/api/datacollection_map_method.md @@ -6,22 +6,22 @@ description: You can explore the map method of DataCollection in the documentati # map() -@short: iterates through all items of the component +@short: iterates through all the items of the component @signature: {'map(callback: (item: object, index?: number, array?: object[]) => any): object[];'} @params: - `callback: function` - a function that will be called for each item of a component. The function is called with the following parameters: - - `item` - the object of an item - - `index` - the index of an item - - `array` - an array of items the method was called upon + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon @returns: A new array of items where each item is the result of the callback function. @example: // getting the ids of all items of the component -component.data.map(function(item, index, array){ +component.data.map(function (item, index, array) { return item.id; }); diff --git a/docs/data_collection/api/datacollection_maprange_method.md b/docs/data_collection/api/datacollection_maprange_method.md index ef1dfc91..8796111c 100644 --- a/docs/data_collection/api/datacollection_maprange_method.md +++ b/docs/data_collection/api/datacollection_maprange_method.md @@ -14,15 +14,15 @@ description: You can explore the mapRange method of DataCollection in the docume - `from: number` - the initial position of an item in the range - `to: number` - the final position of an item in the range - `callback: function` - a function that will be called for each item from the specified range. The function is called with the following parameters: - - `item` - the object of an item - - `index` - the index of an item - - `array` - an array of items the method was called upon + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon @returns: A new array of matching item objects. @example: -const result = component.data.mapRange(0, 20, function(item, index, array) { +const result = component.data.mapRange(0, 20, function (item, index, array) { console.log(item.id, index); }); diff --git a/docs/data_collection/api/datacollection_move_method.md b/docs/data_collection/api/datacollection_move_method.md index f6f07cae..c8236eb9 100644 --- a/docs/data_collection/api/datacollection_move_method.md +++ b/docs/data_collection/api/datacollection_move_method.md @@ -13,13 +13,13 @@ description: You can explore the move method of DataCollection in the documentat @params: - `id: string | string[]` - the ids of items to move - `index: number` - the index to move items to -- `target: object` - optional, the target data collection object +- `target?: object` - optional, the target data collection object @returns: Either the item's id or an array with ids of items. @example: -component.data.move("4",5); // moves the item with id:4 to the position with index 5 +component.data.move("4", 5); // moves the item with id:4 to the position with index 5 @descr: diff --git a/docs/data_collection/api/datacollection_parse_method.md b/docs/data_collection/api/datacollection_parse_method.md index b02d3d2e..e3a7f8ff 100644 --- a/docs/data_collection/api/datacollection_parse_method.md +++ b/docs/data_collection/api/datacollection_parse_method.md @@ -12,7 +12,7 @@ description: You can explore the parse method of DataCollection in the documenta @params: - `data: array | string` - the data to load -- `driver: object | string` - optional, DataDriver or type of data ("json", "csv", "xml"), "json" by default +- `driver?: object | string` - optional, DataDriver or type of data ("json", "csv", "xml"), "json" by default @example: const dataset = [ diff --git a/docs/data_collection/api/datacollection_reduce_method.md b/docs/data_collection/api/datacollection_reduce_method.md index 5e3c39ef..a63029f8 100644 --- a/docs/data_collection/api/datacollection_reduce_method.md +++ b/docs/data_collection/api/datacollection_reduce_method.md @@ -8,20 +8,21 @@ description: You can explore the reduce method of DataCollection in the document @short: reduces the array to a single value -@signature: {'reduce(callback: (acc: any, item: any) => any, acc: any): any;'} +@signature: {'reduce(callback: (acc: any, item: any, index: number) => any, acc: any): any;'} @params: -- `callback: function` - a function that will be called for each item in the array. The function takes two parameters: - - `acc` - the initialValue, or the previously returned value of the function - - `item` - the current item of a data collection +- `callback: function` - a function that will be called for each item in the array. The function is called with the following parameters: + - `acc: any` - the *initialValue*, or the previously returned value of the function + - `item: any` - the current item of a data collection + - `index: number` - the index of the item - `acc: any` - a value to be passed to the function as the initial value @returns: A single output value. @example: -const total = component.data.reduce(function(acc, item) { +const total = component.data.reduce(function (acc, item, index) { return acc + item.value; }, 0); diff --git a/docs/data_collection/api/datacollection_resetfilter_method.md b/docs/data_collection/api/datacollection_resetfilter_method.md index 4a55a9da..ba138bb6 100644 --- a/docs/data_collection/api/datacollection_resetfilter_method.md +++ b/docs/data_collection/api/datacollection_resetfilter_method.md @@ -8,12 +8,17 @@ description: You can explore the resetFilter method of DataCollection in the doc @short: resets the active filters -@signature: {'resetFilter(config?: object): boolean;'} +@signature: {'resetFilter(config?: object, silent?: boolean): boolean;'} @params: -- `config: object` - optional, specifies the parameters of resetting the active filters. If the config isn't specified or it is empty, all the filters except for those that have the **permanent** property in the configuration object will be reset. Can contain the following properties: - - `id: string` - optional, the id of the filter to reset - - `permanent: boolean` - optional, *true* to reset all the active filters, including those that have the **permanent:true** property in their config +- `config?: object` - optional, specifies the parameters of resetting the active filters. If the config isn't specified or it is empty, all the filters except for those that have the `permanent` property in the configuration object will be reset. Can contain the following properties: + - `id?: string` - optional, the id of the filter to reset + - `permanent?: boolean` - optional, *true* to reset all the active filters, including those that have the `permanent:true` property in their config +- `silent?: boolean` - optional, if set to *true*, the method will be called without triggering events, *false* by default + +:::info +Note that after calling the method with the `silent:true` parameter, you may need to repaint the component with the `paint()` method. +::: @returns: - `result: boolean` - *true*, if all the filters, including the permanent ones, have been reset; otherwise *false* diff --git a/docs/data_collection/api/datacollection_save_method.md b/docs/data_collection/api/datacollection_save_method.md index 0a8fc496..6bf0d07a 100644 --- a/docs/data_collection/api/datacollection_save_method.md +++ b/docs/data_collection/api/datacollection_save_method.md @@ -8,29 +8,29 @@ description: You can explore the save method of DataCollection in the documentat @short: saves changes made in a data collection to the server side -@signature: {'save?: (url: string | IDataProxy) => void;'} +@signature: {'save(url: IDataProxy | string): void;'} @params: -- `url: string | IDataProxy` - the URL of a server side or DataProxy with the URL configured +- `url: IDataProxy | string` - the URL of a server side or DataProxy with the URL configured @example: grid.data.save("http://userurl/"); //or -grid.data.save(new DataProxy({url:"http://userurl/"})); +grid.data.save(new DataProxy({ url:"http://userurl/" })); @descr: -Each time the user changes data of the component, the **save()** method will make an AJAX call and expect the remote URL to save data changes. +Each time the user changes data of the component, the `save()` method will make an AJAX call and expect the remote URL to save data changes. The method will send one of the following requests to the backend: - `POST` - after adding new data into the component; - `PUT` - after editing data of the component; - `DELETE` - after deleting data. -Data saving is asynchronous, so you need to return a promise - the result of the saving operation. To do this, use the **saveData** property that returns a "promise" object: +Data saving is asynchronous, so you need to return a promise - the result of the saving operation. To do this, use the `saveData` property that returns a "promise" object: -~~~js +~~~jsx const data = new DataCollection(); data.save(loader); return data.saveData.then(function () { @@ -38,9 +38,9 @@ return data.saveData.then(function () { }); ~~~ -Use the [isSaved](data_collection/api/datacollection_issaved_method.md) method to know whether the changes are saved: +Use the [`isSaved`](data_collection/api/datacollection_issaved_method.md) method to know whether the changes are saved: -~~~js +~~~jsx grid.data.saveData.then(function () { console.log(grid.data.isSaved()); }); diff --git a/docs/data_collection/api/datacollection_serialize_method.md b/docs/data_collection/api/datacollection_serialize_method.md index 5d28c6d8..d23f3d09 100644 --- a/docs/data_collection/api/datacollection_serialize_method.md +++ b/docs/data_collection/api/datacollection_serialize_method.md @@ -11,7 +11,7 @@ description: You can explore the serialize method of DataCollection in the docum @signature: {'serialize(driver?: string): object[];'} @params: -- `driver: string` - optional, the format that the data will be serialized into ("json", "csv", "xml"), "json" by default +- `driver?: string` - optional, the format that the data will be serialized into ("json", "csv", "xml"), "json" by default @returns: Returns serialized data for each item of the component either as an array of JSON objects or as a CSV/XML string. diff --git a/docs/data_collection/api/datacollection_sort_method.md b/docs/data_collection/api/datacollection_sort_method.md index 593e9e3b..3658beb7 100644 --- a/docs/data_collection/api/datacollection_sort_method.md +++ b/docs/data_collection/api/datacollection_sort_method.md @@ -11,19 +11,19 @@ description: You can explore the sort method of DataCollection in the documentat @signature: {'sort(rule?: object, config?: object): void;'} @params: -- `rule: object` - an object with parameters for sorting. The object has the following attributes: - - `by: string | number` - the id of a data field - - `dir: string` - the direction of sorting: "asc" or "desc" - - `as: function` - a function that specifies the type to sort data as - - `rule: function` - optional, a sorting rule; the function must have two parameters and return a number (-1,0,1) -- `config: object` - defines the parameter of sorting. It may contain one property: - - `smartSorting: boolean` - specifies whether a sorting rule should be applied each time after changing the data set +- `rule?: object` - optional, an object with parameters for sorting. The object has the following attributes: + - `by?: string | number` - optional, the id of a data field + - `dir?: string` - optional, the direction of sorting: "asc" or "desc" + - `as?: function` - optional, a function that specifies the type to sort data as + - `rule?: function` - optional, a sorting rule; the function must have two parameters and return a number (-1,0,1) +- `config?: object` - optional, defines the parameter of sorting. It may contain one property: + - `smartSorting?: boolean` - optional, specifies whether a sorting rule should be applied each time after changing the data set @example: grid.data.sort( { - by:"a", - dir:"desc", + by: "a", + dir: "desc", as: item => (item.toUpperCase()) }, { smartSorting: true } diff --git a/docs/data_collection/api/datacollection_update_method.md b/docs/data_collection/api/datacollection_update_method.md index 441eeacc..0530eaf5 100644 --- a/docs/data_collection/api/datacollection_update_method.md +++ b/docs/data_collection/api/datacollection_update_method.md @@ -8,16 +8,32 @@ description: You can explore the update method of DataCollection in the document @short: updates properties of the item -@signature: {'update?: (id: string | number, newItem: object) => void;'} +@signature: {'update?: (id: string | number, newItem: object, silent?: boolean) => void;'} @params: - `id: string | number` - the id of the item which needs to be updated - `newItem: object` - a hash of properties which need to be updated +- `silent?: boolean` - optional, if set to *true*, the method will be called without triggering events, *false* by default + +:::info +Note that after calling the method with the `silent:true` parameter, you may need to repaint the component with the `paint()` method. +::: @example: component.data.update(123, { text:"New text" }); @descr: +Also note, that for correct work of the method the last update of a data collection should be done with the `silent:false` setting applied, for example: + +~~~jsx +const lastIndex = data.getLength() - 1; + +data.forEach((item, index) => { + data.update(item.id, { + param: "change param", + }, index != lastIndex); // the last update isn't silent, as the `silent:false` parameter is set +}); +~~~ **Related sample**: [Data. Update](https://snippet.dhtmlx.com/4g90gi6b) From 8559ddd00d0e3cc06ef250ccf308a754b53fd44e Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Fri, 28 Mar 2025 17:11:20 +0300 Subject: [PATCH 13/14] [update] data collection guides and related docs --- .../api/datacollection_group_method.md | 4 +- .../api/datacollection_remove_method.md | 2 +- docs/grid/data_loading.md | 34 ++++- docs/grid/usage.md | 4 +- docs/guides/datacollection/grouping_data.md | 32 ++-- docs/guides/datacollection/loading_data.md | 116 +++++++++++++-- .../datacollection/working_with_data_items.md | 139 +++++++++++------- docs/guides/events_guide.md | 62 ++++---- docs/list/load_data.md | 2 +- 9 files changed, 267 insertions(+), 128 deletions(-) diff --git a/docs/data_collection/api/datacollection_group_method.md b/docs/data_collection/api/datacollection_group_method.md index eecb5e68..7f6fdf3d 100644 --- a/docs/data_collection/api/datacollection_group_method.md +++ b/docs/data_collection/api/datacollection_group_method.md @@ -43,8 +43,8 @@ group(order: TGroupOrder[], config?: IGroupConfig): void; order - (array) an array that defines the order and configuration for data grouping. Each element in the array can be:
  • a string that represents a grouping field
  • a function `(i: IDataItem) => string` for dynamic defining of a group
  • an `IGroupOrder` object that has the following properties:
    • `by: string | function` - the field name or a function for user-defined grouping
    • `map?: object` - optional, an object for data aggregation in a group, where the keys are field names, and the values can be: -
      • a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the `dhx.methods` helper
      • a user-defined aggregation function `(i: IDataItem[]) => string | number`
    • `summary?: string` - optional, specifies where the total row is rendered - at the `top` or at the `bottom` of the group
+ (array) an array that defines the order and configuration for data grouping. Each element in the array can be:
  • a string that represents a grouping field
  • a function `(item: IDataItem) => string` for dynamic defining of a group
  • an `IGroupOrder` object that has the following properties:
    • `by: string | function` - the field name or a function for user-defined grouping
    • `map?: object` - optional, an object for data aggregation in a group, where the keys are field names, and the values can be: +
      • a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the `dhx.methods` helper
      • a user-defined aggregation function `(item: IDataItem[]) => string | number`
    • `summary?: string` - optional, specifies where the total row is rendered - at the `top` or at the `bottom` of the group
config diff --git a/docs/data_collection/api/datacollection_remove_method.md b/docs/data_collection/api/datacollection_remove_method.md index c54c3ffe..9c940ff6 100644 --- a/docs/data_collection/api/datacollection_remove_method.md +++ b/docs/data_collection/api/datacollection_remove_method.md @@ -16,7 +16,7 @@ description: You can explore the remove method of DataCollection in the document @example: component.data.remove("2"); //or -component.data.remove([ "2", "4" ]); +component.data.remove(["2", "4"]); @descr: diff --git a/docs/grid/data_loading.md b/docs/grid/data_loading.md index 1b69dec4..30836e2b 100644 --- a/docs/grid/data_loading.md +++ b/docs/grid/data_loading.md @@ -73,7 +73,7 @@ const grid = new dhx.Grid("grid_container", { columns: [ // columns config ], - data: dataset + // more options }); ~~~ @@ -91,7 +91,12 @@ There are two ways to load data into Grid after its initialization: To load data from an external file, make use of the **load()** method of [Data Collection](data_collection.md). It takes the URL of the file with data as a parameter: ~~~jsx -const grid = new dhx.Grid("grid_container"); +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + // more options +}); grid.data.load("../common/dataset.json"); ~~~ @@ -112,7 +117,12 @@ grid.data.load("/some/data").then(function(){ To load data from a local data source, use the `parse()` method of [Data Collection](data_collection.md). Pass [a predefined data set](#preparing-data-set) as a parameter of this method: ~~~jsx -const grid = new dhx.Grid("grid_container"); +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + // more options +}); grid.data.parse(dataset); ~~~ @@ -126,7 +136,7 @@ Note that for loading data from a **CSV file** into a grid, you need to: Check the example below: ~~~jsx -const grid = new dhx.Grid("grid", { +const grid = new dhx.Grid("grid_container", { columns: [ { width: 150, id: "country", header: [{ text: "Country" }] }, { width: 150, id: "population", header: [{ text: "Population" }] }, @@ -148,7 +158,7 @@ grid.data.parse(csvData, csvDataDriver); ## Saving and restoring state -To save the current state of a grid, use the **serialize()** method of [Data Collection](data_collection.md). It converts the data of a grid into an array of JSON objects. +To save the current state of a grid, use the `serialize()` method of [Data Collection](data_collection.md). It converts the data of a grid into an array of JSON objects. Each JSON object contains the configuration of a separate row. ~~~jsx @@ -159,7 +169,12 @@ Then you can parse the data stored in the saved state array to a different grid. ~~~jsx // creating a new grid -const grid2 = new dhx.Grid(document.body); +const grid2 = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + // more options +}); // parsing the state of grid1 into grid2 grid2.data.parse(state); ~~~ @@ -186,7 +201,12 @@ new dhx.LazyDataProxy("https://docs.dhtmlx.com/suite/backend/lazyload", { - load data into Grid via the `load()` method of Data Collection and pass `lazyDataProxy` as a parameter of this method: ~~~jsx -const grid = new dhx.Grid("grid_container"); +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + // more options +}); grid.data.load(lazyDataProxy); ~~~ diff --git a/docs/grid/usage.md b/docs/grid/usage.md index a8f6bd27..7ae103e3 100644 --- a/docs/grid/usage.md +++ b/docs/grid/usage.md @@ -1021,12 +1021,12 @@ The method takes the following parameters: - `order` - an array that defines the order and configuration for data grouping. Each element in the array can be: - a string that represents a grouping field - - a function `(i: IDataItem) => string` for dynamic defining of a group + - a function `(item: IDataItem) => string` for dynamic defining of a group - an `IGroupOrder` object that has the following properties: - `by` - the field name or a function for user-defined grouping - `map` - (optional) an object for data aggregation in a group, where the keys are field names, and the values can be: - a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the [`dhx.methods`](helpers/data_calculation_functions.md) helper - - a user-defined aggregation function `(i: IDataItem[]) => string | number` + - a user-defined aggregation function `(item: IDataItem[]) => string | number` - `summary` - (optional) specifies where the total row is rendered - at the `top` or at the `bottom` of the group - `config` - (optional) the configuration of data grouping - `showMissed` - (optional) specifies whether the elements that don't have the field for grouping should be displayed, *true* by default diff --git a/docs/guides/datacollection/grouping_data.md b/docs/guides/datacollection/grouping_data.md index 9107773a..fccf9d54 100644 --- a/docs/guides/datacollection/grouping_data.md +++ b/docs/guides/datacollection/grouping_data.md @@ -16,23 +16,21 @@ The DataCollection API can be used for working with [data grouping in Grid](grid ## Grouping data -The [`group()`](data_collection/api/datacollection_group_method.md) method of DataCollection groups data in a collection that has a plain tree-like structure according to the specified order and additional configuration. The method takes the following parameters: - -- `order` - an array that defines the order and configuration for data grouping. Each element in the array can be: - - a string that represents a grouping field - - a function `(i: IDataItem) => string` for dynamic defining of a group - - an `IGroupOrder` object that has the following properties: - - `by` - the field name or a function for user-defined grouping - - `map` - (optional) an object for data aggregation in a group, where the keys are field names, and the values can be: - - a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the [`dhx.methods`](helpers/data_calculation_functions.md) helper - - a user-defined aggregation function `(i: IDataItem[]) => string | number` - - `summary` - (optional) specifies where the total row is rendered - at the `top` or at the `bottom` of the group -- `config` - (optional) the configuration of data grouping - - `showMissed` - (optional) specifies whether the elements that don't have the field for grouping should be displayed, *true* by default - - if set to *true*, the rows that don't have values for grouping are rendered row by row after all the data - - if a *string* value is set, e.g. "Missed", the rows that don't have values for grouping are rendered as a separate group the name of which will have the specified string value. This group will be rendered as the last one - - if set to *false*, the rows that don't suit the grouping criteria won't be rendered - - `field` - (optional) the group field name, *"group"* by default +The [`group()`](data_collection/api/datacollection_group_method.md) method of DataCollection groups data in a collection that has a flat tree structure according to the specified order and additional configuration. The method takes the following parameters: + + + + + + + + + + + + +
order (array) an array that defines the order and configuration for data grouping. Each element in the array can be:
  • a string that represents a grouping field
  • a function `(item: IDataItem) => string` for dynamic defining of a group
  • an `IGroupOrder` object that has the following properties:
    • `by: string | function` - the field name or a function for user-defined grouping
    • `map?: object` - optional, an object for data aggregation in a group, where the keys are field names, and the values can be: +
      • a tuple `[string, TAggregate]` that specifies the field and the aggregation type ("sum", "count", "min", "max", "avg") from the `dhx.methods` helper
      • a user-defined aggregation function `(item: IDataItem[]) => string | number`
    • `summary?: string` - optional, specifies where the total row is rendered - at the `top` or at the `bottom` of the group
config(object) optional, the configuration of data grouping. The configuration object may include the following properties:
  • `showMissed?: boolean | string` - optional, specifies whether the elements that don't have the field for grouping should be displayed, *true* by default
    • if set to *true*, the rows that don't have values for grouping are rendered row by row after all the data
    • if a *string* value is set, e.g. "Missed", the rows that don't have values for grouping are rendered as a separate group the name of which will have the specified string value. This group will be rendered as the last one
    • if set to *false*, the rows that don't suit the grouping criteria won't be rendered
  • `field?: string` - optional, the group field name, *"group"* by default
There are several examples of grouping Grid data via the `group()` method of DataCollection: diff --git a/docs/guides/datacollection/loading_data.md b/docs/guides/datacollection/loading_data.md index 8b9cfab0..a5f5c260 100644 --- a/docs/guides/datacollection/loading_data.md +++ b/docs/guides/datacollection/loading_data.md @@ -6,7 +6,7 @@ description: You can learn how to load and save data with DataCollection in the # Loading and saving data -You can load data into a component from an external file or from a local data source via the DataCollection API. It also allows saving the state of a component and sending it to a different component, as well as saving changes made in the data to the server side. +You can load data into a component from an external file, a local data source or the server side via the DataCollection API. It also allows saving the state of a component and sending it to a different component, as well as saving changes made in the data to the server side. :::info Please note that if you specify the `id` fields in the loaded data collection, their values should be **unique**. You can also omit the `id` fields in the data collection. In this case they will be generated automatically. @@ -27,7 +27,7 @@ The component will make an AJAX call and expect the remote URL to provide valid Data loading is asynchronous, so you need to wrap any after-loading code into a promise: ~~~jsx -component.data.load(url).then(function(){ +component.data.load(url).then(function () { // do something after load }); ~~~ @@ -36,7 +36,7 @@ or ~~~jsx component.data.load(url); -component.data.loadData.then(function(){ +component.data.loadData.then(function () { // do something after load }); // loadData executes a callback function after an asynchronous @@ -74,6 +74,70 @@ dataview.data.parse(dataset); **Related sample**: [Data. Parse](https://snippet.dhtmlx.com/0zrxtmvi) +## Dynamic loading + +:::tip pro version only +This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package +::: + +You can load data from the server into DHTMLX Grid or DHTMLX List dynamically. It means that data is loaded +partially, on demand, and only those records that are in the visible area are rendered. + +To use this functionality, you should take the following steps: + +- initialize the `LazyDataProxy` helper as described in the [Dynamic Loading](helpers/lazydataproxy.md) article: + +~~~jsx +new dhx.LazyDataProxy("https://docs.dhtmlx.com/suite/backend/lazyload", { + limit: 30, + prepare: 5, + delay: 150, + from: 0 +}); +~~~ + +:::info +To enable dynamic rendering of List items, switch on the `virtual` property of the component: + +~~~jsx +const list = new dhx.List("list_container", { + virtual: true +}); +~~~ +::: + +- load data into Grid or List via the `load()` method of Data Collection and pass `lazyDataProxy` as a parameter of this method: + +~~~jsx +// for Grid +const grid = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + // more options +}); +grid.data.load(lazyDataProxy); +~~~ + +**Related sample**: [External data lazy load](https://snippet.dhtmlx.com/grid_lazy_loading) + +~~~jsx +// for List +const list = new dhx.List("list_container"); +list.data.load(lazyDataProxy); +~~~ + +**Related sample**: [List. External data lazy loading](https://snippet.dhtmlx.com/list_lazy_loading) + +Read the related guides for detailed information: + +- [dynamic loading in Grid](grid/data_loading.md#dynamic-loading) +- [dynamic loading in List](list/load_data.md#dynamic-loading) + +:::info +The `sort()` method of Data Collection will not work until all data are loaded into Grid/List. Note that for correct work of lazy loading, you should send all changes in Data Collection to the server at the proper time. +::: + ## Checking whether data is loaded You can check whether the specified data range is loaded from the server using the [`isDataLoaded()`](data_collection/api/datacollection_isdataloaded_method.md) method of [DataCollection](data_collection.md). @@ -84,8 +148,8 @@ The method works with the [Dynamic loading](helpers/lazydataproxy.md) functional The method takes the following parameters: -- `from: number` - optional, the index of the first element of the data range to be checked -- `to: number` - optional, the index of the last element of the data range to be checked +- `from?: number` - optional, the index of the first element of the data range to be checked +- `to?: number` - optional, the index of the last element of the data range to be checked and returns `true`, if a range of data is loaded; otherwise, `false`. @@ -97,7 +161,7 @@ component.data.isDataLoaded(); To save the current state of a component, use the [`serialize()`](data_collection/api/datacollection_serialize_method.md) method of Data Collection. The method is used to serialize data into the JSON, XML or CSV format. It takes the following parameter: -- `driver: string` - optional, the format that the data will be serialized into ("json" (default), "csv", "xml") +- `driver?: string` - optional, the format that the data will be serialized into ("json" (default), "csv", "xml") and returns serialized data for each item of the component either as an array of JSON objects or as a CSV/XML string. @@ -113,12 +177,44 @@ After you've saved a component's state, you can send the data stored in the save ~~~jsx // creating a new grid -const grid2 = new dhx.Grid(document.body); +const grid2 = new dhx.Grid("grid_container", { + columns: [ + // columns config + ], + // more options +}); // parsing the state of grid1 into grid2 grid2.data.parse(state); ~~~ -## Saving data changes to the server side +## Working with the server side + +To provide communication with the server side, you can use the [`DataProxy`](data_proxy.md) helper. Using this helper you can create a custom URL and assign it to a variable to simplify work with the server-side backend. For example: + +~~~jsx +const proxy = new dhx.DataProxy("someUrl", { + // config options +}); +~~~ + +The `dhx.DataProxy` helper takes two parameters: + +- `url: string` - the external URL +- `params?: object` - optional, a set of custom parameters to be sent to the server with a request + +### Loading data from the server side + +You can apply a custom URL configured by the DataProxy helper to DataCollection while loading data with the [`load()`](data_collection/api/datacollection_load_method.md) method. As a parameter, pass the DataProxy with the configured URL: + +~~~jsx +const dataCollection = new dhx.DataCollection(); +const proxy = new dhx.DataProxy("https://myCustomUrl.com"); +dataCollection.load(proxy); +~~~ + +The same as with [loading data from an external file](#loading-data-from-an-external-file), the component will make an AJAX call and expect the remote URL to provide valid JSON data. + +### Saving data changes to the server side You can save changes made in the data to the server side using the [`save()`](data_collection/api/datacollection_save_method.md) method of Data Collection. The method takes the following parameter: @@ -144,7 +240,7 @@ Data saving is asynchronous, so you need to return a promise - the result of the ~~~jsx const data = new DataCollection(); data.save(loader); -return data.saveData.then(function(){ +return data.saveData.then(function () { // now your data is saved }); ~~~ @@ -152,7 +248,7 @@ return data.saveData.then(function(){ Use the [`isSaved()`](data_collection/api/datacollection_issaved_method.md) method to check whether the changes are saved. The method returns *true*, if the changes are saved, otherwise, *false*. ~~~jsx -grid.data.saveData.then(function(){ +grid.data.saveData.then(function () { console.log(grid.data.isSaved()); }); ~~~ \ No newline at end of file diff --git a/docs/guides/datacollection/working_with_data_items.md b/docs/guides/datacollection/working_with_data_items.md index 54347008..007eecd8 100644 --- a/docs/guides/datacollection/working_with_data_items.md +++ b/docs/guides/datacollection/working_with_data_items.md @@ -6,7 +6,7 @@ description: You can learn how to work with DataCollection items in the document # Working with data items -The DataCollection API provides a wide set of methods for working with data items. You can get the id/index of an item, add, update, delete, copy, move data items, find necessary items, iterate over items, etc. +The [DataCollection API](data_collection.md) provides a wide set of methods for working with data items. You can get the id/index of an item, add, update, delete, copy, move data items, find necessary items, iterate over items, etc. ## Getting the id of an item @@ -47,10 +47,10 @@ const text = item.text; ## Adding items -To add new items into a component, use the [`add()`](data_collection/api/datacollection_add_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: +To add new items into a component, use the [`add()`](data_collection/api/datacollection_add_method.md) method of DataCollection. The method takes two parameters: - `new_item: object | array` - the object of a new item or an array of item objects -- `index: number` - optional, the index of the position starting from which new items will be added +- `index?: number` - optional, the index of the position starting from which new items will be added and returns either the item's id or an array with the ids of items. @@ -83,19 +83,19 @@ component.data.add([ ## Removing items -To delete the specified item from the component, use the [`remove()`](data_collection/api/datacollection_remove_method.md) method. The method takes the following parameter: +To delete the specified item from the component, use the [`remove()`](data_collection/api/datacollection_remove_method.md) method of DataCollection. The method takes the following parameter: - `id: string | string[]` - the ids of the items that should be deleted ~~~jsx component.data.remove("2"); //or -component.data.remove([ "2", "4" ]); +component.data.remove(["2", "4"]); ~~~ **Related sample**: [Data. Remove](https://snippet.dhtmlx.com/ugdlqgp5) -To delete all items from the component, use the [`removeAll()`](data_collection/api/datacollection_removeall_method.md) method. +To delete all items from the component, use the [`removeAll()`](data_collection/api/datacollection_removeall_method.md) method of DataCollection. ~~~jsx component.data.removeAll(); @@ -105,24 +105,41 @@ component.data.removeAll(); ## Updating items -You can update the properties of the item with the help of the [`update()`](data_collection/api/datacollection_update_method.md) method. The method takes two parameters: +You can update the properties of the item with the help of the [`update()`](data_collection/api/datacollection_update_method.md) method of DataCollection. The method takes the following parameters: - `id: string | number` - the id of the item which needs to be updated - `newItem: object` - a hash of properties which need to be updated +- `silent?: boolean` - optional, if set to *true*, the method will be called without triggering events, *false* by default ~~~jsx component.data.update(123, { text:"New text" }); ~~~ +:::info +Note that after calling the method with the `silent:true` parameter, you may need to repaint the component with the `paint()` method. +::: + +For correct work of the method the last update of a data collection should be done with the `silent:false` setting applied, for example: + +~~~jsx +const lastIndex = data.getLength() - 1; + +data.forEach((item, index) => { + data.update(item.id, { + param: "change param", + }, index != lastIndex); // the last update isn't silent, as the `silent:false` parameter is set +}); +~~~ + **Related sample**: [Data. Update](https://snippet.dhtmlx.com/4g90gi6b) ## Copying items -The [`copy()`](data_collection/api/datacollection_copy_method.md) method will help you to create a copy of an item at the defined position. The method takes the following parameters: +The [`copy()`](data_collection/api/datacollection_copy_method.md) method of DataCollection will help you to create a copy of an item at the defined position. The method takes the following parameters: - `id: (string | number) | (string | number)[]` - the id of an item or an array with ids of items to copy - `index: number` - the index to create a copy at -- `target: object` - optional, the target data collection object +- `target?: object` - optional, the target data collection object and returns the item's id or an array with ids of items. @@ -134,16 +151,16 @@ component.data.copy("4", 5); // copies the item with id:4 to the position with i ## Moving items -You can move an item/items to the defined position using the [`move()`](data_collection/api/datacollection_move_method.md) method. It takes the following parameters: +You can move an item/items to the defined position using the [`move()`](data_collection/api/datacollection_move_method.md) method of DataCollection. It takes the following parameters: - `id: string | string[]` - the ids of items to move - `index: number` - the index to move items to -- `target: object` - optional, the target data collection object +- `target?: object` - optional, the target data collection object The method returns either an item's id or an array with the ids of items. ~~~jsx -component.data.move("4",5); // moves the item with id:4 to the position with index 5 +component.data.move("4", 5); // moves the item with id:4 to the position with index 5 ~~~ **Related sample**: [Data. Move](https://snippet.dhtmlx.com/fi66bi8h) @@ -153,8 +170,8 @@ component.data.move("4",5); // moves the item with id:4 to the position with ind You can change the id of the necessary element of a data collection, using the [`changeId()`](data_collection/api/datacollection_changeid_method.md) method. The method takes the following parameters: - `id: string | number` - the old id of an item -- `newId: string | number` - optional, the new id; auto-generated if not set -- `silent: boolean` - optional, *true* to prevent changing the id; otherwise, *false* +- `newId?: string | number` - optional, the new id; auto-generated if not set +- `silent?: boolean` - optional, if set to *true*, the method will be called without triggering events; otherwise, *false* ~~~jsx component.data.changeId("1", "22"); @@ -179,9 +196,13 @@ const item = component.data.exists("1"); You can get the number of items in a data collection via the [`getLength()`](data_collection/api/datacollection_getlength_method.md) method. ~~~jsx -const items = component.data.getLength(); +const dataLength = component.data.getLength(); ~~~ +:::info note +Note that for [TreeCollection](tree_collection.md) the [`getLength()`](tree_collection/api/treecollection_getlength_method.md) method will return the number of the child items of the component. +::: + **Related sample**: [Data. Get length](https://snippet.dhtmlx.com/4weiba8i) ## Searching for certain data items @@ -190,54 +211,58 @@ You can find data items that match some criteria. The DataCollection API allows ### Searching for a particular item -The [`find()`](data_collection/api/datacollection_find_method.md) method finds the item that corresponds to the specified rule. It takes the following parameter: +The [`find()`](data_collection/api/datacollection_find_method.md) method of DataCollection finds the item that corresponds to the specified rule. It takes the following parameter: - `rule: object | function` - the search criteria: - - if set as an *object*, the parameter contains the following attributes: + - if set as an object, the parameter contains the following attributes: - `by: string | function` - the search criterion (either the key of the item attribute or a search function) - `match: string` - the value of the item attribute - - if set as a *function*, the search will be applied by the rule specified in the function. The function may take three parameters: - - `item` - (required) the object of an item - - `index` - (optional) the index of an item - - `array` - (optional) an array with items + - if set as a function, the search will be applied by the rule specified in the function. The function takes three parameters: + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon The method returns the object of the matching item. ~~~jsx -//searching for an item by the function -const item = component.data.find(function(item){ - if(item.text==="Manager"||item.text==="Marketer"){return true} +// searching for an item by the function +const item = component.data.find(function (item) { + if (item.text === "Manager" || item.text === "Marketer") { + return true + } }); -//searching for an item by the attribute key -const item = component.data.find({ by:"text",match:"Manager" }); +// searching for an item by the attribute key +const item = component.data.find({ by: "text", match: "Manager" }); ~~~ **Related sample**: [Data. Find](https://snippet.dhtmlx.com/fpxhdc46) ### Searching for several items -The [`findAll()`](data_collection/api/datacollection_findall_method.md) method finds all the items that correspond to the specified rule. It takes the following parameter: +The [`findAll()`](data_collection/api/datacollection_findall_method.md) method of DataCollection finds all the items that correspond to the specified rule. It takes the following parameter: - `rule: object | function` - the search criteria: - - if set as an *object*, the parameter contains the following attributes: + - if set as an object, the parameter contains the following attributes: - `by: string | function` - the search criterion (either the key of the item attribute or a search function) - `match: string` - the value of the item attribute - - if set as a *function*, the search will be applied by the rule specified in the function. The function may take three parameters: - - `item` - (required) the object of an item - - `index` - (optional) the index of an item - - `array` - (optional) an array with items + - if set as a function, the search will be applied by the rule specified in the function. The function takes three parameters: + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon The method returns an array of matching item objects. -~~~js -//searching for items by the function -const items = component.data.findAll(function(items){ - if(items.text==="Manager"||items.text==="Marketer"){return true} +~~~jsx +// searching for items by the function +const items = component.data.findAll(function (items) { + if (items.text === "Manager" || items.text === "Marketer") { + return true + } }); -//searching for items by the attribute key -const items = component.data.findAll({ by:"text",match:"Manager" }); +// searching for items by the attribute key +const items = component.data.findAll({ by: "text", match: "Manager" }); ~~~ **Related sample**: [Data. Find all](https://snippet.dhtmlx.com/kvemrz93) @@ -249,12 +274,12 @@ You can iterate through the items of a data collection, the items of a component ### Iterating through the items of a data collection The [`forEach()`](data_collection/api/datacollection_foreach_method.md) method iterates through all the items of a data collection. It takes as a parameter a callback function that will iterate over items of a data collection and is called with the following parameters: - - `item` - the object of an item - - `index` - the index of an item - - `array` - an array with items + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon ~~~jsx -component.data.forEach(function(item, index, array) { +component.data.forEach(function (item, index, array) { console.log("This is an item of dataCollection: ", item); console.log("This is an index of the element: ", index); console.log("This is an array of the elements: ", array); @@ -265,16 +290,16 @@ component.data.forEach(function(item, index, array) { ### Iterating through the items of a component -The [`map()`](data_collection/api/datacollection_map_method.md) method iterates through all the items of the component. As a parameter it takes a callback function that will be called for each item of a component. The function is called with the following parameters: - - `item` - the object of an item - - `index` - the index of an item - - `array` - an array of items the method was called upon +The [`map()`](data_collection/api/datacollection_map_method.md) method of DataCollection iterates through all the items of the component. As a parameter it takes a callback function that will be called for each item of a component. The function is called with the following parameters: + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon and returns a new array of items where each item is the result of the callback function. ~~~jsx // getting the ids of all the items of the component -component.data.map(function(item, index, array){ +component.data.map(function (item, index, array) { return item.id; }); ~~~ @@ -283,37 +308,37 @@ component.data.map(function(item, index, array){ ### Iterating through the items of a specified range -The [`mapRange()`](data_collection/api/datacollection_maprange_method.md) method returns a new array of the items corresponding to the specified parameters. The method takes the following parameters: +The [`mapRange()`](data_collection/api/datacollection_maprange_method.md) method of DataCollection returns a new array of the items corresponding to the specified parameters. The method takes the following parameters: - `from: number` - the initial position of an item in the range - `to: number` - the final position of an item in the range - `callback: function` - a function that will be called for each item from the specified range. The function is called with the following parameters: - - `item` - the object of an item - - `index` - the index of an item - - `array` - an array of items the method was called upon + - `item: object` - the object of an item + - `index?: number` - optional, the index of an item + - `array?: object[]` - optional, an array of items the method was called upon and returns a new array of matching item objects. ~~~jsx -const result = component.data.mapRange(0, 20, function(item, index, array) { +const result = component.data.mapRange(0, 20, function (item, index, array) { console.log(item.id, index); }); ~~~ ## Reducing an array of items -You can reduce an array of items to a single value with the [`reduce()`](data_collection/api/datacollection_reduce_method.md) method. It takes the following parameters: +You can reduce an array of items to a single value with the [`reduce()`](data_collection/api/datacollection_reduce_method.md) method of DataCollection. It takes the following parameters: - `callback: function` - a function that will be called for each item in the array. The function is called with the following parameters: - - `acc` - the *initialValue*, or the previously returned value of the function - - `item` - the current item of a data collection - - `index` - the index of the item + - `acc: any` - the *initialValue*, or the previously returned value of the function + - `item: any` - the current item of a data collection + - `index: number` - the index of the item - `acc: any` - a value to be passed to the function as the initial value and returns a single output value. ~~~jsx -const total = component.data.reduce(function(acc, item, index) { +const total = component.data.reduce(function (acc, item, index) { return acc + item.value; }, 0); ~~~ diff --git a/docs/guides/events_guide.md b/docs/guides/events_guide.md index b3416564..5bb50af1 100644 --- a/docs/guides/events_guide.md +++ b/docs/guides/events_guide.md @@ -30,51 +30,51 @@ The following approaches are used to work with events in DHTMLX Suite. ### Attaching event listeners -To attach an event listener, use the **component.events.on()** method: +To attach an event listener, use the `component.events.on()` method: -```js +~~~jsx component.events.on("eventName", function() { do_something(); }); -``` +~~~ where **component** is the name of the component of the DHTMLX Suite library (for example, calendar, grid, list, etc.). -The **component.events.on()** method takes two parameters: +The `component.events.on()` method takes two parameters: -- *eventName* – the name of the event of the component; -- *eventHandler* – a function to run. +- *eventName* - the name of the event of the component; +- *eventHandler* - a function to run. Any user-defined event handler can be attached to the event of the component. The logic of the handler is defined in the function. You can also place any API method of the related widget inside the handler function of the event. ### Detaching event listeners -To detach the event listener, use **component.events.detach()** method. +To detach the event listener, use `component.events.detach()` method. -```js +~~~jsx component.events.detach("eventName"); -``` +~~~ where **component** is the name of the component of the DHTMLX Suite library (for example, calendar, grid, list, etc.). -The **component.events.detach()** method takes one parameter: +The `component.events.detach()` method takes one parameter: -- *eventName* – the name of the event of the component. +- *eventName* - the name of the event of the component. ### Calling events -To call events, use **component.events.fire()** method: +To call events, use the `component.events.fire()` method: -```js +~~~jsx component.events.fire("eventName", args); -``` +~~~ -where **component** is the name of the component of the DHTMLX Suite library (for example, calendar, grid, list, etc.). +where **component** is the name of the component of the DHTMLX Suite library (for example, calendar, grid, list, etc.). -The **component.events.fire()** method takes two parameters: +The `component.events.fire()` method takes two parameters: -- *eventName* – an event of the component; -- *args* – an array of arguments. +- *eventName* - an event of the component; +- *args* - an array of arguments. ## The event usage sample @@ -82,13 +82,13 @@ Let's consider a sample of the event usage. Please, use [the DHTMLX Snippet Tool First, create a form with a slider and a button. -```html +~~~html -
-``` +
+~~~ -```js -const form = new dhx.Form("form", { +~~~jsx +const form = new dhx.Form("form_container", { css: "dhx_widget--bg_white dhx_widget--bordered", padding: 40, rows: [ @@ -103,24 +103,24 @@ const form = new dhx.Form("form", { } ] }); -``` +~~~ -Now, we are to disable the form after the user clicks the button. For this, we will use the **"click"** event and add the **disable()** method of Form API to the event handler. +Now, we are to disable the form after the user clicks the button. For this, we will use the `"click"` event and add the `disable()` method of Form API to the event handler. -```js +~~~jsx //attaching an event handler, which will make the form disabled, to the click event form.events.on ("click", function () { form.disable(); }); -``` +~~~ -Pay attention, usage of the disable() method of Form in the event handler is just an example. You may apply any other method or develop your logic if needed. +Pay attention, the use of the `disable()` method of Form in the event handler is just an example. You may apply any other method or develop your logic if needed. -For some reason, you may need to stop disabling the form. In this case, just use the **form.events.detach()** method. +For some reason, you may need to stop disabling the form. In this case, just use the `form.events.detach()` method. -```js +~~~jsx form.events.detach("click"); -``` +~~~ **You can look at the example we have just created.** diff --git a/docs/list/load_data.md b/docs/list/load_data.md index 94ea4db7..89ececf6 100644 --- a/docs/list/load_data.md +++ b/docs/list/load_data.md @@ -133,7 +133,7 @@ new dhx.LazyDataProxy("https://docs.dhtmlx.com/suite/backend/lazyload", { - to enable dynamic rendering of List items, switch the [`virtual`](list/api/list_virtual_config.md) property on: ~~~jsx {2} -const list = new dhx.list("list_container", { +const list = new dhx.List("list_container", { virtual: true }); ~~~ From fec8878090933e9027cc5146cbf57a7adbb79f42 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Thu, 3 Apr 2025 09:51:42 +0300 Subject: [PATCH 14/14] [update] data collection guides and related docs --- .../api/datacollection_filter_method.md | 2 +- docs/grid/usage.md | 4 +- docs/guides/datacollection/grouping_data.md | 20 ++-- .../datacollection/sorting_filtering_data.md | 91 +++++++++++++------ docs/helpers/lazydataproxy.md | 40 ++++---- 5 files changed, 103 insertions(+), 54 deletions(-) diff --git a/docs/data_collection/api/datacollection_filter_method.md b/docs/data_collection/api/datacollection_filter_method.md index 5abcd69c..48f75d84 100644 --- a/docs/data_collection/api/datacollection_filter_method.md +++ b/docs/data_collection/api/datacollection_filter_method.md @@ -16,7 +16,7 @@ description: You can explore the filter method of DataCollection in the document rule - (function | object) optional, the filtering criteria. It can be:
  • a filtering function. It takes as a parameter a data item and returns true/false
  • an object with the following attributes:
    • `by?: string | number` - optional, the id of a column
    • `match?: string` - optional, a pattern to match
    • `compare?: function` - optional, a function for extended filtering that takes the following parameters:
      • value - the value to compare
      • match - a pattern to match
      • item - a data item the values of which should be compared
+ (function | object) optional, the filtering criteria. It can be:
  • a filtering function. It takes as a parameter a data item and returns true/false
  • an object with the following attributes:
    • `by?: string | number` - optional, the id of a column
    • `match?: string` - optional, a pattern to match
    • `compare?: function` - optional, a function for extended filtering that takes the following parameters:
      • `value` - the value to compare
      • `match` - a pattern to match
      • `item` - a data item the values of which should be compared
config diff --git a/docs/grid/usage.md b/docs/grid/usage.md index 7ae103e3..de25b12c 100644 --- a/docs/grid/usage.md +++ b/docs/grid/usage.md @@ -349,7 +349,7 @@ You can sort Grid by multiple columns simultaneously. **Related sample**: [Grid. Sorting by multiple columns (multisorting)](https://snippet.dhtmlx.com/4ej0i3qi) -Multi-sorting is enabled on initialization of the component. In the example below Grid data is sorted with the help of the `sort()` method of [DataCollection](data_collection.md) by several columns: + In the example below Grid data is sorted with the help of the `sort()` method of [DataCollection](data_collection.md) by several columns: ~~~jsx const grid = new dhx.Grid("grid_container", { @@ -373,7 +373,7 @@ grid.data.sort({ by: "animal_type", dir: "asc" }); **Related sample**: [Grid. Grouping with sorting by multiple columns (multisorting)](https://snippet.dhtmlx.com/786zr190) -If you need to disable the multi-sorting ability, set the [`multiSort`](grid/api/grid_multisort_config.md) Grid property to *false*. +Multi-sorting is enabled on initialization of the component. If you need to disable the multi-sorting ability, set the [`multiSort`](grid/api/grid_multisort_config.md) Grid property to *false*. ~~~jsx const grid = new dhx.Grid("grid_container", { diff --git a/docs/guides/datacollection/grouping_data.md b/docs/guides/datacollection/grouping_data.md index fccf9d54..790d941a 100644 --- a/docs/guides/datacollection/grouping_data.md +++ b/docs/guides/datacollection/grouping_data.md @@ -6,14 +6,14 @@ description: You can learn how to group data with DataCollection in the document # Grouping data +Data grouping functionality allows grouping rows by the values of columns. + You can group the data of a component, ungroup data and check whether data in a collection is grouped via the DataCollection API. :::info important Data grouping isn't intended for working with [`lazyDataProxy`](helpers.md/lazydataproxy/) ::: -The DataCollection API can be used for working with [data grouping in Grid](grid/usage.md/#grouping-data). - ## Grouping data The [`group()`](data_collection/api/datacollection_group_method.md) method of DataCollection groups data in a collection that has a flat tree structure according to the specified order and additional configuration. The method takes the following parameters: @@ -32,9 +32,9 @@ The [`group()`](data_collection/api/datacollection_group_method.md) method of Da -There are several examples of grouping Grid data via the `group()` method of DataCollection: +### Simple grouping -- simple grouping with the use of a callback function and a string field value +The example below shows a simple grouping with the use of a callback function and a string field value: ~~~jsx {12-19} const grid = new dhx.Grid("grid_container", { @@ -58,7 +58,9 @@ grid.data.group([ ]); ~~~ -- grouping with the use of a configuration object and aggregation settings +### Grouping with the use of aggregation settings + +You can pass a configuration object with grouping settings to the `group()` method: specify a particular field or function for grouping, and, optionally, specify an object for data aggregation and the position of the total row: ~~~jsx {12-23} const grid = new dhx.Grid("grid_container", { @@ -86,7 +88,11 @@ grid.data.group([{ }]); ~~~ -- grouping with the use of the `showMissed` property +**Related sample:** [Grouping and totals in the summary row via data collection](https://snippet.dhtmlx.com/ihd6gtpj) + +### Grouping with the use of the `showMissed` property + +The `showMissed` property specifies whether the elements that don't have the field for grouping should be displayed. In the example below this property is set to the string value that defines the name of the group where the rows that don't have values for grouping are rendered: ~~~jsx {12-16} const grid = new dhx.Grid("grid_container", { @@ -107,6 +113,8 @@ grid.data.group(["city"], { }); ~~~ +**Related sample:** [Grid. Grouping missing data](https://snippet.dhtmlx.com/0geopa0v) + ## Ungrouping data To ungroup the data of a component, use the [`ungroup()`](data_collection/api/datacollection_ungroup_method.md) method of DataCollection. diff --git a/docs/guides/datacollection/sorting_filtering_data.md b/docs/guides/datacollection/sorting_filtering_data.md index f6799dc7..64f1ed48 100644 --- a/docs/guides/datacollection/sorting_filtering_data.md +++ b/docs/guides/datacollection/sorting_filtering_data.md @@ -12,13 +12,13 @@ When working with data you may need to sort or filter it. You can sort or filter To sort data items in a component, use the [`sort()`](data_collection/api/datacollection_sort_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: -- `rule: object` - an object with parameters for sorting. The object has the following attributes: - - `by: string | number` - the id of a data field - - `dir: string` - the direction of sorting: "asc" or "desc" - - `as: function` - a function that specifies the type to sort data as - - `rule: function` - optional, a sorting rule; the function must have two parameters and return a number (-1,0,1) -- `config: object` - defines the parameter of sorting. It may contain one property: - - `smartSorting: boolean` - optional, specifies whether a sorting rule should be applied each time after changing the data set +- `rule?: object` - optional, an object with parameters for sorting. The object has the following attributes: + - `by?: string | number` - optional, the id of a data field + - `dir?: string` - optional, the direction of sorting: "asc" or "desc" + - `as?: function` - optional, a function that specifies the type to sort data as + - `rule?: function` - optional, a sorting rule; the function must have two parameters and return a number (-1,0,1) +- `config?: object` - optional, defines the parameter of sorting. It may contain one property: + - `smartSorting?: boolean` - optional, specifies whether a sorting rule should be applied each time after changing the data set ~~~jsx grid.data.sort( @@ -42,7 +42,7 @@ Calling the method without parameters will discard all the applied sorting rules ### Custom sorting -You can also specify the `rule` attribute in a passed object to set a custom function for sorting. For example: +You can specify the `rule` attribute in the object passed to the `sort()` method to set a custom function for sorting. For example: ~~~jsx grid.data.sort({ @@ -50,9 +50,36 @@ grid.data.sort({ }); ~~~ +### Multi-sorting + +:::tip pro version only +The described functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: + +You can sort the data of a component by multiple columns simultaneously. To enable this functionality, you should specify the `smartSorting?: true` property in the configuration object passed as a second parameter of the `sort` method. It will apply the sorting rule set as first parameter each time the data set is modified: + +~~~jsx +const grid = new dhx.Grid("grid_container", { + columns:[ + // columns config + ] + // more options +}); + +grid.data.sort({ by: "volunteer_name", dir: "desc" }, { smartSorting: true }); +grid.data.sort({ by: "task_status", dir: "asc" }); +grid.data.sort({ by: "animal_type", dir: "asc" }); +~~~ + +In the above example Grid data is sorted with the help of the `sort()` method of [DataCollection](data_collection.md) by several columns - "volunteer_name", "task_status" and "animal_type". + +![](../../assets/grid/multisorting_data.png) + +**Related sample**: [Grid. Sorting by multiple columns (multisorting)](https://snippet.dhtmlx.com/4ej0i3qi) + ### Getting the sorting state -To get the current state of sorting data in Grid, use the [`getSortingStates()`](data_collection/api/datacollection_getsortingstates_method.md) method of DataCollection. The method allows getting the result of sorting data by multiple columns and returns an array of objects with the following properties: +To get the current state of sorting data in Grid, use the [`getSortingStates()`](data_collection/api/datacollection_getsortingstates_method.md) method of DataCollection. The method allows getting the result of sorting data and returns an array of objects with the following properties: @@ -88,19 +115,26 @@ const state = grid.data.getSortingStates(); To filter data items in a component, use the [`filter()`](data_collection/api/datacollection_filter_method.md) method of [DataCollection](data_collection.md). The method takes two parameters: -- `rule: function | object` - the filtering criteria - - If set as a *function*, filtering will be applied by the rule specified in the function. The function takes an object of a data item as a parameter and returns *true/false* - - If set as an *object*, the parameter has the following attributes: - - `by: string | number` - mandatory, the id of a data field - - `match: string` - mandatory, a pattern to match - - `compare: function` - optional, a function for extended filtering that takes three parameters: - - `value` - the value to compare - - `match` - a pattern to match - - `item` - a data item the values of which should be compared -- `config: object` - optional, defines the parameters of filtering. It may contain the following properties: - - `id: string` - optional, the id of the filter - - `add: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (*true*), or to the initial data (*false*, default) - - `permanent: boolean` - optional, *true* to make the current filter permanent. It will be applied even if the next filtering doesn't have the `add:true` property in its configuration object. Such a filter can be removed just with the [resetFilter()](data_collection/api/datacollection_resetfilter_method.md) method +
+ + + + + + + + + + + + + + +
rule(function | object) optional, the filtering criteria. It can be:
  • a filtering function. It takes as a parameter a data item and returns true/false
  • an object with the following attributes:
    • `by?: string | number` - optional, the id of a column
    • `match?: string` - optional, a pattern to match
    • `compare?: function` - optional, a function for extended filtering that takes the following parameters:
      • `value` - the value to compare
      • `match` - a pattern to match
      • `item` - a data item the values of which should be compared
config(object) optional, an object with the following properties:
  • `id?: string` - optional, the id of the filter
  • `add?: boolean` - optional, defines whether each next filtering will be applied to the already filtered data (true), or to the initial data (false, default)
  • `permanent?: boolean` - optional, true to make the current filter permanent. It will be applied even if the next filtering doesn't have the `add:true` property in its configuration object. Such a filter can be removed just with the `resetFilter()` method
silent(boolean) optional, if set to true, the method will be called without triggering events, false by default
+ +:::info +Note that after calling the method with the `silent:true` parameter, you may need to repaint the component with the `paint()` method. +::: The `filter()` method returns the id of the filter. @@ -138,7 +172,7 @@ grid.data.filter({ You can get filters applied to the data of a component using the [`getFilters()`](data_collection/api/datacollection_getfilters_method.md) method. The method takes the following parameter: -- `permanent: boolean` - optional, *false* by default. Allows getting the list of permanent filters +- `permanent?: boolean` - optional, *false* by default. Allows getting the list of permanent filters and returns an object with the applied filters, where the key is the id of a filter and the value is an object with the [`rule` and `config` properties](data_collection/api/datacollection_filter_method.md). @@ -150,9 +184,14 @@ const filters = grid.data.getFilters(); You can reset a certain filter or all the active filters using the [`resetFilter()`](data_collection/api/datacollection_resetfilter_method.md) method. It takes the following parameter: -- `config: object` - optional, specifies the parameters of resetting the active filters. If the config isn't specified or it is empty, all the filters except for those that have the `permanent` property in the configuration object will be reset. Can contain the following properties: - - `id: string` - optional, the id of the filter to reset - - `permanent: boolean` - optional, *true* to reset all the active filters, including those that have the `permanent:true` property in their config +- `config?: object` - optional, specifies the parameters of resetting the active filters. If the config isn't specified or it is empty, all the filters except for those that have the `permanent` property in the configuration object will be reset. Can contain the following properties: + - `id?: string` - optional, the id of the filter to reset + - `permanent?: boolean` - optional, *true* to reset all the active filters, including those that have the `permanent:true` property in their config +- `silent?: boolean` - optional, if set to *true*, the method will be called without triggering events, *false* by default + +:::info +Note that after calling the method with the `silent:true` parameter, you may need to repaint the component with the `paint()` method. +::: The method returns *true*, if all the filters, including the permanent ones, have been reset; otherwise *false*. diff --git a/docs/helpers/lazydataproxy.md b/docs/helpers/lazydataproxy.md index 76d5967c..688f5887 100644 --- a/docs/helpers/lazydataproxy.md +++ b/docs/helpers/lazydataproxy.md @@ -6,24 +6,26 @@ description: You can learn about dynamic loading in the documentation of the DHT # Dynamic loading -{{pronote This functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package.}} +:::tip pro version only +The described functionality requires PRO version of the DHTMLX Grid (or DHTMLX Suite) package. +::: -To load data dynamically from the server you can make use of the **LazyDataProxy** helper while loading data into DHTMLX Grid or DHTMLX List. +To load data dynamically from the server you can make use of the `LazyDataProxy` helper while loading data into DHTMLX Grid or DHTMLX List. This helper allows getting data partially, on demand, and rendering only those records that are in the visible area. Read the related articles for detailed information about how to display large lists and tabular data efficiently: - [dynamic loading in Grid](grid/data_loading.md#dynamic-loading) -- [dynamic loading in List](list/load_data.md#dynamic-loading) (You need to set the **virtual:true** property in the configuration object of List) +- [dynamic loading in List](list/load_data.md#dynamic-loading) (you need to set the `virtual:true` property in the configuration object of List) ## Initialize LazyDataProxy -Initialize LazyDataProxy with the dhx.LazyDataProxy object constructor. The constructor takes two parameters: +Initialize LazyDataProxy with the `dhx.LazyDataProxy` object constructor. The constructor takes two parameters: -- **url** - (*string*) the URL which the component will use to load data after its initialization -- **config** - (*object*) a configuration object which contains parameters for loading data from the server +- `url` - (*string*) the URL which the component will use to load data after its initialization +- `config` - (*object*) a configuration object which contains parameters for loading data from the server -~~~js +~~~jsx new dhx.LazyDataProxy("https://docs.dhtmlx.com/suite/backend/lazyload", { limit: 30, prepare: 5, @@ -36,20 +38,20 @@ new dhx.LazyDataProxy("https://docs.dhtmlx.com/suite/backend/lazyload", { There is a list of parameters that you can specify in the configuration object. All parameters are optional. -- **from** - (*number*) the index of the first data item to start loading from; default value: 0 -- **limit** - (*number*) the count of records that should be loaded from the server during each dynamic loading request; default value: 50 -- **delay** - (*number*) time interval (in milliseconds) to wait before the next dynamic loading request to the server (allows decreasing the number of server request during quick scrolling); default value: 50 -- **prepare** - (*number*) the count of extra records that should be loaded from the server; default value: 0 +- `from` - (*number*) the index of the first data item to start loading from; default value: 0 +- `limit` - (*number*) the count of records that should be loaded from the server during each dynamic loading request; default value: 50 +- `delay` - (*number*) time interval (in milliseconds) to wait before the next dynamic loading request to the server (allows decreasing the number of server request during quick scrolling); default value: 50 +- `prepare` - (*number*) the count of extra records that should be loaded from the server; default value: 0 ## Server-side response Server side will send the following data to the client side: -- **data** - (*array*) - the array of data records -- **from** - (*number*) - starting position in the data set to add the loaded data to -- **total_count** - (*number*) - the total number of records available on the server +- `data` - (*array*) - the array of data records +- `from` - (*number*) - starting position in the data set to add the loaded data to +- `total_count` - (*number*) - the total number of records available on the server -~~~js +~~~jsx data: [ {country: "DR Congo", population: "84004989", yearlyChange: "0.0328"} {country: "Germany", population: "82293457", yearlyChange: "0.0022"} @@ -62,12 +64,12 @@ from: 15 ## Updating URL -You can use the **updateUrl** method to update the URL where the data will be loaded or to change parameters for loading data from the backend. The method takes two parameters: +You can use the `updateUrl()` method to update the URL where the data will be loaded or to change parameters for loading data from the backend. The method takes two parameters: -- **url** - (*string*) the URL which the component will use to load data after its initialization. If not specified, the currently existing URL will be used. -- **config** - (*object*) a configuration object with parameters for loading data from the server. If not specified, clears parameters set earlier. +- `url` - (*string*) the URL which the component will use to load data after its initialization. If not specified, the currently existing URL will be used. +- `config` - (*object*) a configuration object with parameters for loading data from the server. If not specified, clears parameters set earlier. -~~~js +~~~jsx lazyDataProxy.updateUrl("https://docs.dhtmlx.com/suite/backend/lazyload", { limit: 30, prepare: 5,