Jump to content

Extension:SubpageNavigation

From mediawiki.org
Translate this page
Languages:
  • English
MediaWiki extensions manual
SubpageNavigation
Release status: stable
Implementation Hook , Special page
Description Shows direct children of current page in article header, provides dynamic subpage tree on the sidebar and a special page to browse all pages/subpages of the wiki in different modalities
Author(s) thomas-topway-it (thomas-topway-ittalk)
Latest version 1.2.1 (2023-03-10)
Compatibility policy Master maintains backward compatibility.
MediaWiki 1.35+
License GNU General Public License 2.0 or later
Download
Download extension
Git [?]:
Parameters
  • $wgSubpageNavigationShowTree
  • $wgSubpageNavigationArticleHeaderSubpagesLimit
  • $wgSubpageNavigationCacheStore
  • $wgSubpageNavigationTreeSubpagesLimit
  • $wgSubpageNavigationDefaultOptions
  • $wgSubpageNavigationDisableCache
  • $wgSubpageNavigationShowBreadcrumbs
  • $wgSubpageNavigationShowArticleHeader
  • $wgSubpageNavigationTreeShowChildrenCount
Hooks used
Quarterly downloads 18 (Ranked 111st)
Translate the SubpageNavigation extension if it is available at translatewiki.net

SubpageNavigation shows a collapsible list of subpages on the header of each article, including empty articles, with subpages. By contrast to similar extensions, SubpageNavigation does not require to add a parser function in the wikitext, and shows only direct children of a page. (A direct child, however, might include slashes if the parent page does not exist.) It also features a breadcrumb navigation placed above the title, and a special page where to browse all the pages of the wiki grouped by subpages, in a similar way to the GitHub file manager.

Since version 1.2 SubpageNavigation also provides a dynamic tree on the sidebar (compatible with Vector skin and Skin:Chameleon) inspired by Extension:CategoryTree .

After the installation the extension adds a link to the special page "Browse subpages" on the left panel, by which to browse all the pages and subpages of the wiki in 3 different modalities and by namespace, and makes available the components described below.


Installation

[edit]
  • Download and move the extracted SubpageNavigation folder to your extensions/ directory.
    Developers and code contributors should install the extension from Git instead, using:cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/SubpageNavigation
  • Add the following code at the bottom of your LocalSettings.php file: 
    wfLoadExtension( 'SubpageNavigation' );
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Components

[edit]

All the following components can be shown/hidden using the #Global parameters below.

Collapsible list of subpages in the article header

[edit]

The extension will show in any page of your wiki with subpages an header like the following, without the need to add a parser function.

The list of subpages is also shown for non-existing articles, this is useful for instance when subpages are created in a programmatic way: however if the intermediate pages are empty, the children won't be grouped in the Special Page "Browse subpages", so it is always preferable to have an empty article for each intermediate level (unless the title itself does not contain a slash, in this case it will be handled correctly by the extension).

When the list of subpages shown on a given article exceeds a given threshold, SubpagesNavigation will display a link to the special page Browse subpages where the user can navigate the entire list of subbpages with the standard MediaWiki navigation.

This feature can be disabled setting $wgSubpageNavigationShowArticleHeader = false; in LocalSettings.php after including the extension.

Dynamic tree

[edit]

Since version 1.2 SubpageNavigation provides a dynamic tree, inspired (and technically derived) by Extension:CategoryTree, that allows to navigate through all pages and subpages of the current namespace as you would do with a typical file system. If a branch exceeds a given limit (configurable through the global parameter $wgSubpageNavigationTreeSubpagesLimit) the complete list of subpages can be navigated through the special page described below.

The subpages are retrieved dynamically from the tree and the current branch/path is statically opened. The children count is also shown for pages having subpages.

The tree (together with the other ways to present subpages) supports LocalServerObjectCache (for servers supporting APCu or WinCache) and SessionCache (enabled by default) to enhance performances. See Object cache for more information.



To enable dynamic tree on Chameleon skin use the following settings in Manual:LocalSettings.php: 

wfLoadExtension( 'SubpageNavigation' );
$wgSubpageNavigationShowTree = true;

wfLoadExtension( 'Bootstrap' );
wfLoadSkin( 'chameleon' );
$wgDefaultSkin='chameleon';
$egChameleonLayoutFile = __DIR__ . '/extensions/SubpageNavigation/resources/ChameleonLayout.xml';




If you have already your own Chameleon layout, use the following component to render the tree, as follows:

<component type="SubpageNavigationTree" />

(for more information about Chameleon layouts and components see here)


[edit]

When the current page has a parent page, the extension (similarly to as Mediawiki already does enabling $wgNamespacesWithSubpages for the current namespace) will also show a breadcrumb navigation like the following:



Breadcrumbs are also shown for Special pages, so the user can easily return to the list of Special pages.



Compared to the standard Mediawiki breadcrumbs, the breadcrumb navigation of SubpageNavigation is distinguished by the following differences:

  • breadcrumbs are shown above the title instead than below (this offers a better header layout when combined with subpages header)
  • breadcrumb navigation is also shown for Special pages
  • the current page is also shown in the breadcrumb (as plain text, not as a link)
  • only the current page/termination page name is shown as article title instead than the entire path (for example "Main/Sub 1/Sub 2" only shows as "Sub 2"). (see here and here for a comparison)


This feature can be disabled setting $wgSubpageNavigationShowBreadcrumbs = false; in LocalSettings.php after including the extension.


Special page "Browse subpages"

[edit]

The Special page "Browse subpages" allows to navigate all pages with subpages of the wiki, within each specific namespace, in 3 different modalities (by grouping subpages, only pages with children, and filesystem-like).

By contrast to the other components described above (namely the list of subpages in the header and the dynamic tree) this Special page allows to navigate the entire list of subpages of a specific path (or "branch" of the tree) through the standard MediaWiki navigation, therefore as long as such components reach their specific limit, they redirect to this special page via the "show all..." link.



The navigation panel allows to switch between 3 different modes within any namespace: "default", "folders", and "filesystem". The first mode will display articles with subpages and articles without subpages together, but will group the articles with subpages (only showing their direct children at a given level). The second mode, "folders" will display only articles with children, and the mode "filesystem" will display first the articles with children and then the articles without children.

Each level can be simply linked from another wiki article pointing to the same special page and adding the desired path after the special page name, as follows: 

Special:SubpageNavigationBrowse/Main_Page/a


Global parameters

[edit]
variable description default
$wgSubpageNavigationShowTree show/hide dynamic tree in the sidebar false
$wgSubpageNavigationShowArticleHeader show/hide article header with list of subpages true
$wgSubpageNavigationShowBreadcrumbs show/hide breadcrumb navigation true
$wgSubpageNavigationTreeShowChildrenCount show/hide children count in the tree true
$wgSubpageNavigationTreeSubpagesLimit limit for each branch of the tree 30
$wgSubpageNavigationArticleHeaderSubpagesLimit max number of subpages shown in the article header 20
$SubpageNavigationCacheStore default cache, LocalServerObjectCache or SessionCache SessionCache
$wgSubpageNavigationDisableCache disable cache false

Example configuration: 

$wgSubpageNavigationShowTree = true;
$wgSubpageNavigationShowArticleHeader = false;
$wgSubpageNavigationShowBreadcrumbs = false;
$wgSubpageNavigationTreeShowChildrenCount = true;
$wgSubpageNavigationTreeSubpagesLimit = 50;
$wgSubpageNavigationArticleHeaderSubpagesLimit = 30;
$wgSubpageNavigationCacheStore = 'LocalServerObjectCache';
$wgSubpageNavigationDisableCache = false;


Known issues

[edit]

Currently breadcrumb navigation is disabled for the Vector-2022 skin.


Roadmap

[edit]
  • implement Ajax navigation of the tree similar to the tables navigation of phpMyAdmin
  • enable breadcrumb navigation also for Vector 2022, using the hook Manual:Hooks/AfterFinalPageOutput and DOMDocument to manipulate the output (breadcrumb navigation is currently inserted within the Page status indicators, however in Vector 2022 it is placed below the title, instead than above, and it seems there is no other way to display the indicators above the title using PHP)
  • use the new rdbms library's query builder for the core subpages query (instead than raw sql)
  • show/hide components based on user groups

To-do

[edit]
  • clear cache on page delete for the related page

Support & bugs

[edit]

Please post error messages in the Talk page of the extension.

For professional support please write at the email address posted here

See also

[edit]
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:SubpageNavigation&oldid=6847544"