Extension:DynamicPageList2

DynamicPageList2 is a Mediawiki extension developed for use on Wikinews (but not yet installed there), but it can be installed on any wiki. It allows wiki users to dynamically create lists of pages that are listed in a set of categories or namespaces using logical AND and OR.

Source code, manual and instructive examples for Release 0.9 can be found on a separate dpl demo web site. That release should be fairly stable now and solves practically all problems and requests mentioned in the discussion page. You are invited to download and test.

The following describes release 0.8.

DynamicPagelist2 vs. DynamicPageList
A short word to the history of this extension:
 * 1) At the beginning there was a small initial version called DynamicPageList (You may be able to find the source code and description still on meta wiki.
 * 2) That version was greatly improved and renamed to DynamicPageList2 (DPL2). With DPL2 came much more freedom when generating dynamic article lists by using AND and OR with categories. Moreover, there were much more display options to set. See the  list of improvements). Note that it was called DynamicPageList2 for distinction of DPL. You could use both extensions at the same time, because the new tag was called  instead of  . ''The text you are reading describes "DPL2". Development of DPL2 came to an end around December, 2006
 * 3) Since then the source code of DPL2 was considerably improved and many more features were added. The extension now became a complete superset of the "old DPL" and "DPL2". It didn´t look very wise to call it DPL3, though. So the name was simply changed back to DynamicPageList. Some names in the source code still have a "2" in their text. You will find that latest version (which is still under active development as of April, 2008) under Extension:DynamicPageList. There is a separate website where the latest release of DPL is installed and can be used for experimenting.

Main Authors / Contacts

 * Unendlich (EMail: fabian AT xover.htu.tuwien.ac.at).
 * Dangerville

See also - similar functionality

 * Extension:Semantic MediaWiki would also allow the inclusion of the result of this kind of queries to categories (union, intersection) (as well as more "Semantic Web" features).

Get code/file
First download the source from (2 possible locations):
 * svn.wikimedia.org (for latest/development version)
 * DynamicPageList2.php: Main file.
 * DynamicPageList2.i18n.php: Required by, internationalization file used for all DPL messages.


 * '''Alternative location: svnweb.tuxfamily.org (for latest or older releases)
 * Development version: Browse - Tarball
 * Older releases: Browse. RELX_Y_Z means version X.Y.Z. Use the Tarball link on the right to download.

Installation
To install it,
 * 1) put the file in your   directory, and add
 * 2) edit to your   file this line:

For 0.8.0 and above, you have to install the Labeled Section Transclusion extension too (both lst.php and lsth.php files).

For v0.7.0 and above, if you want to apply the 'category' parameter on the Uncategorized pages, you are required to execute this manual query on your MediaWiki database, replacing  with your prefix if any: CREATE VIEW prefix_dpl_clview AS SELECT IFNULL(cl_from, page_id) AS cl_from, IFNULL(cl_to, '') AS cl_to, cl_sortkey FROM prefix_page LEFT OUTER JOIN prefix_categorylinks ON page_id=cl_from

If you are using this extension with IIS on a Windows box, make sure to give Read & Execute rights to the user IUSR_MACHINENAME (Anonymous Internet Guest Account) for the extensions directory and the DynamicPageList2.php file itself.

System requirements
Not compatible with Mediawiki 1.5.x. The extension uses (needs) more than two parameters and WikiMedia 1.5.x provides only two.
 * DPL2 0.8.0 and above: MediaWiki 1.8.2 or above, and both lst.php and lsth.php files from Labeled Section Transclusion.
 * DPL2 0.7.8 and above: if using MySQL, MySQL 4.1 or above is required for firstedit/lastedit sorts (because these use nested queries of the form SELECT ... SELECT ..., see also MySQL 3.23, 4.0, 4.1 Reference Manual :: 13.2.8.11 Rewriting Subqueries as Joins for Earlier MySQL Versions).
 * DPL2 0.7.0 and later: if you want to use the 'category' parameter on Uncategorized pages (empty string) with a MySQL server, MySQL 5.0.1 or above is required (the creation of the dpl_clview requires the CREATE VIEW statement, see also MySQL 5.0 Reference Manual :: 19.2 CREATE VIEW Syntax).
 * DPL2 0.6 and later: MediaWiki 1.7.1 or above for internationalization. (more info...).
 * DPL2 0.5.1: See test on MediaWiki 1.7 by gandm.
 * DPL2 0.5.x: Tested (mostly) successfully on Mediawiki 1.6.7.

Sites using DPL2
''Please supply the list below with links to wikis where DynamicPageList2 is installed, and if possible, specific pages where we can see it in action. This is useful for users who do not have their own wiki installation to have a live demo of its features. We appreciate it.''

Here are some (check the Special:Version page to get the version):
 * DPLWiki: official site for demo/testing of the DPL (test there freely)
 * OpenOffice.org Wiki
 * WikiIndex: WikiIndex's DPL Test Page
 * RJS Software: Using DPL2 for adding page links from multiple categories to the bottom of each Troubleshooting page.
 * Princeton University QED (formerly TigerWeb): QED:Dynamic_Page_List
 * OpenWetWare
 * Nissan Tech Wiki
 * Crewscut.com : used for creating dynamic lists on our frontpage
 * D&D Wiki: Used to provide lists for the races, monsters, and other such categories.
 * VoWi: DynamicPageList2 used on VoWi:Moderation to create lists of articles that need to be worked on.
 * self-qs.de : used for creating dynamic lists on our frontpage
 * Dev-Scene.com : Used to manage the news feeds.
 * WikiGrondin
 * unmaintained-free-software Wiki - used to show the recently added projects
 * 
 * Lemonia
 * Videoville.org: Version 0.5.1 used to create front page scrollboxes.

Usage of DynamicPageList2
To use DPL, use the following XML-like syntax on your wiki page:

 ...parameters... 

The output of this would be something like: (depending on the outputmode you select)


 * Page 1
 * Page 2
 * Another Page

You can nest DPL in a static list on your wiki page:  Item1 Item2  ...parameters...   

The list of pages being output, as well as the order and display mode of the list has to match the defined parameters.

The following lists parameters and their effects

category
Purpose:

Include pages in the union of given categories. You can specify more than one category with the pipe '|' as a separator, with the effect that the pages listed have to be at least in one of the categories (logical OR). If you specify the 'category=' parameter more than once, the pages listed have to match all these parameters (logical AND).

Syntax:

Example 1:

 category=Africa|Europe category=Politics and conflicts 

This list will output pages that have OR, AND  listed.

v0.7.0 - You can specify the set of Uncategorized pages as a normal category, with an empty string (e.g. ' ' for uncategorized pages only, ' ' or ' ' for the Uncategorized or the Animals category, ' ' for the Mammals category, uncategorized pages or the Insects category, etc.). See Source and Installation for the extra required installation steps.

v0.7.7 - If ordermethod=category,... and headingmode are enabled, you can restrict the categories you want as headings in the result by preceding the list of categories (specified with the category parameter) with a '+'. See the example below.

Example 2:

 category=+Africa|Europe category=Politics and conflicts ordermethod=category,sortkey headingmode=ordered 

This list will output pages that have OR, AND  listed. The list will be ordered (OL tag) and organized in 2 main items/headings: the Africa one and the Europe one (Politics and conflicts will not be used as a heading). Under each item/heading, a sublist of pages ordered by their sortkey for the category used as heading.

Notes:

You may use Magic words like August, 27, 2024 etc in the category name, as long as they do not contain the character "|".

Related extension variables (more info):,  ,.

notcategory
Purpose:

Much like the category parameter, but requires that every page listed not be in a particular category. Unlike in 'category' you cannot combine several categories using logical OR in this parameter.

Syntax:

Example:

 category=Africa notcategory=Zimbabwe notcategory=Kenya </DPL>

This list will output pages that have but do not have either  or  listed.

Notes:

You may use Magic words like August, 27, 2024 etc in the category name.

Related extension variables (more info):,  ,.

namespace
Purpose:

To restrict the articles in the list to only be in one of the given namespaces.

v0.7.7 - Magic words supported. See m:Help:Magic words and m:Help:Magic words for relevant magic words.

Syntax:

The namespace name may be anyone, assuming it represents a valid namespace in the system, including custom ones, BUT no pseudo-namespace such as Media, Special which have negative namespace ids. See m:Help:Namespace. The empty string is the main article namespace (e.g. ' ' for pages in Main ns only, ' ' or ' ' for Main or Talk ns, ' ' for User, Main or Category, etc.).

Name spaces are case sensitive   will work, but   will not.


 * Namespace ids are no longer allowed as namespace arguments, because it caused a conflict between namespace given a number as name on one hand, and namespace with that same number as namespace id on the other hand. E.g. if you created a custom namespace with '1' as title (yes, it's possible),  would give you pages in '1' and not pages in namespace with id=1 (Talk). In that case, you could not get pages in the Talk ns anymore. Solution: use only ids or only names. Names are more user-friendly.

Example 1:

 category=Policy namespace=Wikinews|Discussion </DPL>

This list will output pages that are in the Wikinews or Discussion namespace and belong to.

Example 2 (with magic word):

 category=Policy namespace= </DPL>

This list will output pages that are in the namespace the current page is in - whatever it is - and belong to.

notnamespace
Purpose:

Much like the notcategory parameter, but for namespaces. Requires that every page listed not be in one of given namespaces.

v0.7.7 - Magic words supported. See m:Help:Magic words and m:Help:Magic words for relevant magic words.

Syntax:

Example 1:

 notnamespace=Wikinews notnamespace=Discussion </DPL>

This list will output pages that are NEITHER in the Wikinews NOR in the Discussion namespace.

Example 2 (with magic word):

 notnamespace=Wikinews notnamespace= </DPL>

This list will output pages that are NEITHER in the Wikinews NOR in the namespace the current page is in.

linksto
Introduced in v0.7.7.

Purpose:

Filters the articles which link to a certain page. Magic words are supported. See m:Help:Magic words for relevant magic words.

Syntax:

Example 1:  category=Poets linksto=Dublin </DPL>

This list will output pages that are in category "Poets" and link to the page with title Dublin in the Main namespace.

Example 2 (with magic word):

 category=Poets linksto= </DPL>

This list will output pages that are in category "Poets" and link to the current page, whatever it is.

shownamespace
Purpose:

To restrict the appearance of the namespace name of a page before the page. For example, when this parameter is used, instead of Template:Stub the listing would simply be Stub.

Example:

If omitted, the default is true.

Example:

 category=Africa namespace=Talk shownamespace=false </DPL>

This list will output all Talk pages in, listed without the Talk: prepended to page names.

mode
Purpose:

To control the output of the DPL.

Syntax:

modename can be one of:
 * unordered &mdash; outputs an unordered list &mdash; HTML tag "ul" &mdash; (default)
 * ordered &mdash; outputs an ordered list &mdash; HTML tag "ol"
 * none &mdash; outputs a list using newlines and HTML tags "br" to separate each item
 * inline &mdash; outputs a list using symbol defined by the inlinetext parameter to separate items. See inlinetext for more info.
 * category &mdash; outputs resulting articles in a way category-pages are shown (you have to use  with this option!)

Example:

 category=Africa mode=ordered </DPL>

This list will output pages that have shown in an &lt;ol&gt;...&lt;/ol&gt; list.

Related extension variable(s):.

inlinetext
This replaced 'inlinesymbol'.

Purpose:

To define the inline text used in.

Syntax:

, with wikitext some wiki text, default is '&amp;nbsp;-&amp;nbsp;'.

'Extra whitespaces are stripped by DPL from the beginning and end of wikitext''. If you want to show one or multiple spaces, use one or multiple ' ', or use 'nowiki' tags like in '&lt;nowiki&gt; - &lt;/nowiki&gt;' which has same effect as '&amp;nbsp;-&amp;nbsp;'.'''

Example:

 category=Africa mode=inline inlinetext=&amp;nbsp;&amp;bull;&amp;nbsp; </DPL>

This list will output pages that have shown like Item1 &bull; Item2 &bull; Item3 &bull; ...

headingmode
Purpose:

To control the output of the headings in a DPL with complex/multi-parameter ordermethods. (No effect with single-param ordermethods.) For, method1 is used for headings. E.g.  affects category headings in   (2-param ordermethod).

Syntax:

modename can be one of:
 * none &mdash; headings are not displayed, no heading &mdash; (default)
 * unordered &mdash; outputs an unordered list &mdash; HTML tag "ul"
 * ordered &mdash; outputs an ordered list &mdash; HTML tag "ol"
 * definition &mdash; outputs a definition list &mdash; HTML tag "dl"
 * H2 &mdash; outputs sections &mdash; HTML tags "H2"
 * H3 &mdash; outputs sections &mdash; HTML tags "H3"
 * H4 &mdash; outputs sections &mdash; HTML tags "H4"

Example:

 category=Africa|Europe ordermethod=category,title headingmode=definition mode=ordered </DPL>

This list will output pages that belong to one of the categories Africa, Europe in a list similar to this (HTML source), with Pages 1 and 2 in the Africa category, Page 1 in the Europe category as well (in fact, the titles are replaced with the appropriate links): <dl> <dt>Africa</dt> <dd> <ol> Page1</li> Page2</li> </ol> </dd> <dt>Europe</dt> <dd> <ol> Page1</li> </ol> </dd> </dl>

titlemaxlength
Purpose:

To limit the number of characters of the title to display. If the page title (this does not include the namespace or any other prefix before the title) is bigger than the titlemaxlength value, the title is truncated and ended by '...'.

Syntax:

Same syntax as the count parameter.

order
Purpose:

Controls the sort direction of the list.

Example:

orderdirection can be one of:
 * descending &mdash; outputs list from most recent to least recent &mdash; (default)
 * ascending &mdash; outputs list from least recent to most recent

Example:

 category=Africa order=ascending </DPL>

This list will output pages that have shown ordered from oldest to newest.

count
Purpose:

Controls the number of results that are shown.

Syntax:

, with  a positive integer

A blank value for unlimited. It is unlimited by default, depending on extension variables:,.

Example:

 category=Africa ordermethod=pagetouched count=2 </DPL>

This list will output the two pages most recently changed that have.

ordermethod
Purpose:

Determines what criterium (resp. criteria) is (resp. are) used to order the list.

Syntax:

means ordered by method1 first, then by method2, etc. (like the ORDER clause in SQL)

methodN can be one of: Multi-param ordermethods (see also headingmode option):
 * categoryadd &mdash; outputs list based on most recent addition to the first category (requires to include one category and one only using 'category' parameter)
 * counter &mdash; outputs list based on the number of times the page has been viewed (by ~popularity)
 * firstedit &mdash; outputs list based on first edit to the pages (creation)
 * lastedit &mdash; outputs list based on most recent edit to the pages
 * pagetouched &mdash; outputs list based on 'page_touched' timestamp. Read comment on  field in Page_table to see the difference from most recent edit by an author.
 * title &mdash; outputs list sorted by article (prefix +) title &mdash; (default)
 * category,firstedit &mdash; outputs list sorted by category, then by first edit
 * category,lastedit &mdash; outputs list sorted by category, then by last edit within a category
 * category,pagetouched &mdash; outputs list sorted by category, then by pagetouched
 * category,title &mdash; outputs list sorted by category, then by title
 * Replaced by category,sortkey in v0.7.7 to customize the order with sortkeys from category tags, like in MediaWiki category pages.


 * user,firstedit &mdash; outputs list sorted by user, then by firstedit by the user
 * user,lastedit &mdash; outputs list sorted by user, then by lastedit by the user

Example:

<DPL> category=Africa ordermethod=lastedit </DPL>

This list will output pages that have showing most recently edited articles at the top.

debug
Purpose:

Sets debugging level.

Syntax:

, where n is one of: If you use debug param but not in first position in the DPL element, the new debug settings are not applied before all previous parameters have been parsed and checked. This will generate a warning for  and above.
 * 0 &mdash; silent mode, shows nothing
 * 1 &mdash; quiet mode, shows (fatal) errors
 * 2 &mdash; default mode, like 1 + shows warnings; &mdash; (default)
 * 3 &mdash; verbose mode, like 2 + shows SQL query.

Example:

<DPL> namespace=Media debug=0 namespace=Special </DPL>

This list will output the error for the first namespace: Media is not a valid namespace value (pseudo-namespace). Assuming you haven't changed the default debug value (2), you will also get a warning:  is not input first (before  ). So it did not apply to  but only to what's after. Indeed, you won't get the warning for the second namespace (Special) since  changed debug settings to silent mode.

DPL debug messages are translatable in. See also Internationalization.

minoredits
Purpose:

Controls the inclusion or exlusion of minor edits in lists.

Requires: ordermethod=[...]firstedit|lastedit

Example:

criteria can be one of:
 * exclude &mdash; ignore minor edits when sorting lists
 * include &mdash; includes minor edits to sort lists &mdash; (default)

Example:

<DPL> category=Africa ordermethod=lastedit minoredits=exclude </DPL>

This list will order pages tagged with by lastedit, but minor edits will be ignored in the ordering.

redirects
Purpose:

Controls the inclusion or exlusion of redirect pages in lists.

Example:

criteria can be one of:
 * exclude &mdash; excludes redirect pages from lists &mdash; (default)
 * include &mdash; allows redirect pages to appear in lists
 * only &mdash; lists only redirect pages in lists

Example:

<DPL> category=Africa redirects=include </DPL>

This list will content pages and redirect pages tagged with.

addfirstcategorydate
Requires to include one and one category only, with 'category' parameter.

Conflicts with other "add*date" (addeditdate, etc.) parameters to avoid confusion.

Purpose:

Shows the date/time the article got added to the first listed include category.

Example:

If omitted, the default is false.

Example:

<DPL> category=Africa addfirstcategorydate=true </DPL>

This list will output a list of pages belonging to, prepending each result with the time and date (formatted according to your local mediawiki date display preferences or the user preferences if user logged in).

addeditdate
Requires ordermethod=[...,]firstedit or ordermethod=[...,]lastedit. ([...,] means complex ordermethods with extra param before firstedit|lastedit are allowed.)

Conflicts with other "add*date" (addpagetoucheddate, etc.) parameters.

Purpose:

If firstedit (resp. lastedit), 'addeditdate=true' shows the date of the first revision/creation (resp. last revision) of the page.

Example:

If omitted, the default is false.

Example:

<DPL> category=Africa ordermethod=lastedit addeditdate=true </DPL>

This list will output a list of pages belonging to, prepending each result with the date of last revision (formatted according to your local mediawiki date display preferences or the user's preferences if logged in).

addpagecounter
Purpose:

Shows number of times the page has been viewed according to the definition of the 'page_counter' field on Page_table.

Example:

If omitted, the default is false.

addpagetoucheddate
Requires ordermethod=[...,]pagetouched or ordermethod=[...,]title. ([...,] means complex ordermethods with extra param before are allowed.)

Purpose:

Shows date/time of last change to the page according to the definition of the 'page_touched' field on Page_table.

Example:

If omitted, the default is false.

Example:

<DPL> category=Africa ordermethod=pagetouched addpagetoucheddate=true </DPL>

This list will output a list of pages belonging to, prepending each result with the date of last change (formatted according to your local mediawiki date display preferences or the user's preferences if logged in).

adduser
Requires ordermethod=[...,]firstedit or ordermethod=[...,]lastedit. ([...,] means complex ordermethods with extra param.)

Purpose:

If firstedit (resp. lastedit), 'adduser=true' shows the name of the user who made the last revision (resp. last revision) of the page.

Example:

If omitted, the default is false.

Example:

<DPL> category=Africa ordermethod=lastedit adduser=true </DPL>

This list will output a list of pages belonging to, prepending each result with the author of the last revision.

--139.76.128.68 17:27, 19 July 2007 (UTC)

includepage
Purpose: include pages (whole content) or include labeled sections.

Requires  from Labeled Section Transclusion

Syntax:
 * To include the whole page, use a wildcard:


 * To include sections labeled 'sec1' or 'sec2'... from the page (refer to Labeled Section Transclusion to know how to label sections in your pages accordingly):


 * To include from the first occurrence of the heading 'heading1' (resp. 'heading2') until the next heading of the same or lower level. Note that this comparison is case insensitive. (Refer to Transcluding visual headings.) :


 * You can combine:


 * To include nothing from the page (no inclusion), leave blank (this is default):

secseparators
Purpose: customize the output format of multiple transcluded labeled sections.

Syntax:

'Startall', 'Start', 'End' and 'Endall' are HTML strings used to separate the transcluded sections in the output (see 'includepage=name1,name2,...'). 'Startall' and 'Endall' define an outer frame for sections of a page; 'Start' and 'End' build an inner frame for each section. Example: secseparators= would output a table with all sections in a row (for every page where sections have been found).

listattr
Purpose: Adds attributes to HTML list elements, depending on 'mode' (html element is 'ol' for ordered, 'ul' for unordered, 'div' for others). Can be used with pseudo 'mode=inline' where 'inlinetext' contains one or more Examples:

itemattr
Purpose: Adds attributes to HTML list items, depending on 'mode' (element is 'li' for ordered/unordered, 'span' for others).

Not applicable to 'mode=category'.

Syntax: Example: see listitemattr.

hlistattr
Purpose: Adds attributes to the HTML list element at the heading/top level, depending on 'headingmode' (HTML element would be 'ol' for ordered, 'ul' for unordered, 'dl' for definition, 'div' for others)

Not yet applicable to 'headingmode=none'.

Syntax: Example:

See also hitemattr.

hitemattr
Purpose: Adds attributes to HTML list items (headings) at the heading level, depending on 'headingmode' (HTML element would be 'li' for ordered/unordered, 'div' for others).

To be used with headingmode='unordered' or 'ordered'. (Not yet applicable for others.)

Syntax: Example:

Extension options
You can set the following global variables, preferably in your  (after including  ) or in   directly, to configure and restrict the usage of the DPL extension server-wide.

$wgDPL2MaxCategoryCount Maximum number of categories specified in a DPL with 'category' or 'notcategory' parameters = Maximum number of categories allowed in the SQL-query. To prevent too complex queries.

$wgDPL2AllowUnlimitedCategories Allows unlimited categories in the query. ( will be ignored)

$wgDPL2MinCategoryCount Minimum number of categories specified in a DPL with 'category' or 'notcategory' parameters = Minimum number of categories needed in the SQL-query for setting limits. To prevent output of a gigantic list.

$wgDPL2MaxResultCount Maximum number of results to allow.

$wgDPL2AllowUnlimitedResults Allow unlimited results to be shown.

$wgDPL2CategoryStyleListCutoff Max length to format a list of articles chunked by letter as bullet list, if list bigger, columnar format user (same as cutoff arg for ). Used by.

$wgDPL2Options Gives control on the extension parameters (see Usage of DynamicPageList2 for the list). The best way to get familiar with it is to look at its declaration in  (beginning). Use it at your own risk. Anyway, below are some usage examples:
 * Change default parameter values: . Make sure val is a valid param value.
 * Example:  to change the shownamespace default value to 'false'.


 * Restrict parameter options: if the parameter param has options option0, ..., optionN (according to the definition of  in  ),   will disable optionn for users (not allowed). If you disable an option currently defined as default parameter value, make sure you change the default value to another option as well (see previous item).

Internationalization
Since MediaWiki 1.7.1, extension messages are translatable (more info). To use this feature and translate the DPL messages into your favorite language, have a look at. All you have to do is to create in this file a  array where 'lang' is your language code, and use   as a model. Replace values with appropriate translations.

Bug report
Before reporting bugs, view old ones on the discussion page. For more recent ones, make an advanced search on MediaZilla. Select Product: MediaWiki extensions, and Component: DynamicPageList2.

Report new bugs on MediaZilla. Select Product: MediaWiki extensions, and Component: DynamicPageList2.

Note: if you have installed DPL2 on a public site, you are invited to add it to the list of sites using DPL2. Thank you.

Feature request
View old requests and request features on the discussion page.

ToDo
See.

Release 0.8.1
Feature:
 * 'includepage=#heading' option (page transclusion of specific headings)

Release 0.8.0
Features:
 * 'includepage' option (page transclusion, labeled section transclusion)
 * 'secseparators' option to separate transcluded sections with custom HTML code

Security fix:
 * SQL injection
 * A few XSS vulnerabilities

Release 0.7.8
Features:
 * addpagecounter feature (adds # times page has been viewed)
 * 'ordermethod=counter' feature: orders pages by #times page has been viewed
 * Date output according to time zone offset in user's preferences
 * Improved generation of links.

Bugfixes:
 * 7773: Wrong user name with 'adduser=true'
 * 7847: Use of 'addfirstcategorydate=true' triggers SQL error.
 * 7772 Date not formatting (user time correction was ignored).
 * Incompatible encodings in mysql string concat when generating sortkeys (ordermethod=category,sortkey)