General usage and invocation syntax: Difference between revisions

The following example would probably be used directly on an article page, but could also be included as part of a template. Parser extensions define a specific tag (in this case <ttcode><nowiki><DPL></nowiki></ttcode>) and a corresponding end tag (<ttcode><nowiki></DPL></nowiki></ttcode>). '''The text between these tags is handed over to the extension module ''just as it is''.'''

* This may be useful if you want to pass wiki syntax elements to DPL3 as arguments (see the <ttcode>[[format]]</ttcode> option, for example).

* [[mw:Magic words|Magic words]] like <ttcode><nowiki>{{PAGENAME}}</nowiki></ttcode> or <ttcode><nowiki>{{CURRENTDAY}}</nowiki></ttcode> '''cannot''' be used.

* Template calls like <ttcode><nowiki>{{{some template}}}</nowiki></ttcode>, cannot be used as parameters.

* Parser function calls like <ttcode><nowiki>{{#if:...|...|...}}</nowiki></ttcode> cannot be used within arguments.

* To pass wiki syntax elements to DPL as parameters it is sometimes necessary to enforce a line break. The reason is that wiki syntax depends on line breaks. Instead, use <ttcode>\n</ttcode> or <ttcode>¶</ttcode> for that purpose.

* Every parameter assignment (<ttcode>=command</ttcode>) has to be on a separate line.

* Tag case doesn't matter, so it can also be written <ttcode><nowiki><dpl></nowiki></ttcode>.

This example would be used inside a template, and uses the variable <ttcode><nowiki>{{{1}}}</nowiki></ttcode> passed to the template. Parser functions look like templates which start with a hash character (#). They are more closely integrated with the wiki system. They are more powerful but their syntax looks a bit more complicated. '''The text between these tags is pre-parsed to expand wiki mark-up ''before'' being handed over to the extension module.'''

* Magic words like <ttcode><nowiki>{{PAGENAME}}</nowiki></ttcode> or <ttcode><nowiki>{{CURRENTDAY}}</nowiki></ttcode> '''can''' be used.

* Template calls like <ttcode><nowiki>{{{some template}}}</nowiki></ttcode>, can be used as parameters.

* Parser function calls like <ttcode><nowiki>{{#if:...|...|...}}</nowiki></ttcode> can be used within arguments.

* What was said before regarding explicit line breaks also holds true for parser function syntax, i.e. the special symbols <ttcode>\n</ttcode> or <ttcode>¶</ttcode> must be used to insert an explicit linefeed character into the wiki output stream if wiki symbols are used which must stand at the beginning of a line.

Note: The pipe character, which is used to define a logical OR for the two categories, must be represented as a call of a special template (which would typically be called "Template:!") which has a single pipe character as its contents. The same kind of trick is also found outside DPL in other templates. The second example shows that the <ttcode>¦</ttcode> character acts as an alternative to this somewhat awkward notation.

* The parameter <ttcode>[[skipthispage]]</ttcode> gives you control over this behaviour. By setting it to ''no'' you can allow self references in DPL result sets.

When mode=userformat is selected, DPL will not output anything by default. Instead it will look for symbols in your input (''listseparators, secseparators, multisecseparators, tablerow'') which it will replace by their corresponding values. For example, <ttcode>%TITLE%</ttcode> will be replaced by the title of an article, <ttcode>%PAGE%</ttcode> will be replaced by the pagename. So, if you write something like <br><code><nowiki>[[%PAGE%|%TITLE%]]</nowiki></code>, DPL will create a hyperlink to an article.

The specification of <ttcode>listseparators</ttcode>, <ttcode>secseparators</ttcode>, and <ttcode>multisecseparators</ttcode> does only make sense in combination with <ttcode>mode=userformat</ttcode>. Therefore <ttcode>mode=userformat</ttcode> is automatically implied when <ttcode>listseparators</ttcode> is specified. To make the syntax even more comfortable the simple word <ttcode>format</ttcode> can be used as an alias for <ttcode>listseparators</ttcode>. So:

Since version 1.7.9 DPL creates an implicit automatic link to <ttcode>Template:Extension DPL</ttcode>.

The same effect can be achieved with <ttcode>[[debug]]=5</ttcode>.

The command <ttcode>scroll=yes</ttcode> must be given to enable scrolling.

DPL can take certain URL parameters from the command line, like &DPL_fromTitle and &DPL_toTitle. If these arguments are given the commands <ttcode>title&gt;</ttcode> and <ttcode>title&lt;</ttcode> will implicitly be set. Within the [[resultsheader]] and/or [[resultsfooter]] you can call a template which generates links to fetch the next / previous page.

If scrolling is enabled, DPL 1.8.0 and later will take a couple of parameters from the URL command line, like <ttcode>DPL_offset</ttcode> for instance; these parameters can be accessed within DPL via a special syntax:

* <ttcode>{%DPL_offset%}</ttcode>.

* <ttcode>{%DPL_offset:defaultvalue%}</ttcode>.

Calling <ttcode><nowiki>http://mywebsite/mywiki/index.php?title=MyPopularArticles</nowiki></ttcode> will give you the first 100 articles in the category. Adding &DPL_offset=100 will give you the next one hundred articles. This mechanism can be used to create a generic page scroll feature - provided you can access the value of <ttcode>DPL_offset</ttcode> also in other templates outside DPL. And this is where the <ttcode>execandexit</ttcode> command comes in: it stores the URL parameters in a variable which can be accessed via #dplvar.