Extension:TreeAndMenu

I've needed to create parser-functions a number of times which allow the rendering of dynamic menu's. Each time I've created a specific extension for the job and have used code from TreeView to achieve it, so finally I bit the bullet and merged the best JavaScript dynamic menu I've found (Sons of Suckerfish) into the TreeView code base, and renamed the extension from TreeView5 to TreeAndMenu.

The TreeAndMenu extension allows bullet lists to be rendered as folder trees or dynamic drop-down menu's. It has been tested successfully on MediaWiki versions 1.6.10, 1.8.4, 1.9.3, 1.10.2, 1.11.0 and 1.12.0. And is known to work on Safari, IE6, IE7 and all Mozilla based browsers such as Firefox and SeaMonkey.

Screenshot showing a tree on the left and a dynamic drop-down menu on the right

Installation
Create a TreeAndMenu folder in your extensions directory. Download the main extension script from SVN into the new folder and include it in your LocalSettings.php file as in the following example. The TreeAndMenu on SVN also contains the dTree tree menu component, but you may want to check source from www.destroydrop.com/javascripts/tree in case a later version is available.

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. The second argument is used to add a label to the tree (as shown on the tree at http://www.organicdesign.co.nz).

Parser function parameters

 * root= The content of the root node. Later this will also affect how sub-trees work
 * id= A tree must be given a unique identifier if you want it's state to be persistent
 * openlevels= not implemented in 5.x yet
 * open= equals top | bottom
 * close= equals top | bottom

Images
Docs to come...

CSS styles for tree's
The style of trees can also be configured purely in CSS by adding the rules to your MediaWiki:Common.css article. An example set of CSS rules have been included below which are those supplied with the dTree source code.

CSS styles for menu's
The look and layout dynamic menu's can also be configured purely in CSS by adding the rules to your MediaWiki:Common.css article. Below is an example which was used in the example at OrganicDesign:Extension talk:TreeAndMenu.php.

Dynamic Trees and Menus
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.
 * There is more detail about manipulating sidebar content and its layout at Manual:Interface/Sidebar.

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.10
 * 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 5.x only)

 * Transclusion needs to account for root node
 * Inline images not done yet

Change Log

 * Version 1.0.1 (2008-05-15): bug fix, only first tree on page would render correctly
 * Version 1.0.0 (2008-04-17, changed name to TreeAndMenu): #menu parser function added to allow rendering as drop-down menu's
 * Version 5.1.10 (2008-04-15): problems with windows paths fixed
 * Version 5.1.9 (2008-03-12): open/close = top/bottom/root options added
 * Version 5.1.8 (2008-03-10): IE rendering bug fixed
 * Version 5.1.7 (2008-03-08): Script elements must 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 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.

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