Table of Content

1. Introduction
2. How it works
3. Hierarchical structure definition
4. Visual formatting
4.1. Required formatting attributes
4.1.1. Positioning on the page
4.2. Additional formatting attributes
4.2.1. Folder and button images
4.2.2. Control of animation process
4.2.3. Control of nodes visualization (colors, CSS classes, etc.)
4.2.3.1. CSS classes
4.2.3.2. Background colors
4.2.3.3. Indentation
4.2.4. Control the behavior
4.3. Table of all possible formatting attributes
4.3.1 Top level only attributes
4.3.2 Attributes allowed anywhere
5. How to add menu initialization to the page
5.1. Absolute positioning
5.2. Relative positioning
6. Example
6.1. Absolute positioning
6.2. Relative positioning

1. Introduction

SoftDrawer jsTree PRO is an advanced version of freeware SoftDrawer jsTree script with a lot of new cool features like relative positioning, great customization possibilities, etc.

2. How it works

There are a lot of javascript tree menus on the market but most of them require full DOM support (only IE5+, NS6+ and Opera7+) or FRAME/IFRAME to work. Such menus can't offer animation effects or complex customization. SoftDrawer jsTree chose another way. Each node of jsTree is a separate layer object and it gives a lot of possibilities to play with customization and animation.

The main problem of somebody, who is not a javascript guru, is a tree initialization but we chose the simplest way when we planned jsTree. You just need to fill simple hierarchical structure and write two-three lines in your HTML code and all other thing jsTree will make without you.

The full structure of jsTree is a complex associative javascript array with two elements in the first level:

format - In this section we define set of parameters which describe how the tree will be look like.
sub - (abbreviation from 'SubNodes') We describe hierarchical structure of the tree in this section.

Example:

var TREE_NODES={
format:{
//formatting parameters
},
sub:[
//tree structure
]
};

3. Hierarchical structure definition

One node of a tree defines as associative javascript array. Main attributes are:

html - node caption. This code will be enclosed in <A> </A> when tree will build code of the node.
url - node URL. It's value of HREF attribute of builded link.
target - target frame. It's value of TARGET attribute of builded link.
exp - if true node will be initially expanded.
sub - array with node children.

Examples:

var TREE_NODES={
format:{
//formatting parameters
},
sub:[
//three nodes without children
{html:'Node 1', url:'http://somewhere.com/'},
{html:'Node 2', url:'http://somewhere.com/'},
{html:'Node 3', url:'http://somewhere.com/'}
]
};

var TREE_NODES={
format:{
//formatting parameters
},
sub:[
//one node with children and twho without ones
{html:'Node 1', url:'http://somewhere.com/',
  sub:[
   {html:'Sub Node 1', url:'#'},
   {html:'Sub Node 2', url:'#'}
  ]
},
{html:'Node 2', url:'http://somewhere.com/'},
{html:'Node 3', url:'http://somewhere.com/'}
]
};

Unlike standard version jsTree PRO allows use not only formatting parameters which affect all nodes but also custom paramerers for particular node or particular level using format and level_format attributes.
Example:
var TREE_NODES={
format:{
//formatting parameters
},
sub:[
{html:'Node 1', url:'http://somewhere.com/', level_format:{/*formatting attributes*/},
  sub:[
   {html:'Sub Node 1', url:'#'},
   {html:'Sub Node 2', url:'#'}
  ]
},
{html:'Node 2', url:'http://somewhere.com/', format:{/*formatting attributes*/}},
{html:'Node 3', url:'http://somewhere.com/'}
]
};

4. Visual formatting

The main difference PRO version from standard is a way of controlling visual formatting of nodes. Standard version allow only format all nodes in the same way but jsTree PRO allow you define all set of formatting parameters not only for particular level but also for one particular node. See example above to look how it may be defined.

4.1. Required formatting attributes

4.1.1. Positioning on the page

For jsTree PRO menu position on the page can be absolute or relative to content. In the first case we have to define the left top corner of the menu in the format section.
Example:
var TREE_NODES={
format:{
left: 100,
top: 100,
...

To use relative positioning we have to set attribute relative to true. Both left and top attributes also may be used but in this case it is not a position on a page but a offset from the left top corner of a tree container.
Example:
var TREE_NODES={
format:{
relative: true,
left: 0,
top: 0,
...

Also we have to define initial width and height of menu rectangle.
Example:
var TREE_NODES={
format:{
...
height: 100,
width: 100,
...

4.2. Additional formatting attributes

4.2.1. Folder and button images

If you want to use folder images in the menu you need to define path to image files (SRC attribute of IMG tag) using following parameters.

e_image - expanded folder
c_image - collapsed folder
i_image - document (if node don't have children)
b_image - transparent 1x1 gif image (used for indentation)

Example:

var TREE_NODES={
format:{
...
e_image:"images/fo_p.gif",
c_image:"images/fc_p.gif",
i_image:"images/i_p.gif",
b_image:'images/b.gif',
...

By default image size is 32x16. If you use images with other size you may define size by img_size attribute. Example:

var TREE_NODES={
format:{
...
img_size:[24,24], //[width, height]
...

If you want to see only text links without any images you may set no_images attribute to true. Example:

var TREE_NODES={
format:{
...
no_images: true,
...

4.2.2. Control of animation process

jsTree gives you the easiest way to turn on tree expand/collapse animation. You need just set animation attribute to true. Also you may control animation timer and animation step by attributes anim_timer and anim_step correspondingly.
Example:

var TREE_NODES={
format:{
...
animation: true,
anim_step: 16,
anim_timer: 100,
...

Note: Opera may work slowly if you have a lot of sliding objects. You may turn off animation only in Opera in next way. Example:

var TREE_NODES={
format:{
...
animation: !window.opera,
...

4.2.3. Control of nodes visualization (colors, CSS classes, etc.)

The first we should understand how the generated HTML code looks like. This is an metamodel which show how jsTree build self.

<DIV class="%format.back_class%">
...
<DIV class="%format.div_class%">
<TABLE class="%format.table_class%">
    <TR>
        <TD>blank image with defined width for indentation</TD>
        <TD class="%format.item_class%">
            <A class="%format.link_class%" href="%node.href%">%node.html%</A>
        </TD>
    </TR>
</TABLE>
</DIV>
...
</DIV>

4.2.3.1. CSS classes

You can see the main layer which contains layers for each defined node. Each node is a layer with table which has two cells: one cell is for indentation and one with link code. There are five possible CSS classes which can keep menu representation in full control.

back_class - CSS class of main layer which contains all nodes.
div_class - CSS class of DIV which contains a table.
table_class - CSS class of table which help to build one node.
item_class - CSS class of one cell which contains the link element.
link_class - CSS class of the link element element.

Example:

var TREE_NODES={
format:{
...
  back_class:'clsLinkContainer',
  div_class:'clsNodeDIV',
  item_class:'clsNodeText',
  link_class:'clsNodeLink',
  table_class:'clsFullNode',
...

4.2.3.2. Background colors

Background color of DIV element of each node we can define by bgcolor attribute.
Background color of TD element of each node we can define by item_bgcolor attribute.
Background color of main layer we can control by attribute back_bgcolor.
Example:

var TREE_NODES={
format:{
...
  back_bgcolor:'yellow',
  item_bgcolor:'pink',
  bgcolor:'silver',
...

4.2.3.3. Indentation

Horizontal indentation for each level can be controlled by level_indent attribute multiplied on level number.
Vertical offset between nodes can be controlled by y_offset. (It may be negative number too)
Example:

var TREE_NODES={
format:{
...
level_indent: 16,
offset_y: 2,
...

4.2.4. Control the behavior

If you have not enough space for the tree menu you may turn on mode when only one branch can be opened at the time. Just set one_branch attribute to true or false.
Example:

var TREE_NODES={
format:{
...
one_branch: true,
...

4.3. Table of all possible formatting attributes

4.3.1 Top level only attributes

Attribute	Type	Required	Default	Description
left	integer	yes	0	Absolute X coordinate of the left top corner of the tree on the page
top	integer	yes	0	Absolute Y coordinate of the left top corner of the tree on the page
animation	boolean	no	false	If true then nodes will slide smoothly when you expand or collapse nodes.
anim_timer	integer	no	20	Timer interval in miliiseconds betwin animation steps
anim_step	integer	no	20	Size of animation step in pixels for one animation timer interval
back_class	string	no	''	CSS class of main layer which contains all nodes
back_bgcolor	string	no	''	Background color of main background layer
level_indent	integer	no	16	Horizontal indentation for each level. It will be multiplied on level number to get indentation for certain node.
one_branch	boolean	no	false	Controls only one branch at time mode.

4.3.2 Attributes allowed anywhere

Attribute	Type	Required	Default	Description
width	integer	yes	0	Recommended width of the tree menu
height	integer	yes	0	Recommended height of the tree menu background
b_image	string	yes	''	Path to 1x1 transparent image. Required for indentation.
e_image	string	no	''	Path to the image of expanded folder
c_image	string	no	''	Path to the image of collapsed folder
i_image	string	no	''	Path to the image of node without children
img_size	array	no	[32,16]	Width and height of folder images in format [width
no_images	boolean	no	false	If true then there are no folder and document images.
div_class	string	no	''	CSS class of DIV which contains a table
table_class	string	no	''	CSS class of table which help to build one node
item_class	string	no	''	CSS class of one cell which contains the link element
link_class	string	no	''	CSS class of the link element element
bgcolor	string	no	''	Background color of DIV element of each node
item_bgcolor	string	no	''	Background color of TD element of each node
offset_y	integer	no	0	Vertical offset between nodes. It may be negative number too
indent	integer	no	level_indent*level	Horizontal indentation for particular level or node.
real_indent	integer	no	0	Horizontal indentation for a layer with particular level or node.

5. How to add menu initialization to the page

5.1. Absolute positioning

You need just follow next steps.

Put TREE_NODES variable definition in separate file and name it structure.js.
Add links to structure.js and sdtree_pro.js to HEAD section of your HTML code.
Note: sdtree_pro.js is a file where SoftDrawerTreePRO object is defined.
Example:

<HEAD>
...
<script language="JavaScript" src="sdtree_pro.js"></script>
<script language="JavaScript" src="structure.js"></script>
...
</HEAD>
Add following code at the end your code before </BODY> tag.
...
  <script language="JavaScript" >
    var tree = SoftDrawerTreePRO('tree', TREE_NODES);
    tree.init();
    tree.draw(1);
  </script>
</BODY>
</HTML>

5.2. Relative positioning

You need just follow next steps.

Put TREE_NODES variable definition in separate file and name it structure.js.

Add links to structure.js and sdtree_pro.js to HEAD section of your HTML code.
Note: sdtree_pro.js is a file where SoftDrawerTreePRO object is defined.
Example:

<HEAD>
...
  <script language="JavaScript" src="sdtree_pro.js"></script>
  <script language="JavaScript" src="structure.js"></script>
  <script language="JavaScript" >
    var tree = SoftDrawerTreePRO('tree', TREE_NODES);
  </script>
...
</HEAD>

Add following code in the place where you want to put the tree. (We use right aligned DIV in example)
...
  <DIV align="right">
  <script language="JavaScript" >tree.init();</script>
  </DIV>
Add following code at the end your code before </BODY> tag.
...
  <script language="JavaScript" >
    tree.draw(1);
  </script>
</BODY>
</HTML>

6. Example

6.1. Absolute positioning

structure.js

var TREE_NODES={
  format:{
    left:50,
    top:50,
    width:160,
    height:210,
    e_image:"images/fo_p.gif",
    c_image:"images/fc_p.gif",
    i_image:"images/i_p.gif",
    b_image:'images/b.gif',
    bgcolor:"#d4d0c8",
    back_bgcolor:"#d4d0c8",
    animation:1,
    padding:2,
    dont_resize_back:1
  },
  sub:[
    {html:'Tree 1',
      sub:[
        {html:'Node 1',
          sub:[
            {html:'Sub Node 1', url:'#'},
            {html:'Sub Node 2', url:'#'},
            {html:'Sub Node 3', url:'#'}
          ]
        },
        {html:'Node 2',
          sub:[
            {html:'Sub Node 1', url:'#'},
            {html:'Sub Node 2', url:'#'},
            {html:'Sub Node 3', url:'#'}
          ]
        }
      ]
    }
  ]
}

index.html
<HTML>
<HEAD>
<SCRIPT language=JavaScript src="sdtree_pro.js" type="text/javascript"></SCRIPT>
<SCRIPT language=JavaScript src="structure.js" type="text/javascript"></SCRIPT>
</HEAD>
<BODY>
<SCRIPT type="text/javascript">
var tree=new SoftDrawerTreePRO('Demo',TREE_NODES);
tree.init(); tree.draw(1); </SCRIPT>
</BODY>
</HTML>

6.2. Relative positioning

structure.js

var TREE_NODES={
  format:{
    relative:true,
    left:0,
    top:0,
    width:160,
    height:210,
    e_image:"images/fo_p.gif",
    c_image:"images/fc_p.gif",
    i_image:"images/i_p.gif",
    b_image:'images/b.gif',
    bgcolor:"#d4d0c8",
    back_bgcolor:"#d4d0c8",
    animation:1,
    padding:2,
    dont_resize_back:1
  },
  sub:[
    {html:'Tree 1',
      sub:[
        {html:'Node 1',
          sub:[
            {html:'Sub Node 1', url:'#'},
            {html:'Sub Node 2', url:'#'},
            {html:'Sub Node 3', url:'#'}
          ]
        },
        {html:'Node 2',
          sub:[
            {html:'Sub Node 1', url:'#'},
            {html:'Sub Node 2', url:'#'},
            {html:'Sub Node 3', url:'#'}
          ]
        }
      ]
    }
  ]
}

index.html
<HTML>
<HEAD>
  <SCRIPT language=JavaScript src="sdtree_pro.js" type="text/javascript"></SCRIPT>
  <SCRIPT language=JavaScript src="structure.js" type="text/javascript"></SCRIPT>
  <SCRIPT type="text/javascript">
  var tree=new SoftDrawerTreePRO('Demo',TREE_NODES);
  </SCRIPT>
</HEAD>
<BODY>

<DIV align="right">
<SCRIPT type="text/javascript">
tree.init();
</SCRIPT>
</DIV>

<SCRIPT type="text/javascript">
tree.draw(1);
</SCRIPT>
</BODY>
</HTML>