Extension:TreeAndMenu

From MediaWiki.org
(Redirected from Extension:Treeview)
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
TreeAndMenu

Release status: stable

TreeAndMenu.png
Implementation Parser function, Skin
Description Creates dynamic dropdown and folder tree menus
Author(s) Aran Dunkley
Latest version 4.2.0 (2015-06-21)
MediaWiki 1.17+
Database changes No
License GPL
Download
Example organicdesign.co.nz

Translate the TreeAndMenu extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

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[edit | edit source]

1. First download the extension:

  • Source code on github:
MediaWiki 1.25+: https://github.com/OrganicDesign/extensions/tree/master/MediaWiki/TreeAndMenu
Older MediaWiki versions: https://github.com/OrganicDesign/extensions/tree/MediaWiki-1.24/MediaWiki/TreeAndMenu
  • Download a copy of the extension from github (note this contains all the Organic Design extensions and you'll need to extract just the TreeAndMenu directory):
MediaWiki 1.25+: https://github.com/OrganicDesign/extensions/archive/master.zip
Older MediaWiki versions: https://github.com/OrganicDesign/extensions/archive/MediaWiki-1.24.zip

2. Clone or extract the TreeAndMenu folder into your wiki extensions folder.

3. Add the following code to your LocalSettings.php (at the bottom).

MediaWiki 1.25+:

wfLoadExtension( 'TreeAndMenu' );


Older versions:

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

New features using FancyTree jQuery plugin[edit | edit source]

  • Can works natively with UL/LI structures which allows the PHP code to be much simpler
  • Supports Ajax loading of sub-nodes
  • Works in preview and diff pages, even live preview
  • Much more extendable and has many other extensions written for it
  • Actively developed code

Usage[edit | edit source]

Trees and menus are created by surrounding normal nested bullet list syntax with a parser-function as in the following examples.

{{#tree:
*Item
**[[Sub-item link]]
**Another sub-item
}}

{{#menu:
*Menu item
**[[Sub-menu with link]]
**Another sub-menu item
}}

{{#tree: id=siteTree | class=navTree | root=Organic Design |
*Item
**[[Sub-item link]]
**Another sub-item
}}

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:

{{#tree: extensions=["persist"] |
*Item
**[[Sub-item link]]
**Another sub-item
}}

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 (full list of available options here):

{{#tree: minExpandLevel=2 |
*Item
**[[Sub-item link]]
**Another sub-item
}}

FancyTree options can also be passed to individual nodes with JSON syntax as follows, id and class values are put directly into the li element, all other JSON data is passed to the FancyTree code via a data-json attribute. Note that property names must also be quoted, not just values.

{{#tree:
*Item
**{"expanded",true "id":"MyExpandedNode"} [[Sub-item link]]
**Another sub-item
}}

The following options are recognised: active, expanded, focus, folder, lazy, selected, unselectable

Styles[edit | edit source]

The style of trees is defined using CSS by adding the rules to your MediaWiki:Common.css page. For example on my site I use the following to make the text and icons more like the last version of TreeAneMenu.

.fancytree ul {
    background: none;
    border: none;
    font-size: 12px;
}
ul.fancytree-container {
    outline: 0;
    border: none;
    overflow: hidden;
}
.fancytree p {
    display: none;
}
span.fancytree-title {
    cursor: default;
}
span.fancytree-title a {
    color: black;
}

Dynamic Trees and Menus[edit | edit source]

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:ExtraMagic 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[edit | edit source]

NOTE: This feature isn't working correctly in version 4.x, the transcluded content can only work with bullet lists and must use the correct depth as the dynamic queries are doing in the previous section.

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 may be another tree or a normal bullet list, if it's a tree, then the attributes and options are ignored and the whole tree renders in accord with the attributes and options of the root tree.

Loading nodes with Ajax[edit | edit source]

The new FancyTree jQuery plugin has support for Ajax loading of nodes. This has been made accessible by the TreeAndMenu extension by passing an ajax option to FancyTree using the JSON syntax shown above. The value of the ajax option is the URL from which to retrieve the data containing the child nodes.

The URL is expected to contain either another tree, a plain bullet list, or JSON formatted array of nodes where each node is an object containing title, optional href key, and optional children array of sub-nodes. If the "ajax" option's value is not an absolute or relative URL, then it is assumed to be an article title and its content will be retrieved with action=render.

{{#tree:
*Item-1
*{"ajax":"http://foo.bar/baz?foobas=1"} Item-2
*Item-3
}}

Adding a tree to the sidebar[edit | edit source]

One of the most common uses of this extension is to add a tree menu to the sidebar. This is easy if you're using your own custom skin, but if you want to do it without modifying the skin code, then you can use the following method.

MediaWiki 1.18+[edit | edit source]

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. Note that this example expects your tree to be defined in the MediaWiki:SidebarTree article. Note also that this code's id is independent of the id attribute you set for the tree itself, that (and the class attribute) are just for allowing different CSS for different trees.

$wgHooks['BeforePageDisplay'][] = 'wfAddSidebarTree';
function wfAddSidebarTree( $out, $skin ) {
	$title = Title::newFromText( 'SidebarTree', NS_MEDIAWIKI );
	$article = new Article( $title );
	$html = $out->parse( $article->getContent() );
	$out->addHTML( "<div id=\"wikitext-sidebar\">$html</div>" );
	return true;
}

This creates a div element (addressable with CSS by the "wikitext-sidebar" id attribute) 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.

$(document).ready( function() {
  var tree = $('#wikitext-sidebar');
  $('#p-logo').after( tree.html() );
  tree.remove();
});

MediaWiki <1.18 (using monobook skin)[edit | edit source]

The following code can be added to your LocalSettings.php file after the TreeAndMenu include line which allows a wiki article to be added to the sidebar below the toolbox. This example adds the article named "MediaWiki:SidebarTree" which can contain your tree, or any other wikitext content you'd like in your sidebar such as user-specific bookmarks etc.

$wgHooks['MonoBookTemplateToolboxEnd'][] = 'wfAddSidebarTree';
function wfAddSidebarTree() {
        global $wgUser, $wgTitle, $wgParser;
        if ( is_object( $wgParser ) ) $psr =& $wgParser; else $psr = new Parser;
        $opt = ParserOptions::newFromUser( $wgUser );
        $article = new Article( Title::newFromText( 'SidebarTree', NS_MEDIAWIKI ) );
        $html = $psr->parse( $article->getContent(), $wgTitle, $opt, true, true );
        echo '</ul></div>' . $html->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.

MediaWiki <1.18 (if using Vector skin)[edit | edit source]

Change the first line of the above code to:

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

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; }

Opening a tree to the current page[edit | edit source]

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 helper function called makeTitleVisible which reveals and activates the first node linking to the current page.

$(document).ready( function() {
    $('#tree').bind('fancytreeinit', function(event, data) {
        data.tree.makeTitleVisible();
    });
});

See also[edit | edit source]