General usage and invocation syntax: Difference between revisions

'''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.

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

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.'''

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

** It is possible to define a special template like, <code><nowiki>{{!}}</nowiki></code> 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 <u>careful</u>: it must be inserted by copy-and-paste from here (or from aan 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").

* What was said before regarding explicit line breaks also holds true for parser function syntax, i.e., the special symbols <code>\n</code> or <code>¶</code> 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.

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.

Sometimes it is necessary to use a character as "plain data" at a place where it normally has a syntactical meaning. MediawikiMediaWiki 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 !! MediawikiMediaWiki character!! Typical use

Within a DPL statement, you can use some [[DPL format variables|variables]] which are implicitly set by DPL.

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

* DPL_count: influences the {{dpl3|count}} parameter (in fact, it overwrites the value specified within the DPL statement)

* DPL_offset: influences the {{dpl3|offset}} parameter (in fact, it overwrites the value specified within the DPL statement)

Within the DPL statement, you can access URL parameters via

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:

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

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.

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.,:

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

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.

When mode=userformat is selected, DPL will not output anything by default.; Insteadinstead, 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 [[Extension:DPL3/Parameters: Controlling output format#format]] for a complete list of symbols.'''

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:

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.

Note that the template does NOT produce any output - sooutput—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 ;-).

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

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

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.

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

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