Other parameters

Manual	Parameters	Other parameters

debug

debug	Sets debugging level.

Syntax:

debug=n, where n is one of:

0 – Silent mode, shows nothing.
1 – Quiet mode, shows (fatal) errors.
2 – Default mode, like 1 + shows warnings; – (default).
3 – Verbose mode, like 2.
4 – Dump raw SQL Query; only if $wgDebugDumpSql is set to true.
5 – Show wiki text output from DPL4 instead of parsed wiki text.

Note: If the debug parameter is not used in the first position of the DPL4 statement, the new debug settings are not applied before all previous parameters have been parsed and checked. This generates a warning for debug=2 and above.

Example:

This statement sets the DPL4 debug output to 5, which outputs the full wikitext result of the query after listing the extension itself. The query selects one article from Category:Fruit examples, puts the title in the first column automatically (default behavior), then includes the "Fruit-Infobox" template's "grows" parameter value, in the second column. The table statement sets the table styles and header text. The first argument of tablerow corresponds to, and formats the second column content to bold, using %% to position the value precisely within the formatting.

{{#dpl:
|debug    = 5
|category = Fruit examples
|include  = {Fruit-Infobox}:grows
|table    = class="wikitable sortable",Page,The "grows"<br>parameter value
|tablerow = <b>%%</b>
|count    = 1
}}

Test in sandbox

View Result

Result:

Debug 5 output:

{|class="wikitable sortable"
!Page
!The "grows"<br>parameter value
|-
|[[Apple|Apple]]
|<b>On trees</b>
|}

Output without debug (for comparison):

Page	The "grows" parameter value
Apple	On trees

Notes:

DPL4 debug messages are translatable in DynamicPageList2.i18n.php.
debug=1 suppresses warning messages (e.g., if the result set of a DPL4 query is empty).

allowcachedresults

allowcachedresults	Cache query results to improve performance, keep servers from crashing under high load.

Syntax:

allowcachedresults=value where value is one of:

true – (default, need not be set).
false – prevent caching.

Notes:

All queries are cached by default to reduce server load, as generally articles do not change often enough to require updating every page load.
If immediate updates are required every page load, such as for displaying scroll navigation via URL parameters, then set this parameter to false.
Cache period is handled by the cacheperiod parameter.

cacheperiod

cacheperiod	Defines the expiration period for the DPL4 cache.

Syntax:

cacheperiod=number of seconds – (default is 3600, meaning 1 hour).

goal

goal	Set the goal for DPL4 to either show pages (default) or categories these pages belong to.

Syntax:

goal=goaltype where goaltype can be one of:

pages – (default, need not be set).
categories.

DPL4 produces a list of pages by default, and this is precisely what the name DPL4 promises.

If the goal parameter is set to 'categories' the list of pages is still be produced, but is not seen. Instead, it is used to calculate a unique ordered list of all categories these pages belong to.

This allows the asking of question like: Given all pages that are a member of category X with a title matching "y%" and which use template "Z": to which categories do these pages belong?

One of the more useful applications would be a question like: "To which categories do the pages belong which contain a reference to the current page?"

The output of goal=categories is technically a list of pages of type category. This means that all DPL4 formatting options can be used (mode=userformat, listseparators, columns etc.) and pseudo variables (%TITLE%, %PAGE%) to customize the layout of the report.

Technical Note:

Due to some limitations in MySQL, it is currently not possible to restrict the intermediate result set of pages to a certain maximum (using the LIMIT clause). In addition, the generated SQL code is not in all cases optimal (as its structure provides for complex selection criteria and therefore is unnecessarily complex in simple cases). So be careful and apply precise selection criteria.

eliminate

eliminate	Suppress references to pages, templates, images, categories in DPL4 output

Syntax:

eliminate=keyword,.. where keyword is one of:

categories
templates
images
links
all – A synonym for all of the above.

The output of a DPL4 statement typically creates links to all pages which are part of the result set. The inclusion of contents from other pages via DPL4 (using include) normally has these consequences:

The page containing the DPL4 query becomes part of the categories of the transcluded page.
It shares ('adopts') their use of templates.
It shares their references to images.
It shares their references to other articles.

In some cases, this may be useful. But in many cases, this is not wanted. Especially when DPL4 is used to create a printable document which contains the full text of other articles, duplicating all links, template uses etc., of those articles is probably undesired.

The eliminate parameter suppresses all or some of the effects described above.

For further explanation, see reset.

Note: The use of eliminate needs a considerable amount of extra computing power as it performs a second parser step for each included document.

reset

reset	Suppress references to pages, templates, images, categories in DPL4 output

Syntax:

reset=keyword,.., where keyword is one of:

categories
templates
images
links
all – A synonym for all of the above.

The output of a DPL4 statement typically creates links to all pages which are part of the result set. The inclusion of contents from other pages via DPL4 (using include) normally has the consequences:

The page containing the DPL4 query becomes part of the categories of the transcluded page.
It shares ('adopts') their use of templates
It shares their references to images
It shares their references to other articles.

In some cases, this may be useful. But in many cases, this is not wanted. Especially when DPL4 is used to create a printable document which contains the full text of other articles, duplicating all links, template uses etc., of those articles is probably undesired.

The reset parameter suppresses all or some of the effects described above.

There are some subtle differences here depending on the mode in which DPL4 is used. These differences affect the question of how links, and categories etc., are treated which are direct part of the document containing the DPL4 query. Example:

[[Category:Q Cat]] linking to [[Q Link]] and showing [[Image:Q Image]] and using {{Q Template}}
... DPL4 query which includes contents from other articles.
    assuming that this contents contains links and images, 
             that it uses templates and that the articles are part of one or more categories
    RESET statement at the end of the DPL4 query with one or more of 'categories,templates,images,links'
...

In parser extension mode (tag like <dpl>):

reset=categories – Ignores categories of included contents but keeps 'own' categories like 'Q Cat'.
reset=images – Throws away references to images contained in included contents but keeps 'own' images like 'Q Image'.
reset=templates – Ignores templates used in included contents but keeps 'own' template usage ('Q Template').
reset=links – Throws away all references to other pages, i.e., links contained in included contents and links like 'Q Link' are ignored. This means all links can be used in the normal "FORWARD" way, but no "BACKLINKS" are available for them.

To avoid the above described effect of reset on one's 'own' links, eliminate can be used. However, it is important to note that eliminate is rather expensive in terms of computer power, as it does a second parse for all included contents.

In parser function mode ({{#dpl:....}}):

reset=categories – Ignores all categories.
reset=images – Throws away all references to images.
reset=templates – Ignores all template invocations.
reset=links – Throws away all references to other pages.

Using reset in parser function mode clears everything, regardless of whether it comes from included contents or whether it is direct part of the document containing the DPL4 query.

To avoid the above described effect of reset, eliminate can be used. However, eliminate is rather expensive in terms of computing power, as it does a second parse for all included contents. The extra parser step is conducted as soon eliminate is specified. In terms of extra processing needed, it does not make a difference whether one or more arguments are specified for the eliminate command.

If there is more than one DPL4 query in a page, the effects depend on the exact mode (parser extension or parser function mode), on the sequence of the statements and on the presence of 'reset' or 'eliminate' statements in each of the queries and on their individual arguments. As this is a very rare case, only a simple rule of thumb is given here: Once 'reset' is used in parser function mode or reset=links in parser extension mode, the effect of these statements dominates the rest.

fixcategory

fixcategory	Assign the article containing a DPL4 statement to a category, although `reset` was used.

Syntax:

fixcategory=category name

Use multiple commands to assign the article to more than one category.

If reset=all or reset=categories are used, the article containing the DPL4 statement is not be recorded in the MediaWiki link database. This may be quite useful if an article transcludes content from other pages. Without the reset command, the article would appear in a category if a text portion containing an assignment to that category was used.

As a side effect of using reset=all, the article does not appear in a category, even if one is literally assigned to it. fixcategory allows a category assignment to be made which is not blocked by the reset command.

execandexit

execandexit	Process the command given as an argument and then exit immediately.

Syntax:

execandexit=wiki text
or
execandexit=geturlargs

If no wiki text is given, the command is ignored. Otherwise, DPL4 outputs the wiki text and exits immediately. Note that the wiki text may be a parser function call which evaluates to an empty string.

Example:

{{#dpl:execandexit  = geturlargs}}
{{#dpl:
|category           = Fruit examples
|count              = {%DPL_count:3%}
|offset             = {%DPL_offset:0%}
|scroll             = yes
|include            = {Fruit-Infobox}:grows:image[15...]
|table              = class="wikitable sortable", Page, Parameter, Description
|resultsheader      = ²{DPL4 scroll¦total={{PAGESINCATEGORY:Fruit examples|R}}¦offset={%DPL_offset:0%}¦count={%DPL_count:3%}¦page={{FULLPAGENAME}}}²\n
|resultsfooter      = ²{DPL4 scroll¦total={{PAGESINCATEGORY:Fruit examples|R}}¦offset={%DPL_offset:0%}¦count={%DPL_count:3%}¦page={{FULLPAGENAME}}}²\n
|allowcachedresults = false
}}

Test in sandbox

View Result

Result:

1..34..6(8 total)

Page	Parameter	Description
Apple	On trees	Red Apple
Apricot	On trees	Apricot_whole44
Banana	On a tree-like plant	Banana-Single.j

1..34..6(8 total)

The special word geturlargs can be used as a wiki text to transform URL arguments starting with DPL_ into variables, which can then be accessed via #var (if the Variables extension is installed) or via #dplvar.

Using this command, DPL4 can be prevented from executing a database query; this may be useful if the user did not give a necessary parameter. Note that an {{#if:}} (Parser Functions extension) function call would NOT help in that case because #if evaluates its complete content before taking the "if" or the "else" path. So, embedding a DPL4 call within an #if is much less efficient than using the execandexit function.

Example:

A typical use appears like the following, the execandexit statement transforms URL args to variables, and the {{#dplvar:set}} sets the value of DPL_cat variable to Category:Dessert examples. Note: The double pipe symbols within the #if. Calling the following page with &DPL_cat=Country examples would list countries, omitting the &cat parameter would trigger the error text message (without DPL4 going to the database):

{{#dpl:execandexit = geturlargs}}{{#dplvar:set|DPL_cat|Category:Dessert examples}}
{{#dpl: 
|execandexit     = {{#if:{{#dplvar:DPL_cat}}||please specify a category via &DPL_cat= in the URL!}}
|resultsheader   = Pages in <i>{{#dplvar:DPL_cat}}</i>:\n
|noresultsheader = There are no pages in <i>{{#dplvar:DPL_cat}}</i>.\n
|count           = 2
|category        = {{#dplvar:DPL_cat}}
}}

Test in sandbox

View Result

Result:Pages in Category:Dessert examples:

See also: Template:DPL4 scroll and scrolling.

Note: execandexit acts like a short-circuit evaluation. This means, for example, that successive statements to influence caching behavior (like allowcachedresults) are not interpreted.