Please remember to make use of the Manual of Style and Code of Conduct during your stay.

 Actions

Help

Extension - DPL3

From Dragon Mania Legends (DML) Wiki


link=Category:{{{base}}} (Element)
The following page or feature is intended for use by DML Wiki Staff (Bureaucrats) who work with advanced MediaWiki Extension functionality.

This page is intended for the documentation of the extension whose manual is hard to read, and also to test and provide contextualized examples that make sense for this wiki.

DynamicPageList3 (DPL3) is a MediaWiki extension used to select existing pages, and to create lists from those pages. DPL can also include (limited) page data from those pages in the results lists. DPL3 does not store data like Sematic MediaWiki, so the data to be accessed and displayed has to already be stored somewhere, usually in a page's template parameter values, or as (limited) page properties (categories, images, links, templates etc.). It is important to note that both the criteria for page (result) selection and the data that can be queried and displayed/formatted, is limited. After retrieving data, DPL can be combined with templates and parser functions to calculate and manipulate the data or display.

Use Method & Syntax[edit]

There are 2 methods for using DPL3 (parser function and DPL tag method) each with pros/cons for use as well as their own syntax, features, and special characters:

Parser Function {{#dpl: }} - Robust, more complex.

  • Parameter assignments don't always have to be on separate lines (|parameter=argument |parameter=argument).
  • Parser functions are pre-parsed to expand wiki mark-up before being handed over to DPL.
  • Magic words {{PAGENAME}} or {{CURRENTDAY}} can be used.
  • Template parameter calls {{{some template}}} can be used as parameters.
  • Parser function calls {{#if:...|...|...}} can be used within DPL parameter values.
Syntax features
  • Each parameter must start with a |.
  • Inside arguments/dpl parameter values, {{!}} or ¦ must be used instead of |, because | is used in DPL syntax as logical OR.
  • \n or must be used to insert new line if wiki symbols are used at the beginning of a line.
  • # Comments (denoted by # cannot be used!
Example Syntax
{{#dpl:
|category=Images:Sugar Rush|Images:Ancient Chests
}}

Result:

Note: By default DPL outputs an unordered (bulleted) list until the formatting is changed.

Extension Tag <DPL></DPL> - Simple, fast, limited

  • Wiki markup expansion does not take place before being handed over to DPL. Useful if you want to pass wiki syntax to DPL3 as arguments (e.g. see Format option. The text between these tags is handed over to DPL just as it is.
  • Magic words like {{PAGENAME}} or {{CURRENTDAY}} cannot be used.
  • Template calls like {{{some template}}}, can not be used as parameters.
  • Parser function calls like {{#if:...|...|...}} can not be used within arguments.
Syntax features
  • Each parameter does not start with |
  • Parameter assignment (=command) has to be on a separate line.
  • Pipe symbols can be used in arguments'/dpl parameter values.
  • must be used to insert an explicit line break in parameter lists.
  • # Comments (denoted by a # can be used.
  • Syntax looks simple and intuitive, no special characters.
  • Tag case doesn't matter, so it can also be written <dpl>.
Example Syntax
<dpl>
 category=Images:Sugar Rush|Images:Ancient Chests
</dpl>

Result:

Note: By default DPL outputs an unordered (bulleted) list until the formatting is changed.

Statement Design[edit]

Designing a DPL statement isn't really a linear process, but it helps to think of it that way.

Difficult vs DPL Approach

Usually, we generally start by:

  • Envisioning what it should look like (format)
  • Determining what will be included/restricted (include/volume)
  • Sequence/Order (output order)
  • Links (selected pages)

Which would result in a difficult approach like this:

Concept Order
Format Output ➤ Include/Volume ➤ Order Output ➤ Select Pages


DPL Approach

Since DPL3 doesn't hold or create content, and simply queries and displays (limited) existing content from its source, it requires a bit of a flipped approach. If you can't get enough data to display what you need (or calculate in combination with templates and parser functions), there is no sense in envisioning or applying formatting. You first need to know what pages hold the data to be displayEd (hopefully with common properties/categories/templates) that can be queried and later formatted using DPL3. So instead, you start with simple arguments check you are getting the right results pages to draw data from, then continue to add to it to narrow the results in the following order:

  1. Select existing pages that hold/source the (limited) data you need displayed, based on common characteristics/property (namespace, category, links, author etc.)
  2. Include associated data held by those pages to see what's possible, and control the volume of pages their data for the output.
  3. Format the output.
  4. Order/Sequence the output.


DPL Statement Design Order
Select Pages ➤ Include/Volume ➤ Format Output ➤ Order Output

Common Pitfalls[edit]

Common pitfalls are often related to result sets that are too large, or issues retrieving what is desired related to how data is stored (categories/templates/parameters):

  • Result sets that are too large (or global DPL settings too lax), causing potential performance issues.
  • Items are not categorized or parameterized (in the case of templates) in ways that make included data accessible or easy to calculate.
  • Categories not being standardized to house/serve one "type" content (e.g., you want to list Dragons according to some criteria, but Category:Dragon of the Month is categorized in the Dragons category, so it displays (unexpectedly) in your list of "Dragons".
  • Items of the same "type" that you want displayed/listed together, have similar but different, or missing parameters (e.g. if some events have start date or end date while others don't, and you need to populate a table column of start and end dates across different event types, your statements may become increasingly complex to try to calculate and standardize the data after the fact, using parser functions, nested statements etc. which can be challenging to combine successfully with DPL3).
  • Different different data types used in the same parameter (e.g., if sometimes a parameter value is sometimes a number or Boolean and other times string/text, it can present some challenges to writing DPL statements to output it, and later parser functions to format it. (e.g. in Template Data, you can only select 1 data type, on purpose (there should never be mixed data types), as mixed data types mean DPL statements and surrogate templates will need an increased level of complexity, multiplied if it is needed in more than one template).

Selecting Pages For Output[edit]

Pages can be selected for output (and contents later included) by several criteria:

Selection
Criteria
Syntax
Category
category
Select pages in given category/categories

Syntax:

OR category=1st category name|2nd category name|3rd category name|...
AND category=1st category name&2nd category name&3rd category name&...
NONE category=_none_

  • Boss Dragons Icon.png Caution: Do not use too large of a possible result set, instead, always restrict the amount of results you're likely to get while testing with: count=5 to prevent large result sets.
Advanced, Details, Caveats
  • You can't mix OR | and AND & in a single statement.
  • If you use more than 1 category line, their arguments will be implicitly connected with AND, so you can build a logical expression with several AND terms with each term consisting of an OR group of categories.
  • Boss Dragons Icon.png Caution: Combining an OR line with an AND line, there can be issues with using ordermethod=category (or anything grouped with 'category' such as 'sortkey' ordermethod=category,sortkey this caused major issues. Do not use ordermethod=category.
Example:
{{#dpl:
|category=Ancient (classification)
|category=Divine (Element)&Ancient (Element)
|count=5
}}
Important: It's a good idea when testing to always limit your output to a small number like 5, then widen as you know you're getting the results you need.
Issues (Broken?)
Had problems with:

If ordermethod=category and headingmode are enabled, you can restrict categories you want as headings in the result with '+' or '-'.

  • + means only categories listed can appear as headings in output (not sure if working).
  • - means categories listed can't appear as headings in output (but all others) (not sure if working).
  • * Boss Dragons Icon.png Broken Currently: before a category, will add all DIRECT subcategories.
  • ** Boss Dragons Icon.png Broken Currently: extend tree search 2 levels, for minimal hierarchy support (might change in future DPL versions).
  • Boss Dragons Icon.png Caution: Combining an OR line with an AND line, there can be issues with using ordermethod=category (or anything grouped with 'category' such as 'sortkey' ordermethod=category,sortkey this caused major issues. Do not use ordermethod=category.
  • Related (see DPL3) extension settings $wgDPL2MaxCategoryCount, $wgDPL2AllowUnlimitedCategories, $wgDPL2MinCategoryCount
  • Boss Dragons Icon.png Caution: To prevent huge output/resource consumption, see configuration variables. [1]
categorymatch
You can specify one or more patterns (SQL LIKE); a page will be selected if at least 1 of its categories matches at least 1 of the patterns.

Syntax:

categorymatch=1st category pattern|..

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

Example:

{{#dpl:
|categorymatch=Fire (Ele%&Wind (Ele%
|count=3
}}
^ This list will output pages that belong to categories like "Fire (Ele" AND "Wind (Ele" such as pages that belong to "Fire Elements" AND "Wind Elements" (I intentionally restricted the number of results to 3).

Important: It's a good idea when testing to always limit your output to a small number like 5, then widen as you know you're getting the results you need.

Result:
notcategory
Selects pages that are not in a specific category.

Syntax:

notcategory=category name

  • You cannot combine several categories using logical OR | in this parameter, each needs its own line.

Example:

{{#dpl:
|category=Uncommon (classification)
|notcategory=Fire (Element)
|notcategory=Wind (Element)
|notcategory=Earth (Element)
|notcategory=Clan Dragons
|notcategory=Water (Element)
|count=3
}}

Important: It's a good idea when testing to always limit your output to a small number like 5, then widen as you know you're getting the results you need.


Result:

Related (see DPL3) extension settings: $wgDPL2MaxCategoryCount, $wgDPL2AllowUnlimitedCategories, $wgDPL2MinCategoryCount.

(Other Items)
notcategorymatch
Works like notcategory but SQL-like
categoryregexp
Select pages with a category matching a regular expression.
  • The complete text behind "categoryregexp" will be taken as ONE argument and used in a SQL REGEXP clause, i.e. | characters can be used as a normal part of the regexp.

Example:


(EXAMPLE NEEDED)

notcategoryregexp
Works like notcategory but based on SQL REGEXP.
categoriesminmax
Select articles which are assigned to at least [min] and at most to [max] categories.

Syntax:

categoriesminmax=[min],[max]


{{#dpl:
|category=Images
|categoriesminmax=,1
|count=5
}}

^ Since the first value is empty, the second value is the max, it will list only pages belinging to "Images" and are not assigned to any other category (listing a maximum of 5 results as count=5 is set ).


Result:

Namespace
namespace
To restrict the pages listed to only be in 1 of the given namespaces.

Syntax:

namespace=1st namespace name|2nd namespace name|3rd namespace name|...

  • Must be any valid namespace(s) including custom ones, BUT no pseudo-namespace such as Media, Special which have negative namespace ids.
  • Leave empty for Main namespace. An empty string is the Main namespace (e.g. 'namespace=' for pages in Main only,namespace=|Talk or namespace=Talk| for Main or Talk ns namespace=Use Category for User, Main or Category, etc.).
  • Namespaces are case sensitive namespace=Use_talk will work, but namespace=Use_Talk won't.
  • You can also use its numeric ID (extension #'s) - though not recommended. DPL will always try to interpret name first. So, if you create a user namespace with the title "1" (which is possible in principle) DPL will take 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 1:

{{#dpl:
|category=Housekeeping
|namespace=|Category
|count=5
}}

^This list will output pages that are in the Main (blank) or Category namespace and belong to [[Category:Housekeeping]] .

Example 2 (with magic word):

  {{#dpl: category = Housekeeping | namespace= {{NAMESPACE}} |count=5}}

^ This list will output pages that are in the current namespace - whatever it is - and belong to [[Category:Housekeeping]] , which would be none, because the current namespace retrieved by the {{NAMESPACE}} magic word, is "Help," and Housekeeping items are in: Templates, Main Pages, or Categories namespaces.

notnamespace
To restrict the pages to those not of the given namespaces.

Syntax:

notnamespace=namespace name

Example:
{{#dpl:
|category=Housekeeping
|notnamespace=Category
|notnamespace=Template
}}
This list will output pages in Housekeeping that are NEITHER in the Category NOR in the Template namespace.
Links
linksfrom
Selects articles which are referenced from at least 1 of the specified pages.

Syntax:

linksfrom=full page name|..

  • The page mentioned in the DPL query can be retrieved via %PAGESEL% dpl variable.

Example 1:

{{#dpl:
  |category = Dragons
  |linksfrom  = Chip{{!}}Boone
  }}

This list will output pages that are mentioned (with a hyperlink) in article Dublin or Cork in the Main namespace and which belong to category "Dragons".

Example 2 (with magic word):

  {{#dpl: category = Dragons | linksfrom = {{FULLPAGENAME}} }}

This list will output pages that are in category "Poets" and which are referenced by the current page, whatever it is. Note that normally 'linksfrom' will only show existing pages. With 'openreferences=yes' this can be changed.

Note that the distinct parameter can be used to control the amount of output you get.

openreferences
Extends the linksfrom to unresolved references.

Syntax:

openreferences=yes

Example 1:
{{#dpl:
|linksfrom  = Dublin|Cork
|openreferences=yes
}}
This list will output pages that are mentioned (with a hyperlink) in article Dublin or Cork in the Main namespace, regardless whether these pages exist or not.

Note that the vast majority of DPL parameters depend on the existence of a page. If you set openreferences to yes none of those parameters can be used. Examples for conflicting parameters are all parameters which relate to categories, revisions, authors, redirections and some other parameters.

Note that you must specify ordermethod=none if you want to use openreferences=yes.

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

Syntax:

linksto=full page name|..

  • The page mentioned in the DPL query can be retrieved via %PAGESEL%.
  • A % can be used as a wildcard (SQL-LIKE expression).
  • If you specify more than one linksto condition, they will act as a logical AND. In this case the %PAGESEL% variable will point to the FIRST condition.
Example:
Parser extension
{{#dpl:
|category = Poets
|linksto  = Dublin|C%r%
}}
Parser function

{{#dpl: category = Poets | linksto = Dublin{{!}}C%r%}}

^ This list will output pages that are in category "Poets" and link to a page with title Dublin or Cork (or Cornwall etc.) in the Main namespace (by default). To make the comparison case-insensitive, use the parameter ignorecase. Note the use of {{!}} as a template call to |. in order for multiple values in parameters when using DPL as a parser function (otherwise DPL would interpret |Cork as another parameter, and give an error).

If a page links to Cork and Cornwall it will appear twice in the output. Use %PAGESEL% to see the name of the page it links to.

Example 2 (with magic word)
  {{#dpl: category = Poets | linksto = {{FULLPAGENAME}} }}
^ This list will output pages that are in category "Poets" and link to the current page, whatever it is.
  • Note that the distinct parameter can be used to control the amount of output you get.
linkstoexternal
Selects articles that contain an external link that matches a given text pattern. }}

Syntax:

linkstoexternal=text pattern|..

  • Selects pages that 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.
  • Is case-sensitive!
  • Is matched against the whole URL, so you need to put % around the pattern if you only give part of the string:
 linkstoexternal=%mywebpage%
  • If you specify more than one linkstoexternal item, a page must match ALL conditions (logical AND).
  • The URL of the external link can be retrieved via %EXTERNALLINK% variable.
  • Forward Button.png See also the addexternallink command.


Example:

(Example Needed)

(Other Items)
notlinksfrom
Selects pages that are NOT referenced from any of the specified pages.

Syntax:

notlinksfrom=full page name|..

  • Similar to linksfrom, you could use the {{FULLPAGENAME}} Magic Word, and not include any pages linked to from the current page. This, however, will generally result in errors.
notlinksto
Selects articles which do NOT link to any of the specified pages.

Syntax:

notlinksto=full page name|..

  • Implementation is not very efficient, use with care, and avoid huge result sets.
  • Note that the distinct parameter can be used to control the amount of output you get.
Example:
{{#dpl:
|category   = Poets
|notlinksto = London|Paris
}}
This list will output pages that are in category "Poets" and do not have a link pointing to a page with title London or Paris in the Main namespace.
Images
imageused
Selects pages which use a certain image.

Syntax:

imageused=image name|..

Example:
{{#dpl:
|imageused = Forward Button.png | Your image.png | Image:His.jpg
}}
As you can see the Namespace 'Image' need not be specified.
  • %IMAGESEL% variable contains the image name(s) used for selection.
imagecontainer
Description

Syntax:

imagecontainer=page name|..

Example:
{{#dpl:
|imagecontainer = MyPage | YourPage
|escapelinks=false
|openreferences=true
}}
This statement will show all images which are contained in the two articles MyPage and YourPage. Normally we would only get the names of images that really exist. But because we have specified openreferences=true we will also see non-existing images. Normally we would get a list of image names. Setting the parameter escapelinks to false, however, causes that we will see existing images directly. Non existing images will be displayed as red links.

See example - Example NEEDED

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

Syntax:

uses=Template:name|Template:.. The "Template" namespace must be specified. You can also specify another namespace if you like.

  • It is not possible to find pages that use 2 templates (e.g. Template:Foo AND Template:Bar).
  • Can be combined with include to include the contents of template parameter values, which is very powerful!
Example 1:
{{#dpl:
|uses = Template:Poet|Template:Painter
}}
This list will output pages that use a template called Poet and/or another template called "Painter".


notuses
Description

Selects pages that don't use any of the specified template.

Syntax:

notuses=Template:name|Template:..

  • Boss Dragons Icon.png Caution: The implementation of this feature is not very efficient. Use with care and avoid huge result sets.
Example 1:
{{#dpl:
|category = Poet
|notuses = Template:Poet
}}
^This list will output pages about poets which do not use the corresponding template.


usedby
Selects articles (templates) which are used (included) by a specified page.

Syntax:

usedby=page

Example 1:
{{#dpl:
|usedby=Main Page
}}
^ This will create a list of all pages which are included by the main page of your wiki.
Author/Editor
createdby
Selects articles which were created by the specified user.

Syntax:

createdby=username

Notes (applies for all user related selection criteria):

  • Boss Dragons Icon.png Caution: This keyword can produce very slow and inefficient queries on your MediaWiki system, impacting performance.
  • You can combine user related selections. For example, you could search for pages which were not created by user1 but modified by him, or you could search for pages which were created by user1 and lastmodified by user. You can also show several or all versions of such articles by specifying one or more of the "revision" group of parameters like allrevisionsbefore.
  • currently there is no mechanism to make a distinction between minor edits and normal modifications
modifiedby
Selects articles which were created or at least once modified by the specified user.

Syntax:

notmodifiedby=username

  • modifiedby will always be a superset of createdby as the creation of a page is interpreted as its first modification.
lastmodifiedby
Selects articles where the last modification was done by the specified user.

Syntax:

lastmodifiedby=username

  • Boss Dragons Icon.png Caution: To avoid huge result sets this will typically be accompanied by other selection criteria.
(Other Items)
notcreatedby
Selects articles which were NOT created by the specified user.

Syntax:

notcreatedby=username

Note:

  • Boss Dragons Icon.png Caution: To avoid huge result sets this will typically be accompanied by other selection criteria.
notmodifiedby
Selects articles which were NOT (created or) modified by the specified user.

Syntax:

notmodifiedby=username

  • Boss Dragons Icon.png Caution: To avoid huge result sets this will typically be accompanied by other selection criteria.
notlastmodifiedby
Selects articles where the last modification was NOT done by the specified user.

Syntax:

notlastmodifiedby=username

Note:

  • Boss Dragons Icon.png Caution: To avoid huge result sets this will typically be accompanied by other selection criteria.
Title
link=Category:{{{base}}} (Element)
This is where Crys is working... And it is taking forever to decide how to organize the content, since there's such a volume and stuff is in such strange places.
title
Select one single page by its (namespace and) title.

Syntax:

title=pagetitle

  • If you specify a title the mode will be automatically set to userformat, which means that you will get no output by default. Specifying an exact title makes sense if you want to transclude contents from one specific other page, e.g. the whole text, a chapter, labeled sections or template calls.
  • Considering the above, DPL may serve as an alternative to Labeled Section Transclusion.

Examples:

{{#dpl:title=My Page|include=#First Chapter}}
{{#dpl:title=My Page|include={My Template}.dpl|multisecseparators=\n----\n}}

^ The first example will include the contents of "My Chapter" of an article named "My Page" in the main namespace.

^ The second example will take all invocations of template "My Template" in article "My Page" and apply "Template:My Template.dpl" instead of "Template:My Template". The output will be separated by horizontal lines.

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

Syntax:

titlelt=string

  • The string given need not be a valid page title.
  • If set together with 'ASCENDING' order and a count limit, you will get the pages which are immediately 'below' the given string. This allows efficient scrolling through huge result sets.

For details see Scrolling.

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

Syntax:

titlegt=string

The string given need not be a valid page title.

If this parameter is set together with 'ASCENDING' order and a count limit, you will get the pages which are immediately 'above' the given string. This allows efficient scrolling through huge result sets.

For details see Scrolling.

scroll
Enables built-in support for scrolling result sets.

Syntax:

scroll=yes

If this command is given, DPL will interpret some special arguments in the URL.

DPL_count       limit number of pages to show
DPL_offset      where to start (nth page)
DPL_refresh     whether to purge the special DPL cache or not 
DPL_fromTitle   page name to start after (will be passed to title< ) 
DPL_toTitle     page name to end with (will be passed to title> , needed for reverse scroll) 
DPL_findTitle   page name to start with (will be passed to title>= ) 
DPL_scrolldir   direction of scroll (can be 'up' or 'down') 

For details see Scrolling.

titlematch
Select pages 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:

{{#dpl:
 |titlematch=%foo%|bar%
 }}

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

Example:

{{#dpl:
 |namespace=
 |titlematch=A%
 }}

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

The match is case-sensitive, even with respect to the first character; to make it case-insensitive, use the parameter ignorecase. Note that 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
Select pages with a title matching the specified regular expressions. The pattern will be 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:

{{#dpl:
 |titleregexp=[0-9]+.*y$
 }}

This will output all pages (regardless of namespace) which have a digit in their name and end with a "y". Use the parameter ignorecase to make the comparison case-insensitive.

(Other Items)
nottitlematch
Select pages 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:

{{#dpl:
 |nottitlematch=%e%|%u%
 }}

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

nottitleregexp
Select pages with a title that does NOT match the specified regular expression.

Syntax:

nottitleregexp=regular expression

  • The expression will be used as a REGEXP argument in an SQL query.
  • Namespaces are ignored as the namespace= parameter can be used to further narrow the selection.
  • Boss Dragons Icon.png Caution: Normally use this selection only in combination with other criteria, otherwise output could become huge.
Contents
includematch
Controls the selection of pages based on contents which shall be included from these pages.

Syntax:

includematch=regexp1,regexp2,..

  • Page will only be selected (and its contents included) if the contents to be included matches a regular expression. In case of (heading based) chapter inclusion and labeled section inclusion the relevant contents of the page must match the pattern; in 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 you must delimit your regexp with two identical characters that are not part of the regexp itself, e.g. with /. Otherwise you will see strange error messages from the php interpreter...
  • If you are not familiar with regular expressions and/or do not know the specifics of Perl regexp used in PHP, you should definitely have a look into the PHP manual before using includematch.
  • You may want to match named parameters or unnamed parameters. In the first case you should use something like this to be safe:
 includematch=/\{{!}}\s*myParameter\s*=\s*myPattern/s

Thus you can put spaces around the = and use linebreaks in your original article when calling the template - and still the pattern will match. Note that you must use a template to produce a pipe symbol - otherwise the pipe will break the parameter structure of your DPL call.

  • In case the template expects unnamed parameters you would specify something like:
 includematch=/\{{!}}\s*myPattern/s
  • If the parameter is not the last one in your template call you might use:
 includematch=/\{{!}}\s*myPattern\s*\{{!}}/s
  • Note that in combination with templates the regexp matching will only work if you produce some output at all via the include statement. So, if you call a dummy parameter only or if you call a phantom template that does not produce any output, you will see no matches. It is, however, sufficient to produce a space character to get output. It is not necessary to output the parameter which matches your regexp.

See the include parameter.

Example:

{{#dpl:
 |category  = Africa
 |include  = #myChapter,{countryProfile}.dpl
 |includematch = ,/Name\s*=\s*[Kk]amerun/s
 }}

This will match articles which contain a call to the template "countryProfile" and use the "Name" parameter of that template with an argument that contains "Kamerun" or "kamerun" as a text string. Note that there is no pattern specified for the first element of the include statement. "KAMERUN" would not match; we could use the "i" modifier with the regexp to match without case sensitivity if we wanted so.

includematchparsed
Controls the selection of pages based on (pre-parsed) contents which shall be included from these pages.

Syntax:

includematchparsed=regexp1,regexp2,..

  • Works exactly like includematch but the contents will be parsed before it is tested against the regular expression.
includenotmatch
Controls the selection of pages based on contents which shall be included from these pages.

Syntax:

includenotmatch=regexp1,regexp2,..

The idea is that a page will only be selected (and its contents included) if the contents to be included does not match a given regular expression. In case of (heading based) chapter inclusion and labeled section inclusion the relevant contents of the page must not match the pattern; in case of template based matching it is the calling code of your template which must not match the regular expression. Be careful to design your regexp in a proper way so that it covers all syntactical variations. You should use something like

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

to be on the safe side. Thus you can put spaces around the '=' and use linebreaks in your original article when calling the template - and still the pattern will do its job.

See the include parameter.

Example:

{{#dpl:
 |category  = Africa
 |include  = #myChapter,{countryProfile}.dpl
 |includenotmatch = ,/Name\s*=\s*[Kk]amerun/s
 }}

This will match articles which contain a call to the template "countryProfile" and use the "Name" parameter of that template with an argument that does not contain "Kamerun" or "kamerun" as a text string. Note that there is no pattern specified for the first element of the include statement. "KAMERUN" would not match; we could use the "i" modifier with the regexp to match without case sensitivity if we wanted so.

includenotmatchparsed
Controls the selection of pages based on (pre-parsed) contents which shall be included from these pages.
  • Works exactly like includenotmatch but the contents will be parsed before it is tested against the regular expression.
Revision
lastrevisionbefore
Shows only articles which existed before the specified date. The date of the last revision

before that date will be shown (and will be available as %REVISION% in mode=userformat).


Syntax:

lastrevisionbefore=dateandoptionaltime

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

firstrevisionsince
The date of the first revision after the specified date will be shown (and will be available as %REVISION% in mode=userformat).

Syntax:

firstrevisionsince=dateandoptionaltime

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

allrevisionsbefore
Shows all revisions which existed before the specified date. The date of each revision will be shown (and will be available as %REVISION% in mode=userformat).

Syntax:

allrevisionsbefore=dateandoptionaltime

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
Shows all revisions which were created after the specified date. The date of each revision will be shown (and will be 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

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

maxrevisions
Show a page (or its revisions) only if there do not exist more than a given number of revisions for that page.

Syntax:

maxrevisions=number

number must be greater or equal than 1.

minrevisions
Show a page (or its revisions) only if there exist at least a given number of revisions for that page.

Syntax:

minrevisions=number

number must be greater or equal than 1. In practice only values of 2 or greater make sense. Using a value of 2, you could exclude freshly created pages from a result set.

Other
articlecategory
Select a talk page based on a category to which the corresponding base article (in the default namespace) belongs.

Syntax:

articlecategory= categoryname

If you want to select articles in namespace=Talk you can use this statement to define (in addition) a category for an article with identical name in namespace 0 (default namespace).

Inclusion & Volume[edit]

(TBD)

Formatting Output[edit]

(TBD)

Sorting Output[edit]

(TBD)

Characters with special meaning[edit]

Sometimes it is necessary to use a character as "plain data" at a place where it normally has a syntactical meaning. Mediawiki is not very clean at character escaping in general. So we had to define our own way in the jungle of "character escaping":

DPL escape character Mediawiki character Typical use
» > Call another MediaWiki extension into a parameter of a DPL call
« <
²{ {{ Call a template within the 'article loop' of DPL. This is especially useful for nesting DPL calls (DPL recursion)
}}
¦ |
newline Inserts a line break into DPL's wikitext output, to allow proper parsing of first-character syntax (such as * # : ;)
\n newline
DPL's mechanism of replacing %xx% variables then can be used to modify the arguments of that call before it will be resolved. Most DPL users will not need this, but for some advanced uses of DPL it is a real help.

Built-in variables[edit]

Within a DPL statement you can use some variables which are implicitly set by DPL. Example: %TITLE%, %PAGE%. Some variables can only be used in the header or footer, like e.g. %PAGES%, %TOTALPAGES%.

Variable Description
%NR% The current article sequence number (starting from 1)
%PAGE% %PAGE% = the name of the article (including namespace)
%PAGEID% The internal unique numeric ID of the article page
%IMAGE% The physical path to an image (based on hash values, e.g. 5/5d/myImage.jpg)
%PAGESEL% The name of a page which was used within the selection criteria (only applies to linksfrom and linksto)
%IMAGESEL% The name of an image which was used within the selection criteria (only applies to imageused)
%TITLE% The title of the page (without the namespace)
%NAMESPACE% The namespace of the page
%SIZE% The article size (requires addpagesize=true)
%SIZEFS% A font size number which is based on the article size (logarithm of square root of counter)
%DATE% The date selected, eg. lastedit; requires addeditdate=true or similar; the formatting of the date can be influenced using userdateformat=
%USER% The user who changed the document last; requires adduser=true
%CONTRIBUTOR% The user who made a contribution; requires addcontribution=true
%CONTRIBUTION% The number of bytes changed; requires addcontribution=true
%CONTRIB% An asterisk bar to indicate the amount of change; requires addcontribution=true
%CATLIST% A pipe-separated list of links to all categories to which the article belongs (requires addcategories=true)
%CATBULLETS% A bullet point list of links to all categories to which the article belongs (requires addcategories=true)
%CATNAMES% A comma-separated list of all categories to which the article belongs (requires addcategories=true)
%REVISION% The name of the revision of the article; only accessible if the DPL query is based on revisions
%EDITSUMMARY% The change log message of a revision; only accessible if the DPL query is based on revisions
%EXTERNALLINK% The external hyperlink found as a consequence of the linkstoexternal statement
These variables will be replaced by the corresponding values if they occur within Start or End or within the corresponding tags of the secseparators= parameter.
In addition there are some symbolic variables which can ONLY be used in resultsheader and resultsfooter:
%PAGES% Number of articles in the result set
%TOTALPAGES% Total number of articles in the result set, regardless of count limits; will only be calculated if used
%VERSION% The current DPL version
%DPLTIME% Contains the amount of time (in seconds + milliseconds) spent within DPL; this can be helpful if you observe slow response times for wiki pages that contain DPL statements. Example: 2 (2009/06/13 09:27:43) would mean that DPL spent two seconds of the whole response time, starting at the time given in brackets.
%FIRSTNAMESPACE%
%FIRSTTITLE%
%LASTNAMESPACE%
%LASTTITLE%
Namespace and title of the first / last article in the result set; the information is intended to be used for page scrolling
%SCROLLDIR% Set by the URL parameter DPL_scrollDir; it is passed to the scroll helper template which uses it to produce its links for scrolling

URL parameters[edit]

DPL understands a couple of parameters which can be passed via an URL specification.

Url Parameters

These URL-parameters all start with DPL_:

  • DPL_count: influences the count parameter (in fact it overwrites the value specified within the DPL statement)
  • DPL_offset: influences the offset parameter (in fact it overwrites the value specified within the DPL statement)
  • DPL_refresh: if used with a value of 'yes' this will clear the DPL cache
  • DPL_fromTitle: restrict the selection to articles with a page title greater or equal to the specified value
  • DPL_toTitle: restrict the selection to articles with a page title less or equal to the specified value
  • DPL_arg1, DPL_arg2, .. DPL_arg5: these are generic parameters that can be used freely to influence a DPL statement
The command
  http://mywebsite/mywiki/index.php?title=MyPage&DPL_offset=20 

would display MyPage and set the offset parameter to a value of 20.

Within the DPL statement you can access URL parameters via

 {%DPL_xxx%}

If a parameter is not set in the URL, DPL will assume an empty string. Instead you can define a default value by using a colon:

{%DPL_xxx:yyy%}

In this case DPL will use 'yyy' if the parameter DPL_xxx is not specified on the URL command line.

Note: There is a template called Template:Extension DPL scroll which uses DPL_offset and DPL_count to provide a generic page scrolling method for huge result sets.

Other[edit]

=Time stamps[edit]

DPL queries which return date/time information (e.g. date of last edit of a page) will display this information according to your local timezone (if this is correctly set in your user preferences).

Special note on Self References[edit]

Normally DPL does not return its own page in the result.
Details

In principle a DPL query could be written in a way that the page containing the query (or the page including a template which contains the query) would be part of the result set. Experience in the past has shown that in some cases this leads to unwanted effects. For instance the page containing the query from a MediaWiki point of view contains links to all pages it lists. If your DPL statement contains a "uses" clause you will be astonished to find your own page in all results. The same happens with categories... In addition there were technical problems with self referencing result sets (parser loop references which seemed very hard to solve). So it was decided to skip a self reference in the result set by default.

  • The parameter skipthispage gives you control over this behavior. By setting it to no you can allow self references in DPL result sets.
  • You can suppress back references to a page containing a DPL query by using reset and/or eliminate.

Symbol replacement in mode=userformat[edit]

When mode=userformat is selected, DPL will not output anything by default. Instead it will look for symbols in your input (listseparators, secseparators, multisecseparators, tablerow) which it will replace by their corresponding values. For example, %TITLE% will be replaced by the title of an article, %PAGE% will be replaced by the pagename. So, if you write something like
[[%PAGE%|%TITLE%]], DPL will create a hyperlink to an article.

'See Controlling output format' for a complete list of symbols.

The specification of listseparators, secseparators, and multisecseparators does only make sense in combination with mode=userformat. Therefore mode=userformat is automatically implied when listseparators is specified. To make the syntax even more comfortable the simple word format can be used as an alias for listseparators. So:

mode=userformat
listseparators=a,b,c,d

is exactly the same as:

format=a,b,c,d

Use of boolean parameters[edit]

A lot of DPL's parameters have type boolean. The manual always assumes that 'true' and 'false' are used to set such parameters. As an alternative, you can also use 'yes' and 'no' or '1' and '0' or 'on' and 'off' as with the standard HTML form checkbox input type.

Implicit link to Template:Extension DPL[edit]

Since version 1.7.9 DPL creates an implicit automatic link to Template:Extension DPL. This means that every page containing a DPL statement will automatically create a link to Template:Extension DPL. You should create this Template in your wiki. We suggest that you copy the source code from our version. The idea is that via this connection you can easily find out which pages in a wiki contain DPL calls.

Note that the template does NOT produce any output - so it is practically invisible to the user. If you forget to create the template, however, the user will see a red link to the template.

Debugging a DPL statement[edit]

If you want to write a DPL query which produces wiki tables a lot of imagination is required because you must produce correct wiki syntax as the result of your query. And that syntax heavily depends on newlines, escaping of pipe symbols and other nice little things which are easy to get wrong ;-)

We recommend to use the following parameters to find out what syntax your DPL statement produces:

 resultsheader=«pre»«nowiki»
 resultsfooter=«/nowiki»«/pre»

The same effect can be achieved with debug=5.

Scrolling[edit]

DPL supports efficient scrolling through huge result sets. ***SCROLLING IS CURRENTLY BROKEN***

About Scrolling
The command scroll=yes must be given to enable scrolling.

DPL can take certain URL parameters from the command line, like &DPL_fromTitle and &DPL_toTitle. If these arguments are given the commands title> and title< will implicitly be set. Within the resultsheader and/or resultsfooter you can call a template which generates links to fetch the next / previous page.

Basically the idea of backward scrolling is that the SQL statement produces a DESCENDING order (with titles below the threshold). Internally DPL buffers the SQl result set and reverses its order. So the user will see a page of entries directly below the threshold, but in ascending order.

If scrolling is enabled, DPL 1.8.0 and later will take a couple of parameters from the URL command line, like DPL_offset for instance; these parameters can be accessed within DPL via a special syntax:

  • {%DPL_offset%}.

or

  • {%DPL_offset:defaultvalue%}.

The variables are:

  • DPL_count
  • DPL_offset
  • DPL_refresh (a value of 'yes' will purge the DPL cache)
  • DPL_fromTitle (will be passed to title< )
  • DPL_toTitle (will be passed to title> )
  • DPL_findTitle (will be passed to title>= )
  • DPL_scrolldir (will be used to influence sort order, can be 'up' or 'down')

Thus you could write an article called 'MyPopularArticles' containing a DPL query like:

{{#dpl:execandexit=geturlargs}}
<dpl>
  category      = Country
  count         = {%DPL_count:100%}
  scroll        = yes
  resultsheader = Showing {%DPL_count:100%} pages starting from page {{#expr:{%DPL_offset%} + 1}}:\n
</dpl>

Calling http://mywebsite/mywiki/index.php?title=MyPopularArticles will give you the first 100 articles in the category. Adding &DPL_offset=100 will give you the next one hundred articles. This mechanism can be used to create a generic page scroll feature - provided you can access the value of DPL_offset also in other templates outside DPL. And this is where the execandexit command comes in: it stores the URL parameters in a variable which can be accessed via #dplvar.

Simple Table Example (no surrogate)[edit]

DPL Extension Method:

Event Type Duration Ended
Afterlife Adventure (19/08/23) Castle 10 Days 2 September 2019

Parser Function Method:

Event Type Duration Ended
Afterlife Adventure (19/08/23) Castle 10 Days 2 September 2019

</nowiki>

Result: