Extension:TreeAndMenu

Recent News: 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 ;-)

Installation
This extension is a single article or file which you can get from OrganicDesign:Extension:Treeview.php which is to be included in your LocalSettings.php article or file as in the following example.

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

The second tree examples uses a tree-view parameter called openlevels to make the tree be expanded 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
The images the tree-view uses are defined a 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.

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, and the rows are of class tree-row. I use the following CSS which just makes the text a bit smaller and prevents the item's text from wraping. 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 a 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.

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):

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

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

Bugs

 * It seems to have a problem in PHP4 currently where the $wgTreeView->info array is cleared between pass1 and 2
 * Trees don't work when transcluded into an article normally, only when transcluded into other trees
 * A work around for this bug is to transclude your tree in an empty containing tree as follows:


 * Changing tree images dynamically in the syntax doesn't work properly yet

Plans
I'm thinking of simplifying it and using an existing pure client-side JavaScript solution to convert it from a standard bullet list. The role of the PHP would be to allow the trees to be nestable using transclusion. For example, kryogenix.org have some appropriate open source javascript that could do it.

Changes in version 3.6.2

 * Don't hardwire to 16px and fix incorrect leaf-node indent

Changes in version 3.6.1

 * Tree-view images are now specified using only the image title with no preceding path information

Changes in 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

Changes in 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.

Changes in 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

Changes in version 3.1

 * TreeViewParseItem and TreeViewRenderItem hooks added.

Changes in 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.

Changes in version 2.1
Added recursion capability.

Changes in 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.