Extension:TreeAndMenu

This extension makes bullet lists into folder trees or dynamic drop-down menus. It works on all versions of MediaWiki since 1.17. If you're using MediaWiki 1.16 or less, then make sure you're using the latest TreeAndMenu version that is less than 2.0.0, and read this old version of this page instead. If using MediaWiki 1.17 or greater then you should use the latest version of TreeAndMenu.

The drop-down menu functionality uses Son of Suckerfish which is 99% CSS, and the tree component is now using the FancyTree jQuery plugin rather than the dTree used in previous version of the TreeAndMenu extension. The new FancyTree has many options and plugins and is very extendable, please view the site and examples for more detail.

Installation

 * Source code on github:
 * https://github.com/OrganicDesign/extensions/tree/git-svn/TreeAndMenu


 * Download a copy of the extension from github:
 * https://github.com/OrganicDesign/extensions/archive/git-svn.zip

Open the zip file and save the TreeAndMenu folder into the extensions folder
 * Add the following code to your LocalSettings.php (at the bottom).

The style of trees is defined using CSS by adding the rules to your page. For exmaple on my site I use the following to make the text and icons more like the last version of TreeAneMenu, and to remove the focus rectangle.

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

The TreeAndMenu extension packages the tree with the ExtPersist plugin which allows the state of the tree to be maintained across page loads. To activate it use the following syntax:

The value of the extensions parameter is JSON so the quotes must be double not single. Other plugins can be added like this, but you'll need to load the JavaScript yourself.

Options can also be passed to the FancyTree code as well like this example:

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 draws its 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 seamlessly 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 (MediaWiki 1.18+)
As of MediaWiki-1.18, I've found a good way to get wikitext into the sidebar is to attach a function to the BeforePageDisplay hook with the following content:

This creates a CSS-addressable div element containing the parsed content from the MediaWiki:SidebarTree article (it's best not to use the default MediaWiki:Sidebar article for this as it can cause some problems). You can then use some JavaScript added to your MediaWiki:Common.js to move the element into a more appropriate location in the page DOM. For example the following JavaScript snippet inserts the rendered wikitext below the site logo.

Adding a treeview to the sidebar <1.18 (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 "MediaWiki: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). CSS rules can be added to the MediaWiki:Common.css article, remember to refresh your browser to force the CSS to reload to see the changes take effect.


 * You may also need to add width: 100%; in your tree-view CSS to fix IE alignment issues when adding to the sidebar.

Adding a treeview to the sidebar <1.18 (if using Vector skin)
Change the first line of the above code to:

And render using IE and Safari, the toolbox was still showing. This fixes it.

Sites using TreeAndMenu
Here's a list of wikis with the tree view installed:
 * OrganicDesign - in the sidebar below the toolbar
 * http://semeb.com/dpldemo - Demo website for two other MediaWiki Extensions -- in the sidebar below the toolbar
 * Citizendium -  Used to redesign the sidebar and probably to organise content in some ways, see citizendium:CZ Talk:Treeview Extension
 * http://pcthailand.org Uses a 4-level dynamic dropdown menu - Mediawiki version 1.17.0
 * An internal documentation wiki at Vistaprint

Opening a tree to the current page
The following example can be added to your MediaWiki:Common.js, it waits until the document is ready, then adds an event to a tree (selected by its id attribute, in this case #tree) so that when the tree is initialised it calls a function that scans the tree for a node with the same title as the current page. If it finds such a node, it opens the tree to reveal it and then selects it. All animations and events are disabled so that it will appear open immediately on page load.

Loading nodes with Ajax
todo...