Slightly off-topic: the <treeview> tag
To insert the hierarchy (or part of it) into the current page, see Help:Treeview_skin#The_.3Ctreeview.3E_tag.
Introduction and version
Quick-start section: the tutorial-style example.
This reference page documents the syntax of the Treeview skin's configuration page, which by default is MediaWiki:Treeview (although the site administrator can change that page's location through the $wgHierarchyPage setting).
It corresponds to version 1.5.beta of the combined Hierarchy extension/Treeview skin package. If the version listed beside Hierarchy at Special:Version is different then parts of this reference might be outdated.
Significant lines and comments
Lines preceding the text "== Hierarchy ==" (without quotes and alone on the line) are not parsed. Thereafter, lines that do not start with a hash or asterisk, including lines with leading whitespace, are treated as comments and ignored, except for "== Remap ==" (also without quotes and alone on the line), which indicates that parsing of remap instructions should commence.
The Hierarchy section
Each line in the initial Hierarchy section is a directive that adds, removes or groups node(s) in a virtual directive tree that gets translated into the "actual" treeview on each page view.
Each directive is preceded by one or more asterisks and/or hashes to indicate depth in the hierarchy.
Directive syntax
Each directive takes the form (omitting the preceding hash/asterisk depth indicator):
specifier directive(conditions)
parameters
"(conditions)" and "parameters" are optional. Currently "directive" can be omitted in which case it defaults to "NODE"; this behaviour might change so safest is to write "NODE" explicitly.
Specifiers
A specifier is one of:
url-link |
[http://srvr.tld/dir/page.html Node text] |
---|---|
This uses the same basic syntax as in ordinary wiki content except that "Node text" is mandatory. | |
title-link | [[Internal:Article:Title|Node text]]
|
This uses the same basic syntax as in ordinary wiki content (|Node text is optional) except that interwiki links are treated as though they were internal links. An empty title - i.e. [[]] - for an IMPORT indicates "use the main namespace", in which case other namespaces will be ignored. | |
subcontext | [[[Subcontext]]] |
This represents the final context in a colon-separated title. Currently changing the display name through a "|" isn't supported but may be in future. | |
range | [[[First]]],[[[Last]]] |
This represents the first and last items in a range. An empty item - i.e. [[[]]] - for the first or last indicates "earliest possible" or "latest possible" respectively. If "First" does not precede "Last" (where order is determined by "natural sort" - see "Ordering and merging" below) then the range is empty. |
Limitation: currently square braces within text aren't supported - they are likely to generate a parser error resulting in the line being ignored.
A specifier can be represented by a message key that when substituted results in one of the above forms.
Directives
NODE
Creates or affirms a new node at the depth specified by the number of prefixing asterisks/hashes. Child nodes may then be specified by subsequent node directives that have one more asterisk than the parent node. Nodes that skip a depth - including the first depth - are ignored along with their children.
In its "subcontext" form, this directive acts to:
- prevent a subcontext from being pruned due to a prior
pruneleafs
option or a higher-level PRUNE directive - establish the node's ordering
- allow parameters to be specified for an imported node
- specify that a non-existent article should have a placeholder link displayed.
Meaningful positionings: | anywhere if specified using an url-link or title-link, otherwise within the scope of an IMPORT directive (including when the IMPORT occurs implicitly for a GRAFT). |
Meaningful specifiers: | url-link, title-link, subcontext. |
Conditionable: | yes, except when specified using a subcontext. |
CATEGORY
Splices into the treeview at the depth specified by the number of preceding asterisks/hashes the category tree starting with the specified category. The preceding "Category:" of the category's title is optional. Articles within a category are not shown, only sub-categories. Each sub-category is shown once only (its first appearance) to avoid loops. PRUNE directives under a CATEGORY directive are not supported.
IMPORT
Splices the subcontexts of the specified title (as split on colons) into the hierarchy at the depth specified by the number of asterisks/hashes that precede the directive, creating a sub-hierarchy where a subcontext itself has children. The specified title need not be top-level (i.e. it may contain colons). If children-of-children article(s) occur without an intervening subcontext(s), then the intervening subcontexts are implied, and placeholder node(s) for them will be displayed using an edit link. Imported nodes are sorted and merged with any explicit nodes as described in "Ordering and merging" below.
Scope: this directive ends when
- a new IMPORT at the same depth begins, or
- the depth decreases to less than that of the original IMPORT, or
- an ENDIMPORT occurs at the same depth as the original IMPORT, or
- the configuration ends.
Within this scope, NODE directives that are specified using a title-link or url-link (as opposed to a subcontext-link) temporarily escape the IMPORT, meaning that their children can contain separate IMPORTs and the parent IMPORT will resume when the NODE and its IMPORT child(ren) end.
IMPORT blocks are indivisible - adjacent blocks can't be merged and sorted together.
Meaningful positionings: | top-level or immediately below a NODE specified using a title-link or url-link. |
Meaningful specifiers: | title-link (the "Node text" component of the title-link, if any is not meaningful). |
Conditionable: | no. |
ENDIMPORT
Explicitly ends the current - if any - IMPORT directive.
GRAFT
This is a shortcut for a NODE followed by an IMPORT at the next depth. The difference is in the treatment of parameters as documented below.
Scope: the implicit NODE encloses an implicit IMPORT where the scoping description above applies.
Meaningful positionings: | anywhere. |
Meaningful specifiers: | title-link. |
Conditionable: | yes. |
PRUNE
Omits from the parent IMPORT/GRAFT the specified subcontext and its sub-tree. Can be recursively combined with child NODE directives to "unprune" parts of the sub-tree.
Meaningful positionings: | within the scope of an IMPORT directive (including when the IMPORT occurs implicitly for a GRAFT). |
Meaningful specifiers: | subcontext. |
Conditionable: | no. |
BLOCK
Defines a group of nodes for ordering.
It takes one (optional) parameter only: exclude
.
If either of the "first" or "last" of the range is specified as [[[]]], then "exclude"ing the relevant boundary has no effect. [arguably it would be reasonable to apply the boundary to the first or last article, respectively, but for now that seems unnecessary; these semantics might change so safest is to avoid applying "exclude" to these cases]
See also "Ordering and merging" below and the
merge
parameter.
Meaningful positionings: | within the scope of an IMPORT directive (including when the IMPORT occurs implicitly for a GRAFT). |
Meaningful specifiers: | range. |
Conditionable: | no. |
Conditions
Conditions are only supported for directives in the list above for which "Conditionable" is "yes".
The conditions are a whitespace-separated, order-insignificant list of one or more of the conditions described below. All of the conditions in the list must test true for the full condition to be satisfied (logical and).
If the conditions are not satisfied, then the effect is as though the entire directive does not exist. Parameters aren't conditionable.
Choosing between nodes (if-else chains)
When the final character of a NODE directive's asterisk/hash depth prefix is a hash, it indicates that the node is part of a group that share the same set of sub-nodes (which might be empty), only one of which in the group - the first whose conditions are satisfied - should be chosen as parent.
Scope: the group is ended when the depth changes (in either direction) or when the hash becomes an asterisk - an empty "asterisk" directive can be used to separate groups.
Restriction: if-else chains aren't supported for "subcontext" NODEs.
Note: a single node with conditions need not use a hash character - an asterisk has the same effect.
Supported conditions
Mnemonics: predir => "pre-redirect"
Naming conventions: if(not)maintest(_predir). "maintest" is verb-followed-
by-noun except where this is too clumsy. The three page types recognised are:
special (specialpage), article (articlepage) and talk (talkpage), with
unqualified 'page' referring to the currently viewed page.
always
,never
- A pseudo-test that succeeds always or never, respectively.
ifarticlepageexists
,ifnotarticlepageexists
- Tests whether the article page associated with the page being viewed exists. From this test's perspective special pages never have associated article pages.
ifarticlepageexists_predir
,ifnotarticlepageexists_predir
- Tests whether the article page associated with the redirect that was
followed to get to the current page exists. From this test's perspective
special pages never have associated article pages. If no redirect was followed
then this test is identical to
ifarticlepageexists
/ifnotarticlepageexists
. ifhasright(<right>)
,ifnothasright(<right>)
- Tests whether the account under which the page is accessed has the right
specified by the string
<right>
(as used in$wgGroupPermissions
, described in MediaWiki's DefaultSettings.php). Variable replacements are performed on the<right>
string; it may optionally be quoted with double-quote marks ("
) which can be escaped by doubling them i.e."a""right""string"
is interpreted asa"right"string
. ifisarticlepage
,ifnotisarticlepage
(orifisnotarticlepage
)- Tests whether an article page - vs a talk or a special page - is currently being viewed.
ifisarticlepage_predir
,ifnotisarticlepage_predir
- Tests whether the redirect that was followed to get to the current page is an article page - vs a talk or a special page. If no redirect was followed then this test is identical to ifisarticlepage / ifnotisarticlepage.
ifisemailableuserpage
,ifnotisemailableuserpage
(orifisnotemailableuserpage
)- Tests whether the page being viewed is associated with a user who may be emailed by the currently logged in user (currently identical to the foreignuser test but this may change to test whether email is enabled).
ifisforeignuserpage
,ifnotisforeignuserpage
(orifisnotforeignuserpage
)- Tests whether the page being viewed is associated with a user other than the logged in user - this applies to user pages, user talk pages and sub-pages of both, using slashes or colons to denote the sub-page.
ifisspecialpage
,ifnotisspecialpage
(orifisnotspecialpage
)- Tests whether a special page - vs a talk/article page - is currently being viewed.
ifistalkpage
,ifnotistalkpage
(orifisnottalkpage
)- Tests whether a talk page - vs an article or a special page - is currently being viewed.
ifistalkpage_predir
,ifnotistalkpage_predir
- Tests whether the redirect that was followed to get to the current page is
a talk page - vs an article or a special page. If no redirect was followed
then this test is identical to
ifistalkpage
/ifnotistalkpage
. ifloggedin
,ifnotloggedin
- Tests whether the viewing agent is logged in.
ifnodeidmatches
,ifnotnodeidmatches
- Tests whether one of current url's query parameters is 'nodeid' and whether that query parameter's value is equal to the node's (auto-generated or specified) nodeid.
ifpageexists
,ifnotpageexists
- Tests whether the page being viewed exists - i.e. for an article/talk page that it has article; special pages always exist for this test.
ifredirected
,ifnotredirected
- Tests whether a redirect was followed to get to the page being viewed - i.e. whether [aliased] is appended to the main heading. If redirect=no is one of the url's query parameters then a redirect has not been followed.
iftalkpageexists
,ifnottalkpageexists
- Tests whether the talk page associated with the page being viewed exists. From this test's perspective special pages never have associated talk pages.
iftalkpageexists_predir
,ifnottalkpageexists_predir
- Tests whether the talk page associated with the redirect that was followed
to get to the current page exists. If no redirect was followed then this test
is identical to
iftalkpageexists
/ifnottalkpageexists
. iftitlematches
,ifnottitlematches
- Tests whether the wiki title of the page being viewed matches the wiki title of the current node after variables have been replaced. The wiki title of an external url is considered to be empty for this test's purposes.
ifurlquerycontains?queryparams
,ifnoturlquerycontains?queryparams
- Tests whether the url query parameters of the page being viewed contain
those specified by
queryparams
; query parameter order is insignificant for these tests; parameters and values are compared after being url-decoded. Variable replacements are performed onqueryparams
prior to splitting and decoding it, so to avoid a replacement, encode one or both of the '{' characters as '%7B', and/or one or both of the '}' characters as '%7D'. ifurlextramatches
,ifnoturlextramatches
;ifurlcontainsextra
,ifnoturlcontainsextra
- Tests whether the url query parameters of the page being viewed match those
of the urlextra parameter of the current node after variables in
urlextra
have been replaced; query parameter order is insignificant for these tests; parameters and values are compared after being url-decoded. The difference betweenifurlextramatches
andifurlcontainsextra
is that 'contains' tests that at least all of theurlextra
parameters are present in the url; 'matches' tests that all of and no more than theurlextra
parameters are present in the url. Url query parameters that are used by the Treeview/Hierarchy code itself are excluded from comparison in both tests; those parameters are:samepage
,tvstate
,skiplinkstaterebuild
andaction=view_tv
- the last one is not excluded and is instead implicitly normalised toaction=view
). Also excluded istitle
, because it can occur implicitly and inconsistently when MediaWiki's$wgUsePathInfo
is true and because a separate test exists for it:iftitlematches
, described above. Other notes:
1. The 'action' query parameter might be implied based on a match with$wgActionPaths
(a MediaWiki-core setting).
2. An emptyurlextra
parameter is 'contain'ed by any set of url query parameters (including none); an emptyurlextra
parameter 'match'es an empty set of url query parameters. ifviewingoldarticlepage
,ifnotviewingoldarticlepage
- Tests whether the page being viewed is a revision of an article page other than the latest revision of that page.
ifviewingoldtalkpage
,ifnotviewingoldtalkpage
- Tests whether the page being viewed is a revision of a talk page other than the latest revision of that talk page.
Parameters
The order in which parameters occur is not meaningful. All parameters are
optional. They are nominally whitespace-separated although the parser currently
tolerates concatenation. "(propagated)" in the "Applies to" column means that
the parameter is applied to each node that is imported due to the IMPORT
statement: a PRUNE or subcontext-NODE though may override the icons
and merge
parameters.
Form and effect | Applies to | ||||
---|---|---|---|---|---|
NODE | PRUNE | GRAFT | IMPORT | BLOCK | |
appendnodeid
|
X | X | X (implied NODE only) | X (propagated) | |
icons=[[Image:<leafimg>]],[[Image:<expandimg>]],[[Image:<collapseimg]]
|
X | X | X (implied NODE only) | X (propagated) | |
exclude=first|last|both
|
X | ||||
expanded
|
X | X | X (implied NODE only) | X (propagated) | |
knownlink
|
X | X | X (implied NODE only) | X (propagated) | |
merge=sort|prepend|append
|
X (when specified using a subcontext) | X | X (propagated) | X (propagated) | |
nodeid=id_string
|
X | X | X (implied NODE only) | ||
selected(<conditions>)
|
X | X | X (implied NODE only) | X (propagated) | |
nomatch
|
X | X | X (implied NODE only) | X (propagated) | |
pruneleafs
|
X (when specified using subcontext) | X | X (applies at top-level only; not propagated) | X (applies at top-level only; not propagated). | |
tooltip=<tooltip>
|
X | X | X (implied NODE only) | ||
urlextra?<querystring>
|
X (when specified using an url-link or title-link) | X (implied NODE only) |
Ordering and merging
The top-level branch and all branches directly below a NODE specified using an url-link or title-link are not sorted - they appear in the same order as on the config page.
All other nodes are within the scope of an IMPORT: imported nodes are automatically sorted.
All sorting occurs in "natural sort" order; sort keys are either the underscore-remapped subcontext, or, for a NODE specified using an url-link or title-link, its display name. The ordering of an import branch's nodes occurs as follows:
If merge=sort is the effective parameter, then explicit and imported nodes are merged and then sorted as an entirety - as described above in that parameter's description - and BLOCKs are ignored.
Otherwise, the following steps take place:
- a sorted merge list of wiki subcontexts is generated
- all explicit nodes (NODEs, and PRUNEs that have child NODEs) are added to the branch and matching entries for subcontext NODEs and PRUNEs are removed from the merge list
- for each BLOCK, the matching sorted region is removed from the merge list and inserted into the branch in place of the BLOCK directive. The BLOCKs are processed in the order in which they appear on the config page.
- Remaining merge list nodes are prepended or appended to the branch per the merge setting.
Replacement variables
The following tokens are replaced with the indicated text when they occur within:
- the display name of a NODE (excluding subcontext NODEs)
- the title or url of a NODE (excluding subcontext NODEs)
- the urlextra and tooltip parameters.
- {{FULLPAGENAME}}
- The title of the currently viewed page after the redirection, if any, has been resolved.
- {{ARTICLEPAGENAME}}
- The title of the article associated with the currently viewed page after the redirection for the current page, if any, has been resolved - for all other than talk pages this is identical to {{FULLPAGENAME}}.
- {{TALKPAGENAME}}
- The title of the discussion page associated with the currently viewed page after the redirection for the current page, if any, has been resolved - empty for Special pages.
- {{FULLPAGENAME_PREDIR}}
- The title of the currently viewed page prior to the redirection, if any, being resolved. i.e. this is the title seen in the url (tidied up to use spaces and after unescaping code characters), whereas {{FULLPAGENAME}} is the title variant that's appended with [primary].
- {{ARTICLEPAGENAME_PREDIR}}
- The title of the article associated with the currently viewed page prior to the redirection for the current page, if any, being resolved.
- {{TALKPAGENAME_PREDIR}}
- The title of the discussion page associated with the currently viewed page prior to the redirection for the current page, if any, being resolved.
- {{REVISIONID}}
- An integer indicating which prior version of a page is being viewed - empty or zero if an old version is not being viewed.
- {{USERNAME}}
- The username of the currently logged-in user, or the IP address of the browser's machine if not logged-in.
- {{USERPAGEUSERNAME}}
- The username or IP addresss associated with any user page being currently viewed.
General notes
Title variables aren't "Remap"ped but do use spaces as underscore substitutes.
The variable naming scheme re-uses those of MediaWiki variables: the implementations are separate though and not all MediaWiki variables are supported.
Miscellaneous syntax notes
- Line breaks are significant
- arbitrary whitespace is accepted before and after these symbols:
- parentheses as part of an "ifhasright" clause
- "=" and "?" when used to separate parameter from value
- "," when used to separate icon links or BLOCK subcontexts
Example and tutorial introduction
The following example explains how to import nodes into a treeview based on article title so that they appear in the desired order.
Configuration directives:
* [[Project:Things]] GRAFT merge=append tooltip="Happenings at this wiki" ** [[[Private_article]]] PRUNE ** [[[A redirect that shouldn't be visible]]] PRUNE ** [[[]]],[[[Development]]] BLOCK ** [[Development]] GRAFT pruneleafs ** [[[Development]]],[[[Involvement]]] BLOCK ** [[Help:Involvement|Involvement]] NODE *** [[Help:Involvement]] IMPORT
Explanation:
The first line creates a top-level treeview node linking to the article
"Project:Things" and displaying that text as its title. The text
"Happenings at this wiki" will be displayed when the mouse hovers over the
node (or something similar for non-graphical browsers). That node is generated
by an implicit NODE directive that takes the place of the
GRAFT directive; the GRAFT also generates an implicit subsequent
IMPORT directive at the next depth:
** [[Project:Things]] IMPORT merge=append
The merge parameter applies only to IMPORTs, so it doesn't affect the implicit NODE, whereas the tooltip parameter affects only the implicit NODE - more on the merge parameter's effect at the end. At this point the conceptual translated treeview looks like this (deferring for now the imported nodes, which are affected by later directives):
o Project:Things
The next two lines:
** [[[Private_article]]] PRUNE ** [[[A redirect that shouldn't be visible]]] PRUNE
specify that the articles "Project:Things:Private_article" and "Project:Things:A redirect that shouldn't be visible" should be excluded from the import (note the triple brackets - double brackets would be a syntax error).
The next line:
** [[[]]],[[[Development]]] BLOCK
causes the insertion of nodes for the articles whose sorted titles start with "Project:Things:" but that are earlier than or equal to "Project:Things:Development" - [[[]]] matches from the start. i.e. This will match "Project:Things:Animation", "Project:Things:Clusters", "Project:Things:Developers:Fred" and "Project:Things:Developers:Ted", which will appear so that the treeview now looks like this:
- Project:Things o Animation o Clusters - Developers o Fred o Ted
Then the next directive:
** [[Development]] GRAFT pruneleafs
causes a node titled "Development" to be added after "Developers" and for any articles within the wiki title context "Development" (which might or might not also be defined as a wiki namespace) to likewise be imported below it - so if the only article is "Development:Code:Module1" then the treeview will now look like this:
- Project:Things o Animation o Clusters - Developers o Fred o Ted - Development - Code o Module1
The "Code" node will appear as a red edit-link because the "Development:Code" article does not exist. To avoid the red-link, the following directive could be inserted after the GRAFT:
*** [[[Code]]] NODE knownlink
The next directive, another BLOCK, causes the insertion of nodes for the imported articles whose sorted subcontexts fall between "Development" and "Involvement", so if these were "Project:Things:Happenings" and "Project:Things:Events:Trips", then the conceptual translated treeview would at that point look like this:
- Project:Things o Animation o Clusters - Developers o Fred o Ted - Development - Code o Module1 - Events o Trips o Happenings
The final two directives are:
** [[Help:Involvement|Involvement]] NODE *** [[Help:Involvement]] IMPORT
As implied earlier, these could also have been written as a single directive:
** [[Help:Involvement|Involvement]] GRAFT
This GRAFT form is preferred - IMPORT is best used only when parameters need to be propagated to all child nodes.
If the only article whose title started with "Help:Involvement:" was "Help:Involvement:Contact" then the conceptual treeview would look like this:
- Project:Things o Animation o Clusters - Developers o Fred o Ted - Development - Code o Module1 - Events o Trips o Happenings - Involvement o Contact
The "Help" part of the title is not displayed due to the retitling of "Help:Involvement" as "Involvement" through the use of the pipe (vertical line) symbol in the NODE directive's link specifier.
Finally, a return to the initial merge=append
parameter. All
explicit nodes and blocks have been added, now all remaining unimported articles
whose titles start with "Project:Things:" are append
ed. So if
those thus-far unmentioned articles were "Project:Things:Links" and
"Project:Things:Zen:Gardens" then the final treeview would appear as:
- Project:Things o Animation o Clusters - Developers o Fred o Ted - Development - Code o Module1 - Events o Trips o Happenings - Involvement o Contact o Links - Zen o Gardens
Not discussed: This tutorial skips over many available parameters and their
values, such as automatic full sorting based on displayed title (merge=sort) and automatically expanding nodes (expanded).
Hints:
Remember that subcontext-specifiers use three brackets and not two
(this applies to PRUNEs and BLOCKs, as well as NODEs below an IMPORT that aren't
intended to escape it). Any syntax errors are output in MediaWiki's debug
stream - you can view them if you have access to the server by setting
$wgDebugLogFile = 'somefile'
within LocalSettings.php and then
running tail -f somefile
(or equivalent if the operating system
doesn't have a tail
command). They are prepended by a
line "Configuration parse error(s) and/or warning(s):".
The Remap section
Each line in the Remap section has the effect of changing the display of the final component of the title when it is used as an article heading, or in the 'alias' or 'closely related' list, or as a node in the treeview. This can be used to reverse MediaWiki's auto-conversion of underscores. Retitlings that don't convert to the same MediaWiki representation as the original (based on full title conversion, not just the final component) aren't accepted.
Each line should start with a single asterisk and is comprised of two components separated by a pipe (|). The first component is the full title in any form acceptable to MediaWiki when specifying a wikilink; the second component is the remapped subcontext (the last part of the colon-separated list) of the title.
The full titles are from the wiki's point of view, not that of the virtual hierarchy defined above.
These examples are as used on clc-wiki:
*STDC|__STDC__ *STDC_VERSION|__STDC_VERSION__ *C language:Components: STDC VERSION|__STDC_VERSION__ *Planning:Voting extension:vote tables.sql|vote_tables.sql