# dhtmlxtree:nodes_manipulation [DHX documentation]

DHTMLX Docs & Samples Explorer

Index
dhtmlxtree

## Nodes Manipulation

### Adding/Removing Items

#### Adding Parent Item

Parent tree nodes can be easily added to the tree from script with the help of insertNewNext() method. The following incoming parameters should be indicated in this method:

- siblingId - id of the item after which the new one will be created;
- itemId - id of the new item;
- label - text of the new item;
- action - 0 in most cases, but can be a custom function;
- imageClosed - image for a collapsed item; if 0 is indicated - the default one is used;
- imageOpen - image for an expanded item; if 0 is indicated - the default one is used;
- imageLeaf - image for a leaf item; if 0 is indicated - the default one is used;
- additional options - a comma delimited string of the following possible values (upper case only):
  - SELECT - move selection to this item after its creation;
  - CALL - call a function on select;
  - TOP - add this item to the top position;
  - CHILD - the node contains child items;
  - CHECKED - the checkbox is checked (if exists).

        <script>
            tree.insertNewNext(1,2,"New Node 2",0,0,0,0,"CHILD,CHECKED");
        </script>

#### Adding Child Node

Method insertNewChild() allows to add a new child item for the chosen tree node. The parameters the user should indicate are:

- parentId - id of the parent item in which the new child will be created;
- itemId - id of the new item;
- label - text of the new item;
- action - 0 in most cases, but can be a custom function;
- imageClosed - image for a collapsed item; if 0 is indicated - the default one is used;
- imageOpen - image for an expanded item; if 0 is indicated - the default one is used;
- imageLeaf - image for a leaf item; if 0 is indicated - the default one is used;
- additional options - a comma delimited string of the following possible values (upper case only):
  - SELECT - move selection to this item after its creation;
  - CALL - call a function on item's select;
  - TOP - add this item to the top position;
  - CHILD - the node contains child items;
  - CHECKED - the checkbox is checked (if exists).

        <script>
            tree.insertNewChild(0,1,"New Node 1",0,0,0,0,"SELECT,CALL,TOP,CHILD,CHECKED");
        </script>

The item added as a child will be created always the last among other child items for the specified parent.

#### Removing Item

Any item can be easily removed from the tree in the following way:

        <script>t
            tree.deleteItem(itemId, selectParent);
        </script>

The parameters the user should specify are:

- itemId - id of the item in question;
- selectParent(true|false) - if set to true, the parent item of the removed one becomes selected when the removal is done, while false means that no other item will be selected in the tree after removal of the indicated item.

#### Removing All Child Items

The following method allows the user to remove all child items of a certain node very easily:

        <script>
            tree.deleteChildItems(itemId);
        </script>

### Collapsing/Expanding Items

#### Expanding Parent Item on Child Adding

There is a possibility in dhtmlxTree to set whether a parent item will be expanded or not when a child item is added to it.

        <script>
            tree.openOnItemAdded(mode);
        </script>

The method can be set either to true (the parent item will be expanded on child adding) or to false (the parent item won't be expanded).

#### Collapsing/Expanding Item

There is the possibility to expand/collapse any node in dhtmlxTree from script. The only value that the user should indicate, is the id of the item in question:

        <script>
            tree.openItem(itemId); // expand the indicated item
            tree.closeItem(itemId); // collapse the indicated item
        </script>

#### Collapsing/Expanding All Items

The user can also expand/collapse all items in the tree. The optional parameter here is the id of the item starting from which all items will be expanded/collapsed:

        <script>
            tree.openAllItems(itemId); // expand all items
            tree.closeAllItems(itemId); // collapse all items
        </script>

The method to expand all tree items that is similar to the above mentioned one but that works in dynamical trees:

        <script>
            tree.openAllItemsDynamic(itemId); // expands all items in a dynamical tree
        </script>

#### Expanding Item's List

The method to expand a list of tree items in dynamical tree (items are expanded one by one, the next item will be opened only when the previous one is loaded):

        <script>
            tree.openItemsDynamic(list,flag);
        </script>

The parameters are:

- list - list of nodes ids that will be expanded;
- flag (true|false) - indicates whether the last node in the list will be selected (true) or not (false).

#### Prevent Item from Collapsing

There is a method that can prevent the item from collapsing:

        <script>
            tree.setItemCloseable(itemId,flag);
        </script>

The parameters here are as follows:

- itemId - id of the node;
- flag(true|false) - if set to false, prevents the item from collapsing.

#### Getting Item State

Item's state (expanded|collapsed) can be got in the following way:

        <script>
             var state = tree.getOpenState(itemId);
        </script>

The method returns true if the item in question is expanded, and false if the item is collapsed.

#### Locking Tree/Item

By locking the tree, the user denies expanding|collapsing tree nodes. By default the tree isn't locked (false). To lock the tree, lockTree() method should be set to true:

        <script>
            tree.lockTree(true); // false to unlock the tree
        </script>

Any item, whether it is a parent or a child one, can be also locked by method lockItem():

        <script>
            tree.lockItem(itemId); // id of the item as the input parameter
        </script>

#### Getting Locking State

To get the state (locked|unlocked) of any item in the tree, the user should apply the following method:

        <script>
            var itemState = tree.isLocked(itemId); // returns current item's state
        </script>

If the item in question is locked, the method returns true, if it is unlocked, false is returned.

### Editing Item

#### Making Items Editable

Any item in the tree can be made editable - double click on the item allows to edit its title text. By default all items in the tree are not editable (false). To make them so, the user should write the following code line:

        <script>
            tree.enableItemEditor(true); // false to deny items editing
        </script>

#### Activating Editor for Item

The user can activate the editor for a specified item from script with the help of method editItem(). The only parameter that should be specified is id of this item:

        <script>
            tree.editItem(itemId);
        </script>

#### Deactivating Editor for Item

Item's editor can be easily deactivated from script bringing the item back to its normal view:

        <script>
            tree.stopEdit();
        </script>

#### Defining Editing Event

The event that starts item's editing can be defined from script in the following way:

        <script>
            tree.setEditStartAction(click, dblclick);
        </script>

The parameters define the following:

- click(true|false) - item's editing will be activated by a click on the selected item;
- dblclick(true|false) - item's editing will be activated by a double click on the selected item.

### Integration with Cookies

#### Saving Items' States to Cookies

The user has the possibility to store states of items to cookies in the following way:

        <script>
            tree.saveOpenStates(cookie_name,cookie_param);
        </script>

The parameters of this method are:

- cookie_name - name of the cookie (optional parameter);
- cookie_param - additional parameters added to cookie.

#### Restoring Items' States from Cookies

There is a method that restores items' states (expanded|collapsed) from cookie's information:

        <script>
            tree.loadOpenStates(cookie_name); // the parameter is optional
        </script>

#### Saving Selection to Cookies

Item's selection can be also stored in cookies in the following way:

        <script>
            tree.saveSelectedItem(cookie_name,cookie_param);
        </script>

The parameters of this method are:

- cookie_name - name of the cookie (optional parameter);
- cookie_param - additional parameters added to cookie.

#### Restoring Selection from Cookies

Item's selection can be restored from cookie in the following way:

        <script>
            tree.restoreSelectedItem(cookie_name); // the parameter is optional
        </script>

#### Saving Tree to Cookies

Method saveState() stores the whole tree to cookies:

        <script>
            tree.saveState(cookie_name,cookie_param);
        </script>

The parameters of this method are:

- cookie_name - name of the cookie (optional parameter);
- cookie_param - additional parameters added to cookie

#### Restoring Tree from Cookies

Method loadState() restores the whole tree from cookies:

        <script>
            tree.loadState(cookie_name); // the parameter is optional
        </script>

#### Enabling Item's Auto Saving

dhtmlxTree allows its users to save the selected node automatically in cookies. Method enableAutoSavingSelected() is used to switch this on|off in the tree:

        <script>
            tree.enableAutoSavingSelected(mode,cookieName);
        </script>

The parameters are:

- mode(true|false) - indicates whether the auto saving is on|off;
- cookieName - name of the cookie.

### Item Text, Tooltip, Color Manipulation

#### Setting Item's Label

The user can set the label (text) of a tree node in the following way:

        <script>
            tree.setItemText(itemId, newLabel, newTooltip);
        </script>

The parameters are as follows:

- itemId - id of the item in question;
- newLabel - new text for item's label;
- newTooltip - the text indicated in this parameter will be used as item's tooltip text (optional parameter).

#### Getting Item's Label

The user has the possibility to get text of item's label indicating item's id in the following way:

        <script>
            var text = tree.getItemText(itemId);
        </script>

The user can also get the text of the currently selected item in the following way:

        <script>
            var textSelected = tree.getSelectedItemText();
        </script>

#### Setting Item's Color

The following line of code is responsible for node's color (text color) in the tree:

        <script>
            tree.setItemColor(itemId, defaultColor, selectedColor);
        </script>

The parameters the user should specify are as follows:

- itemId - id of the item in question;
- defaultColor - item's color;
- selectedColor - item's color for a selected state.

#### Getting Item's Color

Item's color can be easily got by item id in the following way:

        <script>
            car color = tree.getItemColor(itemId);
        </script>

The object returned by the above mentioned method has parameters { acolor:“value”, scolor:“value” } where:

- acolor - means color for the normal state of the item;
- scolor - means color for the selected state of the item.

The format of the color will be the same as it was set in setItemColor() method.

#### Setting Item's Tooltip

There are three ways to set tooltip for an item in dhtmlxTree:

- Using node's text (“label” attribute of a node) as tooltip. In this case the following method should be used:

        <script>
            tree.enableAutoTooltips(true|false); // false by default
        </script>

- Using “tooltip” attribute of a node in XML (it is used by default if this attribute was specified);
- Using setItemText method specifying its third parameter.

#### Getting Item's Tooltip

Item's tooltip is also easy to get with the help of getItemTooltip() method indicating item id:

        <script>
            var tooltip = tree.getItemTooltip(itemId);
        <script>

### Refreshing and Updating Items

#### Refreshing Item/Items

The following method is used to refresh data for the specified node:

        <script>
            tree.refreshItem(itemId); // if item id is not indicated, id of the top tree item will be used
        </script>

The code string mentioned above presupposes that all the child items of the indicated node are removed, an XML file (indicated in setXMLAutoLoading(); auto loading should be activated) is loaded from the server. The data from this file is used for creating new child items of the node in question.

The following method is used to refresh data for several nodes:

        <script>
            tree.refreshItems(itemIdList, source);
        </script>

The parameters of this method include the list of items that should be refreshed, and the path to the XML file from which new data will be loaded. In this case, the data is refreshed only for nodes indicated in itemIdList (not their children).

#### Smart Branch Refreshing

There is one more possibility to refresh tree data. smartRefreshBranch() method is able to load XML from the server and refresh data for the specified branch (text, icons, items). It should be noted that the current position and all changes introduced by the user stay the same in this case.

        <script>
            tree.smartRefreshBranch(itemId,source);
        </script>

The parameters here are responsible for:

- itemId - id of the item from which the refreshing starts in the branch;
- source - server side script, optional parameter. If it is not set, the system will use the source indicated in setXMLAutoLoading().

#### Smart Item Refreshing

Method smartRefreshItem() is responsible for loading XML which data is used for refreshing the specified item in the tree. As with the previous method, this one keeps the current position of the item and all other changes introduced by the user.

        <script>
            tree.smartRefreshItem(itemId,source);
        </script>

The parameters are as follows:

- itemId - id of the item in question;
- source - server side script, optional parameter. If it is not set, the system will use the source indicated in setXMLAutoLoading().

#### Updating Item

There is a simple way of updating items in dhmlxTree - updateItem() method. The used should indicate the id of the item that is going to be updated, and parameters that are going to be updated:

        <script>
            tree.updateItem(itemId,name,im0,im1,im2,achecked);
        </script>

The parameters of this method are as follows:

- itemId - id of the item in question;
- name - title text of the item;
- im0 - the icon for a leaf node;
- im1 - the icon for an expanded parent node;
- im2 - the icon for a collapsed parent node;
- achecked(true|false) - whether the checkbox is checked (true) or not (false).

### Items Ids Manipulation

#### Getting List of Parent Items Ids

The following methods allow the user to get ids of all parent tree nodes:

        <script>
            var parents = tree.getAllItemsWithKids(); // returns the array of nodes ids
        </script>

#### Getting List of Leaf Items Ids

The user can get the list of ids of all tree items that do not have child nodes (childless items):

        <script>
            var childless = tree.getAllChildless(); // returns the array of nodes ids
        </script>

#### Getting List of Sub-Items Ids

The user can easily get ids of all sub-items starting from the item which id is indicated in this method:

        <script>
            var subItems = tree.getAllSubItems(itemId);
        </script>

Getting the list of all sub-items ids for the specified item is quite easy. This parent item id should be specified:

        <script>
            tree.getSubItems(itemId);
        </script>

#### Changing Item Id

The user can change any node's id if there's such a need in the following way:

        <script>
            tree.changeItemId(itemCurrentId,itemNewId);
        </script>

#### Getting Child Item Id

The user can get any child item id by its index (sequence number) and the id of its parent:

        <script>
            var childId = tree.getItemIdByIndex(itemId,index);
        </script>

The parameters are:

- itemId - id of the parent item;
- index - sequence number of the child item (starting with 0).

#### Getting Child Item Index

Child item's index (sequence number) can be easily got by its id:

        <script>
            var childIndex = tree.getIndexById(itemId);
        </script>

The parameter is id of the child item which index the user wants to get.

#### Getting Item's Parent Id

getParentId() method can be used to get item's parent id:

        <script>
            var parent = tree.getParentId(itemId);
        </script>

The id of the item should be indicated as the parameter.

#### Getting Ids List of Checked/Unchecked Tree Items

The ids of all checked/unchecked items in the tree can be easily got by getAllChecked() method:

        <script>
            var list = tree.getAllChecked(); // returns the array of all checked items ids
                // or
            var list = tree.getAllUnchecked(); // returns the array of all unchecked items ids
        </script>

#### Getting Ids List of Partially Checked Items

The method, similar to the above mentioned ones, exists for getting the ids of all partially checked items in the tree:

        <script>
            var list = tree.getAllPartiallyChecked(); // returns the array of all checked items ids
        </script>

#### Getting Ids List of Checked Branches

Ids of all checked branches in the tree can be got like this:

        <script>
            var list = tree.getAllCheckedBranches(); // returns the array of all checked branches ids
        </script>

#### 0 Getting Selected Item Id

Selected item's id is easy to get through getSelectedItemId() method which takes item id as the parameter:

        <script>
            var selectId = tree.getSelectedItemId();
        </script>

#### 1 Setting List Separator

There is a simple way of setting list separator in dhtmlxTree:

        <script>
            tree.setListDelimeter(separator); // by default the separator is ","
        </script>

There is only one parameter here - separator - char or string used for separating items in lists.

### Items Position Manipulation

#### Moving Items

Any item in the tree can be moved with the help of moveItem() method.

        <script>
            tree.moveItem(itemId, mode, targetId, targetTree);
        </script>

The following parameters should be specified for this method:

- itemId - id of the item in question;
- mode - one of the moving modes available:
  - left - the item will be moved to the left of node's current position;
  - up - the item will be moved one level up in the hierarchy;
  - up_strict - the item will be moved one position up, but will remain in the same level of the hierarchy;
  - down - the item will be moved one level down in the hierarchy;
  - down_strict - the item will be moved one position down, but will remain in the same level of the hierarchy;
  - item_child - the item will be made child of the target item;
  - item_sibling - the item will be made sibling of the target item, and will be placed before the target item;
  - item_sibling_next - the item will be made sibling of the target item, and will be placed after the target item;
- targetId - id of the item relative to which the item in question will be moved;
- targetTree (optonal) - the object of some other tree the item in question is moved into.

#### Cutting/Pasting Items

One more way of nodes moving is through doCut() and doPaste() commands. But they work only with selected items:

        <script>
            tree.doCut(); // marks the selected item as cut
            tree.doPaste(itemId); // id of a new parent node
        </script>

The cut item will be made a child node of the item indicated in the method doPaste().

#### Clearing Cut Mark

To clear the mark made by doCut() method, the user is advised to use clearCut() one:

        <script>
            tree.clearCut();
        </script>

#### Getting Item's Level

There is a method in dhtmlxTree that allows the user to get item's current level (position in hierarchy) indicating this item's id:

        <script>
            var level = getLevel(itemId);
        </script>

#### Setting Item Top Offset

There is the possibility to set top offset for a tree item using the following method:

        <script>
            tree.setItemTopOffset(itemId,value);
        </script>

The parameters are:

- itemId - id of the item in question;
- value - offset value.

### Calculating Items

#### Setting Calculation Mode

The user can set calculation mode for the tree in the following way:

        <script>
            tree.setChildCalcMode(mode); // disabled by default
        </script>

There are the following mode variants available:

- child - direct child items, no recursive;
- leafs - direct child items without sub-items, no recursive;
- childrec - child items (leaf items and those with their own child items), recursive;
- leafsrec - child items without sub-items, recursive;
- disabled - disable this mode.

All tree child nodes will be calculated in this mode.

#### Setting Calculation HTML

Along with setting the calculation mode for child items, the user can specify calculation HTML like this:

        <script>
            tree.setChildCalcHTML(htmlA,htmlB);
        </script>

The parameters here are:

- htmlA - prefix of the calculator (”[” by default);
- htmlB - postfix of the calculator (”]” by default).

#### Getting Number of Child Items

The number of child items of a certain parent can be got in the following way:

        <script>
            var childItems = tree.hasChildren(itemId);
        </script>

### User Data Manipulation

#### Setting User Data

User data can be set for any tree item in dhtmlxTree:

        <script>
            tree.setUserData(itemId,name,value);
        </script>

The parameters of this method are:

- iteId - id of the item in question;
- name - name of user data;
- value - value of user data.

#### Getting User Data

User data set for a tree node can be got in the following way:

        <script>
            var userData = tree.getUserData(itemId,name);
        </script>

The parameters of this method are:

- iteId - id of the item in question;
- name - name of user data.

### Using Link-Like Functionality in Tree

Any node if the tree can have link-like functionality specified for it. The link for an item can be set by user in XML. The user should also specify onClick event for the item with link-like functionality.