Difference between revisions of "DPL:Manual - General Usage and Invocation Syntax"

From FollowTheScore
Jump to: navigation, search
(Use of boolean parameters)
(Scrolling)
 
(27 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Type:Manual|section=General Usage and Invocation Syntax}}
+
{{Type Manual|section=General Usage and Invocation Syntax}}
  
DPL2 can be used as a parser '''extension''' or as a parser '''function'''. There is no general rule which one is better. The next two sections describe the differences.
+
DPL2 can be used as a '''parser extension''' (<small><code><nowiki><DPL> .... </DPL></nowiki></code></small>) or as a '''parser function''' (<small><code><nowiki>{{#dpl: .... }}</nowiki></code></small>). There is no general rule which one is better. If in doubt, you may want to use the parser function syntax as it is more powerful.
  
If in doubt, you may want to use the parser function syntax as it is more powerful.
+
;Sample output
 +
Both of the following examples, which illustrate the difference between using DPL as a parser extension and using it as a parser function, will produce a list of all articles which belong to ''cat1'' or ''cat2'' and which contain a reference to ''myPage''. The output of these DPL calls would be something like:
  
=== Using DPL2 as a parser extension ===
+
:* [[Page 1]]
Parser extensions define a specific tag (in this case <tt><nowiki><DPL></nowiki></tt>) and a corresponding end tag (<tt><nowiki></DPL></nowiki></tt>). Case doesn´t matter, so it can also be written <tt><nowiki><dpl></nowiki></tt>. The text between these tags is handed over to the extension module ''just as it is''. The extension module takes this text as a series of commands, executes them, and inserts the output right at the place where it found the two tags.
+
:* [[Page 2]]
 +
:* [[Another Page]]
  
Other issues:
+
=== Parser extension method ===
 +
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 <tt><nowiki><DPL></nowiki></tt>) and a corresponding end tag (<tt><nowiki></DPL></nowiki></tt>). '''The text between these tags is handed over to the extension module ''just as it is''.'''
 +
 
 +
;Example syntax
 +
<blockquote><pre><nowiki>
 +
<DPL>
 +
  category = cat1|cat2
 +
  # only pages which contain a link to myPage
 +
  linksto  = myPage
 +
</DPL>
 +
</nowiki></pre></blockquote>
 +
 
 +
;Parsing procedure
 +
Wiki markup expansion ''does not take place'' before the commands are handed over to the extension module.
 +
* This may be useful if you want to pass wiki syntax elements to DPL2 as arguments (see the <tt>[[format]]</tt> option, for example).
 +
* [[mw:Magic words|Magic words]] like <tt><nowiki>{{PAGENAME}}</nowiki></tt> or <tt><nowiki>{{CURRENTDAY}}</nowiki></tt> '''cannot''' be used.
 +
* Template calls like <tt><nowiki>{{{some template}}}</nowiki></tt>, cannot be used as parameters.
 +
* Parser function calls like <tt><nowiki>{{#if:...|...|...}}</nowiki></tt> 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 <tt>\n</tt> or <tt>¶</tt> for that purpose.
 +
 
 +
;Syntax features
 
* Every parameter assignment (<tt>=command</tt>) has to be on a separate line.
 
* Every parameter assignment (<tt>=command</tt>) has to be on a separate line.
 
* Lines starting with a # will be ignored (comment).
 
* Lines starting with a # will be ignored (comment).
 
* Generally the syntax looks fairly simple and intuitive as it doesn't contain special characters (except for the two embracing tags).
 
* Generally the syntax looks fairly simple and intuitive as it doesn't contain special characters (except for the two embracing tags).
* Wiki markup expansion '''does not take place''' before the commands are handed over to the extension module.
+
* Tag case doesn't matter, so it can also be written <tt><nowiki><dpl></nowiki></tt>.
** This may be useful if you want to pass wiki syntax elements to DPL2 as arguments (see the <tt>listseparators</tt> option, for example).
+
* In many cases there is no need to have macro expansion within the parameter list. Note that in the example above, the pipe character (which is used to define a logical OR between the two categories) can be written as it is. The name of the page (''myPage''), however, must be a hardcoded constant.
** <big>[[mw:Magic words|Magic words]] like <tt><nowiki>{{PAGENAME}}</nowiki></tt> or <tt><nowiki>{{CURRENTDAY}}</nowiki></tt> '''cannot''' be used</big>.
+
 
** Template calls as parameters, like <tt><nowiki>{{{some template}}}</nowiki></tt>, cannot be used.
+
=== Parser function method ===
** Parser function calls like <tt><nowiki>{{#if:...|...|...}}</nowiki></tt> cannot be used within arguments.
+
This example would be used inside a template, and uses the variable <tt><nowiki>{{{1}}}</nowiki></tt> 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.'''
** 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 <tt>\n</tt> or <tt>¶</tt> for that purpose.
 
  
In many cases there is no need to have macro expansion within the parameter list. For example:
+
;Example syntax
<pre><nowiki>
+
<blockquote><pre><nowiki>
<DPL>
+
{{#dpl: category = cat1{{!}}cat2 | linksto = {{{1}}} }}
    category = cat1|cat2
+
</nowiki></pre></blockquote>
    # only pages which contain a link to myPage
+
or
    linksto  = myPage
+
<blockquote><pre><nowiki>
</DPL>
+
{{#dpl:
</nowiki></pre>
+
  |category = cat1¦cat2
The example will produce a list of all articles which belong to ''cat1'' or ''cat2'' and which contain a reference to ''myPage''. Note that the pipe character (which is used to define a logical OR between the two categories) can be written as it is. The name of the page (''myPage''), however, must be a hardcoded constant. The output of this DPL call would be something like:
+
  |linksto  = {{{1}}}
 +
}}
 +
</nowiki></pre></blockquote>
  
* [[Page 1]]
+
;Parsing procedure
* [[Page 2]]
+
Wiki markup expansions (not the final conversion to HTML) take place before the commands are handed over to the extension module.
* [[Another Page]]
+
* Magic words like <tt><nowiki>{{PAGENAME}}</nowiki></tt> or <tt><nowiki>{{CURRENTDAY}}</nowiki></tt> '''can''' be used.
 +
* Template calls like <tt><nowiki>{{{some template}}}</nowiki></tt>, can be used as parameters.
 +
* Parser function calls like <tt><nowiki>{{#if:...|...|...}}</nowiki></tt> can be used within arguments.
  
=== Using DPL2 as a parser function ===
+
;Syntax features
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. In this case, it can be written <tt><nowiki>{{#dpl:...|...}}</nowiki></tt> just the way <tt><nowiki>{{#if:...|...}}</nowiki></tt> is used. The text between the double curly braces is interpreted and expanded according to wiki syntax rules before it is handed over to the extension module. This means:
+
* To use wiki characters as arguments, escape them.<!--need link to what this means-->
* All kind of wiki markup expansions take place before the commands are handed over to the extension module.
+
** It is possible to define a special template like <code><nowiki>{{!}}</nowiki></code> which contains a single | symbol as its contents.
** <big>Magic words like <tt><nowiki>{{PAGENAME}}</nowiki></tt> or <nowiki>{{CURRENTDAY}}</nowiki></tt></big> '''can''' be used.
+
** With DPL it is also possible to use the symbol ¦ instead of |; this is very intuitive and maybe it could be adopted by MediaWiki in general...but be <u>careful</u>: it must be inserted by copy-and-paste from here (or from a HTML symbol or extended ASCII table like Windows' ''Character Map'') as normally a keyboard will not have it available (even worse: on some keyboards the standard pipe character is printed in a way that it looks more like the "broken pipe").
** To use wiki characters as arguments, escape them.<!--need link to what this means-->
 
*** It is possible to either define a special template like <code><nowiki>{{!}}</nowiki></code> which contains a single | symbol as its contents.
 
*** It is possible to use the symbol ¦ instead of |; this is very intuitive and maybe it could be adopted by MediaWiki in general...but be <u>careful</u>: it must be inserted by copy-and-paste from here (or from a HTML symbol or extended ASCII table like Windows' ''Character Map'') as normally a keyboard will not have it available (even worse: on some keyboards the standard pipe character is printed in a way that it looks more like the "broken pipe").
 
 
* The text can (but needs not) be written in one line of text, parameters are separated by pipe characters.
 
* The text can (but needs not) be written in one line of text, parameters are separated by pipe characters.
* What was said before regarding explicit line breaks holds true also for the parser function syntax, i.e. the special symbols <tt>\n</tt> or <tt>¶</tt> 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.
+
* What was said before regarding explicit line breaks also holds true for parser function syntax, i.e. the special symbols <tt>\n</tt> or <tt>¶</tt> 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.
  
Example:
+
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 <tt>¦</tt> character acts as an alternative to this somewhat awkward notation.
<pre><nowiki>
 
{{#dpl: category = cat1{{!}}cat2 | linksto = {{{1}}} }}
 
 
                  or
 
 
{{#dpl:
 
  |category = cat1¦cat2
 
  |linksto  = {{{1}}}
 
}}
 
</nowiki></pre>
 
Both examples will produce an identical list of all articles which belong to ''cat1'' or ''cat2'' and which contain a reference to a certain page. It is assumed that the above invocation of <tt>#dpl</tt> is contained within a template. The desired page name will be passed as a parameter when calling the template. Within the template the page name can be referred to as <tt><nowiki>{{{1}}}</nowiki></tt>.
 
  
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 <tt>¦</tt> character acts as an alternative to this somewhat awkward notation.
+
The second example is not literally equivalent to the first one as there is an additional pipe character before the first parameter. Technically, this creates an additional empty parameter, but as empty parameters are silently ignored by DPL it makes no difference.
  
The second example is not literally equivalent to the first one as there is an additional pipe character before the first parameter. Technically, this creates an additional empty parameter, but as empty parameters are silently ignored by DPL it makes no difference.
+
==== #dplchapter ====
 +
Besides '''#dpl''' there is another parser function which you can use in your wiki text. It is called '''[[#dplchapter]]''' and extracts the body of a chapter from some arbitrary wiki text which it receives as a parameter.
  
 
=== Characters with special meaning ===
 
=== Characters with special meaning ===
  
 
Sometimes it is necessary to use a character as "plain data" at a place where it normally has a syntactical meaning. Mediawiki is not very clean at character escaping in general. So we had to define our own way in the jungle of "character escaping":
 
Sometimes it is necessary to use a character as "plain data" at a place where it normally has a syntactical meaning. Mediawiki is not very clean at character escaping in general. So we had to define our own way in the jungle of "character escaping":
* » is translated to &gt;
+
 
* « is translated to &lt;
+
{| class=wikitable
----
+
|-
* ²{ is translated to <nowiki>{{</nowiki>
+
! DPL escape character !! Mediawiki character!! Typical use
* }² is translated to <nowiki>}}</nowiki>
+
|-
* ¦ is translated to |
+
| align=center | <code>'''»'''</code> || align=center | &gt; || rowspan=2 | Call another MediaWiki extension into a parameter of a DPL call
----
+
|-
* ¶ is translated to a newline
+
| align=center | <code>'''«'''</code> || align=center | &lt;
* \n is translated to a newline
+
|-
----
+
| align=center | <code>'''²{'''</code> || align=center | <nowiki>{{</nowiki> || rowspan=3 | Call a template within the 'article loop' of DPL. This is especially useful for nesting DPL calls (''DPL recursion'')
The first two translations make it possible to embed a ''call to another mediawiki extension'' into a parameter of a DPL call. The next three translations make it possible to ''call a template'' within the 'article loop' of DPL. This is especially useful for nesting DPL calls (''DPL recursion''). The last two translations are needed because sometimes you must be able to control when and where a line break is issued by DPL. Note that DPL produces wikitext which finally is interpreted by the normal wiki parser. And parts of the wiki text format depend on the fact whether a line starts with a special charcter (e.g. a '*', '#',':',';' etc.).
+
|-
+
| align=center | <code>'''}²'''</code> || align=center | <nowiki>}}</nowiki>
DPL's mechanism of replacing <tt>%xx%</tt> variables then can be used to modify the arguments of that call '''before''' it will be resolved. Most DPL users will not need this, but for some advanced uses of DPL it is a real help...
+
|-
 +
| align=center | <code>'''¦'''</code> || align=center | <nowiki>|</nowiki>
 +
|-
 +
| align=center | <code>'''¶'''</code> || align=center | newline || rowspan=2 | Inserts a line break into DPL's wikitext output, to allow proper parsing of first-character syntax (such as <code>* # : ;</code>)
 +
|-
 +
| align=center | <code>'''\n'''</code> || align=center | newline
 +
|}
 +
 
 +
DPL's mechanism of replacing <code>%xx%</code> variables then can be used to modify the arguments of that call '''before''' it will be resolved. Most DPL users will not need this, but for some advanced uses of DPL it is a real help.
 +
 
 +
=== Built-in VARIABLES ===
 +
 
 +
Within a DPL statement you can use some [[variables]] which are implicitly set by DPL.
 +
Example: %TITLE%, %PAGE%
 +
 
 +
Some [[variables]] can only be used in the header or footer, like e.g. %PAGES%, %TOTALPAGES%
 +
 
 +
 
 +
=== URL parameters ===
 +
 
 +
DPL understands a couple of parameters which can be passed via an URL specification. These URL-parameters all start with DPL_:
 +
* DPL_count: influences the [[count]] parameter (in fact it overwrites the value specified within the DPL statement)
 +
* DPL_offset: influences the [[offset]] parameter (in fact it overwrites the value specified within the DPL statement)
 +
* DPL_refresh: if used with a value of 'yes' this will clear the DPL cache
 +
* DPL_fromTitle: restrict the selection to articles with a page title greater or equal to the specified value
 +
* DPL_toTitle: restrict the selection to articles with a page title less or equal to the specified value
 +
* DPL_arg1, DPL_arg2, .. DPL_arg5: these are generic parameters that can be used freely to influence a DPL statement
 +
 
 +
The command
 +
 
 +
<pre><nowiki>  http://mywebsite/mywiki/index.php?title=MyPage&DPL_offset=20 </nowiki></pre>
 +
 
 +
would display ''MyPage'' and set the offset parameter to a value of ''20''.
 +
 
 +
Within the DPL statement you cann access URL parameters via
 +
  {%DPL_xxx%}
 +
If a parameter is not set in the URL, DPL will assume an empty string. Instead you can define a default value by using a colon:
 +
{%DPL_xxx:yyy%}
 +
In this case DPL will use 'yyy' if the parameter DPL_xxx is not specified on the URL command line.
 +
 
 +
Note: There is a template called [[Template:Extension DPL scroll]] which uses DPL_offset and DPL_count to provide a generic page scrolling method for huge result sets.
  
 
=== Syntax used in this manual ===
 
=== Syntax used in this manual ===
Line 84: Line 136:
 
* parameter = value
 
* parameter = value
 
you should have in mind that you must either place DPL tags around (using a separate line for each parameter) or use the parser function syntax and separate parameters by pipe characters.
 
you should have in mind that you must either place DPL tags around (using a separate line for each parameter) or use the parser function syntax and separate parameters by pipe characters.
 +
 +
=== Time stamps ===
 +
 +
DPL queries which return date/time information (e.g. date of last edit of a page) will display this information according to your local timezone (if this is correctly set in your user preferences).
  
 
=== Interaction between your wiki text and DPL2 output ===
 
=== Interaction between your wiki text and DPL2 output ===
Line 113: Line 169:
 
=== Special Note on ''Self References'' ===
 
=== Special Note on ''Self References'' ===
  
In principle a DPL query could be written in a way that the page containing the query (or the page including a template which contains the query) would be part of the result set. Experience in the past has shown that in most cases this leads to unwanted effects. For instance the page containing the query from a mediawiki point of view contains links to all pages it lists. If your DPL statement contains a "uses" clause you will be astonished to find your own page in all results. The same happens with categories... In addition there were technical problems with self referencing result sets (parser loop references which seemed very hard to solve). So it was decided to always skip a self reference in the result set.
+
In principle a DPL query could be written in a way that the page containing the query (or the page including a template which contains the query) would be part of the result set. Experience in the past has shown that in some cases this leads to unwanted effects. For instance the page containing the query from a mediawiki point of view contains links to all pages it lists. If your DPL statement contains a "uses" clause you will be astonished to find your own page in all results. The same happens with categories... In addition there were technical problems with self referencing result sets (parser loop references which seemed very hard to solve). So it was decided to skip a self reference in the result set by default.
  
<center style="border:1px black solid"><big>'''''DPL never returns its own page in the result.'''''</big></center>
+
<center style="border:1px black solid"><big>'''''Normally DPL does not return its own page in the result.'''''</big></center>
  
 +
* The parameter <tt>[[skipthispage]]</tt> gives you control over this behaviour. By setting it to ''no'' you can allow self references in DPL result sets.
 +
* You can suppress back references to a page containing a DPL query by using [[reset]] and/or [[eliminate]].
  
 
=== Symbol replacement in ''mode=userformat'' ===
 
=== Symbol replacement in ''mode=userformat'' ===
  
When mode=userformat is selected, DPL will not output anything by default. Instead it will look for symbols in your input (''listseparators, secseparators, multisecseparators'') which it will replace by their corresponding values. For example, <tt>%TITLE%</tt> will be replaced by the title of an article, <tt>%PAGE%</tt> 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.
+
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, <tt>%TITLE%</tt> will be replaced by the title of an article, <tt>%PAGE%</tt> 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.
  
'''See [[DPL:Manual - DPL_parameters: Controlling output format#listseparators]] for a complete list of symbols.'''
+
'''See [[DPL:Manual - DPL_parameters: Controlling output format#format]] for a complete list of symbols.'''
  
 
The specification of <tt>listseparators</tt>, <tt>secseparators</tt>, and <tt>multisecseparators</tt> does only make sense in combination with <tt>mode=userformat</tt>. Therefore <tt>mode=userformat</tt> is automatically implied when <tt>listseparators</tt> is specified. To make the syntax even more comfortable the simple word <tt>format</tt> can be used as an alias for <tt>listseparators</tt>. So:
 
The specification of <tt>listseparators</tt>, <tt>secseparators</tt>, and <tt>multisecseparators</tt> does only make sense in combination with <tt>mode=userformat</tt>. Therefore <tt>mode=userformat</tt> is automatically implied when <tt>listseparators</tt> is specified. To make the syntax even more comfortable the simple word <tt>format</tt> can be used as an alias for <tt>listseparators</tt>. So:
Line 131: Line 189:
  
 
=== Use of boolean parameters ===
 
=== Use of boolean parameters ===
A lot of DPL's parameters have type [http://en.wikipedia.org/wiki/boolean_datatype boolean]. The manual always assumes that 'true' and 'false' are used to set such parameters. As an alternative, you can also use 'yes' and 'no' or '1' and '0' or 'off' and 'on' as with the standard HTML form checkbox input type.
+
A lot of DPL's parameters have type [http://en.wikipedia.org/wiki/boolean_datatype boolean]. The manual always assumes that 'true' and 'false' are used to set such parameters. As an alternative, you can also use 'yes' and 'no' or '1' and '0' or 'on' and 'off' as with the standard HTML form checkbox input type.
 +
 
 +
=== Implicit link to [[:Template:Extension DPL]] ===
  
 +
Since version 1.7.9 DPL creates an implicit automatic link to <tt>Template:Extension DPL</tt>.
 +
This means that every page containing a DPL statement will automatically create a link to [[:Template:Extension DPL]]. You should create this Template in your wiki. We suggest that you copy the source code from [[:Template:Extension DPL|our version]]. The idea is that via this connection you can easily find out which pages in a wiki contain DPL calls. This may help in maintaining them and it will probably be needed by the dplcache feature which is under construction.
 +
 +
Note that the template does NOT produce any output - so it is practically invisible to the user. If you forget to create the template, however, the user will see a red link to the template.
  
 
=== Debugging a DPL statement ===
 
=== Debugging a DPL statement ===
If you want to write a DPL query which produces wiki tables a lot of imagination is rerquireds because you must produce correct wiki syntax as the result of your query. And that syntax heavily depends on newlines, escaping of pipe symbols and other nice little things which are easy to get wriong ;-)
+
If you want to write a DPL query which produces wiki tables a lot of imagination is required because you must produce correct wiki syntax as the result of your query. And that syntax heavily depends on newlines, escaping of pipe symbols and other nice little things which are easy to get wrong ;-)
  
Inside a parser function call (#dpl: ....) we recommend to use
+
We recommend to use the following parameters to find out what syntax your DPL statement produces:
 
    
 
    
 
   resultsheader=«pre»«nowiki»
 
   resultsheader=«pre»«nowiki»
 
   resultsfooter=«/nowiki»«/pre»
 
   resultsfooter=«/nowiki»«/pre»
 +
 +
The same effect can be achieved with <tt>[[debug]]=5</tt>.
 +
 +
=== Table output ===
 +
 +
We´d also like to point out that there are two special commands named [[table]] and [[tablerow]] which make it quite easy to produce output in table form.
 +
 +
=== Scrolling ===
 +
 +
DPL supports efficient scrolling through huge result sets.
 +
 +
The command <tt>scroll=yes</tt> 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 <tt>title&gt;</tt> and <tt>title&lt;</tt> will implicitly be set. Within the [[resultsheader]] and/or [[resultsfooter]] you can call a template which generates links to fetch the next / previous page.
 +
 +
See [[DPL Example 027]] for details.
 +
 +
Basically the idea of backward scrolling is that the SQL statement produces a DESCENDING order (with titles below the threshold). Internally DPL buffers the SQl result set and reverses its order. So the user will see a page of entries directly below the threshold, but in ascending order.
 +
 +
If scrolling is enabled, DPL 1.8.0 and later will take a couple of parameters from the URL command line, like <tt>DPL_offset</tt> for instance; these parameters can be accessed within DPL via a special syntax:
 +
* <tt>{%DPL_offset%}</tt>.
 +
or
 +
* <tt>{%DPL_offset:defaultvalue%}</tt>.
 +
 +
The variables are:
 +
* DPL_count
 +
* DPL_offset
 +
* DPL_refresh  (a value of 'yes' will purge the DPL cache)
 +
* DPL_fromTitle (will be passed to title<  )
 +
* DPL_toTitle  (will be passed to title>  )
 +
* DPL_findTitle (will be passed to title>=  )
 +
* DPL_scrolldir (will be used to influence sort order, can be 'up' or 'down')
 +
 +
Thus you could write an article called 'MyPopularArticles' containing a DPL query like:
 +
 +
<pre><nowiki>
 +
{{#dpl:execandexit=geturlargs}}
 +
<dpl>
 +
  category      = Country
 +
  count        = {%DPL_count:100%}
 +
  scroll        = yes
 +
  resultsheader = Showing {%DPL_count:100%} pages starting from page {{#expr:{%DPL_offset%} + 1}}:\n
 +
</dpl>
 +
 +
</nowiki></pre>
 +
 +
Calling <tt><nowiki>http://mywebsite/mywiki/index.php?title=MyPopularArticles</nowiki></tt> 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 <tt>DPL_offset</tt> also in other templates outside DPL. And this is where the <tt>execandexit</tt> command comes in: it stores the URL parameters in a variable which can be accessed via #dplvar.

Latest revision as of 12:44, 4 October 2009

Manual General Usage and Invocation Syntax

DPL2 can be used as a parser extension (<DPL> .... </DPL>) or as a parser function ({{#dpl: .... }}). There is no general rule which one is better. If in doubt, you may want to use the parser function syntax as it is more powerful.

Sample output

Both of the following examples, which illustrate the difference between using DPL as a parser extension and using it as a parser function, will produce a list of all articles which belong to cat1 or cat2 and which contain a reference to myPage. The output of these DPL calls would be something like:

Parser extension method

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 <DPL>) and a corresponding end tag (</DPL>). The text between these tags is handed over to the extension module just as it is.

Example syntax
<DPL>
  category = cat1|cat2
  # only pages which contain a link to myPage
  linksto  = myPage
</DPL>
Parsing procedure

Wiki markup expansion does not take place before the commands are handed over to the extension module.

  • This may be useful if you want to pass wiki syntax elements to DPL2 as arguments (see the format option, for example).
  • Magic words like {{PAGENAME}} or {{CURRENTDAY}} cannot be used.
  • Template calls like {{{some template}}}, cannot be used as parameters.
  • Parser function calls like {{#if:...|...|...}} 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 \n or for that purpose.
Syntax features
  • Every parameter assignment (=command) has to be on a separate line.
  • Lines starting with a # will be ignored (comment).
  • Generally the syntax looks fairly simple and intuitive as it doesn't contain special characters (except for the two embracing tags).
  • Tag case doesn't matter, so it can also be written <dpl>.
  • In many cases there is no need to have macro expansion within the parameter list. Note that in the example above, the pipe character (which is used to define a logical OR between the two categories) can be written as it is. The name of the page (myPage), however, must be a hardcoded constant.

Parser function method

This example would be used inside a template, and uses the variable {{{1}}} 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.

Example syntax
{{#dpl: category = cat1{{!}}cat2 | linksto = {{{1}}} }}

or

{{#dpl:
  |category = cat1¦cat2
  |linksto  = {{{1}}}
}}
Parsing procedure

Wiki markup expansions (not the final conversion to HTML) take place before the commands are handed over to the extension module.

  • Magic words like {{PAGENAME}} or {{CURRENTDAY}} can be used.
  • Template calls like {{{some template}}}, can be used as parameters.
  • Parser function calls like {{#if:...|...|...}} can be used within arguments.
Syntax features
  • To use wiki characters as arguments, escape them.
    • It is possible to define a special template like {{!}} which contains a single | symbol as its contents.
    • With DPL it is also possible to use the symbol ¦ instead of |; this is very intuitive and maybe it could be adopted by MediaWiki in general...but be careful: it must be inserted by copy-and-paste from here (or from a HTML symbol or extended ASCII table like Windows' Character Map) as normally a keyboard will not have it available (even worse: on some keyboards the standard pipe character is printed in a way that it looks more like the "broken pipe").
  • The text can (but needs not) be written in one line of text, parameters are separated by pipe characters.
  • What was said before regarding explicit line breaks also holds true for parser function syntax, i.e. the special symbols \n or 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 ¦ character acts as an alternative to this somewhat awkward notation.

The second example is not literally equivalent to the first one as there is an additional pipe character before the first parameter. Technically, this creates an additional empty parameter, but as empty parameters are silently ignored by DPL it makes no difference.

#dplchapter

Besides #dpl there is another parser function which you can use in your wiki text. It is called #dplchapter and extracts the body of a chapter from some arbitrary wiki text which it receives as a parameter.

Characters with special meaning

Sometimes it is necessary to use a character as "plain data" at a place where it normally has a syntactical meaning. Mediawiki is not very clean at character escaping in general. So we had to define our own way in the jungle of "character escaping":

DPL escape character Mediawiki character Typical use
» > Call another MediaWiki extension into a parameter of a DPL call
« <
²{ {{ Call a template within the 'article loop' of DPL. This is especially useful for nesting DPL calls (DPL recursion)
}}
¦ |
newline Inserts a line break into DPL's wikitext output, to allow proper parsing of first-character syntax (such as * # : ;)
\n newline

DPL's mechanism of replacing %xx% variables then can be used to modify the arguments of that call before it will be resolved. Most DPL users will not need this, but for some advanced uses of DPL it is a real help.

Built-in VARIABLES

Within a DPL statement you can use some variables which are implicitly set by DPL. Example: %TITLE%, %PAGE%

Some variables can only be used in the header or footer, like e.g. %PAGES%, %TOTALPAGES%


URL parameters

DPL understands a couple of parameters which can be passed via an URL specification. These URL-parameters all start with DPL_:

  • DPL_count: influences the count parameter (in fact it overwrites the value specified within the DPL statement)
  • DPL_offset: influences the offset parameter (in fact it overwrites the value specified within the DPL statement)
  • DPL_refresh: if used with a value of 'yes' this will clear the DPL cache
  • DPL_fromTitle: restrict the selection to articles with a page title greater or equal to the specified value
  • DPL_toTitle: restrict the selection to articles with a page title less or equal to the specified value
  • DPL_arg1, DPL_arg2, .. DPL_arg5: these are generic parameters that can be used freely to influence a DPL statement

The command

  http://mywebsite/mywiki/index.php?title=MyPage&DPL_offset=20 

would display MyPage and set the offset parameter to a value of 20.

Within the DPL statement you cann access URL parameters via

 {%DPL_xxx%}

If a parameter is not set in the URL, DPL will assume an empty string. Instead you can define a default value by using a colon:

{%DPL_xxx:yyy%}

In this case DPL will use 'yyy' if the parameter DPL_xxx is not specified on the URL command line.

Note: There is a template called Template:Extension DPL scroll which uses DPL_offset and DPL_count to provide a generic page scrolling method for huge result sets.

Syntax used in this manual

If we give complete examples we will typically use the tag based parser extension syntax in this manual. Except when we want to make use of variable expansion.

Most of the manual deals with the explanation of individual parameters. This is independent of the choice between the two variants described above. So, if you read something like

  • parameter = value

you should have in mind that you must either place DPL tags around (using a separate line for each parameter) or use the parser function syntax and separate parameters by pipe characters.

Time stamps

DPL queries which return date/time information (e.g. date of last edit of a page) will display this information according to your local timezone (if this is correctly set in your user preferences).

Interaction between your wiki text and DPL2 output

As mentioned before DPL2 will insert its output exactly at the position where you placed the DPL2 call. This means that you can put wiki syntax around your DPL call, like e.g.:

  {| class=wikitable
  |a table field
  |<DPL>
     linksto=myPage
   </DPL>
  |-
  |another table field
  |...
  |}

You could also use html syntax to surround DPL output as in the following example:

<ul>
  <li>Item1</li>
  <li>Item2
    <DPL>
      ...parameters...
    </DPL>
  </li>
</ul>

Special Note on Self References

In principle a DPL query could be written in a way that the page containing the query (or the page including a template which contains the query) would be part of the result set. Experience in the past has shown that in some cases this leads to unwanted effects. For instance the page containing the query from a mediawiki point of view contains links to all pages it lists. If your DPL statement contains a "uses" clause you will be astonished to find your own page in all results. The same happens with categories... In addition there were technical problems with self referencing result sets (parser loop references which seemed very hard to solve). So it was decided to skip a self reference in the result set by default.

Normally DPL does not return its own page in the result.
  • The parameter skipthispage gives you control over this behaviour. By setting it to no you can allow self references in DPL result sets.
  • You can suppress back references to a page containing a DPL query by using reset and/or eliminate.

Symbol replacement in mode=userformat

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, %TITLE% will be replaced by the title of an article, %PAGE% will be replaced by the pagename. So, if you write something like
[[%PAGE%|%TITLE%]], DPL will create a hyperlink to an article.

See DPL:Manual - DPL_parameters: Controlling output format#format for a complete list of symbols.

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

mode=userformat
listseparators=a,b,c,d

is exactly the same as:

format=a,b,c,d

Use of boolean parameters

A lot of DPL's parameters have type boolean. The manual always assumes that 'true' and 'false' are used to set such parameters. As an alternative, you can also use 'yes' and 'no' or '1' and '0' or 'on' and 'off' as with the standard HTML form checkbox input type.

Implicit link to Template:Extension DPL

Since version 1.7.9 DPL creates an implicit automatic link to Template:Extension DPL. This means that every page containing a DPL statement will automatically create a link to Template:Extension DPL. You should create this Template in your wiki. We suggest that you copy the source code from our version. The idea is that via this connection you can easily find out which pages in a wiki contain DPL calls. This may help in maintaining them and it will probably be needed by the dplcache feature which is under construction.

Note that the template does NOT produce any output - so it is practically invisible to the user. If you forget to create the template, however, the user will see a red link to the template.

Debugging a DPL statement

If you want to write a DPL query which produces wiki tables a lot of imagination is required because you must produce correct wiki syntax as the result of your query. And that syntax heavily depends on newlines, escaping of pipe symbols and other nice little things which are easy to get wrong ;-)

We recommend to use the following parameters to find out what syntax your DPL statement produces:

 resultsheader=«pre»«nowiki»
 resultsfooter=«/nowiki»«/pre»

The same effect can be achieved with debug=5.

Table output

We´d also like to point out that there are two special commands named table and tablerow which make it quite easy to produce output in table form.

Scrolling

DPL supports efficient scrolling through huge result sets.

The command scroll=yes 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 title> and title< will implicitly be set. Within the resultsheader and/or resultsfooter you can call a template which generates links to fetch the next / previous page.

See DPL Example 027 for details.

Basically the idea of backward scrolling is that the SQL statement produces a DESCENDING order (with titles below the threshold). Internally DPL buffers the SQl result set and reverses its order. So the user will see a page of entries directly below the threshold, but in ascending order.

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

  • {%DPL_offset%}.

or

  • {%DPL_offset:defaultvalue%}.

The variables are:

  • DPL_count
  • DPL_offset
  • DPL_refresh (a value of 'yes' will purge the DPL cache)
  • DPL_fromTitle (will be passed to title< )
  • DPL_toTitle (will be passed to title> )
  • DPL_findTitle (will be passed to title>= )
  • DPL_scrolldir (will be used to influence sort order, can be 'up' or 'down')

Thus you could write an article called 'MyPopularArticles' containing a DPL query like:

{{#dpl:execandexit=geturlargs}}
<dpl>
  category      = Country
  count         = {%DPL_count:100%}
  scroll        = yes
  resultsheader = Showing {%DPL_count:100%} pages starting from page {{#expr:{%DPL_offset%} + 1}}:\n
</dpl>

Calling http://mywebsite/mywiki/index.php?title=MyPopularArticles 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 DPL_offset also in other templates outside DPL. And this is where the execandexit command comes in: it stores the URL parameters in a variable which can be accessed via #dplvar.