DynamicPageList3 Manual

Other parameters: Difference between revisions

Page Discussion

Other parameters (view source)

Revision as of 20:34, 21 January 2023

249 bytes added ,  1 year ago
Some minor fixes
imported>FrozenPlum
(Remove purge note (no longer needed))
imported>FrozenPlum
(Some minor fixes)
Line 12:
 
<code>debug=<i>n</i></code>, where ''n'' is one of:
* <code>''0''</code> &mdash; Silent mode, shows nothing
* <code>''1''</code> &mdash; Quiet mode, shows (fatal) errors
* <code>''2''</code> &mdash; Default mode, like 1 + shows warnings; &mdash; '''(default)'''
* <code>''3''</code> &mdash; Verbose mode, like 2
* <code>''4''</code> &mdash; Dump raw SQL Query; only if ''$wgDebugDumpSql'' is set to true.
* <code>''5''</code> &mdash; Show wiki text output from DPL instead of parsed wiki text.
 
'''If you use debug param is used, 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 <code>debug=2</code> and above.
 
Example:
Line 31:
</nowiki></pre>
 
This list will outputoutputs 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), youhasn't willbeen also getchanged, 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, you won't get the warning for the second namespace (''Special'') is not given, since <code>debug=0</code> changed debug settings to silent mode.
 
DPL debug messages are translatable in <code>''DynamicPageList2.i18n.php</code>''.
 
<code>debug=1</code> will suppress warning messages (e.g., if the result set of a DPL query is empty). As an alternative, you can use the <code>{{DPL|suppresserrors}}=</code> statement can be used.
 
 
Line 44:
}}
 
'''Syntax:'''
 
<code>allowcachedresults=''value''<i/code>true |where false</i></code>''value'' is one of:
 
* <code>''true''</code> &mdash; ('''default''', need not be set)
Explanation:
* <code>''false''</code>
 
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.
 
Line 57:
{{DPL Parameter
|name = cacheperiod
|purpose= defineDefine the expiration period for the dplcache
}}
 
'''Syntax:'''
 
<code>cacheperiod=<i>''number of seconds</i>''</code> &mdash; ('''default''' is 3600, meaning 1 hour)
 
The default is 3600 seconds which is one hour.
 
 
Line 70 ⟶ 68:
{{DPL Parameter
|name = goal
|purpose= setSet the overall goal for DPL to either show '''pages''' (default) or '''categories''' these pages belong to
}}
 
'''Syntax:'''
 
<code>goal=''goaltype''<i/code>pages |where categories</i></code>''goaltype'' can be one of:
* <code>''pages''</code> &mdash; ('''default''', need not be set)
* <code>''categories''</code>
 
Explanation:
 
Default is 'pages', which means that DPL produces a list of pages. Andby default, and this is precisely what the name DPL promises.
 
If you set the goal parameter is set to 'categories' the list of pages willis still be produced, but youis won'tnot see itseen. Instead, it willis be used to '''calculate a unique ordered list of all categories these pages belong to'''.
 
This allows youthe toasking ask aof 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 you can use all DPL formatting options can be used (mode=userformat, listseparators, columns etc.) and pseudo variables (<code>%TITLE%</code>, <code>%PAGE%</code>) to customize the layout of yourthe 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.
Line 97 ⟶ 96:
{{DPL Parameter
|name = eliminate
|purpose= suppressSuppress references to pages, templates, images, categories in DPL output
}}
 
'''Syntax:'''
 
<code>eliminate=keyword,..</code>
 
Where <code>eliminate=''keyword,..''</code> where ''keyword'' is one of:
 
* <code>''categories''</code>
* <code>''templates''</code>
* <code>''images''</code>
* <code>''links''</code>
* <code>''all''</code> &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 {{DPL|include}}) normally has these consequences:
Line 118 ⟶ 115:
* shares their references to other articles
 
In some cases, this may be useful. But in many cases, this is not wanted. Especially when youDPL useis DPLused to create a printable document which contains the full text of other articles, you will probably not want to duplicateduplicating all links, template uses etc., of those articles is probably undesired.
 
The <code>eliminate</code> parameter will suppress all or some of the effects described above.
Line 130 ⟶ 127:
{{DPL Parameter
|name = reset
|purpose= suppressSuppress references to pages, templates, images, categories in DPL output
}}
 
'''Syntax:'''
 
<code>reset=<i>''keyword,..</i>''</code>, where ''keyword'' is one of:
*<code>''categories'' </code>
*<code>''templates''</code>
*<code>''images''</code>
*<code>''links'' </code>
*<code>''all''</code> &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
Line 148 ⟶ 145:
* 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 youDPL useis DPLused to create a printable document which contains the full text of other articles, you will probably not want to duplicateduplicateing all links, template uses etc., of those articles is probably undesired.
 
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 youDPL3 useis DPLused. These differences affect the question of how links, and categories etc., are treated which are direct part of the document containing the DPLDPL3 query.
Example:
<pre><nowiki>
[[Category:Q Cat]] linking to [[Q Link]] and showing [[Image:Q Image]] and using {{Q Template}}
... DPLDPL3 query which includes contents from other articles.
assuming that this contents contains links and images,
that it uses templates and thatthethat the articles are part of one or more categories
RESET statement at the end of the DPLDPL3 query with one or more of 'categories,templates,images,links'
...
</nowiki></pre>
 
<u>In parser extension mode (DPLDPL3 '''tag''' like &lt;DPL&gt;):</u>
;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'.
Line 169 ⟶ 166:
;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 toTo avoid the above described effect of <code>reset</code> on yourone's 'own' links, you can use {{DPL|eliminate}} can be used. ButHowever, youit shouldis important to knownote 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 178 ⟶ 175:
;reset=links: will throw away all references to other pages
 
As you see, usingUsing <code>reset</code> in parser function mode will clearclears everything, regardless of whether it comes from included contents or whether it is direct part of the document containing the DPLDPL3 query.
 
If you want toTo avoid the above described effect of <code>reset</code>, you can use {{DPL|eliminate}}</code>. Butcan yoube shouldused. know thatHowever, ''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> is specified. In terms of extra processing needed, it does not make a difference whether you specify one or more arguments are specified for the 'eliminate' command.
 
If youthere haveis '''more than one DPLDPL3 query''' in a documentpage, 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 is given here: Once you have used 'reset' is used in parser function mode or 'reset=links' in parser extension mode, the effect of these statements will dominate the rest.
 
 
Line 188 ⟶ 185:
{{DPL Parameter
|name = fixcategory
|purpose= assignAssign the article containing a DPLDPL3 statement to a category, although <code>reset</code> was used.
}}
 
'''Syntax:'''
<code>fixcategory=<i>''category name</i>''</code>
 
Use multiple commands to assign the article to more than one category.
 
If you use <code>reset=all</code> or <code>reset=categories</code> are used, the article containing yourthe DPLDPL3 statement willis not be recorded in the mediawiki link database. This may be quite useful if youran article transcludes content from other pages. Without the <code>reset</code> command, yourthe article would appear in a category if you included a text portion containing an assignment to that category was used.
 
As a side effect of using <code>reset=all</code> yourthe article will not appear in a category even if youone is literally assign itassigned to oneit.
The <code>fixcategory</code> allows you to make a category assignment to be made which is not blocked by the {{DPL|reset}} command.
 
 
Line 205 ⟶ 202:
{{DPL Parameter
|name = execandexit
|purpose= processProcess the command given as an argument and then exit immediately.
}}
 
'''Syntax:'''
 
<code>execandexit=<i>''wiki text</i>''</code>
<br>or<br>
<code>execandexit=<i>''geturlargs</i>''</code>
 
If no wiki text is given, the command will be ignored. Otherwise, DPLDPL3 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.
Purpose:
 
Using this command, youDPL3 can preventbe DPLprevented 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 DPLDPL3 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 DPLDPL3 going to the database):
<pre><nowiki>
{{#dpl:execandexit=geturlargs}}
Line 244 ⟶ 239:
{{DPL Parameter
|name = updaterules
|purpose= defineDefine a set of rules which are executed to perform an update on selected articles (''bulk update'' or ''template value editing'')
{{note|'''Important:''' The <code>updaterules</code> feature is intended for wiki expert users only. It is recommended that articles using this statement are '[[mw:Help:Protecting and unprotecting pages|protected]]'.|error}}
}}
 
'''Syntax:'''
 
updaterules=
<i>''rule</i>'';
...
<i>''rule</i>'';
 
Where rule is one of the following:
 
# '''Rules for batch update of articles'''
#* A DPLDPL3 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.
 
replace ''pattern'';
Line 319 ⟶ 314:
Defines the text to be inserted.
 
A DPLDPL3 statement may contain replacement, insertion before and after at the same time.
replace /([a-z]+])-cat/;
by \1-dog;
Line 327 ⟶ 322:
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 DPLDPL3 source ´text.
 
 
Line 344 ⟶ 339:
by ''replacement'';
 
For safety reasons, the update statements willare 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 can be checked.
 
Note that if "exec yes" is present, the update will beis performed each time the page is rendered which contains the DPLDPL3 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 staystaying 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]].
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 DPLDPL3 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 359 ⟶ 354:
{{DPL Parameter
|name = deleterules
|purpose= allowAllow the mass deletion of wiki pages
}}
 
deleterules=
reason <i>''text</i>'';
exec ''true'';
 
This command is experimental at the moment.
Anonymous user
Retrieved from "https://dpl3.wikitide.org/wiki/Special:MobileDiff/833"