Extension:TreeAndMenu

MediaWiki extensions manual - list

TreeAndMenu Release status: stable
Implementation	Parser function, Skin
Description	Creates dynamic dropdown and folder tree menus
Author(s)	Nad, Zven
Last version	3.0.4 (2013-02-27)
MediaWiki	1.17+
Database changes	no
License	GPL
Download	OrganicDesign
Parameters $wgTreeViewShowLines
Hooks used ParserAfterTidy
Check usage and version matrix

The TreeAndMenu extension allows for dynamic dropdown menus, merging the best JavaScript dynamic menu (Sons of Suckerfish) into the TreeView code base, and renamed the extension from TreeView5 to TreeAndMenu.

This extension makes bullet lists into folder trees or dynamic drop-down menus. It has been tested successfully on MediaWiki versions 1.6.10, 1.8.4, 1.9.3, 1.10.2, 1.11.0, 1.12.0, 1.13.1, 1.14.0, 1.15.0, 1.16.5, 1.17.1, 1.18.1, 1.19.0. And is known to work on Safari, IE6, IE7 and all Mozilla based browsers such as Firefox and SeaMonkey.

Installation

• Download and extract the files in a directory called "TreeAndMenu" in your extensions/ folder.
• Add the following code to your LocalSettings.php (at the bottom)

require_once( "$IP/extensions/TreeAndMenu/TreeAndMenu.php" );

• Finally, add the CSS stylesheet below to your installation by modifying/creating your MediaWiki:Common.css page (note that's a wiki page not a file). Otherwise, your menu will look just like a nested list.
• Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

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.

CSS styles for trees (only required for old versions of TreeAndMenu)

The style of trees is defined using CSS by adding the rules to your MediaWiki:Common.css page. An example set of CSS rules have been included below which are those supplied with the dTree source code.

/*--------------------------------------------------|
| dTree 2.05 | www.destroydrop.com/javascript/tree/ |
|---------------------------------------------------|
| Copyright (c) 2002-2003 Geir Landr                |
|--------------------------------------------------*/
 
.dtree {
        font-family: Verdana, Geneva, Arial, Helvetica, sans-serif;
        font-size: 11px;
        color: #666;
        white-space: nowrap;
}
.dtree img {
        border: 0px;
        vertical-align: middle;
}
.dtree a {
        color: #333;
        text-decoration: none;
}
.dtree a.node, .dtree a.nodeSel {
        white-space: nowrap;
        padding: 1px 2px 1px 2px;
}
.dtree a.node:hover, .dtree a.nodeSel:hover {
        color: #333;
        text-decoration: underline;
}
.dtree a.nodeSel {
        background-color: #c0d2ec;
}
.dtree .clip {
        overflow: hidden;
        padding-bottom: 1px;
}

CSS styles for menus

The look and layout of dynamic menus can also be configured purely in CSS by adding the rules to your MediaWiki:Common.css page. Below is an example that was used in the example at OrganicDesign:Extension talk:TreeAndMenu.php.

/*
* Dynamic menus
*/
.dmenu { width: 180px }
 
.dmenu, .dmenu ul { /* all lists */
padding: 0;
margin: 0;
list-style: none;
}
.dmenu .selflink { font-weight: normal; }
 
.dmenu li { /* all list items */
position: relative;
float: left;
width: 172px;
padding: 4px;
z-index: 100;
}
 
.dmenu li,
.dmenu li.even a,
.dmenu li.odd a,
.dmenu li li,
.dmenu li li a,
.dmenu li li li,
.dmenu li li li a {
color : black;
}
 
.dmenu li li { margin: 0; }
 
.dmenu li ul { /* second-level lists */
position: absolute;
left: -999em;
z-index: 101;
border: 1px solid #ccc;
}
 
.dmenu li ul ul { /* third-and-above-level lists */
position: absolute;
left: -999em;
margin: 0 0 0 0;
z-index: 102;
}
 
.dmenu li.odd .submenu {
width: 12px;
height: 15px;
float: right;
background: url(/common/images/rarr-lt.png) 0 3px no-repeat;
}
.dmenu li.even .submenu {
width: 12px;
height: 15px;
float: right;
background: url(/common/images/rarr-dk.png) 0 3px no-repeat;
}
.dmenu li.odd {
        background: #E9EDF4;
        border: 2px solid #E9EDF4;
}
.dmenu li.even {
        background: #D0D8E8;
        border: 2px solid #D0D8E8;
}
 
.dmenu li:hover, .dmenu li.sfhover {
        border: 2px solid #385D8A;
}
 
.dmenu li:hover ul ul,
.dmenu li:hover ul ul ul,
.dmenu li.sfhover ul ul,
.dmenu li.sfhover ul ul ul {
left: -999em;
}
 
.dmenu li:hover ul,
.dmenu li li:hover ul,
.dmenu li li li:hover ul,
.dmenu li.sfhover ul,
.dmenu li li.sfhover ul,
.dmenu li li li.sfhover ul { /* lists nested under hovered list items */
left: 182px;
top: -3px;
}

Usage

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

{{#tree:
*Root1
**Sub-item
**Another sub-item
*Root2
**Sub-item
**Another sub-item
}}

{{#menu:
*Root1
**Sub-item
**Another sub-item
*Root2
**Sub-item
**Another sub-item
}}

{{#tree:id=siteTree|openlevels=1|root=Organic Design|
*Root
**Sub-item
**Another sub-item
}}

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 its state to be persistent
• openlevels= Opens a tree to specified depth by default
• open= equals top | bottom
• close= equals top | bottom

Images

• root
• folder
• folderOpen
• node
• empty
• line
• join
• joinBottom
• plus
• plusBottom
• minus
• minusBottom
• nlPlus
• nlMinus

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 {{#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.

{{#tree:
*[[Main Page]]
*[[Special:Recentchanges|Recent changes]]
*{{#ifgroup:sysop|Admin}}
*{{#ifgroup:sysop|Logs}}
*{{#ifgroup:sysop|Tasks}}
}}

• 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.

{{#tree:
*Articles in [[:Category:Foo]]
{{#dpl:category=Foo|format=,**,[[%PAGE%]]\n,}}
}}

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:

{{#tree:
*Tree1
**Item1
***Sub item1
**{{:Tree2}}
**Item3
}}

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

$wgHooks['BeforePageDisplay'][] = 'wfAddSidebarTree';
function wfAddSidebarTree( $out, $skin ) {
        global $wgUser, $wgParser;
        $opt = ParserOptions::newFromUser( $wgUser );
        $title = Title::newFromText( 'Sidebar', NS_MEDIAWIKI );
        $article = new Article( $title );
        $html = $wgParser->parse( $article->fetchContent(), $title, $opt, true, true )->getText();
        $out->addHTML( "<div id=\"wikitext-sidebar\">$html</div>" );
        return true;
}

This creates a CSS-addressable div element containing the parsed content from the MediaWiki:Sidebar article. 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.

var tree = $('#wikitext-sidebar');
$('#p-logo').after( tree.html() );
tree.html('');

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.

$wgHooks['MonoBookTemplateToolboxEnd'][] = 'wfNavTree';
function wfNavTree() {
        global $wgUser, $wgTitle, $wgParser;
        if ( is_object( $wgParser ) ) $psr =& $wgParser; else $psr = new Parser;
        $opt = ParserOptions::newFromUser( $wgUser );
        $nav = new Article( Title::newFromText( 'NavTree', NS_MEDIAWIKI ) );
        $out = $psr->parse( $nav->fetchContent( 0, false, false ), $wgTitle, $opt, true, true );
        echo '</ul></div>' . $out->getText();
        return true;
}

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.

#p-navigation, #p-tb h5, #p-tb .pBody { display:none }

• 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 (if using Vector skin)

Change the first line of the above code to:

$wgHooks['SkinTemplateToolboxEnd'][] = 'wfNavTree';

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

#p-navigation, #p-tb h5, #p-tb div.body { display:none !important; }

Sites using TreeAndMenu

Here's a list of wikis with the tree view installed:

• OrganicDesign:OrganicDesign - MediaWiki version 1.16.5 -- 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
• Illomi wiki - Used to display lists of topics in portals - MediaWiki version 1.19.2

Opening a tree to the current page

Here's a useful snippet of JS that can be put into MediaWiki:Common.js to open the tree to the current page. It finds and .self links in the tree and opens the tree to those nodes. You need to give your tree an id attribute so you can refer to it. Then check the source and find out what the JS object of the tree is called (it will be a new dTree() statement), basically it's just the id attribute with non-alphanumerics stripped and appended to "tam". In the following example the tree being adjusted has the id attribute of "sidebar-tree".

$(document).ready( function() {
    tamsidebartree.closeAll();
    $('#sidebar-tree .selflink').each( function() {
        tamsidebartree.openTo($(this).parent().parent().attr('id').replace(/[^0-9]/g, ''));
    });
});

Change Log

Refer to SVN for changes to TreeAndMenu.php, or to a historical revision of this article for change log and other information about older versions of this extension.

See also

• DPL:Treeview extension - Generating tree view content from DPL queries
• Semantic TreeView
• Extension:CSS Dropdowns