Extension:SubPageList

shortcut: SPL

MediaWiki extensions manual - list

SubPageList Release status: stable
Implementation	Tag, Parser functions
Description	Adds a <subpages /> tag that enables you to list subpages
Author(s)	Jeroen De Dauw, based on SubPageList3
Last version	0.5 (2011-12-27)
MediaWiki	1.16.0 or above
Database changes	no
License	GPL v3 or above
Download	Stable releases - All releases
Tags <subpages />
Hooks used ParserFirstCallInit TitleMoveComplete ArticleInsertComplete ArticleDeleteComplete

The SubPageList extension is a lightweight extension to display subpages.

Feature overview

• Adds a splist or subpages parser hook that you can use to list subpages.
• Backward compatible with the SubPageList3 extension.
• Supports multiple parameters that enable you to customize the subpage list.
• Full integration with the Validator extension.

Download

You can download the extension directly from the MediaWiki source code repository (browse code). You can get:

• One of the extensions tags (click the tag number and then "snapshot"). Tags tend to be stable.
• A snapshot of the latest code. This might be unstable.
• A snapshot made during the release of a MediaWiki version. This might be unstable and is not guaranteed to work with the associated MediaWiki version.

After you've got the code, save it into the extensions/SubPageList directory of your wiki.

If you are familiar with git and have shell access to your server, you can obtain the extension, with all its tags and branches, as follows:

cd extensions
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/SubPageList.git

The last change to the extension was:

Localisation updates from http://translatewiki.net.

Localisation updates from http://translatewiki.net.

— Mon, 7 Jan 2013 20:59:53 +0000

SubPageList requires Validator 0.4.2 or above in order to work. A compatible copy of Validator always comes bundled with the regular releases, and is automatically loaded by SubPageList, so you do not need to worry about it when using one of these. If you are getting the code from SVN, make sure you also get a copy of Validator (see here for instructions).

Installation

Once you have downloaded the code, place the SubPageList and Validator directories within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file:

# SubPageList
require_once( "$IP/extensions/SubPageList/SubPageList.php" );

MediaWiki has a setting that specifies which namespaces can have subpages. For namespaces where this is not set, creating page/subpage will not result in subpage being a child page of page. See Manual:$wgNamespacesWithSubpages. Typically you want to also enable this for the main nemspace, as follows:

$wgNamespacesWithSubpages[NS_MAIN] = true;

Configuration

Configuration of SubPageList is done by adding simple PHP statements to your LocalSettings.php file. These statements need to be placed AFTER the inclusion of SubPageList. The options are listed below and their default is set in the SubPageList settings file. You should NOT modify the settings file, but can have a look at it to get an idea of how to use the settings, in case the below descriptions do not suffice.

Automatic refresh

As of version 0.3, you can choose to automatically refresh subpage lists that are on the base page of subpages you add, move or delete, or on one of the subpages of the base page. This behaviour is off by default as it can produce extra load on your server, but can be turned on with this code:

$egSPLAutorefresh = true;

General subpage settings

MediaWiki itself has some support for subpages, which causes back links to be displayed on subpages to their parent pages. To enable this you need to set wgNamespacesWithSubpages, which is a per namespace setting, like shown below:

$wgNamespacesWithSubpages[NS_MAIN] = 1;

Usage

You have the choice to either use a tag extension ( <subpages /> or <splist /> ) or use a parser function ( {{#subpages: }} or {{#splist: }} ). All these take the same parameters and behave identically.

Parameters

#	Parameter	Aliases	Type	Default	Description
1	page	parent	Text	empty	The page to show the subpages for. Defaults to the current page.
2	format	liststyle	Text	ul	The subpage list can be displayed in several formats: ol — ordered (numbered) list, ul — unordered (bulleted) list, list — comma-separated list.
3	pathstyle	showpath	Text	none	The style of the path for subpages in the list: none, no — show only subpage name, children, notparent — show part of the name starting from below the page, full — show full page name (but namespace is not included).
4	sortby	-	Text	title	What to sort the subpages by: title or lastedit.
5	sort	order	Text	asc	The direction to sort in: asc or desc.
-	showpage	showparent	yes/no	no	yes — show the page itself, no — do not show the page itself.
-	kidsonly	-	yes/no	no	yes — show only direct subpages, no — show all subpages.
-	limit	-	Whole number	200	The max amount of pages to list.

Syntax

Tag extension with only the required parameters.

<subpages />

Tag extension with all parameters.

<subpages page="{Text}" format="{Text}" pathstyle="{Text}" sortby="{Text}" sort="{Text}" showpage="{Yes/no}" kidsonly="{Yes/no}" limit="{Whole number}" />

Tag extension with all parameters using the default parameter notation.

<subpages format="{Text}" pathstyle="{Text}" sortby="{Text}" sort="{Text}" showpage="{Yes/no}" kidsonly="{Yes/no}" limit="{Whole number}">{page, Text}</subpages>

Parser function with only the required parameters.

{{#subpages:}}

Parser function with all parameters.

{{#subpages:
page={Text}
| format={Text}
| pathstyle={Text}
| sortby={Text}
| sort={Text}
| showpage={Yes/no}
| kidsonly={Yes/no}
| limit={Whole number}
}}

Parser function with all parameters using the default parameter notation.

{{#subpages:
{page, Text}
| {format, Text}
| {pathstyle, Text}
| {sortby, Text}
| {sort, Text}
| showpage=Yes/no
| kidsonly=Yes/no
| limit=Whole number
}}

Examples

Listing the subpages of the current page with default options:

<subpages />

Listing the subpages of page "Foobar" with the "ol" format:

<subpages page="foobar" format="ol" />

Using several options and making use of the default parameter system of the parser function (again for page "Foobar"):

{{#subpages:Foobar|list|children|limit=20|sortby=lastedit|order=desc}}

Version

This is a copy of the release notes file on SVN, which might be more up to date than this page.

Version 0.5

2011-12-27

• Added compatibility with MediaWiki 1.18 (bug 33393) and 1.19.
• Dropped compatibility with MediaWiki 1.15.
• Added #subpagecount parser hook.
• Fixed invalid HTML for ul and ol formats (bug 32131).

Version 0.4

2011-07-27

• Added parameters for better output control: element, class, intro, outro, default, separator, template, links.
• Added ability to list pages in a namespace.
• Fixed compatibility with MediaWiki 1.18.

Version 0.3

2011-03-05

• Added $egSPLAutorefresh option.
• Fix to display of the first list item.
• Fixed inverted behaviour of the kidsonly parameter.
• Fixed query issue when using PostGres.

Version 0.2

2011-01-24

• Fixed escaping issue when using the parser function.
• Fixed bug in pathstyle and sortby parameters.
• Added parameter descriptions.

Version 0.1

2010-12-31

• Copied the code of SubPageList3 and ...
  • Modified code to make use of Validator for parameter handling.
  • Rewrote most code of the SubPageList class.
  • Fixed namespace bug.
  • Fixed several minor layout issues.
  • Added 18n magic file.
  • Added COPYING, INSTALL, README and RELEASE-NOTES.
  • Cleaned up and corrected formatting.

Internationalization

SubPageList is fully internationalized. Translation of SubPageList messages is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

Authors

SubPageList has been written by Jeroen De Dauw, and is a rewritten version of SubPageList3, which was written by James McCormack, Martin Schallnahs and Rob Church.

See also

• Subpages help page
• Subpage Fun: extension providing subpage related functions and magic words to gather information about sub- and parentpages
• SubPageList3: the extension this one is based upon
• SubPageList2: the extension SubPageList3 is based upon

External links

• Blog of the author about SubPageList