Difference between revisions of "DPL:Manual - DPL parameters: Other parameters"

From FollowTheScore
Jump to: navigation, search
(→‎debug)
(→‎reset)
Line 65: Line 65:
 
*''all'' — a synonym for all of the above
 
*''all'' — a synonym for all of the above
  
−
Note that '''''reset'' must be the one and only parameter in a separate DPL statement!'''
+
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.
  
−
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 and that it shares its categories and references to images and other articles. '''This is in many cases unwanted.'''
+
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.
  
−
If you use a ''separate DPL query after the last DPL query of your article'' which only has the parameter 'reset' you can prevent these effects. If you use ''all'' or ''links'' in that statement, <big>'''no link from your page to other pages will  be recorded in the database'''</big>, which means that these links work in forward direction but cannot be navigated backwards. This affects not only the links produced by the DPL statement or contained in transcluded contents but simply '''all''' links (=references to other articles) of the page containing the DPL-query with the 'reset' statement.
+
The <tt>reset</tt> parameter will suppress all or some of the effects described above.
  
−
If you use ''categories,templates,images'' only the effects coming from transcluded contents will be eliminated.
+
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:
 +
<pre><nowiki>
 +
[[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 with one or more of 'categories,templates,images,links'
 +
...
 +
</nowiki></pre>
  
−
It is recommended that you add
+
<u>In parser extension mode (DPL '''tag''' like &lt;DPL%gt;):</u>
−
                                  <nowiki>{{#dpl:reset=all}}</nowiki>  
+
;reset=categories: will ignore categories of included contents but keep 'own' categories like 'Q Cat'.
−
            or at least
+
;reset=images: will throw away references to images contained in included contents but keep 'own' images like 'Q Image'.
−
                                  <nowiki>{{#dpl:reset=categories,templates,images}}</nowiki>
+
;reset=templates: will ignore templates used in included contents but keep 'own' template usage ('Q Template').
−
            to pages  
+
;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.
−
            which primarily serve the purpose to show the result of a DPL query.
 
  
−
Example:
+
If you want to avoid the above described effect of <tt>reset</tt> on your 'own' links you can use <tt>[[eliminate]]</tt>. But you should know that ''eliminate'' is rather expensive in terms of computer power as it does a second parse for all included contents.
  
−
<pre><nowiki>
 
−
--- MyQueryArticle ---
 
−
a link to a [[page]]
 
−
[[Category:cat1]]
 
−
{{#dpl: some query .., possibly using the 'include' statement  }}
 
−
a {{template}} being used
 
−
{{#dpl: another query .., possibly using the 'include' statement  }}
 
−
an [[Image:xx]]
 
−
{{#dpl:reset=all}}
 
−
a link to [[another page]]
 
−
{{another template}} being used
 
−
[[Image:YY]]
 
−
[[Category:cat2]]
 
−
</nowiki></pre>
 
  
−
You will see a page which contains links to two pages ('page' and 'another page') and two images, which uses two templates and contains a lot of links as the result of your DPL queries. The contents transcluded by the DPL statements may use OTHER/ADDITIONAL templates, it may contain more images, page links and template references.
+
<u>In parser fuction mode ('''<nowiki>{{#DPL:....}}</nowiki>'''):</u>
  
−
The mediawiki SQL database will, however, not reflect all of the above ('''which it would normally do''' if the 'reset' DPL query was missing).: It will not contain any references from ''myQueryArticle'' to other pages in the wiki (not even the references to ''page'' or ''another page''. It will not contain references to images or templates which happen to be inside transcluded contents. It will, however, contain references to ''template'', ''another template'', ''Image:xx'' and ''Image:YY''. ''MyQueryArticle'' will be part of categories ''cat1'' and ''cat2'' but it will NOT be part of categories to which the articles belong which occur in the DPL result set.
+
;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
  
−
<ul>KNOWN BUG:</ul>
+
As you see, using <tt>reset</tt> 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.
  
−
<tt>reset=categories</tt> will NOT remove categories that were assigned by transcluded contents if the DPL statement doing the transclusion used the '''parser function syntax'''. The reason for this is that the output of a DPL call will '''not be parsed''' by the mediawiki parser at the end of a DPL call. In contrary, parsing of DPL output is left to the final parsing call for the whole document because this allows to embed DPL output into syntactic constructs which are created outside the DPL call (e.g. a wikitable where the DPL call contributes some rows). As a consequence of this category assignments which are created during that final parser call could only be removed AFTER the document processing, but not by a command sitting inside the document text itself.
+
If you want to avoid the above described effect of <tt>reset</tt>, you can use <tt>[[eliminate]]</tt>. 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 <tt>eliminate</tt>. In terms of extra processing needed it does not make a difference whether you specify one or more arguments for the 'eliminate' command.
  
−
On the other hand DPL output is directly processed by the parser if parser extension syntax (DPL tag) is used. In these cases the '''reset''' works as you would expect.
+
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 statements in each of the queries and on their individual arguments. As this is a very rare case we only give a simple rule oif 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 restr.
  
 
===debug===
 
===debug===

Revision as of 09:16, 26 September 2007

Template:Type:Manual

goal

goal set the overall goal for DPL to either show pages (default) or categories these pages belong to

Syntax:

goal=pages | categories

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

allowcachedresults allow delivery of results based on cached database contents.

Syntax:

allowcachedresults=true

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.

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 with one or more of 'categories,templates,images,links'
 ...

In parser extension mode (DPL tag like <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 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 fuction 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 statements in each of the queries and on their individual arguments. As this is a very rare case we only give a simple rule oif 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 restr.

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 + shows SQL query.
  • 4 — for internal use only
  • 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
</DPL>

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. See also #Internationalization.

Retrieved from "http://followthescore.org/dpldemo/index.php?title=DPL:Manual_-_DPL_parameters:_Other_parameters&oldid=6719"