Extension:DynamicPageList2 0.9

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 based on a variety of selection criteria like categories, namespaces, title, references to other articles, usage of templates. Selection criteria can be combined using logical AND and OR. Contents of the pages can be included in the output of DPL2.

Source Code and Examples for Release 0.9 (which has not been officially released so far) can be found on a separate dpl demo web site.

DynamicPagelist2 vs. DynamicPageList
This extension - DynamicPageList2 is a hack of the original DynamicPageList extension featuring many improvements (see Usage of DynamicPageList2). Note that it's called DynamicPageList2 for distinction of DynamicPageList. You can use both extensions at the same time, because the new tag is DPL instead of DynamicPageList.

With DPL2 you have much more freedom when generating dynamic article lists by using AND and OR with categories. Moreover, there are much more display options to set.

Release 0.9 has some major improvements compared to former versions. As a consequence, there are some minor incompatibilities with older versions (mainly in the area of parameter expansion -- see the chapter on ).

Main Authors / Contacts

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

Get code/file
First download the source from:
 * Release 0.9
 * dpl demo web site
 * older releases
 * 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
 * 2) edit your   file and add the following line:

Labeled Section Transclusion is another extension which is used by DPL2.

If you installed release 0.9 there is nothing else to do because a special version of that extension has been integrated into release 0.9.

If you installed release 0.8.x, 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 links where DynamicPageList2 is being used (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
 * Princeton University QED (formerly TigerWeb): TigerWeb: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
 * BridgeLexikon : used to link auction bids in the game of bridge.
 * self-qs : defining and refining quality assurance terms and proceedings.

General Usage of DynamicPageList2
DPL2 can be used as a parser extension or as a parser function. There is no general rule which one is better. The next two sections describe the differences.

If in doubt, you may want to use the parser function syntax as it is more powerful.

Using DPL2 as a parser extension
Parser extensions define a specific tag (in our case   ) and a corresponding end tag (  ). Case doesn´t matter, so you can also write. The text between these tags is handed over to the extension module just as it is. The extension module takes this text as a series of commands, executes them and inserts the output right at the place where it found the two tags.
 * every parameter assignment (=command) has to be on a separate line
 * generally the syntax looks fairly simple and intuitive as it doesn´t contain special characters (except for the two embracing tags).
 * Wiki markup expansion does not take place before the commands are handed over to the extension module.
 * this may be useful if you want to pass wiki syntax elements to DPL2 as arguments (see the listseparators option, for example)
 * you cannot use something like or 27
 * you cannot use template parameters
 * you cannot use parser funtion calls like within the arguments

In many cases there is no need to have macro expansion within the parameter list. For example:  category = cat1|cat2 linksto = myPage  The example will produce a list of all articles which belong to cat1 or cat2 and which contain a reference to myPage. Note that the pipe character (which is used to define a logical OR between the two categories) can be written as it is. The name of the page (myPage), however, must be a hardcoded constant. The output of this DPL call would be something like


 * Page 1
 * Page 2
 * Another Page

Using DPL2 as a parser function
Parser functions are more closely integrated with the wiki system. They are more powerful but their syntax looks a bit more complicated. In our case you can write   just the way you would use. The text between the double curly braces is interpreted and expanded according to wiki syntax rules before it is handed over to the extension module. This means:
 * All kind of wiki markup expansions take place before the commands are handed over to the extension module.
 * If you want to use wiki characters as arguments you must define special templates to "escape" them.
 * the text can (but needs not) be written in one line of text, parameters are separated by pipe characters.

Example: or Both examples will produce an identical list of all articles which belong to cat1 or cat2 and which contain a reference to a certain page. We assume that the above invocation of #dpl is contained within a template. The desired page name will be passed as a parameter when calling the template. Within the template the page name can be referred to as. Note that the pipe character which is used to define a logical OR for the two categories must be represented as a call of a special template which would typically be called "Template:!" and which has a single pipe character as its contents. You will find the same kind of trick also outside DPL in other templates. You may note that the second example is not literally equivalent to the first one as there is an additional pipe character before the first parameter. This creates an empty parameter which is silently ignored by DPL.

Syntax used in this manual
If we give complete examples we will typically use the tag based parser extension syntax in this manual. Except when we want to make use of variable expansion.

Most of the manual deals with the explanation of individual parameters. This is independant from the two variants described above. So, if you read something like you should have in mind that you must either place DPL tags around (using a separate line for each parameter) or use the parser function syntax and separate parameters by pipe characters.
 * parameter = value

Interaction between your wiki text and DPL2 output
As mentioned before DPL2 will insert its output exactly at the position where you placed the DPL2 call. This means that you can put wiki syntax around your DPL call, like e.g.:

You could also use html syntax to surround DPL output as in the following example:  Item1 Item2  ...parameters...   

Usage of DPL2: Criteria for page selection

 * You can select articles based on
 * the category/categories they are assigned to
 * the number of categories they are assigned to
 * their namespace
 * their usage of templates
 * their title
 * their references to other articles
 * their character (#redirect or normal article)


 * You can restrict the number of articles to a certain limit
 * via configuration settings within the DPL2 source
 * via a specific parameter for a given invocation of DPL2


 * You can select a subset from the result list by random

category
Purpose:

Select articles based on 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:

If you want to use magic words like August, 27, 2024 etc in the category name, you must use the parser function syntax variant.

To prevent a DPL query from returning huge output (or consuming too many resources) there are some configuration variables in the source code of the extension module like,  ,.

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:

If you use the parser function syntax you will be able to use Magic words like August, 27, 2024 etc in the category name.

Related extension variables (more info):,  ,.

categoriesminmax
Purpose:

To restrict the search to articles which are assigned to at least [min] and at most to [max] categories.

Syntax:

Example:

 category=Africa categoriesminmax=3 </DPL>

The list will only contain articles which belong to category "Africa" and at least to two other categories

 category=Africa categoriesminmax=,1 </DPL>

The list will only contain articles which belong to category "Africa" and are not assigned to any other category.

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 Help:Magic_words and 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 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):

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 (when using parser function syntax). See Help:Magic_words and 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):

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:

Selects articles which link to a certain page.

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):

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

notlinksto
Purpose:

Selects articles which do NOT link to a certain page.

Syntax:

Example:  category  = Poets notlinksto = London </DPL>

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

Note:

The implementation of this feature is not very efficient. Use with care and avoid huge result sets.

uses
Introduced in v0.9.

Purpose:

Selects articles which use a certain template ( wiki syntax:  ).

Syntax:

Example 1:  uses = Template:Poet </DPL>

This list will output pages that use a template called Poet.

notuses
Introduced in v0.9.

Purpose:

Selects articles which do not use a certain template.

Syntax:

Example 1:  category = Poet notuses = Template:Poet </DPL>

This list will output pages about poets which do not use the corresponding template.

Caution:

The implementation of this feature is not very efficient. Use with care and avoid huge result sets.

titlematch
Purpose:

Select pages with a title matching a certain pattern. "pattern" is used as a LIKE argument in a SQL query. Namespaces are ignored as the namespace= parameter can be used to further narrow the selection.

Syntax:

Example:

 titlematch=%foo% </DPL>

This will output all pages (regardless of namespace) which have a name that contains "foo" somewhere in the title.

Example:

 namespace= titlematch=A% </DPL>

This will output all pages in the main namespace which begin with "A".

nottitlematch
Select pages with a title NOT matching a certain pattern. "pattern" is used as a LIKE argument in a SQL query. Namespaces are ignored as the namespace= parameter can be used to further narrow the selection. Normally you would want to use this selection only in combination with other criteria. Otherwise output could become huge.

Syntax:

Example:

 nottitlematch=%e% </DPL>

This will output all pages (regardless of namespace) which do not contain "e" in their title.

redirects
Purpose:

Controls the inclusion or exlusion of redirect pages in the output. By default redirections are NOT shown.

Syntax:

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:

 category = Africa redirects = include </DPL>

The result will consist of content pages and redirect pages tagged with.

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.

randomcount
Purpose:

create the complete result set and then select a subset for display by random.

Syntax:

, with  a positive integer

If randomcount is larger than the number of results, the complete result set will be displayed.

Example:

 category=Africa ordermethod=size count=20 randomcount=3 </DPL>

This list will output three random articles from the group of the 20 largest articles on Africa.

Usage of DPL2: controlling output order
You can influence the order in which articles are listed.

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)
 * size &mdash; outputs list based on the size of the article (bytes of wiki text)
 * 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:

 category=Africa ordermethod=lastedit </DPL>

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

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:

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

This list will output pages that have shown ordered from oldest to newest. In addition the edit date will be presented with each article.

Usage of DPL2: controlling output volume
Per default DPL2 will show the name of each article, including its namespace. The name will serve as a link to the article.

You can
 * show the number of articles found
 * suppress the namespace part of the articles´ names
 * cut off the articles´ names at a certain length
 * add edit data (size, author, last edited by, date of last change, ..)
 * add access date (frequency, date of last access)
 * add the articles´ contents or parts of it

Furthermore you can add a heading if there are some articles to display.

And you can define an alternate text which will be shown if there are no articles to display.

resultsheader
Purpose: output a headline if there is at least one article to display.

Syntax:

Note: The symbol %PAGES% will be replaced by the number of pages found.

Example:

<DPL> category=Africa mode=userformat resultsheader=There are %PAGES% pages on Africa. </DPL>

With "mode=userformat" we get complete control over the output. We do not specify "listseparators=" - so nothing will be displayed except the results header. The only thing we will get is a message about the existing number of articles.

noresultsheader
Purpose: output a headline if there is no article to display (empty result).

Syntax:

Note:

Setting noresultsheader to the empty string ("noresultsheader=") will suppress the warning message from DPL" which is normally issued if no articles were found.

shownamespace
Purpose:

To restrict the appearance of the namespace name of a page before the page. As the switch is true by default it should be set to false if you want to avoid namespaces to be shown in the output.

Syntax:

Example:

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

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

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.

addpagecounter
Purpose:

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

Example:

<DPL> category      = Africa ordermethod   = counter order         = descending addpagecounter = true counter       = 5 </DPL>

This will show the 5 most popular articles about Africa.

Note: in 'mode=userformat' the access counter can also be referenced as a built-in variable.

addpagesize
Purpose:

Shows the size of the page.

Example:

<DPL> category      = Africa ordermethod   = size order         = descending addpagesize   = true counter       = 5 </DPL>

This will show the 5 biggest articles about Africa.

Note: in 'mode=userformat' the size can also be referenced as a built-in variable.

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

Purpose:

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

Example:

If omitted, the default is false.

Example:

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

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

Note: in 'mode=userformat' the user can also be referenced as a built-in variable.

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).

Note: in 'mode=userformat' this date can also be referenced as a built-in variable.

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).

Note: in 'mode=userformat' this date can also be referenced as a built-in variable.

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).

Note: in 'mode=userformat' this date can also be referenced as a built-in variable.

includepage
Purpose: include pages (whole content) or include certain sections of articles.

Requires  from mw:Extension:Labeled_Section_Transclusion Labeled Section Transclusion

Syntax:
 * To include the whole page, use a wildcard:
 * you can use  to restrict the included text to a portion of the article.
 * you can use  to restrict the included text to a portion of the article.


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


 * To include sections (chapters) by a reference to their headings: use the heading name with a "#" as prefix. This will include text from the first occurrence of the heading 'heading1' (resp. 'heading2') until the next heading of the same or lower level. (Refer to Transcluding visual headings.). Note that the text comparison is case insensitive. Add a limit and an optional link text in square brackets to delimit the size of the included text portion to a certain number of characters. If text is cut off a link will appear which points directly to the chapter which was included. Using "0" as limit will only show the link (if the correpsonding chapter in the article is not empty). When truncating included text portions care is taken not to spoil wiki syntax (i.e. maintain a symmetry of brackets and braces). Therefore the size of the included text can deviate from what you specified.

linktext can be
 * plain text
 * then this text will be used as a link
 * text starting with "img="
 * then the link will appear as an image link (you must provide the image in a suitable size; no scaling will happen); note that image linking only works if there is another mediawiki extension installed (LinkedImages).
 * a text containing %SECTION%";
 * this symbol will be replaced by "article#heading". It is up to you to create a link from this text using normal wiki syntax if you wish.


 * To include variables which are used in a template call, specify the original template name within single curly braces and add a suffix; the template name including the suffix will be called instead of the original template and the result will contain just the output of your alternate template:


 * You can combine all of the above variants:


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

Example:

This will include
 * a text portion which is marked by special tags named "foo"
 * the contents of a chapter named "bar"; only the first 200 characters of wiki text will be shown; if the chapter is larger than that, a link with the text "..more.." will point to the source
 * an image link based on "my.gif" to the chapter "bang" in the article - if there is such a chapter and it is not empty
 * the output of template "boo.dpl" being called with the same parameters that were used to call template "boo" in the original page.

includemaxlength
Purpose:

Delimit the size of an included article to a maximum of [n] characters of wiki source text or less. Care is taken to respect pairs of braces and brackets as far as possible. Otherwise we might confuse the result by half-cut syntax elements of transcluded sections. Therefore the output might be shorter or even larger than [n] characters.

Syntax:

Note: this parameter is only used in combination with ; truncation of included chapter contents is specified by adding a limit in sqauare brackets within the 'includepage=' statement.

Usage of DPL2: controlling output format

 * You can select one of several default formats or define your own format("mode")
 * output can be grouped in columns or rows

mode
Purpose:

Provide basic control over the output of 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:
 * userformat &mdash; will leave output control completely to the user; see parameter listseparators and secseparators; in this mode DPL2 will offer built-in variables which must be referenced in the output format description provided by the user.

<DPL> 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;' except for mode=userformat where inlinetext is empty by default.

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:

<DPL> 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; ...

listseparators
Purpose: customize the output format completely. Requires "mode=userformat". Uses variable references like %PAGE% to describe the output format. See also the secseparators parameter.

Syntax:

'Startall', 'Start', 'End' and 'Endall' are wiki tags used to separate the list items.
 * 'Startall' and 'Endall' define an outer frame for the whole list.
 * 'Start' and 'End' build an inner frame for each article item.

Because wiki syntax depends on newline characters the string '\n' must be used to explicitly insert newline characters into the output.

As we want to be able to control output completely we reference article names and other possible output by special symbols:
 * %NR%   = the current article sequence number (starting from 1)
 * %PAGE% = the name of the article (including namespace)
 * %COUNT% = the usage counter (requires addpagecounter=true)
 * %SIZE% = the article size (requires addsize=true)
 * %SIZEFS% = a font size number which is based on the article size (logarithm of square root of counter)
 * %COUNTFS% = a font size number which is based on the usage counter (currently this is the logarithm of the usage counter)
 * %COUNTFS2% = similar to %COUNTFS%, but based on the logarithm of the square root of the usage counter.


 * %DATE% = the date selected, eg. lasteditr; requires addeditdate=true or similar
 * %USER% = the user who changed the document last; requires adduser=true

These symbols will be replaced by the corresponding values if they occur within 'Start' or 'End' or within the corresponding tags of the "secseparators=" parameter.

This means that the classical default output of DPL2 can also be produced with the following statements:

Example: <DPL> category      = Africa mode          = userformat listseparators = ,\n* %PAGE%,, </DPL>

Note that a bullet point list in wiki syntax is derfined by a "*" at the beginning of a line -- therefore we have to use a special symbol '\n' or '¶' to refer to the beginning of a new line of wiki text. Replace the "*" by a "#" and you will get a numbered list. 'Startall' and 'Endall' are empty (note that we start with a comma, note the two commas at the end), the 'Start' tag is used to create a new line with an initial "* " followed by the page name, written as a link. That´s all.

Creating a top-five hitlist with access rates and bold article names of varying size could be done like this: <DPL> category      = Africa ordermethod   = counter order         = descending addpagecounter = true count         = 5 mode          = userformat listseparators =,\n%COUNT% --- <font size="%COUNTFS%">%PAGE% , </DPL>

You can also use html syntax for the tags, although this is discouraged .. <DPL> linksto       = Africa mode          = userformat listseparators = ,<li>%PAGE%,</li>,</ul> </DPL>

Now let us create a table using wiki syntax: <DPL> linksto       = Africa mode          = userformat listseparators = {| class="wikitable"¶!pages found,¶|-¶|%PAGE%,,¶|} </DPL> We use 'Startall' to define the table header and 'Endall' for the footer. Each article is presented in a table row using wiki syntax for table layout.

we could also produce image galleries: <DPL> namespace=Image mode=userformat listseparators= </DPL>

secseparators
Purpose: customize the output format of included sections. Can be used with standard output modes and with mode=userformat.

Syntax:

'Startall', 'Start', 'End' and 'Endall' are HTML strings or wiki tags 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.

The symbol %SECTION% can be used to refer to the section found (works only for chapter headings).

Example:

<DPL> linksto       = Africa mode          = userformat listseparators = {|¶!pages found¶!fruit¶!color,¶|-¶|%PAGE%,,¶|} includepage   = #fruit,#color secseparators = ,¶|,, </DPL>

We use the listseparators to define a table with three columns and put a link to the article in the first column of each row. We use the secseparators to add more columns for each section we find. Have a careful look at the '¶' symbols ('\n' can be used as an alternative). They always appear before a wiki syntax element which must be placed at the beginning of a new line. Thus we make sure that the wiki parser will understand them. Note that if an article does not contain a section named "fruit" you will see an empty cell in your table.

Example 2: <DPL> linksto         = Africa mode            = userformat listseparators  = {|\n!pages found\n!fruit\n!color,\n|-\n|%PAGE%,,\n|} includepage     = #fruit[50],#color[100 more..] secseparators   = ,\n|, </DPL>

Assuming that the chapters on fruit and color contain long texts we truncate them to 50 or 100 characters. A link which refers directly to those chapters will be generated automatically if needed.

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:

<DPL> 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> <li>Page1</li> <li>Page2</li> </ol> </dd> <dt>Europe</dt> <dd> <ol> <li>Page1</li> </ol> </dd> </dl>

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.

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:

columns
Purpose:

Define a column layout for the output.

Syntax:

In "mode=userformat" the outer tags from "listseparators" will be repeated for each column. Example:

<DPL> category=Africa addpagesize=true ordermethod=size mode=userformat listseparators={|class=sortablewikitable id=2\n!Rank\n!Article\n!Bytes\n|-,\n|%NR%.\n|%PAGE%\n|align=right|%SIZE%,\n|-,\n|} count=12 columns=3 </DPL>

The output will contain a list of the 12 largest articles on Africa, arranged in three columns. Each column consists of a table which has itself three columns: rank, article name and size.

rows
Purpose:

Define a row layout for the output. A "row" is a group of output lines for which the heading is repeated. If you do not know how big your result will be, it may be better to use the "rowsize" parameter.

Syntax:

In "mode=userformat" the outer tags from "listseparators" will be repeated for each column. Thus you can create long lists where the table heading is repeated from time to time. Example:

<DPL> category=Africa addpagesize=true ordermethod=size mode=userformat listseparators={|class=sortablewikitable id=2\n!Rank\n!Article\n!Bytes\n|-,\n|%NR%.\n|%PAGE%\n|align=right|%SIZE%,\n|-,\n|} count=12 rows=2 </DPL>

The output will contain a list of the 12 largest articles on Africa, arranged in two rows (of 6 lines each). Each row consists of a table which has itself three columns: rank, article name and size.

rowsize
Purpose:

Define a row layout for the output. A "row" is a group of n output lines for which the heading will be repeated.

Syntax:

In "mode=userformat" the outer tags from "listseparators" will be repeated after each group of "rowsize" output lines. Thus you can create long lists where the table heading is repeated in regular intervals. Example:

<DPL> category=Africa addpagesize=true ordermethod=size mode=userformat listseparators={|class=sortablewikitable id=2\n!Rank\n!width=200px|Article\n!Bytes\n|-,\n|%NR%.\n|%PAGE%\n|align=right|%SIZE%,\n|-,\n|} rowsize=20 </DPL>

The output will contain a list of all articles on Africa. After each group of 20 entries (article names) the table heading will be repeated. It may be useful to set the width of the column with the article names explicitly, so that the tables in each row havce equal width.

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 DynamicPageList2.

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 Talk:DynamicPageList2.

Release 0.9
Availability of DPL2 also as a parser function; change in behaviour regarding parameter expansion; please read the overview chapter on the general syntax for calling DPL2

New features: ... and somne others
 * mode=userformat
 * listseparators
 * titlematch, nottitlematch
 * notlinksto
 * includemaxlength

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)