Other parameters: Difference between revisions

Line 1:

{{note|This page is in development, some content may be incorrect, outdated, or otherwise misleading. |warn}}

Line 50:

Line 51:

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

The <code>updaterules</code> feature is intended for wiki expert users only. It is recommended that articles ~~usind~~ this statement are 'protected':

The <code>updaterules</code> feature is intended for wiki expert users only. It is recommended that articles using this statement are 'protected':

===Rules for batch update in detail:===

Line 62:

Line 63:

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.

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.

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

====insert ''text'';====

Line 88:

Line 89:

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.

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

a regular expression

Line 96:

Line 97:

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.

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 rendered which contains the DPL statement with the <code>updaterules</code>. 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.

Note that if "exec yes" is present, the update will be performed each time the page is rendered which contains the DPL statement with the <code>updaterules</code>. So it is advisable to set "exec yes" only via a command line argument and not as part of the static article text. Thus, you stay in control when the update happens. Typically, one would use a 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 <code>updaterules</code> feature easier we provide a [[Template:Bulk Update|special user interface]].

<!--To make the use of the <code>updaterules</code> feature easier, we provide a [[Template:Bulk Update|special user interface]].

Note: This template is deliberately not present, as it can apparently alter lots of wiki content. The line above is retained as a comment since it was part of the original DPL documentation. -->

Note: This template is deliberately not present, as it can apparently alter lots of wiki content. The line above is retained as a comment, since it was part of the original DPL documentation. -->

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

Line 133:

Line 134:

Explanation:

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

Default is 'pages', which means that DPL produces a list of pages. And this is precisely 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'''.

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?

This allows you to ask a 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 question like: "To which categories do the pages belong which contain a reference to the current page?"

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 you can use all DPL formatting options (mode=userformat, listseparators, columns etc.) and pseudo variables (%TITLE%, %PAGE%) to customise the layout of your report.

Line 145:

Line 146:

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

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==

{{DPL Parameter

|name = allowcachedresults

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

|purpose= Cache query results to improve performance, keep servers from crashing under high load.

}}

Line 160:

Line 161:

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.

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.

==reset==

Line 183:

Line 184:

* 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.

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 <code>reset</code> 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.

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

Example:

Line 202:

Line 203:

;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.

;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 <code>reset</code> on your 'own' links you can use {{dpl3|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.

If you want to avoid the above described effect of <code>reset</code> on your 'own' links, you can use {{dpl3|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.

<u>In parser function mode ('''<nowiki>{{#DPL:....}}</nowiki>'''):</u>

Line 213:

Line 214:

;reset=links: will throw away all references to other pages

As you see, using <code>reset</code> 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.

As you see, using <code>reset</code> 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 <code>reset</code>, you can use {{dpl3|eliminate}}</code>. 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 <code>eliminate</code>. 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 want to avoid the above described effect of <code>reset</code>, you can use {{dpl3|eliminate}}</code>. 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 <code>eliminate</code>. 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.

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==

{{DPL Parameter

|name = fixcategory

|purpose= assign the article containing a DPL statement to a category although <code>reset</code> was used.

|purpose= assign the article containing a DPL statement to a category, although <code>reset</code> was used.

}}

Line 230:

Line 231:

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

If you use <code>reset=all</code> or <code>reset=categories</code> 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 <code>reset</code> command your article would appear in a category if you included a text portion containing an assignment to that category.

If you use <code>reset=all</code> or <code>reset=categories</code> 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 <code>reset</code> 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 <code>reset=all</code> your article will not appear in a category even if you literally assign it to one.

Line 259:

Line 260:

* 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.

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 <code>eliminate</code> parameter will suppress all or some of the effects described above.

For further explanation see {{dpl3|reset}}.

For further explanation, see {{dpl3|reset}}.

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

Line 295:

Line 296:

</nowiki></pre>

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

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

DPL debug messages are translatable in <code>DynamicPageList2.i18n.php</code>. See also [[#Internationalization]].

'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 {{dpl3|suppresserrors}} statement.

'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 {{dpl3|suppresserrors}} statement.

==execandexit==

Line 313:

Line 314:

<code>execandexit=<i>geturlargs</i></code>

If no wiki text is given the command will be ignored. Otherwise DPL will output the wiki text and exit immediately.

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 <code>DPL_</code> into variables which can then be accessed via #var (if the Variables extension is installed) or via #dplvar.

The special word ''geturlargs'' can be used as a wiki text to transform URL arguments starting with <code>DPL_</code> 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.

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.

Line 351:

Line 352:

The default is 3600 seconds which is one hour.

[[Category:Primary Module]]

<!-- Extension prefix in other languages:

[[de:Erweiterung:{{subst:BASEPAGENAME}}]]

[[es:Extensión:{{subst:BASEPAGENAME}}]]

[[fr:Extension:{{subst:BASEPAGENAME}}]]

[[it:Estensione:{{subst:BASEPAGENAME}}]]

[[nl:Uitbreiding:{{subst:BASEPAGENAME}}]]

[[pl:Rozszerzenie:{{subst:BASEPAGENAME}}]]

[[pt:Extensão:{{subst:BASEPAGENAME}}]]

[[ru:Расширение:{{subst:BASEPAGENAME}}]]

[[zh:扩展:{{subst:BASEPAGENAME}}]]

-->