Other parameters: Difference between revisions
Content added Content deleted
imported>FrozenPlum m (Fix a couple more things I couldn't see on first edit) |
imported>FrozenPlum (Fixes and edits) |
||
Line 13: | Line 13: | ||
<code>debug=<i>n</i></code>, where ''n'' is one of: |
<code>debug=<i>n</i></code>, where ''n'' is one of: |
||
* <code>''0''</code> |
* <code>''0''</code> – Silent mode, shows nothing |
||
* <code>''1''</code> |
* <code>''1''</code> – Quiet mode, shows (fatal) errors |
||
* <code>''2''</code> |
* <code>''2''</code> – Default mode, like 1 + shows warnings; – '''(default)''' |
||
* <code>''3''</code> |
* <code>''3''</code> – Verbose mode, like 2 |
||
* <code>''4''</code> |
* <code>''4''</code> – Dump raw SQL Query; only if ''$wgDebugDumpSql'' is set to true. |
||
* <code>''5''</code> |
* <code>''5''</code> – Show wiki text output from DPL3 instead of parsed wiki text. |
||
'''If debug |
'''If the debug parameter is used, but not in first position in the DPL3 element, the new debug settings are not applied before all previous parameters have been parsed and checked.''' This generates a warning for <code>debug=2</code> and above. |
||
Line 36: | Line 36: | ||
This outputs the error for the first namespace: ''Media'' is not a valid namespace value (pseudo-namespace). Assuming the default debug value (2) hasn't been changed, a warning is also displayed: <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, the warning for the second namespace (''Special'') is not given, since <code>debug=0</code> changed debug settings to silent mode. |
This outputs the error for the first namespace: ''Media'' is not a valid namespace value (pseudo-namespace). Assuming the default debug value (2) hasn't been changed, a warning is also displayed: <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, the warning for the second namespace (''Special'') is not given, since <code>debug=0</code> changed debug settings to silent mode. |
||
DPL3 debug messages are translatable in ''DynamicPageList2.i18n.php''. |
|||
<code>debug=1</code> |
<code>debug=1</code> suppresses warning messages (e.g., if the result set of a DPL3 query is empty). As an alternative, the <code>{{DPL|suppresserrors}}=</code> statement can be used. |
||
Line 51: | Line 51: | ||
<code>allowcachedresults=''value''</code> where ''value'' is one of: |
<code>allowcachedresults=''value''</code> where ''value'' is one of: |
||
* <code>''true''</code> |
* <code>''true''</code> – ('''default''', need not be set) |
||
* <code>''false''</code> |
* <code>''false''</code> |
||
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. |
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. Cache period is handled by the <code>{{DPL|cacheperiod}}</code> parameter. |
||
Line 61: | Line 61: | ||
{{DPL Parameter |
{{DPL Parameter |
||
|name = cacheperiod |
|name = cacheperiod |
||
|purpose= |
|purpose= Defines the expiration period for the DPL3 cache |
||
}} |
}} |
||
Line 67: | Line 67: | ||
'''Syntax:''' |
'''Syntax:''' |
||
<code>cacheperiod=''number of seconds''</code> |
<code>cacheperiod=''number of seconds''</code> – ('''default''' is 3600, meaning 1 hour) |
||
Line 73: | Line 73: | ||
{{DPL Parameter |
{{DPL Parameter |
||
|name = goal |
|name = goal |
||
|purpose= Set the |
|purpose= Set the goal for DPL3 to either show '''pages''' (default) or '''categories''' these pages belong to |
||
}} |
}} |
||
Line 80: | Line 80: | ||
<code>goal=''goaltype''</code> where ''goaltype'' can be one of: |
<code>goal=''goaltype''</code> where ''goaltype'' can be one of: |
||
* <code>''pages''</code> |
* <code>''pages''</code> – ('''default''', need not be set) |
||
* <code>''categories''</code> |
* <code>''categories''</code> |
||
DPL3 produces a list of pages by default, and this is precisely what the name DPL3 promises. |
|||
If the goal parameter is set to 'categories' the list of pages is still be produced, but is not seen. Instead, it is |
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? |
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? |
||
Line 96: | Line 96: | ||
The output of |
The output of <code>goal=categories</code> is technically a ''list of pages of type category''. This means that all DPL3 formatting options can be used (<code>mode=userformat</code>, <code>listseparators</code>, <code>columns</code> etc.) and pseudo variables (<code>%TITLE%</code>, <code>%PAGE%</code>) to customize the layout of the report. |
||
Line 107: | Line 107: | ||
{{DPL Parameter |
{{DPL Parameter |
||
|name = eliminate |
|name = eliminate |
||
|purpose= Suppress references to pages, templates, images, categories in |
|purpose= Suppress references to pages, templates, images, categories in DPL3 output |
||
}} |
}} |
||
Line 118: | Line 118: | ||
* <code>''images''</code> |
* <code>''images''</code> |
||
* <code>''links''</code> |
* <code>''links''</code> |
||
* <code>''all''</code> |
* <code>''all''</code> – A synonym for all of the above. |
||
The output of a |
The output of a DPL3 statement typically creates links to all pages which are part of the result set. The inclusion of contents from other pages via DPL3 (using <code>{{DPL|include}}</code>) normally has these consequences: |
||
* |
* The page containing the DPL3 query becomes part of the categories of the transcluded page |
||
* shares ('adopts') their use of templates |
* It shares ('adopts') their use of templates. |
||
* shares their references to images |
* It shares their references to images. |
||
* shares their references to other articles |
* It shares their references to other articles. |
||
In some cases, this may be useful. But in many cases, this is not wanted. Especially when |
In some cases, this may be useful. But in many cases, this is not wanted. Especially when DPL3 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 <code>eliminate</code> parameter |
The <code>eliminate</code> parameter suppresses all or some of the effects described above. |
||
For further explanation, see {{DPL|reset}}. |
For further explanation, see <code>{{DPL|reset}}</code>. |
||
'''Note:''' 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. |
'''Note:''' 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 140: | Line 140: | ||
{{DPL Parameter |
{{DPL Parameter |
||
|name = reset |
|name = reset |
||
|purpose= Suppress references to pages, templates, images, categories in |
|purpose= Suppress references to pages, templates, images, categories in DPL3 output |
||
}} |
}} |
||
Line 147: | Line 147: | ||
<code>reset=''keyword,..''</code>, where ''keyword'' is one of: |
<code>reset=''keyword,..''</code>, where ''keyword'' is one of: |
||
*<code>''categories''</code> |
* <code>''categories''</code> |
||
*<code>''templates''</code> |
* <code>''templates''</code> |
||
*<code>''images''</code> |
* <code>''images''</code> |
||
*<code>''links''</code> |
* <code>''links''</code> |
||
*<code>''all''</code> |
* <code>''all''</code> – A synonym for all of the above. |
||
The output of a |
The output of a DPL3 statement typically creates links to all pages which are part of the result set. The inclusion of contents from other pages via DPL3 (using <code>include</code>) normally has the consequences: |
||
* |
* The page containing the DPL3 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 |
In some cases, this may be useful. But in many cases, this is not wanted. Especially when DPL3 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 <code>reset</code> parameter |
The <code>reset</code> parameter suppresses all or some of the effects described above. |
||
There are some subtle differences here depending on the mode in which DPL3 is used. These differences affect the question of how links, and categories etc., are treated which are direct part of the document containing the DPL3 query. |
There are some subtle differences here depending on the mode in which DPL3 is used. These differences affect the question of how links, and categories etc., are treated which are direct part of the document containing the DPL3 query. |
||
Line 177: | Line 177: | ||
'''In parser extension mode''' (tag like <code><nowiki><dpl></nowiki></code>): |
|||
* <code>reset=categories</code> – Ignores categories of included contents but keeps 'own' categories like 'Q Cat'. |
|||
* <code>reset=images</code> – Throws away references to images contained in included contents but keeps 'own' images like 'Q Image'. |
|||
* <code>reset=templates</code> – Ignores templates used in included contents but keeps 'own' template usage ('Q Template'). |
|||
* <code>reset=links</code> – 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 <code>reset</code> on one's 'own' links, {{DPL|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. |
To avoid the above described effect of <code>reset</code> on one's 'own' links, <code>{{DPL|eliminate}}</code> 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''' (<code><nowiki>{{#dpl:....}}</nowiki></code>): |
|||
* <code>reset=categories</code> – Ignores all categories.<br> |
|||
* <code>reset=images</code> – Throws away all references to images. |
|||
* <code>reset=templates</code> – Ignores all template invocations. |
|||
* <code>reset=links</code> – Throws away all references to other pages. |
|||
Using <code>reset</code> 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 DPL3 query. |
Using <code>reset</code> 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 DPL3 query. |
||
To avoid the above described effect of <code>reset</code>, {{DPL|eliminate}}</code> 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 |
To avoid the above described effect of <code>reset</code>, <code>{{DPL|eliminate}}</code> 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 DPL3 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 |
If there is '''more than one DPL3 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 <code>reset=links</code> in parser extension mode, the effect of these statements dominates the rest. |
||
Line 215: | Line 215: | ||
Use multiple commands to assign the article to more than one category. |
Use multiple commands to assign the article to more than one category. |
||
If <code>reset=all</code> or <code>reset=categories</code> are used, the article containing the DPL3 statement is not be recorded in the |
If <code>reset=all</code> or <code>reset=categories</code> are used, the article containing the DPL3 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 <code>{{DPL|reset}}</code> 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 <code>reset=all</code> the article |
As a side effect of using <code>reset=all</code>, the article does not appear in a category even if one is literally assigned to it. |
||
<code>fixcategory</code> allows a category assignment to be made which is not blocked by the <code>reset</code> command. |
|||
Line 235: | Line 235: | ||
If no wiki text is given, the command |
If no wiki text is given, the command is ignored. Otherwise, DPL3 outputs the wiki text and exits immediately. |
||
Note that the wiki text may be a parser function call which evaluates to an empty string. |
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 [[mw:Extension:Variables|Variables]] extension is installed) or via #dplvar. |
||
Using this command, DPL3 can be prevented from executing a database query; this may be useful if |
Using this command, DPL3 can be prevented from executing a database query; this may be useful if the user did not give a necessary parameter. Note that an <code><nowiki>{{#if:}}</nowiki></code> ([[mw:Help:Extension:ParserFunctions|Parser Functions]] extension) function call would NOT help in that case because <code>#if</code> evaluates its complete content before taking the "if" or the "else" path. So, embedding a DPL3 call within an <code>#if</code> is much less efficient than using the ''execandexit'' function. |
||
A typical use would look like this (note the double pipe symbols within the #if. |
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 DPL3 going to the database): |
Calling the following page with &DPL_cat=Country would list countries, omitting the <code>&cat</code> parameter would trigger the error text message (without DPL3 going to the database): |
||
<pre><nowiki> |
<pre><nowiki> |
||
{{#dpl:execandexit=geturlargs}} |
{{#dpl:execandexit=geturlargs}} |
||
Line 257: | Line 257: | ||
''See also:''' [[Template:Extension DPL scroll]] and {{DPL|scrolling}} |
'''See also:''' [[Template:Extension DPL scroll]] and {{DPL|scrolling}}. |
||
'''Note:''' <code>execandexit</code> acts like a short-circuit evaluation. This means, for example, that successive statements to influence caching |
'''Note:''' <code>execandexit</code> acts like a short-circuit evaluation. This means, for example, that successive statements to influence caching behavior (like <code>{{DPL|allowcachedresults}}</code>) are not interpreted. |
||
Line 278: | Line 278: | ||
''rule''; |
''rule''; |
||
Where rule is one of the following: |
Where ''rule'' is one of the following: |
||
# '''Rules for batch update of articles''' |
# '''Rules for batch update of articles''' |
||
#* A DPL3 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. |
#* A DPL3 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. |
||
Line 327: | Line 327: | ||
====before ''pattern'';==== |
====before ''pattern'';==== |
||
Defines locations where text will be inserted. The location(s) |
Defines locations where text will be inserted. The location(s) are immediately before the match(es) of the pattern. If a pattern matches multiple times, multiple inserts are 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. |
||
Line 333: | Line 333: | ||
====after ''pattern'';==== |
====after ''pattern'';==== |
||
Defines locations where text will be inserted. The location(s) |
Defines locations where text will be inserted. The location(s) are immediately after the match(es) of the pattern. If a pattern matches multiple times, multiple inserts are 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. |
||
Line 341: | Line 341: | ||
Defines the text to be inserted. |
Defines the text to be inserted. |
||
A DPL3 statement may contain replacement, insertion before and after at the same time. |
A DPL3 statement may contain replacement, insertion, before, and after at the same time. |
||
<pre> |
|||
replace /([a-z]+])-cat/; |
replace /([a-z]+])-cat/; |
||
by \1-dog; |
by \1-dog; |
||
Line 348: | Line 349: | ||
after foo; |
after foo; |
||
insert bar2; |
insert bar2; |
||
</pre> |
|||
Only one |
Only one <code>replace</code> - <code>by</code> sequence, one insertion <code>before</code> and one insertion <code>after</code> can be specified. <code>replace</code> is always executed first, followed by <code>insert before</code> and <code>insert after</code>, regardless of the sequence in which the rules appear in the DPL3 source text. |
||
Line 356: | Line 358: | ||
The name of the template; the prefix "Template:" must be given. |
The name of the template; the prefix "Template:" must be given. |
||
The location(s) are immediately before the match(es) of the pattern. If a pattern matches multiple times, multiple inserts are 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: |
|||
<pre> |
|||
after ''pattern''; |
after ''pattern''; |
||
insert ''text''; |
insert ''text''; |
||
replace ''pattern''; |
replace ''pattern''; |
||
by ''replacement''; |
by ''replacement''; |
||
</pre> |
|||
For safety reasons, the update statements are only performed if "exec yes" is specified. So, leaving this away, what would happen if the update were to be executed can be checked. |
For safety reasons, the update statements are only performed if "exec yes" is specified. So, leaving this away, what would happen if the update were to be executed can be checked. |
||
Note that if "exec yes" is present, the update is performed each time the page is rendered which contains the DPL3 statement |
Note that if "exec yes" is present, the update is performed each time the page is rendered which contains the DPL3 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, staying 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 |
The size of the form fields adapts 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]]. |
||
Line 390: | Line 394: | ||
This command is experimental at the moment. |
This command is experimental at the moment. |
||
This |
This deletes the selected pages; If "exec true" is missing, nothing happens. |
||
[[Category:Primary Module|05]] |
[[Category:Primary Module|05]] |