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..48f75d84 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..7f6fdf3d 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 `(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
## 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) diff --git a/docs/grid/data_loading.md b/docs/grid/data_loading.md index de7e5717..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,14 +169,21 @@ 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); ~~~ ## 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: @@ -184,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 8cf3b5f2..de25b12c 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: @@ -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", { @@ -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", { @@ -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` helper - - a user-defined aggregation function `(i: IDataItem[]) => string | number` + - 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 `(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 new file mode 100644 index 00000000..790d941a --- /dev/null +++ b/docs/guides/datacollection/grouping_data.md @@ -0,0 +1,134 @@ +--- +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 + +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/) +::: + +## 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: + +
+ + + + + + + + + + +
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
+ +### Simple grouping + +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", { + 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 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", { + 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 +}]); +~~~ + +**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", { + 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" +}); +~~~ + +**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. + +~~~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..a5f5c260 --- /dev/null +++ b/docs/guides/datacollection/loading_data.md @@ -0,0 +1,254 @@ +--- +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 and saving data + +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. +::: + +## 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) + +## 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). + +:::tip pro version only +The method works with the [Dynamic loading](helpers/lazydataproxy.md) functionality which is available in the PRO edition only. +::: + +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(); +~~~ + +## 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("grid_container", { + columns: [ + // columns config + ], + // more options +}); +// parsing the state of grid1 into grid2 +grid2.data.parse(state); +~~~ + +## 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: + +- `url: IDataProxy | string` - 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 new file mode 100644 index 00000000..64f1ed48 --- /dev/null +++ b/docs/guides/datacollection/sorting_filtering_data.md @@ -0,0 +1,221 @@ +--- +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` - 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( + { + by:"a", + dir:"desc", + as: item => (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 + +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({ + rule: (a, b) => a.id > b.id ? 1 : (a.id < b.id ? -1 : 0) +}); +~~~ + +### 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 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: + + + + + + + + + + + + + + + + +
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. + +~~~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) + +### 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 +- `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*. + +~~~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) + +## 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 new file mode 100644 index 00000000..007eecd8 --- /dev/null +++ b/docs/guides/datacollection/working_with_data_items.md @@ -0,0 +1,346 @@ +--- +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 + +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 + +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) + +## Adding items + +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 + +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 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"]); +~~~ + +**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 of DataCollection. + +~~~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 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 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 + +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 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 + +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 + +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, if set to *true*, the method will be called without triggering events; otherwise, *false* + +~~~jsx +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 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 + +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 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: + - `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: 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 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 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: + - `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: 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. + +~~~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" }); +~~~ + +**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. + +### 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: 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) { + 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) + +### Iterating through the items of a component + +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) { + return item.id; +}); +~~~ + +**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 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: 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) { + 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 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: 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) { + 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 61bc5138..72d06335 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,42 +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 -- 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. - 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(){}); @@ -80,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. @@ -89,7 +57,16 @@ 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) +- [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. @@ -265,7 +242,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); @@ -273,7 +250,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( @@ -296,13 +273,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. @@ -312,7 +289,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 }); @@ -321,7 +298,7 @@ Do not forget to add a separate container for the new component. 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 @@ -331,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. +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.** 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/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, 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 }); ~~~ diff --git a/docs/whatsnew.md b/docs/whatsnew.md index 5b7ec1dd..e074c4fa 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 March 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 diff --git a/sidebars.js b/sidebars.js index 08066c69..af18a797 100644 --- a/sidebars.js +++ b/sidebars.js @@ -4915,7 +4915,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/working_with_data_items", + "guides/datacollection/sorting_filtering_data", + "guides/datacollection/grouping_data", + + ], + }, + //"guides/datacollection_guide", ], }, // end Guides