Merge pull request #60 from DHTMLX/update-datacollection-api

[update] datacollection api descriptions

Author: mafanya23

docs/data_collection/api/datacollection_add_method.md

@@ -12,18 +12,23 @@ description: You can explore the add method of DataCollection in the documentati
 Please note that data should be loaded into DataCollection via the `parse()` method. The `add()` method is primarily intended for loading standalone elements or small groups of elements, so its loads data slower than the `parse()` method.
 :::
 
-@signature: {'add(new_item: object | object[], index?: number): (string | number) | (string | number)[];'}
+#### Usage
+
+~~~ts
+type Id = string | number; 
+add(newItem: IDataItem | IDataItem[], index?: number): Id | Id[];
+~~~
 
 @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
+- `newItem: IDataItem | IDataItem[]` - 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
 
 @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([

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` - 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");

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:
 

docs/data_collection/api/datacollection_filter_method.md

@@ -8,22 +8,28 @@ 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*
+
+- `rule?: function | object` - optional, the filtering criteria
+    - If set as a *function*, filtering will be applied by the rule specified in the function. It takes as a parameter a data item 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:
+        - `by?: string | number` - optional, the id of a data field 
+        - `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, 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 (<i>true</i>), or to the initial data (<i>false</i>, 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
+- `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 (<i>true</i>), or to the initial data (<i>false</i>, default)
+    - `permanent?: boolean` - optional, *true* to make the current filter permanent. It will be applied even if the next filtering doesn't have the `add:true` property in its configuration object. Such a filter can be removed just with the [resetFilter()](data_collection/api/datacollection_resetfilter_method.md) method
+- `silent?: boolean` - optional, if set to <i>true</i>, the method will be called without triggering events, <i>false</i> 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

docs/data_collection/api/datacollection_find_method.md

@@ -8,29 +8,31 @@ description: You can explore the find method of DataCollection in the documentat
 
 @short: finds the item that corresponds to the specified rule
 
-@signature: {'find(rule: object | (item: object, index?: number, array?: object[]) => any): object;'}
+@signature: {'find(rule: object | (item: object, index: number, array: object[]) => any): object;'}
 
 @params:
 - `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` - (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` - the index of an item
+        - `array: object[]` - 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:
 

docs/data_collection/api/datacollection_findall_method.md

@@ -8,29 +8,31 @@ description: You can explore the findAll method of DataCollection in the documen
 
 @short: finds all the items that correspond to the specified rule
 
-@signature: {'findAll(rule: object | (item: object, index?: number, array?: object[]) => any): object[];'}
+@signature: {'findAll(rule: object | (item: object, index: number, array: object[]) => any): object[];'}
 
 @params:
 - `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` - (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` - the index of an item
+        - `array: object[]` - 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:
 

docs/data_collection/api/datacollection_foreach_method.md

@@ -8,16 +8,16 @@ description: You can explore the forEach method of DataCollection in the documen
 
 @short: iterates over all items of a data collection
 
-@signature: {'forEach(callback: (item: object, index?: number, array?: object[]) => any): void;'}
+@signature: {'forEach(callback: (item: object, index: number, array: object[]) => any): void;'}
 
 @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` - the index of an item
+    - `array: object[]` - 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);

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, <i>false</i> 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)

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;
 ~~~

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: