View source for Help:DPL/Parameters: Controlling output volume

{{DPL manual|section=Parameters|subsection=Controlling output volume|sort=P4}}

Per default, DynamicPageList3 will show the name of each article, including its namespace. The name will serve as a link to the article.
By setting the '''output control parameters''' of DPL you can

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

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

And you can define an alternate text which will be shown '''if there are no articles''' to display.
{{TOC right}}
==Defining header and footer for the result==
===resultsheader===
{{DPL parameter
 |name   = resultsheader
 |purpose= output a headline if there is at least one article to display.
}}


Syntax: <code>resultsheader=''some wiki text''</code>

Notes: 
* The symbol %PAGES% will be replaced by the number of pages found. If your query result is limited (by system settings or by the {{DPL|count}} parameter) %PAGES% will only show the upper limit.
* The symbol %TOTALPAGES% will be replaced by the number of pages found - regardless of count limits. This may consume extra resources.
* %VERSION% will be replaced by the current DPL version.
* The symbol '\n' will be converted to a newline symbol. This is useful if you want to use wiki markup which needs to start at the begin of a line. You may need to add \n if the wiki parser requires a linefeed to understand your wikitext.
* If 'oneresultheader' is specified as well, the latter will be used in case there is exactly one entry in the DPL result set. Then 'resultsheader' will only be used if there are '''two or more''' entries in the result set.

Example:

<pre><nowiki>
{{#dpl:
|category=Africa
|mode=userformat
|resultsheader=There are %PAGES% pages on Africa.
}}
</nowiki></pre>

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

===resultsfooter===
{{DPL parameter
 |name   = resultsfooter
 |purpose= output a summary 'footline' if there is at least one article to display.
}}

Syntax: <code>resultsfooter=''some wiki text''</code>

Note: The rules of <code>[[#resultsheader]]</code> apply here as well.

Example:

<pre><nowiki>
{{#dpl:
|category=Africa
|mode=userformat
|resultsfooter=\n===There are %PAGES% pages on Africa.===\n
}}
</nowiki></pre>

With "mode=userformat" we get complete control over the output.
We do not specify "listseparators=" - so nothing will be displayed except the results footer.
The only thing we will get is a message about the existing number of articles. We used '\n' to make sure that our headline syntax will really be recognized by the wikitext parser.

See also [[Help:DPL/Parameters: Controlling output volume#resultsheader]].

===oneresultheader===
{{DPL parameter
 |name   = oneresultheader
 |purpose= output a headline if there is exactly one article to display.
}}

Syntax: <code>oneresultheader=''some wiki text''</code>

Note: The symbol '\n' will be converted to a newline symbol. %VERSION% will be replaced by the current DPL version. This is useful if you want to use wiki markup which needs to start at the begin of a line. You may need to add \n if the wiki parser requires a linefeed to understand your wikitext.

===oneresultfooter===
{{DPL parameter
 |name   = oneresultfooter
 |purpose= output a footline if there is exactly one article to display.
}}

Syntax: <code>oneresultfooter=''some wiki text''</code>

Note: The symbol '\n' will be converted to a newline symbol. %VERSION% will be replaced by the current DPL version. This is useful if you want to use wiki markup which needs to start at the begin of a line.

===noresultsheader===
{{DPL parameter
 |name   = noresultsheader
 |purpose= output a headline if there is no article to display (empty result).
}}

Syntax: <code>noresultsheader=''some wiki text''</code>

Note:

Setting <code>noresultsheader</code> to a single blank or to a newline character ("<code>noresultsheader=&amp;nbsp;</code>" or "<code>noresultsheader=\n</code>") will suppress the warning message from DPL which is normally issued if no articles were found.
Example:

<pre>
A)
{{#dpl:
|titlematch=nosuchArticle
}}

B)
{{#dpl:
|noresultsheader=&amp;nbsp;
|titlematch=nosuchArticle
}}
</pre>

<u>This produces:</u>

A)
{{#dpl:
|titlematch=nosuchArticle
}}

B)
{{#dpl:
|noresultsheader=&nbsp;
|titlematch=nosuchArticle
}}

===suppresserrors (DEPRECATED)===
This parameter is deprecated and is left in the code as a null parameter to give people time to remove it from their queries.  It will be fully removed in a future release of DPL.

{{DPL parameter
 |name   = suppresserrors
 |purpose= suppress the warning message if no matching article was found.
}}

Syntax: <code>suppresserrors=true</code>

See also: <code>[[Help:DPL/Parameters: Other parameters#debug]]</code>

Note: Setting <code>suppresserrors</code> to true has the same effect as setting noresultsheader to a single space character. The command is provided for downward compatibility reasons with older DPL versions.

===noresultsfooter===
{{DPL parameter
 |name   = noresultsfooter
 |purpose= output a footline if there is no article to display (empty result).
}}

Syntax: <code>noresultsfooter=''some wiki text''</code>

Note: <code>noresultsfooter</code> is essentially the same as <code>noresultsheader</code>. If there is no output to display the difference between header and footer becomes incredibly marginal ..

==Adding meta data to the output==
===addcategories===
{{DPL parameter
 |name   = addcategories
 |purpose= Shows all categories to which an article belongs as a small text line after the article name.
}}

Example:

<pre><nowiki>
{{#dpl:
|category       = DPL3
|addcategories  = true
}}
</nowiki></pre>
{{#dpl:
|category       = DPL3
|addcategories  = true
}}


This will show all DPL pages together with a list of categories per article. Of course "DPL" will be present in each entry of the list.

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

===addpagecounter===
{{DPL parameter
 |name   = addpagecounter
 |purpose= Shows number of times the page has been viewed according to the definition of the 'page_counter' field on [[mw:Page_table|Page_table]].
}}

Example:

<pre><nowiki>
{{#dpl:
|category       = Africa
|ordermethod    = counter
|order          = descending
|addpagecounter = true
|count          = 5
}}
</nowiki></pre>

This will show the 5 most popular articles about Africa.

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

===addpagesize===
{{DPL parameter
 |name   = addpagesize
 |purpose= Shows the size of the page.
}}

Example:

<pre><nowiki>
{{#dpl:
|category       = Africa
|ordermethod    = size
|order          = descending
|addpagesize    = true
|counter        = 5
}}
</nowiki></pre>

This will show the 5 biggest articles about Africa.

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

===addcontribution===
{{DPL parameter
 |name   = addcontribution
 |purpose= shows how much a user contributed to an article.
}}

Syntax:

<code>addcontribution=true</code>

If omitted, the default is ''false''.

Using this parameter will restrict your output to articles which were edited recently (This is usually one week or one month, according to the setup of your wiki).

You will get a link to the contributor and an "asterisk bar" which indicates how many bytes in the article were changed by that user.

You will also have the built-in [[Help:DPL format variables|variables]] %CONTRIBUTOR%, %CONTRIB% and %CONTRIBUTION% available to be used in your own {{DPL|format}}</code> statement.

===adduser===
{{DPL parameter
 |name   = adduser
 |purpose= Requires ordermethod=[...,]firstedit or ordermethod=[...,]lastedit (where the [...,] signifies a complex ordermethod with extra parameters). If firstedit (lastedit), 'adduser=true' displays the user who made the first (last) revision of the page. In this way the parameter is equivelent to the {{DPL|addauthor}} ({{DPL|addlasteditor}}) parameter (see below).
}}

Syntax:

<code>adduser=true</code>

If omitted, the default is ''false''.

Example:

<pre><nowiki>
{{#dpl:
|category    = Africa
|ordermethod = lastedit
|adduser     = true
}}
</nowiki></pre>

This will output a list of pages belonging to <nowiki>[[Category:Africa]]</nowiki>, prepending each result with the author of the last revision.

Note: if '{{DPL|mode}}={{DPL|userformat}}' the user can be referenced as the built-in variable {{DPL|format|%USER%}}.

===addauthor===
{{DPL parameter
 |name   = addauthor
 |purpose= show the user who created the article
}}

Syntax:

<code>addauthor=true</code>

If omitted, the default is ''false''.

Example:

<pre><nowiki>
{{#dpl:
|category    = Africa
|addauthor   = true
}}
</nowiki></pre>

This will output a list of pages belonging to <nowiki>[[Category:Africa]]</nowiki>, which shows the user who edited the initial revision of that page.

Note: addauthor and addlasteditor '''cannot be used within the same DPL query'''

===addlasteditor===
{{DPL parameter
 |name   = addlasteditor
 |purpose= show the user who edited the most recent revision of a page
}}

Syntax:

<code>addlasteditor=true</code>

If omitted, the default is ''false''.

Note: addauthor and addlasteditor '''cannot be used within the same DPL query'''

===addpagetoucheddate===
{{DPL parameter
 |name   = addpagetoucheddate
 |purpose= Shows date/time of last change to the page according to the definition of the 'page_touched' field on [[mw:Page_table|Page_table]].

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

Example:

<code>addpagetoucheddate=true</code>

If omitted, the default is ''false''.

Example:

<pre><nowiki>
{{#dpl:
|category=Africa
|ordermethod=pagetouched
|addpagetoucheddate=true
}}
</nowiki></pre>

This list will output a list of pages belonging to <nowiki>[[Category:Africa]]</nowiki>, prepending each result with the date of last change (formatted according to your local mediawiki date display preferences or the user's preferences if logged in).

Note: in 'mode=userformat' this date can also be referenced as a built-in variable %DATE%. The formatting of the date can be influenced using [[Help:DPL/Parameters:_Controlling_output_format#userdateformat|userdateformat]]. The date is translated to your local time zone (if defined in your preferences) or to the server's time zone.

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

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

Purpose:

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

Example:

<code>addeditdate=true</code>

If omitted, the default is ''false''.

Example:

<pre><nowiki>
{{#dpl:
|category=Africa
|ordermethod=lastedit
|addeditdate=true
}}
</nowiki></pre>

This list will output a list of pages belonging to <nowiki>[[Category:Africa]]</nowiki>, prepending each result with the date of last revision (formatted according to your local mediawiki date display preferences or the user's preferences if logged in).

Note: in 'mode=userformat' this date can also be referenced as a built-in variable %DATE%. The formatting of the date can be influenced using [[Help:DPL/Parameters:_Controlling_output_format#userdateformat|userdateformat]].  The date is translated to your local time zone (if defined in your preferences) or to the server's time zone.

===addexternallink===
{{DPL parameter
 |name   = addexternallink
 |purpose= add the URL of an external link to the output list.
}}

Purpose:

Allows to display external links found in articles.

Example:

<code>addexternallink=true</code>

If omitted, the default is ''false''.

Note: The command makes only sense in combination with {{DPL|linkstoexternal}}.

===addfirstcategorydate===
{{DPL parameter
 |name   = addfirstcategorydate
 |purpose= Shows the date/time the article got added to one of the listed include categories. If there are more than one categories listed and an article belongs to more than one of them, the result is ambiguous.

From a logical point of view it is recommended to include one category only with 'category' parameter or to make sure that each of the article in the result belongs to only one of the categories listed.
Conflicts with other "add*date" (addeditdate, etc.) parameters to avoid confusion.
}}

Example:

<code>addfirstcategorydate=true</code>

If omitted, the default is ''false''.

Example:

<pre><nowiki>
{{#dpl:
|category             = Africa
|addfirstcategorydate = true
}}
</nowiki></pre>

This list will output a list of pages belonging to <nowiki>[[Category:Africa]]</nowiki>, prepending each result with the time and date (formatted according to your local mediawiki date display preferences or the user preferences if user logged in).

Note: in 'mode=userformat' this date can also be referenced as a built-in variable %DATE%. The formatting of the date can be influenced using [[Help:DPL/Parameters:_Controlling_output_format#userdateformat|userdateformat]].  The date is translated to your local time zone (if defined in your preferences) or to the server's time zone.

===showcurid===
{{DPL parameter
 |name   = showcurid
 |purpose= page links will contain the current page id
}}

Example:

<code>showcurid=true</code>

If omitted, the default is ''false''.

Example:

<pre><nowiki>
{{#dpl:
|category             = Africa
|showcurid            = true
}}
</nowiki></pre>

This DPL command will output a list of pages belonging to <nowiki>[[Category:Africa]]</nowiki>; the hyperlinks to these pages look normal, but they have an additional parameter named 'curid' which contains the numeric id of the linked page. Using this type of link may be somewhat faster than using the title only. This kind of link is useful for some web spiders (e.g. google spider needs a unique id within the pagelink) and it works even if the title has moved.

<code>showcurid=true</code> cannot be used together with <code>openreferences=true</code>.

==Include contents from the articles in the result set==
===include===
{{DPL parameter
 |name   = include
 |purpose= include pages (whole content) or include certain sections of articles or template parameters.
''This functionality is based on the ideas and work of Steve Sanbeg and his extension [[mw:Extension:Labeled_Section_Transclusion|Labeled Section Transclusion]]. DPL comes with a modified version of Sanbeg´s source, so there is no need for additional installation.''
}}

With <code>include</code> you can incorporate one or more of the following
* the whole article as it is
* a certain chapter -- identified by its headline
* a certain chapter -- identified by its position (sequence number, regardless of level)
* parameter(s) used in template calls
* the output of a surrogate template (phantom template) which is used instead of the original template
* pieces of text which are marked by special section markers

There is a close correlation between the output of the <code>include</code> statement and {{DPL|table}} and {{DPL|tablerow}}. You should understand those statements if you want to create tabular output from included content.

Syntax:

====include whole article====
To include a '''whole page''', use a wildcard: 

:<code>include=*</code>
:you can use <code>includemaxlength=[n]</code> to restrict the included text to a portion of the article. The text is truncated in a way which will not spoil tag structures or bracket nestings. It will be cut at a word boundary if possible.

====include chapters====
To include '''sections (chapters) by a reference to their heading''': use the heading name with a "#" as prefix. This will include text from the first occurrence of the heading 'heading1' (resp. 'heading2') until the next heading of the same or lower level. (Refer to [[mw:Extension:Labeled_Section_Transclusion#Transcluding_visual_headings|Transcluding visual headings]].). Specifying a single "#" will include the text up to the first heading. Note that the text comparison is ''case insensitive''. 

* Note that this functionality is also available as a separate parser function (called [[Help:DPL/Dplchapter]]).

* Normally your text pattern will be compared ''literally'' and it must match the whole headline of the chapter. If you use a ''double hash sign'' ('''##'''), however, the text will be taken as a regular expression. It will automatically be enclosed within slashes and the matching will be case insensitive and will refer to the headline as a whole (^regexp$). So if you only want to match part of the text you must add ".*" around your pattern. It is your responsibility to provide correct regexp syntax. Otherwise you may see runtime errors, get no output etc.
:<code>include = ##.*omethin.*</code>
:The above will match a Headline like "This is something old" or "That Was Something Old".
* Instead of the #-sign the @-sign can be used (the # lead to problems in certain cases); @@ will act as a regexp comparison just as ## does.
*Add one or more optional filter expressions, a character limit and/or an optional link text in square brackets to shape the included portion of text : <code>[filter 1~...~filter n~limit text]</code>.
** the filters will be applied before calculating the length of the text; they simply throw away the matching part of the contents. 
** If the remaining text is longer than the limit, it will be cut and a link will appear which points directly to the chapter which was included. Using "1" as a limit will only show the link (if the corresponding chapter in the article is not empty), "0" will not show anything, not even the link. When truncating included text portions care is taken ''not to spoil wiki syntax'' (i.e. maintain a symmetry of brackets and braces, make sure that ''nowiki'' and ''pre'' tags are balanced). Therefore, the size of the included text can deviate from what you specified.

*If there is no chapter with the specified heading the output will be empty.
:<code>include = #heading1,#heading2[filter~limit linktext],....</code>

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

* To include sections (chapters) by a reference to their '''position in the text''': use a simple number with a "%" as prefix. "%0" will include the text BEFORE the first chapter, "%1" will include the first chapter, %6 the sixth and so on. Chapters are counted regardless of their level. No nesting logic is applied. "%-1" is a special value which refers to the '''last''' chapter of an article (%-2 will ''not'' work, however). "%2[30]" will include the first 30 characters of the second chapter. %SECTION% will contain the heading of the selected chapter. See [http://web.archive.org/web/20160530125613/http://semeb.com/dpldemo/index.php?title=Test_include_sections_by_number Test include sections by number].

:<code>include = %1[100]</code>
includes the first 100 characters of the first chapter

====include contents related to templates====
* You can include '''the result of a template call''' by specifying the template name within curly braces. So, <code>include={my template}</code> will display the result of the template call with the original parameters used on the selected article page.
Note that you need a space char or a line break after this statement before ending the #dpl parser function call because otherwise the MW parser may be fooled by three successive closing curly braces.

* MediaWiki treats spaces like underscores. Therefore ''{my template}'' will also match a template invocation like <nowiki>{{My_template|...}}</nowiki>.

* MediaWiki searches for template calls in the template namespace. Specifying ''{my template}'' will also match a template invocation like <nowiki>{{Template:My_template|...}}</nowiki>.
* Using a different namespace also works: ''{Xyz:my template}'' will match a template invocation in namespace Xyz. ''{:my template}'' will match a template invocation in the main namespace like <nowiki>{{:my template|...}}</nowiki>.

* You can include '''one or more parameters of a template call''' by specifying a list of names or position numbers separated by colons (and optional white space). Names are use for named parameters, numbers for positional parameters.

:<code> include={animal}:age:size:1</code>
:This will include the values of the two parameters named 'age' and 'size' and the value of the first unnamed parameter in all calls of the template "animal".

It is even possible to use expressions which contain a % symbol as pseudo parameters:
:<code> include={animal}:age:%PAGE%:size:1</code>
:This will output the page name after the 'age'; this is useful in combination with the {{DPL|table}} statement when using a '-' symbol as the second argument for 'table'. This combination makes it possible to produce a list where the link to the article need not be in the first column; enclosing the %PAGE% in double square brackets would create a link, see the second example in [http://web.archive.org/web/20160306041047/http://semeb.com/dpldemo/index.php?title=Test_table Test table]

* Instead of collecting parameter values you can '''include the output of a 'surrogate' template''' (also called a 'phantom template'). DPL calls this template instead of the original template with the identical parameter list (plus the two additional parameters %PAGE% and %TITLE%). You will get the output of the surrogate template. To make this happen you specify the name of a template within single curly braces and add a suffix. As said before, the template name ''including the suffix'' will be '''called instead of the original template''', with the same parameters, and the result will contain just the output of your alternate template (see [http://web.archive.org/web/20160310132723/http://semeb.com/dpldemo/index.php?title=Examples_of_including_a_template example]).  Note that we pass five additional parameters to each template, called
** %PAGE%
** %TITLE%
** %DATE%
** %USER%
** %CATLIST%
They allow the template to produce a link to the source file from where it was included, show the date from the DPL query (e.g. lasteditdate) and show the user from the query (e.g. the user who made the last edit).<br>
If a page listed in your result '''does not use the specified template''' you will get the possibility to react properly as the DPL engine will call a template with the additional suffix ".default".

:Example: includepage={myTemplate}.dpl
:If a page does not contain a reference to "Template:myTemplate" then "Template:myTemplate.dpl.default" will be invoked with %PAGE% and %TITLE% as parameters.

* There is an alternate syntax to specify a surrogate template. It has the advantage that the surrogate template may reside in a different namespace than the original template. Also, the surrogate template's name can be completely different from the original template name: <code>{template¦surrogate template}</code>. For example, you may specify something like <code>{my template¦Help:Substitution for my template}</code>.

==== include parser function calls ====
* if you specify a pattern like <code>{#pfunc}.list</code> DPL will look for calls of the parser function 'pfunc'. DPL will pass the parameters of this parser function to a template which you have to provide under the name of 'Template:pfunc.list'. Instead of '.list' you can use your own suffix. The Template will receive the parser function name as %PFUNC% and all parameters under their normal name or number. Instead of specifying a single parser function you can also use a generic pattern. See [http://followthescore.org/dpldemo/index.php?title=DPL_Example_026 DPL Example 026]. Note that this function is not very robust. It cannot handle nested parser functions properly.

====include parser extension calls====
* if you specify a pattern like <code>{~func}.list</code> DPL will look for calls of the parser extension with the tag name &lt;func&gt;. DPL will pass the body of the tag structure to a template which you have to provide under the name of 'Template:func.list'. Instead of '.list' you can use your own suffix. The Template will receive the function name as %TAG% and the body will be named %TAGBODY%. See [http://web.archive.org/web/20160310133416/http://semeb.com/dpldemo/index.php?title=DPL_Example_028 DPL Example 028]. Note that this function is not very robust. It cannot handle nested tags properly.

====include specially labeled text portions====
* To include '''sections which are labeled''' with special tags you just mention the tag name. Refer to [[mw:Extension:Labeled_Section_Transclusion|Labeled Section Transclusion]] for details on how to label sections in your pages accordingly: 

:<code>include=sec1,sec2,...</code>

If the section name starts with a '*' the asterisk will be cut off and the rest of the text will be taken as a regular expression. If the section name is '**' it will match all section names. In both cases the tag name will precede the output, separated by '::'.

See [http://web.archive.org/web/20160310132821/http://semeb.com/dpldemo/index.php?title=Test:Section_inclusion Test:section inclusion]

====include nothing====
* To '''include nothing''' from the page (no inclusion), leave blank (this is '''default'''):
:<code>include=</code>
* A single '-' sign has the same effect; such a dummy parameter can be useful if you want to put content into columns of the output table which is not derived from the include statement

====combinations of the above possibilities====
All of the above can be combined, you can even refer to the same template or heading more than once.

:<code>include = {template1}suffix1,{template1}:p1:p2:2,#headline,marker,....</code>

----

Example:  <code>include = foo,#bar[200 ..more..],#bang[0 img=my.gif],{boo}.dpl</code>

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

Note: See also [[Help:DPL/Parameters: Criteria for page selection#includematch]].

===includepage===
{{DPL parameter
 |name   = includepage
 |purpose= this can be used as a longer name for {{DPL|include}}.
}}

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

Syntax:
:<code>includemaxlength=[n]</code>

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

===includetrim===
{{DPL parameter
 |name   = includetrim
 |purpose= removes all leading and trailing whitespace from transcluded contents.
}}

Syntax:
:<code>includetrim=true</code>   (default is ''false'')

Note: this parameter is only useful in combination with <code>include=</code>.