General usage and invocation syntax

Manual

General usage and invocation syntax

DynamicPageList3 (DPL3) can be used as a parser extension (<dpl> .... </dpl>) or as a parser function ({{#dpl: .... }}). There is no general rule which one is better. If in doubt, you may want to use the parser function syntax, as it is more powerful.

Sample output

Both of the following examples, which illustrate the difference between using DPL3 as a parser extension and using it as a parser function, will produce a list of all articles which belong to cat1 or cat2 and which contain a reference to myPage. The output of these DPL3 calls would be something like:

• Apple
• Grape
• Orange

Syntax used in this manual

Most examples in this manual typically use the parser function-based syntax, {{#dpl:}} given it is the more flexible syntax. Examples are wrapped in <pre></pre> tags, so the plain wikitext used to create a result can be seen without rendering the result itself.

Most of the manual deals with the explanation of individual parameters. This is independent of the choice between the two variants described above. So, if you read something like

• parameter = value

you should have in mind that you must either place DPL3 tags around (using a separate line for each parameter) or use the parser function syntax and separate parameters by pipe characters.

DPL3 Invocation syntax

Parser extension (tag) method

The following example would probably be used directly on an article page, but could also be included as part of a template. Parser extensions define a specific tag (in this case <dpl>) and a corresponding end tag (</dpl>). The text between these tags is handed over to the extension module just as it is.

Example syntax

<dpl>
  category = cat1|cat2
  # only pages which contain a link to myPage
  linksto  = myPage
</dpl>

Parsing procedure

Wiki markup expansion does not take place before the commands are handed over to the extension module.

• This may be useful if you want to pass wiki syntax elements to DPL3 as arguments (see the format option, for example).
• Magic words like {{PAGENAME}} or {{CURRENTDAY}} cannot be used.
• Template calls, like {{some template}}, cannot be used as parameters.
• Parser function calls like {{#if:...|...|...}} cannot be used within arguments.
• To pass wiki syntax elements to DPL3 as parameters, it is sometimes necessary to enforce a line break. The reason is that wiki syntax depends on line breaks. Instead, use \n or ¶ for that purpose.

Syntax features

• Every parameter assignment (=command) has to be on a separate line.
• Lines starting with a # will be ignored (comment).
• Generally the syntax looks fairly simple and intuitive as it doesn't contain special characters (except for the two embracing tags).
• Tag case doesn't matter, so it can also be written <dpl>.
• Often, there is no need to have macro expansion within the parameter list.
• In the example above, the pipe character (which is used to define a logical OR between the two categories) can be written as it is. The name of the page (myPage), however, must be a hard-coded constant.

Parser function method

This example would be used inside a template, and uses the variable {{{1}}} passed to the template, which would be set to myPage here. Parser functions look like templates which start with a hash character (#). They are more closely integrated with the wiki system. They are more powerful, but their syntax looks a bit more complicated. The text between these tags is pre-parsed to expand wiki mark-up before being handed over to the extension module.

Example syntax:

{{#dpl: category = cat1{{!}}cat2 | linksto = {{{1}}} }}

or

{{#dpl:
  |category = cat1¦cat2
  |linksto  = {{{1}}}
}}

Parsing procedure

Wiki markup expansions (not the final conversion to HTML) take place before the commands are handed over to the extension module.

• Magic words like {{PAGENAME}} or {{CURRENTDAY}} can be used.
• Template calls, like {{some template}}, can be used as parameters.
• Parser function calls like {{#if:...|...|...}} can be used within arguments, though they must be formatted differently ²{#if:...¦...¦...}²

Syntax features

• To use wiki characters as arguments, they must be escaped.
  • It is possible to use the Magic Word {{!}} which 'hides' the pipe from the MediaWiki parser, ensuring that it is not considered until after other items have been expanded, though if multiple need to be used this can make your statements harder to read.
  • With DPL3 it is also possible to use the symbol ¦ instead of |; this is very intuitive, and maybe it could be adopted by MediaWiki in general...but be careful: it must be inserted by copy-and-paste from here (or from an HTML symbol or extended ASCII table like Windows' Character Map) as normally a keyboard will not have it available (even worse: on some keyboards the standard pipe character is printed in a way that it looks more like the "broken pipe").
• The text can (but needs not) be written in one line of text, parameters are separated by pipe characters.
• What was said before regarding explicit line breaks also holds true for parser function syntax, i.e., the special symbols \n or ¶ must be used to insert an explicit linefeed character into the wiki output stream if wiki symbols are used which must stand at the beginning of a line.

Notes:

• The pipe character, which is used to define a logical OR for the two categories, must be represented as a Magic Word {{!}} which 'hides' the pipe from the MediaWiki parser, ensuring that it is not considered until after other items have been expanded. The second example shows that the ¦ character acts as an alternative to this somewhat awkward notation.
• The second example is not literally equivalent to the first one, as there is an additional pipe character before the first parameter. Technically, this creates an additional empty parameter, but as empty parameters are silently ignored by DPL3 it makes no difference.

Special note on Self References

In principle, a DPL3 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 perspective contains links to all pages it lists. If your DPL3 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.

Important: DPL3 does not normally return its own page (a self link/reference) in the result set. To include a page that references itself in the result, you must use skipthispage

You can suppress back references to a page containing a DPL3 query by using reset and/or eliminate.

Characters with special meaning

Occasionally, 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":

DPL3 escape character	MediaWiki character	Typical use
»	>	Call another MediaWiki extension into a parameter of a DPL3 call, or create a gallery <gallery></gallery> using DPL3's parser function syntax.
«	<
²{	{{	Call a template or parser function within the 'article loop' of DPL3's parser function syntax; this is especially useful for nesting DPL3 calls (DPL recursion).
}²	}}
¦	|
¶	newline	Inserts a line break into DPL3's wikitext output, to allow proper parsing of first-character syntax (such as {| * # : |} ;)
\n	newline

DPL3's mechanism of replacing %xx% variables then can be used to modify the arguments of that call before it will be resolved. Most DPL3 users will not need this, but for some advanced uses of DPL3 it is a real help.

Built-in variables

Within a DPL3 statement, you can use some symbols (called variables in this manual) which are implicitly set by DPL3. Some variables can only be used in the header or footer. {{#lst:Controlling output format|formatvariables}}

Variable	Description
%SECTION%	The page name and its included section anchor Page Name#SectionName. Corresponds to include=#SectionName (when a page section is included by name). It currently appears that %SECTION% can only be used in secseparators.
%PFUNC%	The name of the parser function, set when include is used to look for parser function calls in an article or result set. This variable requires a corresponding include statement and is not very robust, it cannot handle nested parser functions properly. %PFUNC% is only applicable to the template for which the parser function and its parameters are passed (under their normal names or numbers).
%TAG%	The name of the parser extension (tag), set when include is used to look for parser extension (tag) calls an article or result set. This variable requires a corresponding include statement and is not very robust, it cannot handle nested parser functions properly. %TAG% is only applicable to the template for which the parser extension information is passed.
%TAGBODY%	The body content (as-is, including line breaks) of the parser extension (tag), set when include is used to look for parser extension calls an article or result set. This variable requires a corresponding include statement and is not very robust, it cannot handle nested parser functions properly. %TAGBODY% is only applicable to the template for which the parser extension information is passed.

Scrolling/URL Parameters

DPL3 supports efficient scrolling through huge result sets. Basically, the idea of backward scrolling is that the SQL statement produces a DESCENDING order (with titles below the threshold). Internally, DPL3 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.

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

Scroll/URL syntax

If scrolling is enabled, DPL3 1.8.0 and later will take some parameters from the URL command line (e.g., like DPL_offset); these parameters can be accessed within DPL3 via a special syntax:

• {%DPL_offset%}.

or

• {%DPL_offset:defaultvalue%}.

Within the DPL3 statement, you can access URL parameters via

 {%DPL_xxx%}

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

{%DPL_xxx:yyy%}

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

Note: There is a template called Template:DPL3 scroll which uses DPL_offset and DPL_count to provide a generic page scrolling method for huge result sets, where there is an expected number of results. See scroll for more information.

Scroll/URL parameters

When scrolling is enabled, DPL will interpret the following special parameters in the URL.

URL Parameter	Description
DPL_count	Limit number of pages to show, overwrites the values of the count= parameter.
DPL_offset	Where to start, nth page, overwrites the value of the offset= parameter.
DPL_refresh	Note: This feature was removed in DPL3 version 3.0.0.
DPL_findTitle	Page name to start with, value is passed to titlegt= (previously title>= ).
DPL_toTitle	Page name to end with, value is passed to titlegt (previously title>), which is needed for reverse scroll and which restricts the selection to articles with a page title less or equal to the specified value.
DPL_fromTitle	Page name to start after, value is passed to titlelt (previously title<), which and restricts the selection to articles with a page title greater or equal to the specified value.
DPL_scrolldir	direction of scroll (can be 'up' or 'down').

Time stamps

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

Interaction between your wiki text and DPL3 output

As mentioned before, DPL3 will insert its output exactly at the position where you placed the DPL3 call. This means that you can put wiki syntax around your DPL3 call, like:

  {| class="wikitable"
  |a table field
  |<dpl>
     linksto=myPage
   </dpl>
  |-
  |another table field
  |...
  |}

You could also use HTML syntax to surround DPL3 output, as in the following example:

<ul>
  <li>Item1</li>
  <li>Item2
    <DPL>
      ...parameters...
    </DPL>
  </li>
</ul>

Variable replacement in mode=userformat

When mode=userformat is selected, DPL3 will not output anything by default; instead, it will look for variables in your parameter 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 page name. So, if you write something like
[[%PAGE%|%TITLE%]], DPL3 will create a hyperlink to an article.

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 the same as:

format=a,b,c,d

Use of boolean parameters

A lot of DPL3'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

Since version 1.7.9, DPL3 creates an implicit automatic link to Template:Extension DPL. This means that every page containing a DPL3 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 DPL3 calls.

Note: 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 DPL3 statement

If you want to write a DPL3 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 using the following parameters to find out what syntax your DPL3 statement produces:

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

The same effect can be achieved with debug=5.

Tracking Categories

Built-in tracking categories include:

Category Name	On Use of
Category:Pages using DynamicPageList3 parser tag	<dpl></dpl>
Category:Pages using DynamicPageList3 Intersection parser tag	<DynamicPageList></DynamicPageList>
Category:Pages using DynamicPageList3 parser function	{{#dpl:}}
Category:Pages using DynamicPageList3 dplnum parser function	{{#dplnum:}}
Category:Pages using DynamicPageList3 dplvar parser function	{{#dplvar:}}
Category:Pages using DynamicPageList3 dplreplace parser function	{{#dplreplace:}}
Category:Pages using DynamicPageList3 dplchapter parser function	{{#dplchapter:}}
Category:Pages using DynamicPageList3 dplmatrix parser function	{{#dplmatrix:}}

Note: If the display of tracking categories is not desired on-page, see tracking categories for information about using the __HIDDENCAT__ magic word.