Conventions used in this document:

• Any text that is in this font is considered code, a literal value, the name of a file, folder, MySQL table, MySQL field, or a value in a MySQL field.
• Any text that is surrounded by angle brackets like  <this>  means that you should substitute it for your own value.
  Example: vconsole/modules/<module>/ means that you should substitute <module> for your own value like invoices for the Manage Invoices module.
• Any text that is surrounded by square brackets like  [this]  means that it is optional.
  Example: check_email($email, $error[, $dnscheck]);  means that [, $dnscheck] is optional
• When you see ... in the code font, this means that you can add 1 or more items at that point. Do not actually include ... in your code.
  

Creating Tree Fields. Tree fields allow you to present the user with a hierarchical tree like interface in which tree branches can be expanded, collapsed, and selected. The interface allows you to specify what tree branches can be expanded, what tree branches can be selected, how many branches can be selected, and what happens when a branch is selected. You can even do some advanced stuff like allow users to perform operations on tree branches using a right click menu. Tree fields are perfect for allowing the user to browse through a file structure or any other type of hierarchical structure while allowing them to select 1 or more of those items. The selected items' ids are passed back to you in the $data array and can be used to perform operations on those branches. Here is what a tree field may look like:

 
There are 2 tasks that need to be done in order to create a tree field.

1. Create Your fielddata structure
2. Insert tree branch records into the vc_trees table.

Let's start with the first task - creating your fielddata structure. You create your fielddata structure just like any other field (or you can use the Dreamweaver Toolkit and all the work is done for you.), except there are some additional parameters that are required for tree fields. Let's just give an example then we will give you a walk through of what each parameter is.
  OK, lets go through the code in the above example and see what it all does.

• Lines 1 - 12: These lines take care of starting a php block and initializing the $wm wizardmanager array.
• Line 15: field_type This line specifies the type of field as a tree field.
• Line 16: field_name This line specifies the name of the field. This name must be unique throughout the $wm structure and is used to grab input values after the user has selected 1 or more branches.
• Line 17: field_label This line specifies the label for the field. Users will see this at the top of any tree field.
• Line 18: field_pack This line specifies how to pack the field in relation to previous fields.
• Line 19: field_help This line specifies the help that is displayed when users hover their mouse over the label.
• Line 21: min_choices This line specifies the minimum number of choices that the user must select. We set this to 1 to make sure that the user selects at least 1 tree branch.
• Line 22: max_choices This line specifies the maximum number of choices that the user can select. We set this to 5 to make sure that the user does not select more than 5 tree branches.
• Line 23: treeid This line specifies the treeid for the tree. All branches for this tree must have the same treeid (treeid field) in the vc_trees MySQL table.
• Line 24: treetable This line specifies the tree table where the tree branch records are stored. The table should have the same structure as the vc_trees table.
• Line 25: defaultexpanded This line should contain an array of branches that should be expanded by default.
• Line 26: defaultselected This line should contain an array of branches that should be selected by default.
• Lines 27 - 36: treecolumns These lines define the columns for the tree. The tree can have up to 9 columns. (Unless you use a different table than the vc_trees table and add more col<num>val columns). Checkout the structure of the vc_trees table to get an idea of how to do this.
• Lines 37 - 46: treeops These lines define 1 or more tree operations. This allows you to create a menu that the user will see when they right click on any branch.
• Lines 47 - 57: These lines are the same as any other wizardmanager.
• Line 58: This line shows how to access the branches that the user selected.
• Line 61: This line shows how to access the branches that the user had expanded.

OK, the 2nd task is to enter all your branches into the vc_trees table. Each record in the vc_trees table is a separate branch. Simply enter a single table record for each branch that you want in your tree. You can stack these branches in a hierarchical manner that allows the user to expand and collapse branches. The vc_trees table structure follows the same principles as explained in the "Managing Hierarchical Data - Nested Set Model" section of this documentation. Here is the structure of the vc_trees table and what each field should contain:

• id - This is the primary key for the table and is also an auto-increment field. Each new record that is inserted into the table will get a unique id
• treeid - This field specifies the treeid for the tree. Each branch that belongs to the same tree should have the same treeid. You can have multiple trees within the vc_trees table. Each tree can contain 1 or more branches (records in the table) and should have a unique treeid.
• value - This field should contain the unique branch value. This field is not required and is not returned in the $data array, but rather, you can choose to use this field to hold a unique value for each branch in the tree. To get the values of selected branches, after the user completes the wizard, simply query the vc_trees table and get the value for each selected id. (Selected ids are stored in the $data[<step>][<field_name>]['selected'] array.)
• expandable - This field should be set to 1 or 0. If 1, then the branch is allowed to be expanded and will show a plus or minus icon next to the branch indicating to the user that they can expand or collapse the branch. If set to 0, then no plus, minus sign is shown next to the branch and the branch is not allowed to be expanded, even if the branch contains child branches.
• selectable - This field should be set to 1 or 0. If 1, then the branch is allowed to be selected by the user. If set to 0, then the branch is not allowed to be selected by the user and darkened checkbox will appear instead of the regular checkbox.
• disablechildresifselected - This field should be set to 1 or 0. If 1, then when the branch is selected, all child branches will be disabled and not be able to be selected, and likewise, when the branch is unselected, all child branches will be enabled again. If set to 0, then child branches will not be disabled when the branch is selected.
• disableparentsifselected - This field should be set to 1 or 0. If 1, then when the branch is selected, all parent branches will be disabled and not  be able to be selected, and likewise, when the branch is unselected, all parent branches will be enabled again. If set to 0, then parent branches will not be disabled when the branch is selected.
• image - This field should contain the name of an image to display for the branch. This string is passed directly to the getimage() php function and is NOT the path of an image file, but rather, the name of the image file as required by the getimage() php function. (To see a list of available images, open up a web browser and pull up the vconsole/showimages.php page.) You can add your own images by placing them in the vconsole/skins/vsource/icons/ folder. If you don't specify an image, then the icon_folder (16x16 small folder icon) image is displayed.
• col1val - This should contain the value of the first column of the tree. This is displayed directly next to the image for each branch. How the value is displayed to the user is determined by the type of column as set in the treecolumns section of the field structure (above)
• col2val - col9val - These fields should contain the values of the columns 2 through 9 and follow the same rules as the col1val field. In order for a column to be displayed, it must have a definition in the treecolumns section of the field structure.
• lft - This field contains the left index of the field and is part of what determines the hierarchical structure for the tree. Check out "Managing Hierarchical Data - Nested Set Model" for more information on how to specify parents and children for the tree.
• rgt - This field contains the right index of the field and is part of what determines the hierarchical structure for the tree. Check out "Managing Hierarchical Data - Nested Set Model" for more information on how to specify parents and children for the tree.
• depth - This field should contain the depth of the branch in the tree. Top level branches should have a depth of 0 and any child of a top level branch should have a depth of 1 and so on.

NOTE: You can use the hierarchical_add(), hierarchical_delete(), hierarchical_moveto(), and hierarchical_setorder() php functions in order to insert tree branches in the correct way dynamically.

Advanced Stuff -Tree Operations:
Regular tree fields are great for allowing the user to select 1 or more branches in your tree, but what if you want to allow the user to perform operations on the tree like add a new branch on the fly, or delete a branch, or maybe rename a branch or change the image of a branch? Tree operations are the way to go. Tree operations allow you to create menus (and possibly sub menus) that appear when the user right clicks on a branch. (See the example above on lines 37 through 46 for an example of how to do this.) When a user right clicks on a branch, they get the menu that you define. And when the user clicks on a menu item, the code that is specified in the link parameter is executed. The link parameter can contain a simple URL (in which case, the user will be redirected to a new url and will exit the VConsole interface) or it can contain a javascript function like in the example above on line 42. If it contains a javascript function, then you have to define that javascript function in the vconsole/javascript/customscripts.js file. What you do in that function is up to you, however, you probably should pass in some type of tree operation that you can check for and do the operation before you define the $wm array. Here is an example of such a javascript function:  
Now in our wizardmanager file, we can check the value of $_REQUEST['treeop'] and insert a new child branch under the branch that the user right clicked on.