Extension:SubPageList3

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
SubPageList3

Release status: stable

Splist 1.png
Implementation Tag
Description provides a splist tag to list the subpages of a page; based on Extension:SubPageList2
Author(s) McCormack
Latest version 1.05 (29.03.08)
MediaWiki 1.11.1, 1.12alpha
License GPL
Download
Example here
Parameters

none

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

Check usage and version matrix; code metrics

SubPageList3 is a tag extension based on Extension:SubPageList2 for listing subpages of a parent page with critical fixes necessary to meet criteria requirements for use on Wikimedia projects. This is especially helpful on wikis which make extensive use of subpages to organize clusters of related pages (e.g. Wikibooks, Wikiversity).

Votes for activation on Wikimedia projects[edit | edit source]

The English and Greek Wikiversities have voted unanimously in favour of activation of this extension. See discussion and voting.

Installation[edit | edit source]

  • Download both PHP files from the Subversion repository: SubPageList3.php and SubPageList3.i18n.php.
  • Upload both PHP files to the extension directory.
  • Add the following line at the end of your LocalSettings.php:
require_once("$IP/extensions/SubPageList3/SubPageList3.php"); // for SubPageList3 extension

Usage[edit | edit source]

The extension disables caching on any page using the <splist/> tag. (more)

The <splist> tag[edit | edit source]

Simply place <splist /> where you wish your subpage list to appear.

Attributes of the splist tag[edit | edit source]

Example with use of all available attributes.

<splist
 parent=
 showparent=yes
 sort=desc
 sortby=title
 liststyle=ordered
 showpath=no
 kidsonly=no
 debug=0
/>
  • Liststyle: default is unordered; values are ordered|unordered|bar. Toggles list between <ol> and <ul> lists. The bar value causes the list to align horizontally with · symbols acting as delimiters (for bar lists rather than tree lists).
  • Sort: default is asc; values are asc|desc. Toggles list between ascending and descending sort order. By default, the tag sorts subpages in ascending alphabetical order; all sorting, however, is subject to hierarchical position - i.e. pages will always be subordinated to their parents; sorting is only among siblings.
  • Sortby: default is title; values are title|lastedit. Toggles list sort determinant between title and date of the last edit.
  • Showpath: default is no; values are no|notparent|full. Determines how the title of each page is displayed in the list. "No" means that only the subpage title (i.e. the bit after the last slash) is displayed. "Notparent" shows the full path without the top level. "Full" shows all levels in the page title name including the top level (e.g. "my page/my subpage/my subpage2").
  • Kidsonly: default is no; values are yes|no. If this is set to "yes", then only the first generation of subpages (i.e. the children but not the grandchildren) is displayed. This is especially useful if the liststyle is set to bar. It's also good if you just want a list rather than a tree.
  • Parent: by default the tag analyses the subpage system of its own page. However you can set the tag to analyse and display the subpage system of any other page on the wiki. Use local name format. E.g. "parent=Template:FOO" (with a namespace) or "parent=My Page" (in the main namespace). A common source of error is typing the page name incorrectly. The extension checks whether or not the page you name actually exists, and will report an error if it doesn't.
  • Showparent: default is no; values are yes|no. If this is set to "yes", then the page indicated by parent (above) will be inserted as the top level item in the list. If the list is a bulletted list, then this top level item will have a bullet and the rest of the list will be indented one level further than it would be otherwise.
  • Debug: you can switch debugging on by setting this option to 1; the debugging goes no further than reporting invalid input for the other options.

CSS formatting[edit | edit source]

The parser puts a <div> around the list with the class "subpagelist".

History[edit | edit source]

Acknowledgements[edit | edit source]

Thanks are due to the following, all of whom helped to degrees large and small. The bugs are all mine, though! Apologies to anyone I have forgotten - so many have helped that it is difficult to remember everyone. --McCormack

  • SubPageList1 was a very simple script written by User:Robchurch which did the same as what you can now do with {{Special:Prefixindex/{{FULLPAGENAME}}/}} (see the talk page discussion of the latter).
    • A note in the code of SubPageList2 says that the orginal version of the SubpageList extension... can produce a fatal error while using the <subpages> element. No further information was given about this. However it might be that the following is meant: that the original SubPageList and SubPageList2 cannot be used together (probably because the tag and hook names weren't changed).
    • Another note on the SVN code says (correctly) that SubPageList1 was "Obsoleted by including Special:Prefixindex".
  • SubPageList2 was a feature-rich enhancement of the above written by Martin Schallnahs, described as an extension that automatically creates a list of the subpages of a page. The dynamic created list will be created automatically on every edit of the page where the SubPageList element is given.
  • A simplified variant was written by User:Karora in January 2008. See below for code.
  • For coding help / bug reports / SVN uploads: Duesentrieb, FlyingParchment, Sayuri, PeterBlaise, JeLuF, Fungiblename, Werdna, Tim Starling, Splarka, Siebrand and PaulHat.
  • For encouragement: everyone at Wikiversity who wanted this extension.

Version Summary[edit | edit source]

  • Uses the <splist> tag to enter a list/menu of a subpage system.
  • The subpage system is that of the current page (by default), or of any specified page elsewhere on the wiki.
  • The subpage system can be displayed as an ordered or unordered indented list, or as a horizontal bar.
  • The subpage list is updated each time the page in which the tag is embedded is updated (by editing it or by calling it with the parameter ?action=purge) dynamically (i.e. every time the subpages change).

The most important changes are:

  • Bugfixes.
  • Removal of the preview mode and removal of associated caching of actual content of subpages, which considerably shortened and simplified the extension.
  • Generally bringing the other features into line with what would have been expected of a simple subpage list extension.
  • Code size cut from 21kb to 14kb.

Version 1.05[edit | edit source]

This revision follows Brion Vibber's code review.

Brion changed (revision 32559):

  • Remove PHP4-ism in call params
  • Work correctly if asked to list subpages of page titled "-1"

Comments from Brion:

Some fundamental issues which need to be fixed before any Wikimedia deployment:

Sorting:

The code causes an inefficient filesort operation by sorting on
UPPER(page_title) instead of page_title. Depending on how smart the database
is, that may be a non-issue (small result data sets) or it may be wildly
inefficient, but it's a red flag.

More generally, note that the case-insensitive intention of this sort will fail
on non-ASCII characters in MySQL 4 and default compat configurations, as the
transformation applied at the DB won't be correct.

Recommend sorting simply on page_title, as elsewhere in the system (eg
Special:Prefixindex).

Caching:

Currently the extension outright disables caching on any page using the
<splist/> tag. While this ensures that up-to-date page lists are displayed, it
could make a site widely using it very expensive indeed -- the entire page,
however large, needs to be reparsed on every view -- even under a load spike
like a Slashdotting, where the same page is hit over and over.

To correctly handle cache updates, uses on a page should be registered at
links-update time, and creation/deletion of a subpage can trigger update jobs
for registered pages.

Changes made:

  • Now sorts on page_title instead of UPPER(page_title).
  • Removed the page decaching again.

Discussion notes:

  • Duesentrieb and Dantman have suggested the addition of a render dependency table, which tracks pages which may need cache disabling (purging) when other pages change.

Version 1.04[edit | edit source]

PaulHat kindly submitted some code which addressed the "background issue" mentioned above.

Version 1.03[edit | edit source]

PaulHat found a bug. When the <splist> was required to list the subpages of a page which had both a parent and children, and the "kidsonly" parameter was set to "yes", then the implode() function in line 478 produced an error. The background to this is that the "kidsonly" parameter assumes that the splist tag will normally be applied to a top-level item only. In version 1.03, this bug has been fixed, but the background issue will remain on the wishlist for a bigger upgrade.

Version 1.02[edit | edit source]

Outcomes of discussion on IRC on 26th Feb '08:

  • Added cache disabled call in constructor (Tim/Werdna).
  • Discussion of namespace subpage disabling and the $wgNamespacesWithSubpages variable. The issue is that on some wikis the slash is used as part of page names rather than as the marker for an "official" subpage. The user won't see the difference, but the wiki does. Currently the extension sees page titles as the user does, not as the wiki does. Is this a good thing or a bad thing? Should a flag be available to switch the extension between two different modes in this respect? For example, while Wikiversity and Wikibooks can have real subpages in the main namespace, Wikipedia doesn't so that slashes can be used as part of article titles (but the User: namespace on WP nevertheless allowed real subpages). (Splarka) (See discussion on talk page)
  • 'Added Internationalization. (Werdna)
  • Documentation should probably draw attention to and distinguish from transclusion of stuff using code like this: {{Special:Prefixindex/{{FULLPAGENAME}}/}}; what does the extension do to add value to this? (a lot, but explain). (Splarka) See discussion on talk page)
  • Changed: Werdna changed the way the namespace was detected (SVN version differs from code posted on MediaWiki.org).

Version 1.01[edit | edit source]

  • User:Sayuri went through the code with some minor tweaks, which have been adopted: corrected URL to extension; turned authors list into an array; removed closing ?> (PHP close tag); corrected copyright symbol.

Version 1.0[edit | edit source]

Feedback from other developers[edit | edit source]

The following feedback was given about Extension:SubPageList2:

I've done a quick review of this extension:
- Unused variables in several places, including variables that get 
 filled with data using string operations (line 547)
- The content of the subpages will be loaded even if no preview is 
 requested (lines 567ff). This costs a lot of ressources.
- Odd code: 
   if ( $this->debug || $this->debug == 1 ) {  
 (line 276). The "|| $this->debug == 1" part is superfluous.
Overall, I don't think that we should activate this code.
JeLuF

To respond to this feedback, the current extension project was created and the changes below implemented.

Things changed[edit | edit source]

  • Improved use of $wgExtensionCredits as suggested by User:Peterblaise.
  • Corrected typo of array $conditions.
  • Corrected code error where $debug was always on.
  • Removed preview mode. This is a major feature removal. The old version could (allegedly) include previews of the subpages. This was considered far too ambitious and outside the current needs. This also removed a lot of the code which "JeLuF" (above) did not like.
  • Removed the $articlecontent array used for caching subpage previews (as well as a bunch of other variables) plus the code which cached subpage previews.
  • Removed restriction of subpage choice by category and namespace.
  • Removed options for limiting and ignoring certain subpages.
  • Renamed option "deepness" to "depth".
  • Renamed option "mode" to "liststyle".
  • Renamed the tag from "subpages" to "splist" (i.e. subpagelist).
  • Renamed classes and hooks to avoid any conflict with previous extension.
  • Changed default value of showpath attribute to no and changed value normal to full.
  • Renamed options "order" and "ordermethod" to "sort" and "sortby".
  • Added the critical feature whereby grandchildren (and further descendent levels) are indented properly to indicate their level of descendence. Previously this extension simply did a one-level bulleted list which indicated inheritance/descendence only by the use of paths in the text.
  • Replaced the deepness/depth option with some more useful (and simpler) toggles (kidsonly, showparent) because the original option didn't even come near to working properly.
  • Fixed a bunch of problems with namespaces.
  • Added a visible report to the output in the event of there being no subpages to list. Previously the white space gave the feeling of a malfunction.
  • Added a limit (200) to the number of displayable subpage titles after noting that invalid inputs for the parent option might end up extracting too much from the database.
  • Added some validity tests, including a page exists check, to the parent option, because otherwise malicious wiki editing could produce a database output error.
  • Replaced use of REGEXP with LIKE following advice from FlyingParchment.

Options in Extension:SubPageList2 which were retained, tested and repaired[edit | edit source]

  • Debug. Values: 0 = show errors; 1 = hide errors. Illogical. Documentation error, plus code error.
  • Deepness (now depth). Specifies how deep to go. Note bug report by Fungiblename. Completely crazy. Replaced with: kidsonly, showparent.
  • Mode (now liststyle). Remove the "preview" value and keep just the choice between numbered and bulleted lists.
  • Showpath: whether to show just page titles or the full path in the list.
  • Order (now sort): whether to sort subpages in ascending or descending order.
  • Ordermethod (now: sortby): whether to sort subpages by date or title.
  • Parent: used to choose the top level page in the nav. Had namespace issues.

Options in Extension:SubPageList2 which were axed[edit | edit source]

  • Category: was used to restrict selected subpages to those belonging to a specific category.
  • Count: maximum number of subpages to display.
  • Ignore: list of subpages to ignore.
  • Namespace: was used to restrict subpage selection by namespace.
  • Previewcount: used to determine how much of a subpage was previewed; as the preview feature is being removed, this is no longer needed.
  • Previewmode: ditto.
  • Headline: was an option for the preview mode.

Testing[edit | edit source]

MediaWiki versions tested[edit | edit source]
  • Environment #1: MediaWiki: 1.11.1 / PHP: 5.2.3 (cgi) / MySQL: 4.1.22
    (internal; not accessible)
  • Environment #2: MediaWiki: 1.11.1 / PHP: 5.2.3 (cgi) / MySQL: 4.1.22
    View some of the tests here: http://www.qedoc.org/en/index.php?title=Subpagelist_Extension
  • Environment #3: MediaWiki: 1.6.10 / PHP: 4.4.7 (cgi) / MySQL: 4.1.22
    This extension does not, unfortunately, work with Mediawiki 1.6, nor is it likely any simple hack would help.
  • Environment #4: MediaWiki: 1.12alpha / PHP: 5.2.3 (cgi) / MySQL: 4.1.22
    (internal; not accessible)
Things actually tested[edit | edit source]
  • Tested the following options and established that they appear to work as they should: sort, sortby, liststyle, showpath.
  • Tested (after fixing): parent option (especially with namespaces), kidsonly, showparent (replacements for the depth option).
  • Tested indentation ability up to great-great-grandchildren.
  • Tested namespace stuff more.
  • Tested putting the output results inside tables and formatted divs to see how well this works with attractive menu box templates.
  • Tested namespace stuff even more.
  • Tried exploiting vulnerabilities in the parent option and successfully produced database errors; then programmed safety mechanisms to prevent such exploitation.

Observations[edit | edit source]

  • The original documentation says that the subpage list is only updated when the page containing the tag is updated. In practice it was noted that sometimes this was true and sometimes not (i.e. sometimes the list appeared to update even when the page containing the tag had not been updated).
    • Probably a mirage.
    • This is ancient history. From version 1.02 Tim's suggestion to add cache disabling means that the extension really updates dynamically.
  • The parent attribute must have the namespace removed before it does anything.

Bugs[edit | edit source]

  • The entire way SubPageList2 deals with grandchildren and their descendents was unacceptably buggy.
    • Fixed in initial release.
  • There is a namespaces issue with the parent option if any namespace crossing is attempted. First, the parent option cannot be used with a namespace. Second, the subpagelist then assumes that all subpages are in the same namespace as the page in which the tag is embedded, not the namespace of the page given as the parent of the list.
    • Fixed in initial release.
  • Can you please use another variable name for $dir, this conflicts with other extensions. Here is a patch:
--- SubPageList3.php~   lun. juil. 20 12:53:01 2009
+++ SubPageList3.php    lun. juil. 20 12:48:59 2009
@@ -26,8 +26,8 @@
        'author' => array('James McCormack', 'Martin Schallnahs', 'Rob Church'),
 );
 
-$dir = dirname(__FILE__) . '/';
-$wgExtensionMessagesFiles['SubPageList3'] = $dir . 'SubPageList3.i18n.php';
+$dirSubPageList3 = dirname(__FILE__) . '/';
+$wgExtensionMessagesFiles['SubPageList3'] = $dirSubPageList3 . 'SubPageList3.i18n.php';
 
 /**
  * Hook in function


Code[edit | edit source]

Wishlist for future versions[edit | edit source]

  • Add options for showing extra data after each page in the list; e.g. page visits, last edit date, page size.
  • Option to watch all pages shown.
  • Use a render dependency table for dynamic updating of contents.
  • Possibility to exclude certain pages.
  • Option to automatically include list of all subpages if the article has subpages. (a bit like an auto TOC)

See also[edit | edit source]

  • SubPageList: based upon this one and backwards compatible
  • SubPageList2: the extension this one is based upon
  • Subpage Fun: extension providing subpage related functions and magic words to gather informations about sub- and parentpages