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

Revision as of 02:21, 2 September 2007

Template:Type:Manual

goal

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

Syntax:

allowcachedresults=true

Explanation:

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

So, if you do not use this parameter you will alwas 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 chached results you can still enforce DPL to produce a correct result via using "&action=purge" in the command line.

reset

Syntax:

reset=keyword,.., where keyword is one of:

• categories
• templates
• images
• links
• 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 and that it shares its categories and references to images and other articles. This is in many cases unwanted.

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, no link from your page to other pages will be recorded in the database, 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.

If you use categories,templates,images only the effects coming from transcluded contents will be eliminated.

It is recommended that you add
                                  {{#dpl:reset=all}} 
            or at least 
                                  {{#dpl:reset=categories,templates,images}} 
            to pages 
            which primarily serve the purpose to show the result of a DPL query.

Example:

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

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.

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.

debug

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.

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.