Criteria for page selection

Manual

Parameters

Criteria for page selection

Articles can be selected based on:

• The category/categories they are assigned to, or the number of categories.
• Their namespace.
• Their references/links to and from other articles.
• Their usage of templates.
• The author/editor of articles.
• Their titles.
• Their character (redirect or normal article).
• Their revision date.

Article result counts can be restricted to a certain limit:

• Via configuration settings within the DPL3 source.
• Via a specific parameter for a given invocation of DPL3.

A subset of results can be selected by random.

Important:

• Care to select the most appropriately narrow selection criteria is ideal to avoid large result sets; for testing and display purposes, the count parameter can also be used.
• Before applying format, ordering, or adjusting output volume, it is generally advised to view page selection results first (to confirm it works as expected).

Select articles based on CATEGORY

category

category

Selects articles based on categories. More than one category can be specified with pipe | (tag syntax) or broken pipe ¦ (parser function syntax) as a separator; the effect being that pages listed have to be at least in one of the categories (logical OR). If the category parameter is specified more than once, the pages listed have to match all these parameters (logical AND).

Syntax:

category=1st category name¦2nd category name¦3rd category name¦...
or
category=1st category name<&>2nd category name<&>3rd category name<&>...
or
category=_none_

Either the ¦ broken pipe can be used for logical OR, or the & symbol wrapped with <> (so like <&>) can be used for logical AND, mixing both is not possible! If more than one category= line is specified, their arguments are implicitly connected with AND. Thus, a logical expression can be built using several AND terms, with each term consisting of an OR group of categories.

Important: the category command uses the pipe | symbol to delimit its arguments (logical OR). When using DPL3 with the parser function syntax (the more powerful syntax), the pipe symbol must be escaped either by using the broken pipe ¦ symbol, or the magic word {{!}}.

Example:

This lists pages in the category Countries in Africa OR Countries in United Kingdom, AND are in Part of NATO.

Code

<dpl>
 category = Countries in Africa|Countries in United Kingdom
 category = Part of NATO
</dpl>

 or

{{#dpl:
|category = Countries in Africa¦Countries in United Kingdom
|category = Part of NATO
}}

 or

{{#dpl:
|category = Countries in Africa{{!}}Countries in United Kingdom
|category = Part of NATO
}}

Result

• England

or

• England

or

• England

Test in sandbox

View Result

Notes:

• A set of Uncategorized pages can be specified as a normal category, with the keyword _none_, for example:
  • category=_none_ for uncategorized pages only.
  • category=_none_¦Animals or namespace=Animals¦_none_ for the Uncategorized or the Animals category.
  • category=Mammals¦_none_¦Insects for the Mammals category, uncategorized pages or the Insects category.

• If * is put before the name of a category, DPL3 adds all DIRECT subcategories of that category to the statement.
• Using TWO asterisks ( ** ) extends the tree search to two levels. This provides some minimal support for hierarchies of categories. The syntax and/or semantics of this feature might be changed in a future version.

In some special cases (when DPL3 queries refer to 'uncategorized pages') DPL3 needs a special database view (dpl_clview) in the MySQL database.

Example:

This lists pages in the category Countries in Europe OR Countries in North America, AND are in the category Part of NATO or a direct subcategory or second level subcategory of the latter, with results limited to a count of 4.

Code

{{#dpl:
|category = Countries in Europe¦Countries in North America
|category = *Part of NATO
|count    = 4
}}

Result

• England
• Finland
• Canada
• United States

Test in sandbox

View Result

If ordermethod=category,... and headingmode= are enabled, categories output as headings in the result can be restricted by preceding the list of categories (specified with the category parameter) with + or -:

• + – Only the categories listed in the statement are allowed to appear as headings in the output.
• - – The categories listed in the statement are NOT allowed to appear as headings in the output (but all others).

Example:

This lists pages in category Countries in Europe OR Countries in North America, or a direct subcategory or a second level subcategory of the latter. The list headingmode is ordered (ol tag for numbers) in two main headings (matching the categories specified). Under each heading is a sublist of pages ordered by category,pagetouched using ordermethod.

Code

{{#dpl:
|category        = +Countries in Europe¦Countries in North America
|headingmode     = ordered
|ordermethod     = category,pagetouched
}}

Result

1. Countries in Europe
   • Finland
   • England
2. Countries in North America
   • United States
   • Canada

Test in sandbox

View Result

Notes:

• To use magic words in the category name, the parser function syntax method must be used.
• To prevent a DPL3 query from returning huge output (or consuming too many resources) there are some configuration variables, for related configuration settings also see the complete list of DynamicPageList3 configuration variables.
• Using the category statement without an argument will have no effect (note that in previous DPL3 versions, this acted like category=_none_).

categorymatch

categorymatch

Selects articles based on categories. One or more patterns can be specified (SQL LIKE); a page is selected if at least one of its categories matches at least one of the patterns.

Syntax:

categorymatch=1st category pattern¦...

% is used to denote "any number of any characters".

Example:

This lists pages that end in "Europe" or "North America" that belong to categories matching (categorymatch) Countries in Europe or Countries in North America etc., limited to a count of 3 results.

Code

{{#dpl:
|categorymatch = %Europe¦%North America
|count         = 3
}}

Result

• Canada
• Finland
• United States

Test in sandbox

View Result

categoryregexp

categoryregexp

Selects pages with a category matching a regular expression.

The complete text behind "categoryregexp" is taken as one argument and used in a SQL REGEXP clause (i.e., | characters can be used as a normal part of the regexp).

Note: If you are not familiar with regular expressions and/or do not know the specifics of Perl regexp used in PHP, it may be helpful to see:

• The PHP manual and W3Schools for more information.
• RegExr for testing regular expressions.

notcategory

notcategory

Much like the category parameter, but requires that every page listed not be in a particular category. Unlike in the category parameter, categories cannot be combined using logical OR, only one criterion can be specified per line.

Syntax:

notcategory=category name

Example:

This lists pages that belong to category Countries in Europe but notcategory NATO membership debates or other example categories.

Code

{{#dpl:
|category    = Countries in Europe
|notcategory = NATO membership debates
|notcategory = Another example category
}}

Result

• England

Test in sandbox

View Result

Notes:

• To use magic words in the category name, the parser function syntax method must be used.
• There are some related configuration variables, also see the complete list of DynamicPageList3 configuration variables.

notcategorymatch

notcategorymatch

Works like notcategory but based on SQL LIKE.

notcategoryregexp

notcategoryregexp

Works like notcategory but based on SQL REGEXP.

Note: If you are not familiar with regular expressions and/or do not know the specifics of Perl regexp used in PHP, it may be helpful to see:

• The PHP manual and W3Schools for more information.
• RegExr for testing regular expressions.

categoriesminmax

categoriesminmax

Restricts article selection to those assigned to at least [min] categories, and/or at most to [max] categories.

Syntax:

categoriesminmax=[min],[max] where min and max are each a desired number.

Example:

The lists pages in category Countries in Europe and at least 3 other categories, for a total of 4 minimum as set in the min position of categoriesminmax argument syntax. Note the parameter name's ending, minmax, provides an order reminder for specifying arguments [min],[max]. Either parameter is optional, but their position must be held appropriately using a , comma (if the first value is not set).

Code

{{#dpl:
|category         = Countries in Europe
|categoriesminmax = 4
}}

Result

• England

Test in sandbox

View Result

Example:

This lists pages in the category Countries in Europe that are only assigned to 2 other categories, for a maximum of 3 categories. The first categoriesminmax argument for minimum (or min) is left blank, meaning no minimum applies, and just the last (comma separated) argument specifying the maximum is applied. Alternatively, both a min and a max value could be specified if desired.

Code

{{#dpl:
|category         = Countries in Europe
|categoriesminmax = ,3
}}

Result

• Finland

Test in sandbox

View Result

Select articles based on NAMESPACES

namespace

namespace

Restricts article selection to the given namespace(s).

Syntax:

namespace=1st_namespace_name¦2nd namespace_name¦3rd_namespace_name¦...

Notes:

• The namespace name may be any, 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.
• The empty string is the main article namespace. This behavior may be removed in future versions, so explicitly specifying namespace=Main is recommended. For example:

• namespace= for pages in Main namespace only, but namespace=Main is preferred.
• namespace=User¦¦Category for User, Main, or Category, but namespace=User¦Main¦Category is preferred.

• Name spaces are case-sensitive, namespace=User_talk works, but namespace=User_Talk does not.
• Instead of using the title of a namespace its numeric ID can be used, although this is not recommended; DPL3 always tries to interpret the argument as a name first. So, if a user namespace is created with the title "1" (which is possible in principle) DPL3 takes this namespace if given a "1" as an argument. In this case, the "Talk" namespace (which has the numeric ID "1") cannot be specified by its number, but only by the literal "Talk".

Example:

This output pages in the Talk OR Help talk namespace, that belong to the category Number examples.

In DPL3 (versions older than 4.0.0), namespaces with spaces in their name (such as "Help talk") requires replacing the space with an underscore — e.g. "Help_talk". If you use a space instead, inclusions and exclusions won't work as expected, and pages like Help talk:Three are not included/excluded. This is due to MediaWiki namespaces internally using underscores. This is not an issue in DPL4 4.0.0 and later, where spaces in namespace names are handled correctly.

Code

{{#dpl:
|category  = Number examples
|namespace = Talk¦Help talk
}}

Result

• Help talk:Three
• Talk:Four

Test in sandbox

View Result

Example (with magic word):

This lists pages in the namespace the current page is in – in this case the Main namespace – and that belong to category Number examples.

Code

{{#dpl:
|category  = Number examples
|namespace = Main
}}

Result

• One
• Two
• Five
• ThirtyTwo
• ThirtyOne

Test in sandbox

View Result

notnamespace

notnamespace

Much like the notcategory parameter, but for namespaces. Restricts article selection to those not in the given namespace(s).

Syntax:

notnamespace=namespace_name

Example:

Namespaces have underscores in their proper names. In DPL3 (versions older than 4.0.0), when excluding a namespace that contains a space (such as Help talk), you must replace the space with an underscore — e.g. Help_talk. Using a space instead causes different results and the exclusion will not behave as expected. This is fixed in DPL4 4.0.0 and later, where spaces in namespace names are handled correctly for exclusions.

This lists pages from the category Number examples that are neither in the Talk namespace nor the Help talk namespace (by listing each using notnamespace). The results are limited to a count of 3.

Code

{{#dpl:
|category     = Number examples
|notnamespace = Talk
|notnamespace = Help talk
|count        = 3
}}

Result

• One
• Two
• Five

Test in sandbox

View Result

Example (with magic word):

This list pages in the category Number examples that are neither in the Talk namespace, nor the Main namespace using notnamespace and listing each one after the other.

Code

{{#dpl:
|category     = Number examples
|notnamespace = Talk 
|notnamespace = Main
}}

Result

• Help talk:Three
• Category:Digit-related examples

Test in sandbox

View Result

Select articles based on LINKS

linksfrom

linksfrom

Selects articles that are referenced/linked from at least one of the specified pages.

Syntax:

linksfrom=full page name¦...'

Example:

This lists pages in category Number examples that are mentioned (hyperlinked) in page Five (using linksfrom). Results are limited to a count of 5.

Code

{{#dpl:
|category  = Number examples
|linksfrom = Five
|count = 5
}}

Result

• Two

Test in sandbox

View Result

Notes:

• Normally linksfrom only shows existing pages. With openreferences=yes this can be changed.
• The distinct parameter can be used to control the amount of output received.
• The page mentioned in the DPL3 query can be retrieved via %PAGESEL% variable.

openreferences

openreferences

Extends linksfrom to unresolved references (non-existing articles or image links). Implicitly sets ordermethod=none if set to yes or missing. Most DPL3 parameters depend on the existence of a page. If openreferences is set, none of those parameters can be used. Examples of conflicting parameters are all parameters related to categories, revisions, authors, redirections, and some other parameters.

Syntax:

openreferences=criteria where criteria can be one of:

• yes – Pages that do not exist are included – conflicts with some options; implicitly sets ordermethod=none.
• missing – Only includes pages that do not exist from missing articles in the pagelinks table; conflicts with some options. Implicitly sets ordermethod=none.

• This option may be useful to create a list of wanted pages (redlinks) (e.g., wanted pages for a specific namespace).

• no – Pages that do not exist are excluded – (default, need not be specified).

Example:

This lists any page that linksfrom the Apple page, regardless of whether the page(s) exist or not, and even non-existing articles or image links are included by specifying openreferences).

Code

{{#dpl:
|linksfrom      = Apple
|openreferences = yes
}}

Result

• Category:Fruit examples
• Non-existing page
• Apricot

Test in sandbox

View Result

notlinksfrom

notlinksfrom

Selects articles that are NOT referenced/linked from any of the specified pages.

Syntax:

notlinksfrom=full page name¦...

Similar to linksfrom the {{FULLPAGENAME}} magic word could be used, to not include any pages linked to from the current page; however this generally results in errors.

linksto

linksto

Selects articles that link to at least one of the specified pages.

Syntax:

linksto=full page name¦...

Notes:

• % can be used as a wildcard (SQL LIKE expression).
• If more than one criterion is specified, they act as a logical AND. In this case, the %PAGESEL% variable points to the first condition.
• %PAGESEL% can be used to display the name of the page linking to the criteria specified.
• If two criteria are set, and a result links to both, the result appears twice in the output.
  • The distinct parameter can be used to control the amount of output received.

Example:

This lists any page in the category Number examples that linksto pages whose name starts with Tw (e.g., pages that link to page Two, but not to ThirtyTwo) that are in the Main namespace (by default). To make the comparison case-insensitive, the parameter ignorecase is used.

Code

{{#dpl:
|category = Number examples
|linksto  = Tw%
}}

Result

• One
• Five

Test in sandbox

View Result

Example (with magic word):

This lists any page in category Number examples, that linksto the current page (the full namespace is included due to the {{FULLPAGENAME}} magic word).

Code

{{#dpl:
|category = Number examples
|linksto  = {{FULLPAGENAME}}
}}

Result

• Help talk:Three

View Result

notlinksto

notlinksto

Selects articles that do NOT link to any of the specified pages.

Syntax:

notlinksto=full page name¦...

Example:

This lists pages in the category Number examples having no link(s) pointing to (notlinksto) pages named Two or Five. Results are limited to a count of 5.

Code

{{#dpl:
|category   = Number examples
|notlinksto = Two¦Five
|count      = 5
}}

Result

• Help talk:Three
• Talk:Four
• Two
• ThirtyTwo
• ThirtyOne

Test in sandbox

View Result

Notes:

• The implementation of this feature is not very efficient. Use with care and avoid huge result sets.
• The distinct parameter can be used to control the amount of output received.

linkstoexternal

linkstoexternal

Selects articles that contain an external link that matches a given text pattern.

Syntax:

linkstoexternal=text pattern¦...

This command selects pages which contain external HTTP links that match a certain pattern. The pattern is used in SQL LIKE expression, i.e., _ and % are treated as special symbols that match any character respecting a group of arbitrary characters.

Notes:

• The pattern is case-sensitive.
• The pattern is matched against the whole URL. Therefore, % is required around the pattern if only part of a string is given:

linkstoexternal=%mywebpage%

• If more than one linkstoexternal parameter is specified, articles must match all conditions (logical AND).
• The URL of the external link can be retrieved via %EXTERNALLINK%.
• See also the addexternallink parameter.

imageused

imageused

Selects articles that use a certain image.

Syntax:

imageused=image name¦...

The Namespace "File" need not be specified.

Example:

This lists pages with imageused being either "Red Apple Fruit With Black Background.jpeg" OR "Grapes on White Table.jpeg", with the result count limited to 3.

Code

{{#dpl:
|imageused = Red Apple Fruit With Black Background.jpeg¦Grapes on White Table.jpeg
|count     = 3
}}

Result

• Images used (examples)
• Controlling output format
• Controlling output volume

Test in sandbox

View Result

Note: There is a variable %IMAGESEL% which contains the image name(s) used for selection.

imagecontainer

imagecontainer

Select images that are contained in one or more articles.

Syntax:

imagecontainer=page name¦...

Normally setting openreferences to true lists non-existing images, including those not housed locally, such as images used from Wikimedia Commons; however, currently this function may cause errors that prevent a page from being saved.

Example:

This displays images contained (displayed, using imagecontainer) within the Apple page. Setting escapelinks=false causes direct image display (at full-size), rather than a file page link. Setting mode=none removes the default (bulleted list) formatting, displaying the image plain. Note that using format may give greater output control (see Images used (examples)).

Code

{{#dpl:
|imagecontainer = Apple
|escapelinks    = false
|mode           = none
}}

Result

Test in sandbox

View Result

See: Images used (examples) for more image-related examples.

Select articles based on the use of TEMPLATES

uses

uses	Selects articles that use (transclude) at least one of the specified templates (wiki syntax: {{...}}).

Syntax:

uses=Template:name¦Template:...

The "Template" namespace must be specified, or other namespaces can be specified.

Example:

This lists any page that uses the Template:Fruit-Infobox, limited to 3 results using count.

Code

{{#dpl:
|uses  = Template:Fruit-Infobox
|count = 3
}}

Result

• Controlling output volume
• Apple
• Grape

Test in sandbox

View Result

Note: It is not possible to find pages that use two templates (e.g., Template:Foo AND Template:Bar).

notuses

notuses

Selects articles that do not use any of the specified templates. Caution: The implementation of this feature is not very efficient. Use with care and avoid huge result sets.

Syntax:

notuses=Template:name¦Template:...

Example:

This list pages in category Fruit examples which does not use (notuses) Template:Color. If no results are found (noresultsheader), then No pages found appears. Results are limited to a count of 3.

Code

{{#dpl:
|category        = Fruit examples
|notuses         = Template:Color
|noresultsheader = \n ''No pages found''
|count           = 3
}}

Result

• Orange
• Plum
• Banana

Test in sandbox

View Result

usedby

usedby

Selects articles (templates) that are used (transcluded) by a specified page.

Syntax:

usedby=page

Example:

This lists pages usedby the Apple page. Results are limited to a count of 5.

Code

{{#dpl:
|usedby = Apple
|count = 5
}}

Result

• Template:Navigation
• Template:Previous
• Template:Next
• Template:Fruit-Infobox
• Template:Color

Test in sandbox

View Result

Select articles based on authors / editors

createdby

createdby

Selects articles that were created by the specified user. Warning: This keyword can result in very slow and inefficient queries on your MediaWiki system, potentially impacting performance for all users (see bug report).

Syntax:

createdby=username

Notes: (applies for all user related selection criteria):

• User related selections can be combined. For example, pages which were not created by user1 but modified by them could be specified, or pages which were created by user1 and lastmodifiedby user2 could be specified.
• Several or all versions of articles can be shown by specifying one or more of the "revision" group of parameters, like allrevisionsbefore.

notcreatedby

notcreatedby

Selects articles that were not created by the specified user. Warning: This keyword can result in very slow and inefficient queries on your MediaWiki system, potentially impacting performance for all users (see bug report).

Syntax:

notcreatedby=username

Note: To avoid huge result sets, this is typically accompanied by other selection criteria.

modifiedby

modifiedby

Selects articles that were created or at least once modified by the specified user.

Syntax:

modifiedby=username

Note: modifiedby is always a superset of createdby as the creation of a page is interpreted as its first modification.

notmodifiedby

notmodifiedby

Selects articles that were not (created or) modified by the specified user.

Syntax:

notmodifiedby=username

Note: To avoid huge result sets, this is typically accompanied by other selection criteria.

lastmodifiedby

lastmodifiedby

Selects articles where the last modification was done by the specified user.

Syntax:

lastmodifiedby=username

notlastmodifiedby

notlastmodifiedby

Selects articles where the last modification was not done by the specified user.

Syntax:

notlastmodifiedby=username

Note: To avoid huge result sets, this is typically accompanied by other selection criteria.

Select articles based on TITLE

There are several possibilities to select articles by their title. When the titles of matching articles are displayed later in the output list, their names can be shown in different ways: The namespace may be shown or skipped and even parts of the name can be changed. See shownamespace, replaceintitle, escapelinks and titlemaxlength for details.

title

title

Select one single page by its (namespace and) title, sets mode=userformat giving no output by default, and requires an include statement. For single page selection see include notes. This parameter's behavior is different from most other selection criteria, it is primarily useful for including/transcluding contents from one specific page.

Syntax:

title=pagetitle

Given its unique behavior, specifying an exact "title" makes sense if transcluding (including) contents from one specific page is desired. E.g., All content, a page section, labeled sections, or template calls of one page. Thus, DPL may serve as a more flexible alternative to Labeled Section Transclusion.

Using this parameter causes the following:

• mode=userformat is automatically set, causing no output to be given by default until specified.
• Some type of include= statement must be specified to get output.
  • The content can be presented as-is directly from the include statement, or the output can be formatted:
    • By setting format= arguments.
    • By using other types of formatting (or a combination of compatible formatting types).
    • By specifying a surrogate template.
  • Specified formatting affects if article title is displayed, is repeated, and/or if results appear separated or grouped.
    • If there is more than one section with the same name, the contents of each are displayed one after the other.
    • When content is formatted using table, by default each result with the same name appears in a separate row with a separate heading, as can be seen in the example for including page sections.
  • The %SECTION% variable can be used, but only in secseparators, to retrieve page section/chapter heading text.

Example:

This example selects the page with the title Apple in the Main namespace (by default), and includes (using include) the contents of the page's Notes section heading in the result.

Code

{{#dpl:
|title   = Apple
|include = #Notes
}}

Result

There are multiple varieties of apples; thus apples can be different colors.

Apples can also be green.

Apples skins contain more fiber than the rest of an apple.

Test in sandbox

View Result

titlelt (Previously title<)

titlelt

Restrict the selection to articles with a title less or equal to a given value.

Syntax:

titlelt=string

The string given need not be a valid page title.

This parameter was standardized to titlelt and it is recommended to switch instances to the new wording. For compatibility purposes, title< continues to work.

Example:

This selects page titles to the left of (titlelt), or before, the Chocolate Cake article in category Dessert examples. The format statement formats the output into a plain page title link (with no list style), and the result count is limited to 1 to ensure only the one (previous) page from the category is returned.

Code

{{#dpl:
|titlelt  = Chocolate Cake
|category = Dessert examples
|format   = ,[[%PAGE%|%TITLE%]]
|count    = 1
}}

Result

Apple Pie

Test in sandbox

View Result

Notes:

• It may be helpful to remember:
  • The last two letters of titlelt ("lt") correspond to letters in "left", so result(s) to the left of the article specified are returned.
• This parameter may allow efficient navigation between pages in the same category or result set, or large result sets.
• In DPL3 parser function syntax method:
  • titlelt could be set to {{PAGENAME}}, a count of one, and used to compose a left/previous navigation.
  • titlegt could be set to {{PAGENAME}}, a count of one, and used to compose a right/next navigation.
• For other methods of scrolling navigation between items in a category, that makes implicit use of this parameter, see scrolling.

Combined (multipart) Result:
The navigation template is used on a page and passes the Fruit examples category name as follows:

Code

{{navigation|category=Fruit examples}}

Result

Banana

Fruit examples

Grape

Test in sandbox

View Result

titlegt (Previously title>)

titlegt

Restrict the selection to articles with a title greater or equal to a given value.

Syntax:

titlegt=string

The string given need not be a valid page title.

This parameter was standardized to titlegt and it is recommended to switch instances to the new wording. For compatibility purposes, title> continues to work.

Example:

This selects the pages whose title is to the right of (titlegt), or after, the Chocolate Cake page, that appear in category Dessert examples. The format statement formats the output into a plain page title link, and the count is set to 1 to ensure only the (one) or next page is returned.

Code

{{#dpl:
|titlegt  = Chocolate Cake
|category = Dessert examples
|format   = ,[[%PAGE%|%TITLE%]]
|count    = 1
}}

Result

Raspberry Ice Cream

Test in sandbox

View Result

Notes:

• It may be helpful to remember:
  • The last two letters of titlegt ("gt") correspond to letters in "right", so result(s) to the right of the article specified are returned.
• This parameter may allow efficient navigation between pages in the same category or result set, or large result sets.
• In DPL3 parser function syntax method:
  • titlegt could be set to {{PAGENAME}}, a count of one, and used to compose a right/next navigation.
  • titlelt could be set to {{PAGENAME}}, a count of one, and used to compose a left/previous navigation.
• For other methods of scrolling navigation between items in a category, that makes implicit use of this parameter, see scrolling.

titlematch

titlematch

Select articles with a title matching at least one of the specified patterns. The patterns are used as a LIKE argument in an SQL query. Namespaces are ignored, as the namespace parameter can be used to further narrow the selection.

Syntax:

titlematch=pattern¦...

Example:

This lists all pages (regardless of namespace) whose titlematch contains "pple" OR "Oran", with results limited to a count of 5.

Code

{{#dpl:
|titlematch = %pple%¦Oran%
|count      = 5
}}

Result

• Orange
• Apple Pie
• Apple
• File:Red Apple Fruit With Black Background.jpeg

Test in sandbox

View Result

Example:

This lists all pages in the namespace Main which have a titlematch beginning with "Apple" (and ending with anything due to % use at the end).

Code

{{#dpl:
|namespace  = Main
|titlematch = Apple%
}}

Result

• Apple
• Apple Pie

Test in sandbox

View Result

Notes:

• Can be used without % to query a single page, since the title parameter operates as full page transclusion and cannot be used for single page selection.
• The match is case-sensitive, even regarding the first character; to make it case-insensitive, use the parameter ignorecase.
• Spaces are translated to \_ (escaped underscore) as MediaWiki internally stores names with underscores instead of spaces. Using an underscore in your titlematch argument means 'any single character' in SQL LIKE expressions.

titleregexp

titleregexp

Select articles with a title matching the specified regular expressions. The pattern is used as a REGEXP argument in a SQL query. Namespaces are ignored, as the namespace parameter can be used to further narrow the selection.

Syntax:

titleregexp=regular expression

Example:

This lists pages (regardless of namespace) that have an "A" in their name and end with an "e" (using titleregexp). Results are limited to a count of 3. Note that the ignorecase parameter can be used to make the comparison case-insensitive.

Code

{{#dpl:
|titleregexp = [A]+.*e$
|count       = 3
}}

Result

• Apple Pie
• Apple

Test in sandbox

View Result

Note: If you are not familiar with regular expressions and/or do not know the specifics of Perl regexp used in PHP, it may be helpful to see:

• The PHP manual and W3Schools for more information.
• RegExr for testing regular expressions.

nottitlematch

nottitlematch

Select articles with a title not matching any of the specified patterns. The patterns are 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:

nottitlematch=pattern¦...

Example:

This lists pages in category Fruit examples (regardless of namespace), where the title does not match (nottitlematch) pages with a "p" or a "r" in their title (it does not exclude titles containing "P" or "R" because it is case-sensitive). The result count is limited to 3.

Code

{{#dpl:
|category      = Fruit examples
|nottitlematch = %p%¦%r%
|count         = 3
}}

Result

• Grape
• Orange
• Plum

Test in sandbox

View Result

nottitleregexp

nottitleregexp

Select articles with a title that does not match the specified regular expression. The pattern is used as a REGEXP 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:

nottitleregexp=regular expression

Note: If you are not familiar with regular expressions and/or do not know the specifics of Perl regexp used in PHP, it may be helpful to see:

• The PHP manual and W3Schools for more information.
• RegExr for testing regular expressions.

Select articles based on CONTENTS

includematch

includematch

Controls the selection of articles based on the content that is included from them.

Syntax:

includematch=regexp1,regexp2,...

This option only works with the output of include. A page is only selected (and its contents included) if the contents to be included matches a regular expression. In the case of (heading based) chapter inclusion and labeled section inclusion, the relevant contents of the page must match the pattern; in the case of template based matching it is the complete wikitext of the calling code of your template which is tested against your regular expression. Be careful to design your regexp in a proper way so that it can match all syntactical variations, and note that we use Perl regular expressions. This means that the regexp must be delimited with two identical characters that are not part of the regexp itself, e.g., with /. Otherwise, strange error messages are given from the PHP interpreter.

Note: If you are not familiar with regular expressions and/or do not know the specifics of Perl regexp used in PHP, it may be helpful to see:

• The PHP manual and W3Schools for more information.
• RegExr for testing regular expressions.

For named parameters something like this should be used, to be on the safe side:

includematch = /\{{!}}\s*myParameter\s*=\s*myPattern/s

• Thus, spaces can be put around the = and line breaks used in the original article when calling the template – and the pattern will still match.
• Note: {{!}} must be used to produce a pipe symbol – otherwise the pipe breaks the parameter structure of the DPL call.

For unnamed parameters something like the following could be specified

includematch = /\{{!}}\s*myPattern/s

If the parameter is not the last one in the template call, this might be used:

includematch = /\{{!}}\s*myPattern\s*\{{!}}/s

See the include parameter.

Example:

This lists pages in the category Fruit examples, in the namespace Main, which contain (include) a call to the template Fruit-Infobox and with a grow parameter of that template (using includematch) to restrict results to those whose parameter value contains "Vines" or "vines" as a text string. The include parameter also includes the page name by default in the output, and the grows parameter value. The table parameter is then used to format the results into a (simple) table.

• There is no pattern specified for the first element of the include statement. "VINES" would not match; the "i" modifier could be used with the regexp to match without case sensitivity if desired.

Code

{{#dpl:
|category     = Fruit examples
|namespace    = Main
|include      = {Fruit-Infobox}:grows
|includematch = /grows\s*=\s*[^¦]*[Vv]ines/s
|table        = class="wikitable", Page, Growth Area
}}

Result

Page	Growth Area
Grape	On vines

Test in sandbox

View Result

Note(s):

• In combination with templates, the regexp matching only works if some output is produced via the include statement. So, if a dummy parameter only is called, or a surrogate/phantom template is called that does not produce any output, no matches are seen. It is, however, sufficient to produce a space character to get output. It is not necessary to output the parameter which matches your regexp.
• Remember, the pipe | must be replaced with either broken pipe ¦ or {{!}}, or with in [^¦] when parser function {{#dpl:}} syntax is used, or the statement won't work because the pipe would be mistaken as a field delimiter for #dpl itself, and break the parameter structure of the DPL3 call.

To stop the pattern matching at field boundaries (i.e., at pipe characters) something such as this might be used:

Parser function syntax (note that broken pipe ¦ is used).

includematch = /languages\s*=\s*[^¦]*English/s

Parser extension syntax (note that regular pipe | is used).

includematch = /languages\s*=\s*[^|]*English/s

Example:

This lists pages in the category Countries in North America, which contain (include) a call to the template "Country-Infobox" and uses the "capital" parameter of that template (using includematch) with an argument that contains "Ottawa" as a text string. The include parameter also includes the page name by default in the output, and the "capital" parameter value. The table parameter is then used to format the results into a (simple) table.

It would stop pattern matching after the line containing |capital=Ottawa. This example is formatted as a (simple) table using the table parameter.

Code

{{#dpl:
|category     = Countries in North America
|include      = {Country-Infobox}:capital
|includematch = /capital\s*=\s*[^¦]*Ottawa/s
|table        = class="wikitable sortable",Page,Capital
}}

Result

Page	Capital
Canada	Ottawa

Test in sandbox

View Result

includematchparsed

includematchparsed

Controls the selection of articles based on (pre-parsed) contents that is included from them.

Works exactly like includematch but the contents are parsed before it is tested against the regular expression.

includenotmatch

includenotmatch

Controls the selection of articles based on contents that is included from them.

Syntax:

includenotmatch=regexp1,regexp2,...

The idea is that a page is only selected (and its contents included) if the contents to be included does not match a given regular expression. In the case of (heading based) chapter inclusion and labelled section inclusion, the relevant contents of the page must not match the pattern; in the case of template based matching, it is the calling code of the template which must not match the regular expression. Be careful to design the regexp in a proper way, so it covers all syntactical variations. Something like the following should be used to be on the safe side:

includenotmatch = myParameter\s*=\s*myPattern/s

Thus, spaces can be put around the = and line breaks used in the original article when calling the template – and still, the pattern will do its job.

See the include parameter.

Example:

This lists pages in the category Countries in North America, which contain (include) a call to the template "Country-Infobox" and uses the "capital" parameter of that template (using includematch) with an argument that contains "Ottawa" or "ottawa" as a text string. The include parameter also includes the page name by default in the output, and the "capital" parameter value. The table parameter is then used to format the results into a (simple) table.

Note that there is no pattern specified for the first element of the include statement. "OTTAWA" would not match; we could use the "i" modifier with the regexp to match without case sensitivity if desired.

Code

{{#dpl:
|category        = Countries in North America
|include         = {Country-Infobox}:capital
|includenotmatch = /capital\s*=\s*[^¦]*[Oo]ttawa/s
|table           = class="wikitable sortable",Country,Capital
}}

Result

Country	Capital
United States	Washington, D.C.

Test in sandbox

View Result

Note: If you are not familiar with regular expressions and/or do not know the specifics of Perl regexp used in PHP, it may be helpful to see:

• The PHP manual and W3Schools for more information.
• RegExr for testing regular expressions.

includenotmatchparsed

includenotmatchparsed

Controls the selection of articles based on (pre-parsed) contents that are included from them.

Works exactly like includenotmatch but the contents are parsed before it is tested against the regular expression.

Select articles based on REVISION dates

By default, DPL uses "Y-m-d H:i:s" to display date and time. Note that MediaWiki stores all dates/times in UTC format. When displaying a time stamp, DPL translates it according to:

1. The timezone preference (difference to UTC/GMT) given by the user in user settings.
2. If no preference is given, and for all anonymous users, the local time on the server is used.

So, either a time based on the user's local time (browser based), or based on the timezone in which the wiki server is running is seen.

The same kind of translation applies to dates specified when selecting articles by revision date/time.

lastrevisionbefore

lastrevisionbefore

Selects articles that existed before the specified date, and displays the last revision before that date (this latter date can be accessed using the REVISION variable in mode=userformat).

Syntax:

lastrevisionbefore=dateandoptionaltime where dateandoptionaltime is a numeric string of up to 14 digits, like "200812041300" (4th of Dec., 2008, 13:00).

The string may contain separation characters like "2008/12/04--13:00".

Note: If this parameter is used, the variable %REVISION% contains/returns the revision of the selected page(s).

firstrevisionsince

firstrevisionsince

Selects articles that had a revision created after the specified date, and displays that revision date (this latter date can be accessed using the REVISION variable in mode=userformat).

Syntax:

firstrevisionsince=dateandoptionaltime where dateandoptionaltime is a numeric string of up to 14 digits, like "200812041300" (4th of Dec., 2008, 13:00).

The string may contain separation characters like "2008/12/04--13:00".

Note: if this parameter is used, the variable %REVISION% contains/returns the revision of the selected page(s).

allrevisionsbefore

allrevisionsbefore

Shows all revisions that existed before the specified date. The date of each revision is shown (and is available as REVISION in mode=userformat).

Syntax:

allrevisionsbefore=dateandoptionaltime where dateandoptionaltime is a numeric string of up to 14 digits, like "200812041300" (4th of Dec., 2008, 13:00).

The string may contain separation characters like "2008/12/04--13:00".

Note: if this parameter is used, the variable %REVISION% will contain the revision of the selected page(s).

allrevisionssince

allrevisionssince

Shows all revisions that were created after the specified date. The date of each revision is shown (and is available as REVISION in mode=userformat). If there was no new revision of an existing article after the specified date, that article will not appear in the output.

Syntax:

allrevisionssince=dateandoptionaltime where dateandoptionaltime is a numeric string of up to 14 digits, like "200812041300" (4th of Dec., 2008, 13:00).

The string may contain separation characters like "2008/12/04--13:00".

Note: if this parameter is used, the variable %REVISION% will contain the revision of the selected page(s).

Example:

This lists pages in category Fruit examples, in the namespace Main, which have a revision since (via allrevisionssince) of the 1st of April 2022. The result count is limited to 2. The revision date and time are listed first by default, then the page name, linked to the revision.

Code

{{#dpl:
|category          = Fruit examples
|namespace         = Main
|allrevisionssince = 2022-04-01
|count             = 2
}}

Result

• 2025-09-07 18:44:10 Apricot
• 2025-09-07 18:40:57 Apricot

Test in sandbox

View Result

maxrevisions

maxrevisions

Shows an article (or its revisions) only if its number of revisions are less than the value specified.

Syntax:

maxrevisions=number where number must be greater than or equal to 1.

minrevisions

minrevisions

Shows an article (or its revisions) only if its number of revisions are greater than the value specified.

Syntax:

minrevisions=number where number must be greater or equal than 1.

In practice, only values of 2 or greater make sense. Using a value of 2, freshly created pages could be excluded from a result set.

Select articles based on OTHER criteria

articlecategory

articlecategory

Selects a talk page based on the corresponding base article (in the default namespace) category.

Syntax:

articlecategory= categoryname

To select articles in namespace=Talk this statement could be used to define (in addition) a category for an article with an identical name in namespace 0 (default namespace).

includesubpages

includesubpages

Controls the inclusion or exclusion of pages which have a '/' in their name. The default is true.

Syntax:

includesubpages=false

As subpages are by default always included, only no or false makes sense as an argument for includesubpages.

redirects

redirects

Controls the inclusion or exclusion of redirect pages in the output. By default, redirections are not shown.

Syntax:

redirects=criteria where criteria can be one of:

• include – Redirect pages are allowed in lists.
• only – Lists only redirect pages in lists.
• exclude – Redirect pages are excluded from lists – (default, need not be specified).

Example:

This lists pages in category Countries in North America and specifies redirects as included (the page US is a redirect to the United States page). Results are limited to a count of 3.

Code

{{#dpl:
|category  = Countries in North America
|redirects = include
|count     = 3
}}

Result

• Canada
• United States
• US

Test in sandbox

View Result

Note: this parameter does not show pages that link to the redirect (as Special:Whatlinkshere/United States does); only redirect pages themselves.

minoredits

minoredits

Controls the inclusion or exclusion of minor edits in output. Requires ordermethod=[...]firstedit¦lastedit.

Example:

minoredits=criteria where criteria can be one of:

• exclude – Minor edits are excluded from lists.
• include – Minor edits are included in lists – (default, need not be specified)

Example:

This lists pages in category Countries in North America, with its ordermethod set to lastedit, but with minoredits ignored in the ordering. Results are restricted to a count of 3.

Code

{{#dpl:
|category    = Countries in North America
|ordermethod = lastedit
|minoredits  = exclude
|count       = 3
}}

Result

• Canada
• United States

Test in sandbox

View Result

stablepages

stablepages

Controls the inclusion or exclusion of pages which are flagged as 'stable'.

Syntax:

stablepages=criteria where criteria can be one of:

• exclude – Stable pages are excluded from lists.
• only – Only stable pages appear in lists.
• include – Stable pages appear in lists – (Default, need not be specified).

Note: This parameter is only useful if the wiki uses FlaggedRevs; it controls whether the pages flagged as 'stable' are part of the DPL result or not.

qualitypages

qualitypages

Controls the inclusion or exclusion of pages which are flagged as 'quality pages'.

Syntax:

qualitypages=criteria where criteria can be one of:

• exclude – Quality pages are excluded from lists
• only – Only quality pages appear in lists.
• include – Quality pages are included in lists – (default, need not be specified)

Purpose: This parameter is only useful if the wiki uses FlaggedRevs. It controls whether pages flagges as 'quality pages' are part of the DPL result or not.

skipthispage

skipthispage

Includes the page containing the DPL query in the result set (self reference, which is excluded by default).

Syntax:

skipthispage=no – (default is yes, need not be specified and may cause problems if specified).

Notes:

• The source page of the query is not included in the result set by default, even if it meets the query's criteria.
• Setting this parameter to no may lead to runtime errors which are hard to track down. This value should only be used if the query is straightforward in structure, and the current page is required in the result set (if it matches the selection criteria).

Restrict the output (selection) volume

count

count

Controls the number of results shown.

Syntax:

count=n, where n is a positive integer.

Notes:

• DPL3 limits the result count to 500 by default for performance reasons, this can be changed depending on extension configuration variables:
  • $wgDplSettings['maxResultCount'] – Query result number maximum limit.
  • $wgDplSettings['allowUnlimitedResults'] – Allow unlimited query results, which may result in slow or failed page loads.
    • A blank value (count=) sets results to unlimited, which may also result in slow or failed page loads.
• See DynamicPageList3 more information on all configuration variables.
• Count can also be set or overridden from outside a DPL3 query, by using the URL parameter DPL_count.

Example:

This list pages in category Fruit examples, with ordermethod set to pagetouched, which includes the pages most recently changed. Results are limited to a count of 2.

Code

{{#dpl:
|category    = Fruit examples
|ordermethod = pagetouched
|count       = 2
}}

Result

• Orange
• Plum

Test in sandbox

View Result

scroll

scroll

Enables built-in support for scrolling through large result sets, allowing them to be split into smaller result sets.

Syntax:

scroll=yes – (default is no which need not be specified, it only makes sense to set yes when required).

DPL3 can take certain URL parameters from the command line, like &DPL_fromTitle and &DPL_toTitle. Within the resultsheader and/or resultsfooter a template can be called that generates links to fetch the next / previous page.

Enabling scrolling does the following:

• DPL3 enables the acceptance of special scroll URL parameters, such as &DPL_fromTitle and &DPL_toTitle.
  • If these arguments are given, the commands title> and title< are implicitly be set.
  • To make scrolling possible, DPL3 relies on such variables, which give the name of the first and last result items actually shown.
• scroll=yes is used to fill the special URL parameters with proper values, and to set the title limits according to URL parameters derived from them.
  • See scroll parameter/URL syntax for use.
  • See scroll/URL parameters for a full list of special parameters.
• URLs can then be used to create scroll navigation between results in the result set, or a template can be used within the resultsheader and/or resultsfooter that generates links to fetch the next / previous page(s), though if such is used it is likely that allowcachedresults=false needs to be set.
  • Doing such sets auxiliary selection criteria titlelt= and titlegt=.

This mechanism can be used to create a generic page scroll feature – provided the value of DPL_offset can also be accessed in other templates outside of DPL3. This is where the other parameter execandexit comes in, it stores the URL parameters in a variable which can be accessed via #dplvar.

Example:

This lists pages from category Fruit examples. The count displays the first article using URL parameters, and an empty offset also using that syntax; setting both using scroll or url syntax, allows their query values to be overwritten by the URL. The scroll parameter fills the url parameter values. The resultsheader displays header text to show the count and current result start number. Setting allowcachedresults=false prevents caching, so result changes are immediately seen when the URL is changed, without the need to manually purge the MediaWiki cache.

The result is a static display of the first page, but its display offset (page to start at) and count can be overwritten just by adding two DPL3-specific URL parameters &DPL_count=1&DPL_offset=1 to the end of the (index.php-style) URL. If you copy/paste the URL into your browser's URL bar, you can see the next result is loaded from the URL parameters:

• https://dpl3.wikitide.org/wiki/Examples/Parameter:_scroll_(example_1)?DPL_count=1&DPL_offset=1 and the number can be incremented to view other pages.

Code

{{#dpl:execandexit  = geturlargs}}
{{#dpl:
|category           = Fruit examples
|count              = {%DPL_count:1%}
|offset             = {%DPL_offset:0%}
|scroll             = yes
|resultsheader      = Showing {%DPL_count:1%} pages starting from page ²{#expr:{%DPL_offset%} + 1}²:\n
|allowcachedresults = false
}}

Result

Showing 1 pages starting from page 1:

• Apple

Test in sandbox

View Result

Example:

This lists pages from the category Fruit examples, the count and empty offset displays the first 3 articles using Scroll or URL syntax, and scroll parameter being enabled fills the url parameter values. The resultsheader and footer use a helper template (Template:DPL3 scroll) to create scroll navigation, composed of the magic word ({{PAGESINCATEGORY:Category}}) and some parameters are fed to that template, so it can determine total pages, count, and amount of offset. allowcachedresults prevents caching, to prevent the need for manual purge to view the results.

Code

{{#dpl:execandexit  = geturlargs}}
{{#dpl:
|category           = Fruit examples
|count              = {%DPL_count:3%}
|offset             = {%DPL_offset:0%}
|scroll             = yes
|resultsheader      = ²{DPL3 scroll¦total={{PAGESINCATEGORY:Fruit examples|R}}¦offset={%DPL_offset:0%}¦count={%DPL_count:3%}¦page={{FULLPAGENAME}}}²\n
|resultsfooter      = ²{DPL3 scroll¦total={{PAGESINCATEGORY:Fruit examples|R}}¦offset={%DPL_offset:0%}¦count={%DPL_count:3%}¦page={{FULLPAGENAME}}}²\n
|allowcachedresults = false
}}

Result

1..34..6(8 total)

• Apple
• Grape
• Orange

1..34..6(8 total)

Test in sandbox

View Result

offset

offset

Shows only a portion of a big result list; typically used in combination with count.

Syntax:

offset=n where n is the number of result lines to skip, (integer) – (default = 0)

Example:

This lists pages from category Fruit examples, in the category Main, and offset by a count of 3 (starting at the fourth in the list). Results are limited to a count of 3 also. This means this displays articles #4, #5, and #6 from Category:Fruit examples. Next, ordermethod is set title, and the order set to ascending (alphabetically by title).

Code

{{#dpl:
|category    = Fruit examples
|namespace   = Main
|offset      = 3
|count       = 3
|ordermethod = title
|order       = ascending
}}

Result

• Grape
• Mango
• Orange

Test in sandbox

View Result

Notes:

• A DPL query could be put into a template with count and offset parameters. Calling this template with different values would allow different portions of the result list to be displayed.
• If mode=ordered is used, the numbers are adjusted to reflect the absolute position of the entries, i.e., in the above example, numbers starting from 11 are observed.
• If 'offset' is missing, it can be set from outside via the URL parameter DPL_offset.

randomcount

randomcount

Selects a subset from the result set for display, based on a random count.

Syntax:

randomcount=n where n is a positive integer.

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

Example:

This selects pages from category Category:Fruit examples and displays a randomcount of 1 pages from a pool (or subset) of several, limited to a count of 7. Setting allowcachedresults to false disables the cache so each time the page is previewed or refreshed, the result randomly changes.

Code

{{#dpl:
|category    = Fruit examples
|randomcount = 1
|count       = 7
|allowcachedresults = false
}}

Result

• Plum

Test in sandbox

View Result

randomseed

randomseed

Sets an initial value for the random generator.

Syntax:

randomseed=n where n is a positive integer.

Example:

This lists pages from category Fruit examples, sets a randomcount of 3, with the randomseed set to a new value every day using the {{#time:Ymd}} #time ParserFunction.

This example requires the ParserFunctions extension, and it also requires $wgPFEnableStringFunctions to be set to "true" (enabled) to function correctly; on Miraheze, ParserFunctions is already installed and the latter setting can be found and enabled in ManageWiki.

Code

{{#dpl:
|category    = Fruit examples
|randomcount = 3
|randomseed  = {{#time:Ymd}}
}}

Result

• Orange
• Apricot
• Pear

Test in sandbox

View Result

distinct

distinct

Allows / suppresses duplicates in the output.

Syntax:

distinct=critria where criteria can be one of:

• false – A page can occur more than once in the output.
• strict – A page can occur only once in the output if more than one page is specified for linksto or linksfrom, and the same page is referenced by more than one.
• true – A page can occur only once in the output – (default, need not be specified)

Works in connection with linksto and linksfrom:

• A page can occur more than once in the output.
  • This happens if more than one page is specified in linksfrom= or linksto= parameters, and the same page contains links to more than one of them (linksto), or if the same page is referenced by more than one of them (linksfrom).
  • To see a page only once also in these cases, use distinct=strict.
  • To see multiple result entries, set the value to false. This may make sense in combination with linksto= or linksfrom= to see how many links from one document to another document exist.

Example:

This lists any page with a titlematch of Apple, that uses Template:Color, and then include ensures the page name (automatic) and 1 (first parameter value) of the template is displayed in the output. The table statement formats the results as a simple table. The distinct parameter when set to true typically ensures each page is only displayed once in the output. The result count is restricted to 5 results.

This example is currently non-working, it may be replaced or removed at a later date to improve the clarity of this manual. As this needs to be done at a deliberate pace, the Gamepedia DPL3 Manual can be used in the interim, keeping in mind some functions may have changed.

Code

{{#dpl:
|titlematch   = Apple
|uses         = Template:Color
|include      = {color}:1
|table        = class="wikitable", Page, Color
|distinct     = true
|count        = 5
}}

Result

Page	Color
Apple	red
Apple	green

Test in sandbox

View Result

ignorecase

ignorecase

Makes comparisons insensitive to case.

Syntax:

ignorecase=true:

• true – Comparisons are case-insensitive (only true makes sense as an argument)
• false – Comparisons are case-sensitive – (default, need not be specified)

The parameter has an effect on linksto, uses, titlematch, titleregexp and their not-equivalents.

Note: For case-insensitivity in ordering result sets, see ordercollation.