Setting Tree Appearance

Tree Lines and Icons Manipulation

Enabling/Disabling Tree Lines

Tree lines are tiny lines that visually "connect" elements of the tree. These lines can be easily enabled/disabled from script:

tree.enableTreeLines(true/false); // true by default

Setting +/- Icons

"+" and "-" icons indicate whether a parent node is closed or opened. The setImageArrays() method is used to set these images:

tree.setImageArrays(arrayName,image1,image2,image3,image4,image5);

The parameters for this method are as follows:

arrayName - name of an array: plus, minus;
image1 - crossed lines image (+);
image2 - image with top line (г);
image3 - image with bottom line (L);
image4 - image without lines ( );
image5 - single root image (-).

Showing/Hiding +/- Icons

There is a simple way of showing/hiding +/- signs of a certain item:

tree.showItemSign(itemId,mode);

The following parameters should be indicated:

itemId - id of the item the +/- icon of which will be shown/hidden;
mode(true/false) - true stands for showing the icon, false means hiding it.

This method works only for individual items not for the entire tree.

Specifying Icons for Locked Items

If the user wants to specify the icons for the locked state of tree items, they should be indicated before any of the data loading methods:

...
tree.setLockedIcons("lock.gif","lock.gif","lock.gif");
tree.load("tree.xml")

The parameters of setLockedIcons method indicate paths to the icons that will be used for locked nodes:

m0 - icon for a locked leaf;
im1 - icon for a closed branch;
im2 - icon for an opened branch.

Tree Images Manipulation

Setting Images for Items

It should be noted that the tree will get images for its nodes from the path the user specified in the setImagePath() method.

But there are also other ways available for setting custom images of nodes in the tree. The difference between these two methods lies in the way the user adds item to the tree:

JavaScript way: using arguments of the insertNewChild() or insertNewNext() methods:

var im0 = "doc.gif"; // the icon for a leaf node
var im1 = "opened.gif"; // the icon for an expanded parent node
var im2 = "closed.gif"; // the icon for a collapsed parent node
 
 
tree.insertNewItem(0,1,"New Node 1",0,im0,im1,im2);
tree.insertNewNext(1,2,"New Node 2",0,"txt.gif","opened.gif","closed.gif");

JavaScript way: using the setItemImage() and setItemImage2() methods:

The first method for setting an image for an item should be written in this way:

tree.setItemImage(itemId,image1,image2);

The parameters are as follows:

itemId - id of the item in question;
image1 - image for the leaf item or image for the collapsed parent item (if the third parameter is indicated);
image2 - image for the expanded parent item.

The second method for setting an image is the following:

tree.setItemImage2(itemId,image1,image2, image3);

The parameters are as follows:

itemId - id of the item in question;
image1 - image for a leaf item;
image2 - image for a collapsed parent item;
image3 - image for an expanded parent item.

XML way: using parameters of the <item> tag:

<?xml version='1.0' encoding='iso-8859-1'>
 <tree id="0">
  <item text="My Computer" id="1" child="1" im0="doc.gif" im1="my_open.gif" 
        im2="my_closed.gif">
 </tree>

See XML Format Template.

Getting Item's Image

Item's image can be got with the help of getItemImage() method:

var image = tree.getItemImage(itemId,imageInd,fullPath);

In order to get items image, the user should indicate:

itemId - id of the item the image of which should be got;
imageInd - index of the image (0 - leaf image, 1 - closed parent node image, 2 - open parent node image);
fullPath (true/false) - indicates whether the method returns full path to the image (true), or just the name of the image file (false).

Enabling Tree Images

Images are enabled in dhtmlxTree by default. To disable images the user should call the following method:

tree.enableTreeImages(false); // true to enable

Setting Default Item's Images

There is a simple way of setting default item's images in Tree:

tree.setStdImages(image1,image2,image3);

This method should be called before XML loading takes place. It is useful when a lot of similar images are going to be used in the tree. It is better to use this method once rather than specify these images every time for every item.

The parameters that the user should specify are the following:

image1 - image for a leaf node;
image2 - image for a closed parent node;
image3 - image for an opened parent node.

Changing Icon Sets

dhtmlxTree is a highly customizable component. You can use different icon sets for trees simply by changing the image path:

tree.setImagePath("[full path to this folder]/codebase/images/"); //default icons set
    //or
tree.setImagePath("[full path to this folder]/codebase/images/dhxtree_web/");
    // or
tree.setImagePath("[full path to this folder]/codebase/images/dhxtree_terrace/");

Setting Icon's Size

Setting icon's size is quite simple with the setIconSize() method. The default size of tree icons is 18x18 px.

tree.setIconSize(newWidth,newHeight,itemId);

The parameters the user should specify are:

newWidth - new width of the icon;
newHeight- new height of the icon;
itemId - the item that the new sizes will be applied to (optional parameter).

If the last parameter is not indicated, new sizes will be applied to all icons in the tree.

Related sample: Icon size

Making Images Clickable

There is a simple method used to make all images in the tree clickable:

tree.enableActiveImages(true/false); // enabled by default

Enabling Image Dragging

There is a method that is responsible for allowing the user to drag items not only by text, but also by their images. This functionality is enabled by default.

tree.enableImageDrag(true/false);

Enabling IE Images Fixing

There is a special method to change the way of images rendering in IE. It also helps to solve the problem of images caching in IE:

tree.enableIEImageFix(true|false); // disabled by default

Text Manipulation

Setting text Direction

dhtmlxTree supports both LTR and RTL text directions. LTR is set by default in the tree. The user can set the text direction to RTL like this:

tree.enableRTL(true); // false to disable

To set text direction to LTR again, use false in the above mentioned method.

Enabling Multiline

Tree nodes' labels can contain only one text line by default. However, in some situations it can be useful to make them multiline. There is a special method for this in dhtmlxTree. It is recommended to turn tree lines off for better appearance:

tree.enableTreeLines(false); 
tree.enableMultiLineItems(true/false/width);

This method should be called before loading tree data takes place. The parameter of this method can be one of these options:

true - the multiline is enabled;
false - the multiline is disabled;
width - the multiline is enabled and set in pixels (for example, "50px").

Related sample: Multi-line items

Setting Text Signs

There is the possibility to enable/disable text signs [+] and [-] instead of corresponding icons. This can be done in the following way:

tree.enableTextSigns(mode);

Setting this method to true equals enabling text signs for the tree, while false means disabling them.

Making Plain Text Tree

There is also a possibility to create a plain one-level tree. The steps the user should take for this are quite simple:

Add the following style in the HTML file where the tree will be created:

treeboxbox_tree.standartTreeImage img{
    width:0px;
}

Create a div element on a page and write the following script lines:

<div id="treeboxbox_tree" style="width:200;height:200"></div>
<script>    tree=new dhtmlXTreeObject("treeboxbox_tree","100%","100%",0);
    tree.setImagePath("[full path to this folder]/imgs/");
    tree.enableTreeImages("false"); // disable tree images
    tree.enableTreeLines("false"); // disable tree lines
    tree.load(file);
</script>

Enabling Loading Text

The user can set loading text for a tree item. This text will appear on item loading instead of its original text, and will be replaced by the original text when loading is done:

tree.enableLoadingItem(text);

The default loading text set in dhtmlxTree is "Loading...".

Using HTML in Item's Text

The user may use HTML escape characters in the text attribute of an item tag to include some HTML into a node's label, or he can use the nested <itemtext> tag with CDATA for the same purpose (this tag is supported only in PRO edition):

<?xml version="1.0">
 <tree id="0">
  <item id="1" text="&amp;lt; img src='some.gif' &amp;gt;"/> //using HTML escape characters
 </tree>
 <tree id="0">
 <item id="1">
  <itemtext><![CDATA <img src='some.gif'> ]]></itemtext> //using <itemtext> tag with CDATA
 </item>
</tree>

Style Manipulation

Setting Individual Style for an Item

The user can set individual style for any item in the tree in the following way:

tree.setItemStyle(itemId,style_string);

The parameters here are responsible for:

itemId - id of the item;
style_string - valid CSS string.