This wiki has been automatically Anonymous user
General usage and invocation syntax: Difference between revisions
no edit summary
m (Alianin moved page DPL:General Usage and Invocation Syntax to Extension:DPL3/General usage and invocation syntax without leaving a redirect: Changing namespaces.) |
No edit summary |
||
Line 1:
{{DPL
'''DynamicPageList3 (DPL3)''' 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.
;Sample output
Line 9:
:* [[Page 2]]
:* [[Another Page]]
{{tocright}}
==
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 <code><nowiki><DPL></nowiki></code>) and a corresponding end tag (<code><nowiki></DPL></nowiki></code>). '''The text between these tags is handed over to the extension module ''just as it is''.'''
Line 37:
* 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.
==
This example would be used inside a template, and uses the variable <code><nowiki>{{{1}}}</nowiki></code> 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.'''
Line 69:
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.
===
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.
==
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":
{| class="wikitable"
|-
! DPL escape character !! Mediawiki character!! Typical use
Line 97 ⟶ 96:
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.
==
Within a DPL statement you can use some [[variables]] which are implicitly set by DPL.
Example: %TITLE%, %PAGE%
Line 104 ⟶ 102:
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)
Line 129 ⟶ 125:
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.
==
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.
Line 137 ⟶ 132:
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.
==
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).
==
As mentioned before DPL3 will insert its output exactly at the position where you placed the DPL3 call. This means that you can put wiki syntax around your DPL call, like e.g.:
<pre><nowiki>
Line 167 ⟶ 161:
</nowiki></pre>
==
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
▲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>'''''Normally DPL does not return its own page in the result.'''''</big></center>
* The parameter <code>[[skipthispage]]</code> gives you control over this
* You can suppress back references to a page containing a DPL query by using [[reset]] and/or [[eliminate]].
==
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, <code>%TITLE%</code> will be replaced by the title of an article, <code>%PAGE%</code> 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 [[
The specification of <code>listseparators</code>, <code>secseparators</code>, and <code>multisecseparators</code> does only make sense in combination with <code>mode=userformat</code>. Therefore <code>mode=userformat</code> is automatically implied when <code>listseparators</code> is specified. To make the syntax even more comfortable the simple word <code>format</code> can be used as an alias for <code>listseparators</code>. So:
Line 188 ⟶ 180:
format=a,b,c,d
==
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.
==
Since version 1.7.9 DPL creates an implicit automatic link to <code>Template:Extension DPL</code>.
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.
Line 198 ⟶ 189:
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.
==
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 ;-)
Line 208 ⟶ 199:
The same effect can be achieved with <code>[[debug]]=5</code>.
==
We
▲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.
| |||