Help:DPL/manual/other parameters

allowcachedresults

allowcachedresults

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

Syntax:

allowcachedresults=true | false

Explanation:

Default: true 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 then set this parameter to false. The cache period is handled by the #cacheperiod parameter.

This parameter has no effect on Fandom projects since cached results is always set to true to reduce server load. The default cacheperiod is quite short though: One hour instead of 14 days for a page without DPL. In the vast majority or cases this default can be increased by one or even two orders of magnitude.

cacheperiod

cacheperiod

define the expiration period for the dplcache

Syntax:

cacheperiod=number of seconds

The default is 3600 seconds which is one hour. By comparison, the default expiration period when DPL is not involved is 1,209,600 seconds on Fandom, or 14 days. The DPL cache gets invalidated (and the page rebuilt before cacheperiod ends) when the page that hosts the DPL query is edited or whenever a page already in the results is. On the other hand, if a page that is not part of the results gets edited and starts matching the DPL query, it will not be picked up until cacheperiod ends or something else invalidates the DPL cache.

So it is perfectly fine to set the cache to 14 days for DPL queries that aren't expected to grow their number of results quickly. In most other cases, a cache of 1 day (86,400 seconds) is probably good enough.

DPL is a resource-intensive tool. Longer cache periods reduce computing costs and greenhouse gas emissions. With that said, only the first person(s) to load a page containing a DPL query whose cache has expired or is invalidated will have to wait for the servers to rebuild it.

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 DPL instead of parsed wiki text.

If you use debug param but not in first position in the DPL element, the new debug settings are not applied before all previous parameters have been parsed and checked. This will generate a warning for debug=2 and above.

Example:

{{#dpl:
 | namespace = Media
 | debug     = 0
 | namespace = Special
}}

This list will output the error for the first namespace: Media is not a valid namespace value (pseudo-namespace). Assuming you haven't changed the default debug value (2), you will also get a warning: debug=1 is not input first (before namespace=Media). So it did not apply to namespace=Media but only to what's after. Indeed, you won't get the warning for the second namespace (Special) since debug=0 changed debug settings to silent mode.

DPL debug messages are translatable in DynamicPageList2.i18n.php.

'debug=1' will suppress warning messages (e.g. if the result set of a DPL query is empty). As an alternative, you can use the suppresserrors statement.

reset

reset

suppress references to pages, templates, images, categories in DPL 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 DPL statement typically creates links to all pages which are part of the result set. The inclusion of contents from other pages via DPL (using 'include') normally has the consequence

• that the page containing the DPL query becomes part of the categories of the transcluded page
• that it shares ('adopts') their use of templates
• that it shares their references to images
• that it shares their references to other articles.

In some cases this may be useful. But in many cases this is not wanted. Especially when you use DPL to create a printable document which contains the full text of other articles you will probably not want to duplicate all links, template uses etc. of those articles.

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

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

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

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

reset=categories

will ignore categories of included contents but keep 'own' categories like 'Q Cat'.

reset=images

will throw away references to images contained in included contents but keep 'own' images like 'Q Image'.

reset=templates

will ignore templates used in included contents but keep 'own' template usage ('Q Template').

reset=links

will throw away all references to other pages, i.e. links contained in included contents and links like 'Q Link' will be ignored. This means that all links can be used in the normal "FORWARD" way, but no "BACKLINKS" are available for them.

If you want to avoid the above described effect of reset on your 'own' links you can use eliminate. But you should know 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

will ignore all categories

reset=images

will throw away all references to images

reset=templates

will ignore all template invocations

reset=links

will throw away all references to other pages

As you see, using reset in parser function mode will clear everything regardless whether it comes from included contents or whether it is direct part of the document containing the DPL query.

If you want to avoid the above described effect of reset, you can use eliminate. But you should know that 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 as you specify eliminate. In terms of extra processing needed it does not make a difference whether you specify one or more arguments for the 'eliminate' command.

If you have more than one DPL query in a document the effects will 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 we only give a simple rule of thumb here: Once you have used 'reset' in parser function mode or 'reset=links' in parser extension mode the effect of these statements will dominate the rest.

eliminate

eliminate

suppress references to pages, templates, images, categories in DPL 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 DPL statement typically creates links to all pages which are part of the result set. The inclusion of contents from other pages via DPL (using include) normally has these consequences:

• the page containing the DPL query becomes part of the categories of the transcluded page
• shares ('adopts') their use of templates
• shares their references to images
• shares their references to other articles

In some cases this may be useful. But in many cases this is not wanted. Especially when you use DPL to create a printable document which contains the full text of other articles you will probably not want to duplicate all links, template uses etc. of those articles.

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

For further explanation see reset.

Please note that the use of eliminate needs a considerable amount of extra computing power as it performs a second parser step for each included document.

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 will be ignored. Otherwise DPL will output the wiki text and exit immediately. Note that the wiki text may be a parser function call which evaluates to an empty string.

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.

Purpose:

Using this command you can prevent DPL from executing a database query; this may be useful if a necessary parameter was not given by the user. Note that an #if function call would NOT help in that case because #if evaluates its complete content before taking the "if" or the "else" path. So, emebdding a DPL call within a #if is much less efficient than using the execandexit function.

A typical use would look like this (note the double pipe symbols within the #if. Calling the following page with &DPL_cat=Country would list countries, omitting the &cat parameter would trigger the error text message (without DPL going to the database):

{{#dpl:execandexit=geturlargs}}
{{#dpl: 
 | execandexit     = {{#if:{{#dplvar:DPL_cat}}||please specify a category via &DPL_cat= in the URL!}}
 | resultsheader   = pages in category {{#dplvar:DPL_cat}}:\n
 | noresultsheader = there are no pages in category {{#dplvar:DPL_cat}}.\n
 | count           = 5
 | category        = {{#dplvar:DPL_cat}}
}}

See also: Scrolling

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

---

DPL manual (Help:DPL)