Help:DPL Manual/Other parameters

updaterules
Syntax:

Where rule is one of the following:

replace  pattern; by       replacement; before   pattern; insert   text; after    pattern; insert   text;
 * rules for batch update of articles

template template name; legend   legend article name; table    table format; editform form parameters; action   form action; hidden   value; submit   submit button; commit   commit button; parameter parameter name; value     value; format    display format; tooltip   text; optional  value; afterparm parameter name;
 * rules for interactive update of articles

summary  edit summary text; exec     value;
 * common rules

The first group of rules is intended for batch updates of articles. A DPL query can select a group of articles and perform updates like inserting a piece of text at a certain position or changing text portions based on regular expressions.

The second group of rules is intended for interactive form-based editing of template values.

The third group of rules is common to both other groups and controls the update process.

The  feature is intended for wiki expert users only. It is recommended that articles usind this statement are 'protected':

replace pattern;
Defines a regular expression which matches text portions that shall be replaced. It is in the responsibility of the user to provide enclosing characters for the regexp; modifiers line 'U' or 'm' can be used.

by replacement;
Defines the replacement for the above pattern; back references like \1 can be used.

before pattern;
Defines locations where text will be inserted. The location(s) will be immediately before the match(es) of the pattern. If a pattern matches multiple times, multiple inserts will be performed.

The regexp will implicitly be enclosed in slashes. Hence literal slash characters must be escaped by backslashes.

after pattern;
Defines locations where text will be inserted. The location(s) will be immediately after the match(es) of the pattern. If a pattern matches multiple times, multiple inserts will be performed.

The regexp will implicitly be enclosed in slashes. Hence literal slash characters must be escaped by backslashes.

insert text;
Defines the text to be inserted.

A DPL statement may contain replacement, insertion before and after at the same time. replace /([a-z]+])-cat/; by     \1-dog; before foo; insert bar; after foo; insert bar2;

Only one 'replace'-'by' sequence, one insertion 'before' and one insertion 'after' can be specified. 'replace' is always executed first, followed by 'insert before' and 'insert after', regardless of the sequence in which the rules appear in the DPL source ´text.

template template name;
The name of the template; the prefix "Template:" must be given.

be inserted. The location(s) will be immediately before the match(es) of the pattern. If a pattern matches multiple times, multiple inserts will be performed.

The regexp will implicitly be enclosed in slashes. Hence literal slash characters must be escaped by backslashes.

a regular expression after    pattern; insert   text; replace  pattern; by       replacement;

For safety reasons the update statements will only be performed if "exec yes" is specified. So, leaving this away, you can check what would happen if the update were to be executed.

Note that if "exec yes" is present the update will be performed each time the page is renderes which contains the DPL statement with the. So it is advisable to set "exec yes" only via a command line argument and not as part of the statioc article text. Thus you stay in control when the update happens. Typically one would use an URL parameter like DPL_arg1 for that purpose.

The size of the form fields will dapt to the size of the displayed content.

To make the use of the  feature easier we provide a special user interface.

text is plain text; replacement is text which may contain references (like \1) to the matching pattern (provided that this pattern contains match groups).

deleterules
This command is experimental at the moment.

This will delete the selected pages; If "exec true" is missing, nothing will happen.

goal
Syntax:

Explanation:

Default is 'pages', which means that DPL produces a list of pages. And this is exactly what the name DPL promises.

If you set the goal parameter to 'categories' the list of pages will still be produced but you won´t see it. Instead it will be used to calculate a unique ordered list of all categories these pages belong to.

This allows you to ask a question like: Given all pages that are 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 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 you can use all DPL formatting options (mode=userformat, listseparators, columns etc.) and pseudo variables (%TITLE%, %PAGE%) to customise the layout of your 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.

allowcachedresults
Syntax:

Explanation:

Default is FALSE, so normally DPL will disable the parser cache before it produces a result. Disabling the cache produces some extra server load but guarantees always correct results.

So, if you do not use this parameter you will always get a result which is based on the latest changes made on any articles. But in many cases you could have gotten the same result with using less server resources!

If you set 'allowcachedresults=true', the parser cache will be used. That means, your results might be a little bit outdated (usually one hour or so). But there are less resources used on the server side. You might want to experiment with that parameter and check the size of load reduction (i.e. gain in term of response time).

If you allow cached results you can still enforce DPL to produce a correct result via using "&action=purge" in the command line.

'yes+warn' will use the cache; in addition the result will contain a warning indicating that the result may be out-dated. This is achieved by including the template DPL Cache Warning into the result header. It is up to you to provide a useful text under that name, see e.g. Template:DPL Cache Warning.

reset
Syntax:

, where keyword is one of:
 * categories
 * templates
 * images
 * links
 * all &mdash; 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  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: linking to Q Link and showing and using ... 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 &lt;DPL&gt;):
 * 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  on your 'own' links you can use. 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 fuction mode ( ):


 * 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  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, you can use. 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. 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.

fixcategory
Syntax:

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

If you use  or   the article containing your DPL statement will not be recorded in the  mediawiki link database. This may be quite useful if your article transcludes content from other pages. Without the  command your article would appear in a category if you included a text portion containing an assignment to that category.

As a side effect of using  your article will not appear in a category even if you literally assign it to one. The  allows you to make a category assignment which is not blocked by the  command.

eliminate
Syntax:

Where  is one of:


 * &mdash; a synonym for all of the above
 * &mdash; a synonym for all of the above
 * &mdash; a synonym for all of the above
 * &mdash; a synonym for all of the above
 * &mdash; 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 ) 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  parameter will suppress all or some of the effects described above.

For further explanation see.

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

debug
Syntax:

, where n is one of:
 * 0 &mdash; silent mode, shows nothing
 * 1 &mdash; quiet mode, shows (fatal) errors
 * 2 &mdash; default mode, like 1 + shows warnings; &mdash; (default)
 * 3 &mdash; verbose mode, like 2 + shows SQL query.
 * 4 &mdash; for internal use only
 * 5 &mdash; show Wiki text output from DPL instead of parsed wiki text
 * 6 &mdash; show SQL query but DO NOT EXECUTE the query.

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  and above.

Example:

 namespace=Media debug=0 namespace=Special 

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

DPL debug messages are translatable in. See also variables.

'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 statement.

execandexit
Syntax:

or

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 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 &cat=Country would list countries, omitting the &cat parameter would trigger the error text mnessage (without DPL going to the database):

See also: Template:Extension DPL scroll and DPL Example 020 and Scrolling

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

dplcache
Syntax:

name must be a symbol which is unique for the DPL statement WITHIN your page. As you will in most cases have only one DPL statement in your page, a simple symbol like '1' will be o.k.

Purpose:

Save processing time and avoid unnecessary resource consumption. You can decide how long the result of a DPL query shall be considered to be reasonably 'valid'. This may be longer or shorter than the ParserCacheExpiration time which you have configured in your LocalSettings.php.

The DPLcache will even survive editing of the page which contains the DPL statememnt as long as the DPL statement remains unaltered.

Details:

The cache is automatically registered under the page_id of your article. So there is no need to specify the page name or something similar here. Currently the cache is held in the file system (this may cahnge to the database in one of the next releases).

As the cache works on page_id level it will only affect the most recent version of each page. When viewing older revisions it may be useful to add &DPL_refresh=yes to the URL to make sure that the cache is rebuilt (if this is really desirable).

If your page uses scrolling you can provide an advanced cache which will take each result page (if it is viewed). In this case the name should look like this: This will create a separate cache entry for each result page. If one of these pages is purged (i.e. the cache is to be refreshed), all corresponding pages will be thrown away as well. See DPL Example 022 to understand the details of this mechanism.

The following principles apply to caching:


 * By default MW uses a ParserCache with an expiration of 24 hours. The expiration period can be influenced via $wgParserCacheExpireTime.
 * Once a page is in the ParserCache DPL will not be invoked any more as long as the cache is considered to be up-to-date. For this reason DPL normally DISABLES the MW ParserCache.
 * On really huge websites you may still want to use the MW ParserCache in addition to the DPL cache. You can do so via setting 'allowcachedresults=true' as part of your DPL statement. Alternatively the administrator can configure DPL in a way that 'allowcachedresults=true' is the general default for DPL statements (set ExtDynamicPageList::$respectParserCache = true; after the require_once for DPL).
 * If DPL is used together with an active ParserCache DPL can only check its own cache as soon as the MW ParserCache has expired, i.e. you cannot have a shorter period for the DPL cache than the MW ParserCache has.
 * You can always enforce the MWParserCache to be purged by adding &action=purge to the URL of a page. This will enforce a page refresh and DPL will be invoked. It can then find out if it still wants to rely on its DPL cache content or if it wants to re-execute the query against the database to produce the latest results and update its cache with that result.
 * Purging the ParserCache will silently be accepted for usres who are logged in; anonymous users will get a "do you really want ..." confirmation box.
 * Note that if your page contains more than one DPL statements, all of them need to set 'allowcachedresults=true' to avoid switching off the MW ParserCache. If, on the other hand, keeping the ParserCache is configured as DPL's default behaviour, the cache will be disabled as soon one of several DPL statements of a page explicitly switches it off via 'allowcachedresults=no'.
 * Regardless of the DPL configuration in your LocalSettings.php the &lt;DynamicPageList&gt; tag will always use the ParserCache (for reasons of compatibility with older versions of Dynamic Page List aka Extension:Intersection).
 * If a page is being served from the MW ParserCache there will be a respective comment in the HTML text - but the user will not get any notice. He may be surprosed however, that a page reflects 'outdated contents' although he has just made a change which should have had an impact on the DPL result being displayed.
 * If you use the 'dplcache' command the user will see a little box under the DPL result which indiactes that the DPL cache has been used. It tells the user how old the content is and it can reduce the amount of annoyance caused by outdated results being taken from the cache. The note also offers a refresh button. If the MW ParserCache is active, however, this mechanism cannot work.
 * Using the FlaggedRevisions Extension together with DPL caching adds another level of complexity as that extension uses an additional cache ("StableParserCache").

dplcacheperiod
Syntax:

The default is 86400 seconds, i.e. one day.