This wiki has been automatically Anonymous user
General usage and invocation syntax: Difference between revisions
m
Add more variables found elsewhere but not collected together.
miraheze:dpl3>Soukupmi (→Parser function method: parameter value is myPage) |
imported>FrozenPlum m (Add more variables found elsewhere but not collected together.) |
||
Line 3:
{{tocright}}
'''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
Both of the following examples, which illustrate the difference between using
* [[Apple]]
* [[Grape]]
* [[Orange]]
==Parser extension (tag) 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 <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''.'''
;Example syntax
Line 22 ⟶ 25:
</dpl>
</pre>
;Parsing procedure
Line 29 ⟶ 33:
* Template calls, like <code><nowiki>{{some template}}</nowiki></code>, cannot be used as parameters.
* Parser function calls like <code><nowiki>{{#if:...|...|...}}</nowiki></code> cannot be used within arguments.
* To pass wiki syntax elements to
;Syntax features
Line 38 ⟶ 43:
* In many cases, there is no need to have macro expansion within the parameter list.
* 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 hard-coded constant.
==Parser function method==
This example would be used inside a template, and uses the variable <code><nowiki>{{{1}}}</nowiki></code> passed to the template, which would be set to ''myPage'' here. 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:'''<br>
<pre>
{{#dpl: category = cat1{{!}}cat2 | linksto = {{{1}}} }}
Line 54 ⟶ 61:
</pre>
'''Parsing procedure'''<br>
Wiki markup expansions (not the final conversion to HTML) take place before the commands are handed over to the extension module.
* Magic words like <code><nowiki>{{PAGENAME}}</nowiki></code> or <code><nowiki>{{CURRENTDAY}}</nowiki></code> '''can''' be used.
* Template calls, like <code><nowiki>{{some template}}</nowiki></code>, can be used as parameters.
* Parser function calls like <code><nowiki>{{#if:...|...|...}}</nowiki></code> can be used within arguments, though they must be formatted differently <code><nowiki>²{#if:...¦...¦...}²</nowiki></code>
'''Syntax features'''<br>
* To use wiki characters as arguments, they must be escaped.
** It is possible to use the [[mw:Help:Magic_words#Other|Magic Word]] <code><nowiki>{{!}}</nowiki></code> which 'hides' the pipe from the MediaWiki parser, ensuring that it is [[mw:Help:Extension:ParserFunctions#Escaping pipe characters in tables|not considered until after]] other items have been expanded, though if multiple need to be used this can make your statements harder to read.
** With DPL3 it is also possible to use the symbol <code>¦</code> instead of <code>|</code>; 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 an 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 <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.
'''Notes:'''
* The pipe character, which is used to define a logical OR for the two categories, must be represented as a [[mw:Help:Magic words#Other|Magic Word]] <code><nowiki>{{!}}</nowiki></code> which 'hides' the pipe from the MediaWiki parser, ensuring that it is not considered until after other items have been expanded. The second example shows that the <code>¦</code> 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 DPL3 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":
{| class="wikitable"
|-
!
|-
| align=center | <code>'''»'''</code> || align=center | > || rowspan=2 | Call another MediaWiki extension into a parameter of a
|-
| align=center | <code>'''«'''</code> || align=center | <
|-
| align=center | <code>'''²{'''</code> || align=center | <nowiki>{{</nowiki> || rowspan=3 | Call a template within the 'article loop' of
|-
| align=center | <code>'''}²'''</code> || align=center | <nowiki>}}</nowiki>
Line 91 ⟶ 108:
| align=center | <code>'''¦'''</code> || align=center | <nowiki>|</nowiki>
|-
| align=center | <code>'''¶'''</code> || align=center | newline || rowspan=2 | Inserts a line break into
|-
| align=center | <code>'''\n'''</code> || align=center | newline
|}
==Built-in variables==
Within a DPL3 statement, you can use some symbols (called ''variables'' in this manual) which are implicitly set by DPL3. Some variables can only be used in the header or footer.
{{#lst:Controlling output format|formatvariables}}
{| class="wikitable" style="max-width:1200px;"
! Variable
! Description
|-
|%SECTION%
|The page name and its included section anchor <code>''Page Name#SectionName''</code>. Corresponds to <code>include=''#SectionName''</code> (when a page section is included by name). It currently appears that <code>%SECTION%</code> can only be used in <code>{{DPL|secseparators}}</code>.
|-
|%PFUNC%
|The name of the parser function,
|-
|%TAG%
|The name of the parser extension (tag), set when <code>{{DPL|include}}</code> is used to look for parser extension (tag) calls an article or result set. This variable requires a corresponding <code>include</code> statement and is not very robust, it cannot handle nested parser functions properly. <code>%TAG%</code> is only applicable to the template for which the parser extension information is passed.
|-
|%TAGBODY%
|The body content (as-is, including line breaks) of the parser extension (tag), set when <code>{{DPL|include}}</code> is used to look for parser extension calls an article or result set. This variable requires a corresponding <code>include</code> statement and is not very robust, it cannot handle nested parser functions properly. <code>%TAGBODY%</code> is only applicable to the template for which the parser extension information is passed.
|}
==URL parameters==
DPL3 understands a couple of parameters which can be passed via a URL specification. These URL-parameters all start with DPL_:
* <code>DPL_count</code>: Influences the <code>{{DPL|count}}</code> parameter which limits the number of pages to show, it overwrites the value specified within the DPL3 statement.
* <code>
* <code>DPL_refresh</code>: Specifies whether or not to purge the cache ('yes' will clear the DPL3 cache).
* <code>
* <code>DPL_toTitle</code>: Influences the <code>{{DPL|titlegt}}</code> (previously title>), specifies the page name to end with, so restricts the selection to articles with a page title less than or equal to the specified value.
* <code>DPL_findTitle</code>: Influences the <code>{{DPL|titlegt}}</code> parameter, specifies the page name to start with that is passed to {{DPL|titlegt}}.
* <code>DPL_arg1, DPL_arg2, .. DPL_arg5</code>: Generic parameters that can be used freely to influence a DPL3 statement.
The command following would display ''MyPage'' and set the offset parameter to a value of ''20'':
Line 129 ⟶ 156:
Within the
{%DPL_xxx%}
If a parameter is not set in the URL,
{%DPL_xxx:yyy%}
In this case,
'''Note:''' There is a template called [[Template:Extension DPL scroll]] which uses <code>DPL_offset</code> and <code>DPL_count</code> to provide a generic page scrolling method for huge result sets, where there is an expected number of results.
==Syntax used in this manual==
Most examples in this manual typically use the parser function-based syntax <code><nowiki>{{#dpl:}}</nowiki></code> given it is the more flexible syntax. Examples are wrapped in <code><nowiki><pre></pre></nowiki></code> tags, so the plain wikitext used to create a result can be seen without rendering the result itself.
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
==Time stamps==
DPL3 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 DPL3 output==
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 DPL3 call, like:
<pre>
{| class="wikitable"
Line 161 ⟶ 195:
</pre>
You could also use HTML syntax to surround DPL3 output, as in the following example:
<pre>
<ul>
Line 172 ⟶ 207:
</ul>
</pre>
==Special note on ''Self References''==
In principle a DPL3 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 DPL3 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.
{{note|'''Important:''' DPL3 does not normally return its own page (a self link/reference) in the result set. To include a page that references itself in the result, you must use <code>{{DPL|skipthispage}}{{=}}''no''</code>|error}}
You can suppress back references to a page containing a DPL3 query by using <code>{{DPL|reset}}</code> and/or <code>{{DPL|eliminate}}</code>.
==Variable replacement in ''mode=userformat''==
When <code>mode=userformat</code> is selected, DPL3 will not output anything by default; instead, it will look for variables in your parameter 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>, DPL3 will create a hyperlink to an article.
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 191 ⟶ 230:
is exactly the same as:
format=a,b,c,d
==Use of boolean parameters==
A lot of DPL3's parameters have type [[w: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, DPL3 creates an implicit automatic link to <code>Template:Extension DPL</code>.
This means that every page containing a DPL3 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 DPL3 calls.
‘’’Note:’’’ 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 DPL3 statement==
If you want to write a DPL3 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 using the following parameters to find out what syntax your DPL3 statement produces:
resultsheader=«pre»«nowiki»
resultsfooter=«/nowiki»«/pre»
The same effect can be achieved with <code>{{DPL|debug}}=5</code>.
==Table output==
We'd also like to point out that there are two special commands named <code>{{DPL|table}}</code> and <code>{{DPL|tablerow}}</code> which make it quite easy to produce output in table form.
==Scrolling==
DPL3 supports efficient scrolling through huge result sets.
The command <code>scroll=yes</code> must be given to enable scrolling.
Basically, the idea of backward scrolling is that the SQL statement produces a DESCENDING order (with titles below the threshold). Internally,
If scrolling is enabled,
* <code>{%DPL_offset%}</code>.
or
Line 231 ⟶ 280:
* DPL_count
* DPL_offset
* DPL_refresh (a value of 'yes' will purge the
* DPL_fromTitle - Will be passed to {{DPL|titlelt}} (previously title<)
* DPL_toTitle - Will be passed to {{DPL|titlegt}} (previously title>)
Line 237 ⟶ 286:
* DPL_scrolldir (will be used to influence sort order, can be 'up' or 'down')
Thus, you could write an article called 'MyPopularArticles' containing a DPL3 query like:
<pre><nowiki>
Line 250 ⟶ 300:
</nowiki></pre>
Calling <code><nowiki>http://mywebsite/mywiki/index.php?title=MyPopularArticles</nowiki></code> will give you the first 100 articles in the category. Adding <code>&DPL_offset=100</code> 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 <code>DPL_offset</code> also in other templates outside
==References==
| |||