Help:Treeview skin

Introduction and version

This is the main reference page for the Treeview skin for MediaWiki (ordinarily it would be imported as the "Help:Treeview skin" article on a wiki on which the skin was installed). The Treeview skin bolts on some extra structuring and navigation support to MediaWiki's Monobook skin, and slightly alters the Monobook look (Monobook was at one point the default skin for MediaWiki; now the default skin is Vector).

It corresponds to version 1.6.7 beta, unchanged since 1.6.6 beta. If the version listed beside Hierarchy at Special:Version on your wiki does not fall within that range then parts of this reference might be outdated.

Activating

If the skin is installed and it is not the default skin, then it can be activated through the "Skin" section on the account preferences page for logged-in users (Special:Preferences). If "Treeview" is not listed there, then the skin is not installed or has been disabled by an administrator.

Installing

Installation instructions for the wiki administrator are in the README.Treeview file in the skins directory in the distribution archive.

Feedback, bug reports, feature requests and new versions

The Planning:Treeview skin:Feedback page on clc-wiki.net may be used for feedback, bug reports and feature requests. New versions will be listed on and may be downloaded from the page http://creativeandcritical.net/mediawiki_treeview_skin/.

Use

There are installation notes in the README.Treeview file in the skins directory. Beyond that, these directions might help:

Default config

The default configuration is located at MediaWiki:Treeview. You can, if $wgDatabaseMessages is true, modify this configuration (and even if $wgDatabaseMessages is false, you can specify a different configuration article through the $wgHierarchy setting, which article you can then modify).

The <treeview> tag

To insert the hierarchy into a wiki page, use the <treeview></treeview> syntax, which takes the following optional parameters:

In the case that showtitle and showthis are specified simultaneously, showthis will be ignored.

Wikified, importable documentation

Read (and optionally import into your wiki) the documentation in the wikified skins/treeview/help_articles/* files.

Summary

The skin adds the concept of "pseudo-namespaces" - termed "contexts" or "sub-contexts" - in wiki article titles using colons as separators, and creates a hierarchy out of them. It then displays that hierarchy as a treeview that replaces Monobook's native sidebar navigation pane. As well it allows a category tree to be shown in the treeview. It also displays a navigation bar at the top of the page for traversal of the hierarchy without using the treeview.

Aside from the treeview and navigation bar, the concept is pretty similar to MediaWiki's native sub-page functionality that uses forward slashes.

The hierarchy can be configured through the (by default) 'Treeview' message, which is visible and editable as the MediaWiki:Treeview article unless the wiki administrator has disabled database messages. This configuration article corresponds to the Monobook skin's MediaWiki:Sidebar configuration article for its navigation pane. It provides a superset of the MediaWiki:Sidebar functionality, with a slightly different syntax.

The Treeview configuration is flexible - it supports variables, conditionals, static nodes, grafting and pruning. Sub-trees can be grafted in multiple places with different prunings applied.

Detailed feature listing

Style based on Monobook with slight modifications

Style changes include: a curved border around content, a single background colour and a shorter vertical space for the site logo. The personal/login menu has been converted into a drop-down menu displayed when the mouse hovers over an LED-style icon; the LED is green if the page was accessed whilst logged in, otherwise it is grey.

Rationale: Differentiates the skin from Monobook/Wikipedia without making too radical a change.

A customisable treeview sidebar component

This is a graphical aid for visualising and categorising the site, in the style of an expandable and collapsable treeview component. It auto-expands to display the node(s), if any, corresponding to the currently viewed title, highlighting that node(s) and its ancestors. Load-on-demand when expanding nodes is available where supported (many graphical browsers), falling back to a full-page reload. MediaWiki-supported caching, aside from squid, has been considered so that unnecessary re-downloads of content are avoided where possible. The complete expanded/collapsed state of the treeview persists across page views in most situations. It supports most browsing paradigms, from simple text-based browsers to javascript + css + cookie-enabled graphical browsers. Custom icons can be uploaded to the wiki and specified per-node in the configuration page. Help:Treeview skin:Treeview is a reader, user and admin reference to this component. Help:Treeview skin:Syntax is a reference to the configuration page's syntax.

Rationale: It is often easier to find information in a structured hierarchy - related pages are visible nearby. It is also helpful to be able to see and explore the full scope of the wiki's contents without clicking through content links or full category pages. Having previously expanded nodes remain in that state across page views can be an aid to navigation; likewise persisting collapsed nodes across page views avoids the irritation of having to re-collapse them on each view.

A navigation bar

The navigation bar is displayed under the page title. It provides buttons linking to the first, previous, previous child (last child of the previous parent), previous parent, next parent, first child, next, and last node relative to the current node. Links that don't exist are greyed out. The location of the "current node" in the hierarchy is the first match if the title appears in multiple places. When there is no previous sibling, the previous button turns into a "previous node at same depth" icon; likewise for the next button. Adds rel="[value]" attributes to links as appropriate.

Rationale: It's helpful to be able to "click-through" a set of related pages, or to otherwise navigate in a structured way without using the treeview component. The "first child" button is handy to drop into the child nodes with a single click when the selected node isn't expanded in the treeview. Bars like this are reportedly supported by some browsers based on the "rel" link attribute - here the opposite occurs: the rel attribute is supplied after generating the bar.

Colons denote subcontexts

Contexts can be of an arbitrary number and namespaces are recognised and treated appropriately; MediaWiki's translation of leading and trailing underscores is handled sensibly.

Rationale: Inspiration has been drawn from the way that interwiki links are specified in wikitext - Wikipedia:Help:Contents can specify an interwiki context, now C standard library:stdlib.h:NULL can specify an internal context. The forward slashes of the native subpage functionality were avoided partly because of the reputation/baggage of subpages in the MediaWiki/Wikipedia community.

Contextualised titles in the page heading

Each separate sub-context is linked in page headings i.e. C standard library and stdlib.h are separately clickable when the title is C standard library:stdlib.h:NULL. The set of contexts is based on the wiki title rather than any location(s) onto which it may have been grafted in the virtual hierarchy shown by the treeview.

Rationale: This is a pretty standard feature for navigating; it's one of the simplest ways to reach an article's ancestors and to visualise it in context.

Aliases are supported

When one title redirects to another title, the two are said to alias. The displayed title is not, as occurs natively, that of the redirected-to title, but of the redirected-from title.

Rationale: This slight modification transforms a redirect into something more like the UNIX concept of a soft-linked file. It allows for content to alias without the need to transclude[*] pages and it also allows for aliases to be "categorised" under separate node parents: this solves the problem that redirect pages cannot be included in a MediaWiki category.

[*] Transclusion is the mechanism of including the content of one page in another using the syntax {{Transcluded_Article}}. In earlier MediaWiki versions, if Transcluded_Article was not a template - i.e. if its title was prefixed with a colon - then the main article did not always update when the transcluded article was edited and saved.

A list of aliases in the header

The aliases list is auto-generated by the skin by querying for all redirects to the primary content page - even if that page was reached through a redirect. The alias holding the actual content is given a [primary] subtext. The main title heading either has a subtext [alias] that links to the article's title with &redirect=no as a query parameter, or a subtext [primary].

Rationale: Using the previous example, it is handy to see at a glance all of the other headers that NULL occurs in by looking at the aliases list

A "closely related" list in the header

The closely related list is also auto-generated based on the full list (duplicates removed) of articles in all categories that this article (primary alias because redirects can't be categorised) is a member of.

Rationale: Originally the skin did not support treeview-like navigation for categories and this was a handy alternate use for them. It still seems useful although if there's demand for an option to turn it off then one might be added.

Title underscore remappings

Remappings can be specified in the config page so that e.g. the page heading for "__STDC_VERSION__" can be unmangled from its default MediaWiki display: "STDC VERSION". This doesn't affect the title's appearance in skins other than Treeview and it also doesn't affect the title's appearance in the "tooltips" (i.e. the "title" html attribute) of auto-generated links in page content or in other MediaWiki-core-generated titles such as in page listings under Special:Allpages.

Rationale: This is a pretty important requirement for a programming-related wiki - along with correct capitalisation. It avoids the need for a template explaining technical limitations.

A <treeview> tag

The treeview structure as a nested series of unordered lists can be inserted onto any wiki page using the <treeview pruneids="id1,id2"></treeview> syntax, as described above under the heading "Use".

Rationale: This was a requested feature.

Help pages

Manually importable wiki-formatted help pages (you're reading one now) are distributed along with the skin.

Rationale: On-site documentation in wiki format is quicker to reach and easier to tailor than off-site documentation in an external format.

Administrative controls

Various tools are accessible on the Special:Hierarchy page to those who have been assigned the right; these aid with customising the treeview through its configuration page and ensuring that caching is functional, that there are no syntax errors in the configuration and that the treeview can be rebuilt and recached manually at any time.

Rationale: This is simpler than debugging through the command-line, which is not available to all wiki administrators.