Documentation for update functions

[alumezi]

The updateTree function does not have an example on the docs. We need more information on how it works.

[sasatatar]

The docs with examples are underway, but I'll try to give a quick answer here until then.

function updateTree(
    array: Array<TreeItem>,
    updateCallback: (item?: TreeItem, index?: number) => TreeItem,
    itemFilter?: (item?: TreeItem, index?: number) => boolean,
    childrenField?: string,
    removeFilter?: (item?: TreeItem, index?: number) => boolean,
): Array<TreeItem>;

updateTree is normally used with tree grids and allows us to make safe updates on the tree in a systematic way. Here is a common workflow:

// get the tree from the store
let tree = this.store.get("tree");

// create updated copy
let updatedTree = updateTree(tree, updateCallback[, ...]);

// save the updated copy to the store
this.store.set("tree", updatedTree);

updateTree is a pure function, meaning it takes the tree, makes some updates and returns an updated copy of the tree. The original tree is left unchanged.

• array is the tree structure, that is an array of objects/tree items with their children subarrays stored under the childrenField, which is by default children.
• updateCallback is the update function that will be executed on each tree item that passes the filter, if there is one set. updateCallback takes two arguments, item and index, and returns an updated copy of the tree item. This should be a pure funciton that makes no changes on the original item.
• itemFilter is a predicate function, meaning, it receives the tree item and its index as arguments, and returns true or false. Only items for which itemFilter returns true will get updated.
• childrenField is the name of the property under which child items are stored. By default, it's children.
• removeFilter is another predicate function that receives tree item and its index as arguments and returns either true or false. Each tree item for which removeFilter returns true is removed from the updated tree.

The array and updateCallback parameters are obligatory, whereas itemFilter, childrenField and removeFilter are optional.

Hope this helps. Let me know if you have any other qustions. We'll leave the issue open until the docs are complete.

[alumezi]

Thanks, that is very helpful!