Extension:TreeAndMenu

There are currently some problems with Treeview5 preventing it from working with MediaWiki versions prior to 1.11. This will hopefully be resolved soon.

Installation
Create a Treeview5 folder in your extensions directory. Download the main extension script from OrganicDesign:Extension:Treeview5.php (older versions still available: version 3.x, version 4.x), save it into the new folder and include it in your LocalSettings.php file as in the following example. Download the dTree tree menu component as a .zip file from here and unpack it into the Treeview5 directory you created and saved the script into.

Ensure that all the files you've downloaded and saved are accessible by the webserver.

Usage
Tree-views are created by surrounding a normal nested bullet list within the following couple of examples:

The second tree example uses a tree-view parameter called openlevels to make the tree expand by default to one level. Currently the parameter can only be supplied on a per-tree basis, to have different branches open to different depths requires multiple tree definitions.

Images
Notes for current version (5.x) to come

Images (Version 4.x)
The images the tree-view uses are defined in the $wgTreeViewImages global array, opened and closed folder images and a document (leaf node) image are required, as well as plus and minus images to click on to open or close the folders. Also a blank.gif image is required which is just a single pixel transparent image used for layout.

You can create your own images, or use some from a selection listed in OrganicDesign:Category:Tree view images. Use the following format to define the images and place it in your LocalSettings.php file. If you have some cool images to use for your tree-view that you'd like to share, feel free to upload them to OrganicDesign and categorise them into Category:Tree view images where they'll be seen.
 * note1: specifying tree-view images has been simplified in version 3.6.1 to require only the image title with no preceding file path information.
 * note2: if preferred, images can still be defined using relative or absolute URL's rather than image titles
 * note3: the image names shown above are the defaults used by the extension, so you only need to set the values for the images you're using which differ from these.
 * note4: Tree-view images can be any size, but the indentation is based on the pixel width of the "plus" image and defaults to 16px if this width cannot be obtained for some reason.

Inline images
As of version 4.0.8, custom images can be specified for treeview rows using normal wikitext image link syntax (currently no parameters such as px are allowed in the link). An image to be used for a tree view icon must be the first thing in the row otherwise it will be treated as normal content and use the default icons as specified in the $wgTreeViewImages array. Here's an example in which the second row has a custom icon,

CSS styles
Copy the content of the dtree.css file in your Treeview5 folder to the end of your MediaWiki:Common.css article in your wiki.

More notes on CSS for version 5 to come

TreeView 4.x CSS Styles
Other design aspects of the tree can be changed from your wiki's CSS stylesheet, which can be added to your "MediaWiki:Monobook.css" article if you're using the Monobook skin. The tree is in the form of an HTML table of CSS-class tree-view, there are also classes in the table's td elements called tree-icon and tree-text for specifically isolating those aspects of the tree's style. We use the following CSS which produces the tree style which you can see in the side-bar of the OrganicDesign wiki.

TreeView 3.x CSS Styles
Remember that you need get your browser to refresh the page after adjusting stylesheets because it normally only reloads the HTML when a page changes, not the associated stylesheets.

Dynamic Trees
You can use transclusion to embed the content of trees from other articles, or dynamically manipulate the content. For example a DPL query could generate the body of a treeview statement. Articles containing trees should not have any whitespace above the wikitex markup specifying the parser function tree otherwise the rendering can fail. Here's a dynamic example used in conjunction with Extension:Simple Security which creates a tree which exhibits some links that are only visible for sysops.


 * Note: The tree-view code will remove any empty items so they can work conditionally like this.

Here's another example of a dynamic tree using the DPL extension to make a tree which draw it's items from all the articles in the foo category.

The query uses some DPL parameters to ensure that the results are preceded by double asterisks so that the items can appear inside the root node. See also this example for a more advanced use of DPL with tree-view to create a menu which contains two levels of outgoing links from a given page, or incoming pages to a given page.

Sub-trees
Trees can be transcluded within other trees so we can define large trees from structures of smaller trees. Such sub-trees are defined using the following syntax:

In this example, an article called Tree2 is transcluded as an item in Tree1. Tree2 is defined as a normal tree starting at root which can be used elsewhere in the normal way. The tree-view code matches nested trees and adjusts them to the appropriate depth for them to seemlessly integrate into single whole tree. The class and other attributes of sub-trees are ignored and the whole tree renders in accord with the attributes of the root tree.

Adding a treeview to the sidebar (if using monobook skin)
One of the most common uses for the treeview is to replace the links in the sidebar with a tree. The following code can be added to your LocalSettings.php file after the treeview include line which allows a wiki article to be added to the sidebar below the toolbox. This example adds the article named "NavTree" which can contain your tree, or any other wikitext content you'd like in your sidebar such as user-specific bookmarks etc. If you want to also remove the existing toolbox and navigation links, you can use CSS as in the following example (the toolbox needs to be removed slightly more specifically than navigation because the tree-view renders inside its main div element):
 * You may also need to add width: 100%; in your tree-view CSS to fix IE alignment issues when adding to the sidebar.

Testing & experimentation
Here's a list of environments the tree-view has been tested in:
 * Works with PHP5 but may have problems with PHP4
 * Works on MediaWiki 1.6.7
 * Works on MediaWiki 1.9.3
 * Works on MediaWiki 1.10.0
 * Works on MediaWiki 1.11.0

Sites using the tree
Here's a list of wikis with the tree view installed:
 * OrganicDesign - MediaWiki version 1.10.0
 * http://www.peerix.org/Sandbox - MediaWiki version 1.6.7
 * http://www.wikifs.org/Sandbox - MediaWiki version 1.9.3
 * http://semeb.com/dpldemo - Demo website for two other MediaWiki Extensions
 * http://www.inmatelaw.org - Used to create law outlines
 * Citizendium - To redesign the sidebar and probably to organise content in some ways, see citizendium:CZ Talk:Treeview Extension

Bugs & Todo (Version 4.x only)

 * Session-based persistence
 * Need to allow a root node because the first items have a broken bit of connector where the root should be
 * There's a broken connector line if a container item is a multi-liner, as in the following image

Change Log

 * Version 5.1.7 (2008-03-08): Script elements muxt have closing tags for page to be valid xhtml
 * Version 5.1.5 (2008-03-07): Fix rootname bug
 * Version 5.1.4 (2008-03-05): Change rendering code to use innerHTML instead of document.write
 * Version 5.1.3 (2008-03-03): Persistence and pfunc args fixed
 * Version 5.1 (2008-03-03): New voodooless method written to work with all MediaWiki versions including 1.12
 * Version 5.0.3 (2008-02-27): Fix bug with node's calculation of parent id
 * Version 5.0.2 (2008-02-27): Tree id's based on wrong variable
 * Version 5.0.1 (2008-02-27): Make $wgTreeViewImages and $wgTreeViewShowLines work again
 * Version 5 (2008-02-25): Changed tree JavaScript to dTree
 * Version 4.0.8: Added ability to have custom images
 * Version 4.0.7: get rid of strange character that cropped up on the end of transcluded trees in MW1.11
 * Version 4.0.6: Connector lines working, and multi-line items working
 * Version 4.0.3: Fix entire tree indentation problem, and add $wgTreeViewIndent
 * Version 4: Rebuilt core to fix long-standing transclusion problem
 * Version 3.6.2: Don't hardwire to 16px and fix incorrect leaf-node indent
 * Version 3.6.1: Tree-view images are now specified using only the image title with no preceding path information
 * Version 3.6.0: The treeview id's have been changed to be globally unique so that trees received within ajax requests don't have conflicting id's
 * Version 3.5.7: JavaScript inclusion uses $wgOut->addScript, but this seems to fail on MediaWiki versions < 1.9.x when called from within the parser hooks, so I've added the script to the page unconditionally if the version is less than 1.9.0.
 * Version 3.5:
 * The tree was proving to be very processor intensive which turned out to be due to the invoking of the MediaWiki parser for each individual item. The main rendering method has been changed so that the parsing of the items is now done by the normal page parsing process.
 * The hooks introduced in the last version have been removed
 * Version 3.1: TreeViewParseItem and TreeViewRenderItem hooks added.
 * Version 3.0:
 * The syntax has changed from using div tags to using the double-curly-braces parser functions syntax.
 * The code has been made far more efficient by hooking into the parser instead of matching and replacing trees in the entire page text.
 * Images can be set specifically on a per-tree basis.
 * Empty items don't render so that parser functions like #ifexists can be used to filter the tree content.
 * The javascript code is added properly to the page's head scripts, and is not added if there are no trees on the page.
 * Version 2.1: Added recursion capability.
 * Version 2.0: This tree-view was originally created for our own Organic Design wiki which is a slightly different environment than a normal MediaWiki, so I had created a simple wrapper to allow the same code to work in normal MediaWiki's too. Using a wrapper like this meant that the trees wouldnt render properly if they were transcluded from another article, but that has now been fixed by creating a separate MediaWiki specific extension instead.

About TreeView4
TreeView4 has been developed which is more efficient and handles transclusion in a more robust way. The core code has been re-written in the new version to include special voodoo techniques to overcome a long standing bug preventing articles containing trees from being able to be transcluded unless they're transcluded directly into another tree. The new version appears to execute a little faster too, but I'll test it for a while before making it the new default version here. If you'd also like to try out the new version, you can download it from OrganicDesign:Extension:Treeview4.php. You can run it concurrently with TreeView 3.x by setting $wgTreeView4Magic to a different name than your old version's magic. Also, you can experiment with the sandboxes on OrganicDesign (a MediaWiki 1.10.0) and Peerix (a MediaWiki 1.6.10) which are both running TreeView4.

The main voodoo is the following bit of code which allows the recursive tree stuff to work even though there's no way to determine the transclusion depth from MediaWiki's parser environment. I understood the voodoo enough to get it working by combining it with some minor hacks, some trial-and-error, some perserverence and some luck ;-)

Features added in version 4

 * More efficient and robust rendering mechanism
 * Connector lines between nodes (can be removed by setting $wgTreeViewShowLines to false
 * Icons can be specifically set on a per-row basis by adding   (open name is optional)
 * Handles transclusion properly (the 3.x tree's could not be included within transcluded articles)
 * Allows item text to span multiple lines

About TreeView5
TreeView5 still uses the same black magic and voodoo as version 4 for allowing trees to work recursively properly, but now uses dTree for the JavaScript aspect.