View source for Controlling output format

{{DPL manual|section=Parameters|subsection=Controlling output format}}
<div id="dpl">
{{tocright}}


With controlling output format, it is possible to:
* Setting basic modes of output formatting.
* Set advanced modes of output formatting (complete control over output).
* Generate simple/quick tabular output.
* Generate advanced tabular output (or format though special surrogate formatting templates).
* Apply formatting to and around lists with headings (and their contents).
* Arranging article lists in columns and rows ({{red|currently non-working}}).
* Control (or rewrite) the way article names are displayed.


In the examples that follow, the DPL output has been kept small to reduce page load time and page size, most notably using <code>{{DPL|titlematch}}</code>, <code>{{DPL|nottitlematch}}</code>, <code>{{DPL|count}}</code>, and <code>{{DPL|includesubpages}}=false</code>.


==General approach to output formatting==

The general approach to output formatting is two-fold:

# There are a couple of simple predefined output formats which generate lists of articles.
#* You will understand their meaning directly from reading.
# There is a mode called [[Controlling output format#userformat|userformat]] which puts complete control into your hands.
#* You will understand their meaning directly from reading.


==Setting the basic output mode==

{{DPL parameter
 |name   = mode
 |purpose= Provide basic control over the output of DPL3.
}}

'''Syntax:'''<br>

{{syntax|mode{{=}}''modename''}} where ''modename'' can be one of:

* <code>''unordered''</code> – outputs an unordered list – HTML tag {{tt|ul}} – ('''default''').
* <code>''ordered''</code> – outputs an ordered list – HTML tag {{tt|ol}}.
* <code>''none''</code> – outputs a list using newlines and HTML tags {{tt|br/}} to separate each item.
* <code>''inline''</code> – outputs a list using symbols defined by the <code>{{DPL|inlinetext}}</code> parameter to separate items.
* <code>''category''</code> – outputs resulting articles in a way category pages are shown (<code>{{DPL|ordermethod}}=</code> '''must''' be used with one of the values: {{tt|title}}; {{tt|titlewithoutnamespace}}; {{tt|category,title}}; or {{tt|user,title}}).
* <code>''gallery''</code> - outputs resulting articles in a gallery.
* <code>''userformat''</code> – leaves output control completely to the user. <br/> See parameters <code>{{DPL|listseparators}}</code> and <code>{{DPL|secseparators}}</code>; in this mode, DPL3 offers built-in variables which must be referenced in the output format description provided by the user. <code>{{DPL|mode}}=''userformat''</code> is essential to have complete control over the output.


For advanced use of DPL3, it is important to understand <code>{{DPL|mode}}=''userformat''</code>. Note that this mode is '''automatically implied''' when <code>{{DPL|listseparators}}</code> or <code>{{DPL|format}}</code> are used.


===mode 'ordered', 'unordered', 'none'===
<br>

'''Example:'''<br>

For space and comparison reasons, this example has been modified and put inside wikitable syntax to display the results side-by-side, rather than one after the other. See the [[Examples/Parameter: mode (example 1)|actual example page]] for the proper (simplified) result, or test it in a sandbox (link at the right). The below examples create abbreviated lists of articles in [[:Category:Fruit examples]], each formatted either using an {{tt|ordered}} list (numbered), an {{tt|unordered}} list (bulleted), or the {{tt|none}} list style (no list item markers). {{ViewTest|Examples|Parameter: mode (example 1)}}


{| style="border-spacing: 10px 0;"
| align=center| In an <code><nowiki><ol>...</ol></nowiki></code> list: || align=center| In a <code><nowiki><ul>...</ul></nowiki></code> list: || align=center| In a <code><nowiki><br/></nowiki></code> list:
|- style="vertical-align:middle;"
|{{DPL Code|<nowiki>
{{#dpl:
|category      = Fruit examples
|titlematch    = %a%
|nottitlematch = %pl%¦%go%
|mode          = ordered
|count           = 3
}}
</nowiki>|noresult=y}}
|{{DPL Code|<nowiki>
{{#dpl:
|category      = Fruit examples
|titlematch    = %a%
|nottitlematch = %pl%¦%go%
|mode          = unordered
|count           = 3
}}
</nowiki>|noresult=y}}
|{{DPL Code|<nowiki>
{{#dpl:
|category      = Fruit examples
|titlematch    = %a%
|nottitlematch = %pl%¦%go%
|mode          = none
|count           = 3
}}
</nowiki>|noresult=y}}
|-
|{{#dpl:
|category      = Fruit examples
|titlematch    = %a%
|nottitlematch = %pl%¦%go%
|mode          = ordered
|count           = 3
}}
|{{#dpl:
|category      = Fruit examples
|titlematch    = %a%
|nottitlematch = %pl%¦%go%
|mode          = unordered
|count           = 3
}}
|{{#dpl:
|category      = Fruit examples
|titlematch    = %a%
|nottitlematch = %pl%¦%go%
|mode          = none
|count           = 3
}}
|}

===mode 'category'===
<br>

'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: mode (example 2)|Example}}
{{ViewTest|Examples|Parameter: mode (example 2)}}


'''Note:''' You '''must''' use <code>{{DPL|ordermethod}} {{=}}&nbsp;</code> with one of: <code>title</code> / <code>titlewithoutnamespace</code> / <code>category,title</code> / <code>user,title</code> with this option.


===mode 'inline'===

{{DPL parameter
 |name   = inlinetext
 |purpose= To define the inline text used in <code>{{DPL|mode}}=inline</code>.
}}


'''Syntax:'''<br>
{{syntax|inlinetext{{=}}''wikitext''}}, where ''wikitext'' is the text to be set.


The default formatting is <code>{{&|nbsp}}-{{&|nbsp}}</code> which results in <code>&nbsp;-&nbsp;</code> except when <code>{{DPL|mode}}=userformat</code> where <code>{{DPL|inlinetext}}</code> is empty by default.


'''Notes:'''
* To get normal "breaking spaces" (and not the NON-breaking spaces) use <code>&amp;#32;-&amp;#32;</code>.
* Extra white spaces are stripped by DPL3 from the beginning and end of ''wikitext''. To show one or multiple spaces, use one or multiple <code>&amp;nbsp;</code>, or use ''nowiki'' tags <code><nowiki><nowiki> - </nowiki></nowiki></code> which has the same effect as <code>&amp;nbsp-&amp;nbsp</code>.
* Bullets can be displayed with either <code>{{&|bull}}</code> or {{tl|*}}.


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: mode (example 3)|Example}}
{{ViewTest|Examples|Parameter: mode (example 3)}}

===mode 'gallery'===

{{DPL parameter
 |name   = gallerymode
 |purpose= To define the mode for the gallery tag, such as traditional, nolines, or packed.
}}

{{DPL parameter
 |name   = imageheight
 |purpose= To define the <code>heights</code> attribute for the gallery tag.
}}

{{DPL parameter
 |name   = imagewidth
 |purpose= To define the <code>widths</code> attribute for the gallery tag.
}}

{{hr}}

===mode 'userformat'===
{{anc|userformat}}
{{hr}}


{{note|'''Note:''' As the below information is difficult to understand, there are additional DPL3 commands (<code>{{DPL|table}}</code>, <code>{{DPL|tablerow}}</code>) which make it fairly quick/easy to create tabular output. If tabular output is needed, skip to the {{DPL|table}} section.}}



While the standard output formats are meant for fast generation of simple page lists, the {{DPL|mode|userformat}} approach aims at transcluding contents from ''other'' pages and requires some effort to understand. There is a '''system of three tags''' which are used to enclose {{Tt|(a)}} the whole output, {{Tt|(b)}} each item, {{Tt|(c)}} each transcluded section of an item. A '''fourth tag''' is used to separate values between items of one section which occur more than once.

We assume that we have two documents {{tt|A}} and {{tt|B}} which use templates {{tt|x}} and {{tt|y}} with varying arguments; while {{tt|x}} is being used once within each document, {{tt|y}} is used several times. In very short notation, the structure might look as follows:

<syntaxhighlight lang="wikitext" copy>
 A: x(a) y(3) y(5)
 B: x(b) y(4) y(1) y(2)
</syntaxhighlight>

The following DPL parameters are used to define a set of tags which are used to construct the output:
* <code>{{DPL|listseparators}} = ''liststart'',''itemstart'',''itemend'',''listend''</code>
* <code>{{DPL|secseparators}} = ''sec-1-start'',''sec-1-end'',''sec-2-start'',''sec-2-end'', .. , ..</code>
* <code>{{DPL|multisecseparators}} = ''multi-sep''</code>
The arguments of the above statements can contain references to <code>{{DPL|variables|%VARIABLES%}}</code>. So, {{tt|sec-1-start}} might contain a reference like <code>%PAGE%</code> to output the page name. See <code>{{DPL|format}}</code> for more details on variable substitution.


Now think of the following page inclusion statement:
<syntaxhighlight lang="wikitext" copy>
  includepage={x}.dpl,{y}.dpl
</syntaxhighlight>


The output then looks like this:
<syntaxhighlight lang="wikitext" copy>
  liststart
     itemstart
        sec-1-start
           x.dpl(a)
        sec-1-end
        sec-2-start
           y.dpl(3)
           multi-sep
           y.dpl(5)
        sec-2-end
     itemend
     itemstart
        sec-1-start
           x.dpl(b)
        sec-1-end
        sec-2-start
           y.dpl(4)
           multi-sep
           y.dpl(1)
           multi-sep
           y.dpl(2)
        sec-2-end
     itemend
  listend
</syntaxhighlight>


Assuming that the tags ({{tt|liststart}}, {{tt|itemstart}}, etc.) contain wiki syntax for table definitions and {{tt|multi-sep}} defines a horizontal line, the output might look like this:

<syntaxhighlight lang="wikitext" copy>
  +------+---------------------+
  |      |          | y.dpl(3) |
  |  A   | x.dpl(a) |  ----    |
  |      |          | y.dpl(5) |
  +------+----------+----------+
  |      |          | y.dpl(4) |
  |      |          |  ----    |
  |  B   | x.dpl(b) | y.dpl(1) |
  |      |          |  ----    |
  |      |          | y.dpl(2) |
  +------+----------+----------+
</syntaxhighlight>

In some situations, however, an output table may be desired where each of the calls of template {{tt|y}} is used to create a separate output row. Using a sortable table, the output could then be easily rearranged.

<syntaxhighlight lang="wikitext" copy>
  +------+---------------------+       +------+---------------------+
  |  A   | x.dpl(a) | y.dpl(1) |       |  B   | x.dpl(b) | y.dpl(1) |
  +------+---------------------+       +------+---------------------+
  |  A   | x.dpl(a) | y.dpl(2) |       |  B   | x.dpl(b) | y.dpl(2) |
  +------+---------------------+       +------+---------------------+
  |  B   | x.dpl(b) | y.dpl(3) |       |  A   | x.dpl(a) | y.dpl(3) |
  +------+---------------------+       +------+---------------------+
  |  B   | x.dpl(b) | y.dpl(4) |       |  A   | x.dpl(a) | y.dpl(4) |
  +------+---------------------+       +------+---------------------+
  |  B   | x.dpl(b) | y.dpl(5) |       |  B   | x.dpl(b) | y.dpl(5) |
  +------+---------------------+       +------+---------------------+
</syntaxhighlight>



A special parameter called <code>{{DPL|dominantsection}}</code> is used to mark '''one''' section of the <code>{{DPL|includepage}}</code> statement as "dominant" (in our example: {{Tt|1="dominantsection=2"}} as {{tt|{y}.dpl}} is the second argument of the <code>{{DPL|includepage}}</code> statement). Only one dominant section can be used in a DPL3 statement. Marking a section as ''dominant'' only makes sense if there are '''multiple calls of the same template''' (or multiple page chapters with the same heading) in the pages. Each piece of content in the dominant section generates an individual output row with the values of all other columns being repeated.


====format====

{{DPL parameter
 |name   = format
 |purpose= Customize the output format completely. Implicitly sets "{{DPL|mode}}=userformat". Uses variable references like <code>%PAGE%</code> to describe the output format. See also the {{DPL|secseparators}} parameter. '''Note:''' <code>format</code> is incompatible with <code>{{DPL|tablerow}}</code>. 
}}


'''Syntax:'''

{{FormatSyntax|expanded=y}}


'''Notes''':
* <code>{{DPL|listseparators}}</code> is an alias for <code>{{DPL|format}}</code>.
* The <code>{{DPL|format}}</code> command is very flexible, but somewhat complicated. To create tabular output, also see the <code>{{DPL|table}}</code> command.
* Because wiki syntax depends on newline characters, <code>\n</code> or <code>¶</code> must be used to explicitly insert newline characters into the output.
* A bullet point list in wiki syntax is defined by a <code>*</code> at the ''beginning of a line'' – therefore <code>\n</code> or <code>¶</code> must be used. 
* A numbered list in wiki syntax is defined by a <code>#</code> at the ''beginning of a line'' – therefore <code>\n</code> or <code>¶</code> must be used.


'''Example:'''<br>
For space and comparison reasons, this example has been modified and put inside wikitable syntax to display the results side-by-side, rather than one after the other. See the [[Examples/Parameter: format (example 1)|actual example page]] for the proper (simplified) result, or test it in a sandbox (link at the right). The classic default output of DPL3, an unordered (bulleted) list, can be produced by using a default statement (first example and result). It can also be created using <code>{{DPL|format}}</code> with the following statements (last example and result). 

This selects pages whose <code>{{DPL|titlematch}}</code> has {{tt|"ntries"}} anywhere in it, it excludes pages that have {{tt|"f"}} in the title, and it also excludes subpages. The <code>{{DPL|format}}</code> statement's {{tt|Startall}} (before all), {{tt|End}} (after each), and {{tt|Endall}} (after all) arguments are empty, only the {{tt|Start}} (before each) argument is used to manually define a bulleted list followed by the liked page name, which is then applied to each row of output. {{ViewTest|Examples|Parameter: format (example 1)}}

{| style="border-spacing: 10px 0;"
| align=center| '''default''' || align=center| '''formatted'''
|- style="vertical-align:top;"
|{{DPL Code|<nowiki>
<dpl>
  titlematch	  = %ntries%
  nottitlematch	  = %f%
  includesubpages = false
</dpl>
</nowiki>|noresult=y}}
|{{DPL Code|<nowiki>
<dpl>
  titlematch	  = %ntries%
  nottitlematch	  = %f%
  includesubpages = false
  format	  = ,\n* [[%PAGE%|%TITLE%]],,
</dpl>
</nowiki>|noresult=y}}
|-
|<dpl>
  titlematch	  = %ntries%
  nottitlematch	  = %f%
  includesubpages	= false
</dpl>
|<dpl>
  titlematch	  = %ntries%
  nottitlematch	  = %f%
  includesubpages	= false
  format			= ,\n* [[%PAGE%|%TITLE%]],,
</dpl>
|}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: format (example 2)|Example}}
{{ViewTest|Examples|Parameter: format (example 2)}}


'''Notes:''' 
* You can also use HTML syntax for the tags, although '''this is discouraged'''.
<syntaxhighlight lang="wikitext" copy>
|format   = <ul type="disc">,<li>[[%PAGE%]],</li>,</ul>
</syntaxhighlight>


The <code>{{DPL|format}}</code> parameter can be used to create a table using wiki syntax (note that the parser function syntax <code><nowiki>{{#dpl:}}</nowiki></code> invocation method requires the pipe <code>|</code> characters to be replaced by broken pipe <code>¦</code>. Again, as wiki syntax depends on newline characters, <code>\n</code> or <code>¶</code> must be used to explicitly insert newline characters into the output.


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: format (example 3)|Example}}
{{ViewTest|Examples|Parameter: format (example 3)}}


'''Notes:'''
* The {{tt|Start}} position of the <code>format=</code> syntax starts and formats a row of output, which is then applied to ''each'' item in the result set.
* In the case of results outside the ''Main'' [[mw:Manual:Namespace|namespace]], such as in the "Category" namespace, if "Category:" is not desired in the page title/link, <code><nowiki>[[%PAGE%|%TITLE%]]</nowiki></code> can be used instead.
* The <code>{{DPL|table}}</code> parameter, with <code>{{DPL|tablerow}}</code> and the <code>{{DPL|include}}</code>/<code>{{DPL|includepage}}</code> parameter, can also be used to output table syntax. 


'''Image galleries''' can also be produced using the format syntax.


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: format (example 4)|Example}}
{{ViewTest|Examples|Parameter: format (example 4)}}


<br>{{anc|variables}}


=====Variables=====

As we want to be able to control output completely, we reference article names and other possible output by special <code>{{DPL|variables|%VARIABLES%}}</code>:

{{anc|variables}}<section begin="formatvariables" />
{| class="wikitable alternating-rows"
! Variable
! Description
|-
|<code>%PAGE%</code>
|<section begin="%PAGE%" />Outputs the name of the article (including namespace), corresponds to the [[mw:Help:Magic words#Page names|Magic Word]]<nowiki> {{FULLPAGENAME}}.</nowiki><section end="%PAGE%" />
|-
|<code>%TITLE%</code>
|<section begin="%TITLE%" />Outputs the title of the article (without the namespace), corresponds to the [[mw:Help:Magic words#Page names|Magic Word]]<nowiki> {{PAGENAME}}.</nowiki><section end="%TITLE%" />
|-
|<code>%NAMESPACE%</code>
|<section begin="%NAMESPACE%" />Outputs the namespace of the article.<section end="%NAMESPACE%" />
|-
|<code>%PAGEID%</code>
|<section begin="%PAGEID%" />Outputs the internal unique numeric ID of the article page.<section end="%PAGEID%" />
|-
|<code>%NR%</code>
|<section begin="%NR%" />Outputs the current article sequence number (starting from 1).<section end="%NR%" />
|-
|<code>%IMAGE%</code>
|<section begin="%IMAGE%" />Outputs the physical path to an image (based on hash values, e.g., ''5/5d/myImage.jpg'').<section end="%IMAGE%" />
|-
|<code>%PAGESEL%</code>
|<section begin="%PAGESEL%" />Outputs the name of an article which was used within the selection criteria (only applies to <code>{{DPL|linksfrom}}</code> and <code>{{DPL|linksto}}</code>).<section end="%PAGESEL%" />
|-
|<code>%IMAGESEL%</code>
|<section begin="%IMAGESEL%" />Outputs the name of an image which was used within the selection criteria (only applies to <code>{{DPL|imageused}}</code>).<section end="%IMAGESEL%" />
|-
|<code>%SIZE%</code>
|<section begin="%SIZE%" />Outputs the article size (requires <code>{{DPL|addpagesize}}=true</code>).<section end="%SIZE%" />
|-
|<code>%SIZEFS%</code>
|<section begin="%SIZEFS%" />Outputs a font size number which is based on the article size (logarithm of square root of counter).<section end="%SIZEFS%" />
|-
|<code>%DATE%</code>
|<section begin="%DATE%" />Outputs the date selected, e.g., <code>ordermethod={{tt|lastedit}}</code>; requires <code>{{DPL|addeditdate}}=true</code> or similar; the formatting of the date can be influenced using <code>{{DPL|userdateformat}}=</code>.<section end="%DATE%" />
|-
|<code>%EXTERNALLINK%</code>
|<section begin="%EXTERNALLINK%" />Outputs the external hyperlink found as a consequence of the <code>{{DPL|linkstoexternal}}</code> statement.<section end="%EXTERNALLINK%" />
|-
!colspan="2"|Relating to categories
|-
|<code>%CATLIST%</code>
|<section begin="%CATLIST%" />Outputs a pipe-separated list of links to all categories to which the article belongs (requires <code>{{DPL|addcategories}}=true</code>).<section end="%CATLIST%" />
|-
|<code>%CATBULLETS%</code>
|<section begin="%CATBULLETS%" />Outputs a bullet point list of links to all categories to which the article belongs (requires <code>{{DPL|addcategories}}=true</code>).<section end="%CATBULLETS%" />
|-
|<code>%CATNAMES%</code>
|<section begin="%CATNAMES%" />Outputs a comma-separated list of all categories to which the article belongs (requires <code>{{DPL|addcategories}}=true</code>).<section end="%CATNAMES%" />
|-
! colspan="2"| Relating to Revisions and Contributors
|-
|<code>%REVISION%</code>
|<section begin="%REVISION%" />Outputs the name of the article revision; only accessible if the DPL query selects articles based on [[Criteria for page selection#Select articles based on REVISION dates|revision dates]].<section end="%REVISION%" />
|-
|<code>%USER%</code>
|<section begin="%USER%" />Outputs the user who changed the article last; requires <code>{{DPL|adduser}}=true</code> or <code>{{DPL|addlasteditor}}=true</code>.<section end="%USER%" />
|-
|<code>%CONTRIBUTOR%</code>
|<section begin="%CONTRIBUTOR%" />Outputs the user who made a contribution; requires <code>{{DPL|addcontribution}}=true</code>.<section end="%CONTRIBUTOR%" />
|-
|<code>%CONTRIBUTION%</code>
|<section begin="%CONTRIBUTION%" />Outputs the number of bytes changed; requires <code>{{DPL|addcontribution}}=true</code>.<section end="%CONTRIBUTION%" />
|-
|<code>%CONTRIB%</code>
|<section begin="%CONTRIB%" />Outputs asterisk <code>*</code> bar to indicate the amount of change; requires <code>{{DPL|addcontribution}}=true</code>.<section end="%CONTRIB%" />
|}
'''Note:''' The above variables are replaced by the corresponding values if they occur within ''Start'' or ''End'' or within the corresponding tags of the <code>{{DPL|secseparators}}=</code> parameter.
{| class="wikitable alternating-rows"
! Variable
! Description
|-
!colspan="2"|Symbolic variables for use in <code>{{DPL|resultsheader}}</code> and/or <code>{{DPL|resultsfooter}}</code>
|-
|<code>%PAGES%</code>
|<section begin="%PAGES%" />Outputs the number of articles in the result set. If the query result is limited (by system settings or by the <code>{{DPL|count}}</code> parameter) <code>%PAGES%</code> only shows the upper limit.<section end="%PAGES%" />
|-
|<code>%TOTALPAGES%</code>
|<section begin="%TOTALPAGES%" />Outputs the number of articles in the result set, regardless of count limits, which may consume extra resources; it is only calculated if used.<section end="%TOTALPAGES%" />
|-
|<code>%VERSION%</code>
|<section begin="%VERSION%" />Displays the current DPL3 version (see also [[Special:Version]]).<section end="%VERSION%" />
|-
|<code>%DPLTIME%</code>
|<section begin="%DPLTIME%" />Outputs the amount of time that the DPL3 call itself took (in seconds + milliseconds).<br>
* This useful to find out if or which DPL3 call, on a page, is taking a long time (if long loading times are noticed).<br>
* '''Example:''' 2 (2009/06/13 09:27:43) would mean the DPL3 call accounts for 2 seconds of the total load time, and that the call started at bracketed time.<section end="%DPLTIME%" />
|-
!colspan="2"|Variables for {{DPL|scrolling}}
|-
|
<code>%FIRSTNAMESPACE%</code><br>
<code>%FIRSTTITLE%</code><br>
<code>%LASTNAMESPACE%</code><br>
<code>%LASTTITLE%</code>
|<section begin="%FIRSTNAMESPACE%" />Variables used for page scrolling, that produce the output described in their names. These variables<br>correspond to {{DPL|%NAMESPACE%}} and {{DPL|%TITLE%}} of the first / last article in the result set, respectively.<section end="%FIRSTNAMESPACE%" />
|-
|<code>%SCROLLDIR%</code>
|<section begin="%SCROLLDIR%" />Outputs the value set by the URL parameter <code>{{tt|DPL_scrollDir}}</code> (up or down);<br>it is passed to the scroll helper template, which uses it to produce its links for scrolling.<section end="%SCROLLDIR%" />
|-
! colspan="2"| Removed parameters
|-
|<code>%COUNT%</code>
|<section begin="%COUNT%" />The usage counter (requires <code>{{DPL|addpagecounter}}=true</code>). The built-in feature for this was {{red|removed}} in MediaWiki 1.25.<ref name=hitcounters/>
{{note|'''Note:''' Requires the [[mw:Extension:HitCounters|HitCounters]] extension.}}<section end="%COUNT%" />
|-
|<code>%COUNTFS%</code>
|<section begin="%COUNTFS%" />A font size number which is based on the usage counter (currently this is the logarithm of the usage counter). The built-in feature for this was {{red|removed}} in MediaWiki 1.25.<ref name=hitcounters/>
{{note|'''Note:''' Requires the [[mw:Extension:HitCounters|HitCounters]] extension.}}<section end="%COUNTFS%" />
|-
|<code>%COUNTFS2%</code>
|<section begin="%COUNTFS2%" />Similar to %COUNTFS%, but based on the logarithm of the square root of the usage counter. The built-in feature for this was {{red|removed}} in MediaWiki 1.25.<ref name=hitcounters/>
{{note|'''Note:''' Requires the [[mw:Extension:HitCounters|HitCounters]] extension.}}<section end="%COUNTFS2%" />
|}
<section end="formatvariables" />


====listseparators====
{{DPL parameter
 |name   = listseparators
 |purpose= An alias for format, see the <code>{{DPL|format}}</code> parameter. Implicitly sets <code>{{DPL|mode}}=userformat</code>.
}}


====secseparators====
{{DPL parameter
 |name   = secseparators
 |purpose= Customize the output format of included sections. Can be used with standard output modes and with <code>{{DPL|mode}}=userformat</code>.
}}

'''Syntax:'''<br>

{{syntax|secseparators{{=}}''Start1'',''End1'',''Start2'',''End2'',..,..}}

or

{{syntax|secseparators{{=}}''Start''}}


In the first syntax variant, specify ''pairs of tags'' which correspond to the <code>{{DPL|includepage}}</code> statement. {{tt|StartN}} and {{tt|EndN}} are HTML strings or wiki tags which are put around each transcluded section (see {{syntax|{{DPL|includepage}}{{=}}name1,name2,...}}).

In the second syntax variant, specify just one element which is then used as {{tt|StartN}} for all sections; in this case the second tag ({{tt|EndN}}) will be empty for all transcluded sections.

Symbolic replacements of <code>{{DPL|%PAGE%}}</code> etc. take place as described in <code>{{DPL|listseparators}}</code>. In addition, the variable <code>{{DPL|%SECTION%}}</code> can be used to refer to the section found (works only for page section/chapter headings).

If the same section occurs more than once in an article (or an article includes the same template more than once) all such occurrences are transcluded as a block, and the <code>{{DPL|secseparators}}</code> tags are only put once around the whole block (but see <code>{{DPL|dominantsection}}</code>).


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: secseparators (example 1)|Example}}
{{ViewTest|Examples|Parameter: secseparators (example 1)}}


As mentioned above, a single element can be used in the <code>{{DPL|secseparators}}</code> statement to apply this as a start tag to all transcluded sections; so it could have also been written as shown in the example below.


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: secseparators (example 2)|Example}}
{{ViewTest|Examples|Parameter: secseparators (example 2)}}


====multisecseparators====

{{DPL parameter
 |name   = multisecseparators
 |purpose = Put a tag between multiple transcluded parts which refer to (use) the same template or page section or chapter.
}}


'''Syntax:'''<br>

{{syntax|multisecseparators{{=}}''sep1'',''sep2'',...}}

The tags correspond to the transcluded section (see {{syntax|{{DPL|includepage}}{{=}}name1,name2,...}}).

Symbolic replacements of <code>{{DPL|%PAGE%}}</code> etc. take place as described in {{DPL|listseparators}}. In addition, the variable <code>{{DPL|%SECTION%}}</code> can be used to refer to the section found (works only for chapter headings). It gives the precise name of each heading, even if a regular expression (double ##) was used in the include statement.

If an article uses the same template more than once, all references are provided with {{tt|sepN}} as a separator.


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: multisecseparators (example 1)|Example}}
{{ViewTest|Examples|Parameter: multisecseparators (example 1)}}


Values cannot be formatted within <code>{{DPL|include}}</code>, as formatting can only occur in formatting statements (this can be done in <code>{{DPL|listseparators}}</code> or <code>{{DPL|secseparators}}</code>, and <code>{{DPL|multisecseparators}}</code>). Variables can be omitted from the <code>{{DPL|include}}</code>, and instead be placed in these formatting statements, for further formatting.<br/>

We can achieve some field formatting by changing some of the above dpl statements: 


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: multisecseparators (example 2)|Example}}
{{ViewTest|Examples|Parameter: multisecseparators (example 2)}}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: multisecseparators (example 3)|Example}}
{{ViewTest|Examples|Parameter: multisecseparators (example 3)}}


Formatting handled by a surrogate (also known as phantom) template (e.g., [[Template:DPL parameter.surrogateexample]]) applies to both <code>{{DPL|secseparators}}</code> and <code>{{DPL|multisecseparators}}</code>.


If separate formatting is required, it needs to be assigned to their respective parameters (as shown in the surrogate, and in the example above if "View result" is clicked). In the surrogate and in the result, it can be seen that a link was applied to the second column in addition to the first, this required the use of a surrogate, though there are simpler ways to accomplish a task as basic as this, see the <code>{{DPL|table}}</code> and <code>{{DPL|tablerow}}</code> parameters for more information.


====dominantsection====

{{DPL parameter
 |name   = dominantsection
 |purpose= Define a section with multiple occurrences as dominant, i.e., each piece of the contents of this section (which is associated with a template call or an article section/chapter within the original document) creates a separate output line.
}}


'''Syntax:'''<br>

{{syntax|dominantsection{{=}}''number''}} between 1 and the number of arguments in the <code>{{DPL|includepage}}=</code> statement


If there is only 0 or 1 piece of content for the dominant section, no difference from normal DPL3 behavior is observed.

See the explanations at the [[#General approach to output formatting|top of this document]] to understand the meaning of dominantsection.


'''Note:''' Using <code>{{DPL|dominantsection}}</code> together with <code>{{DPL|table}}</code> may lead to strange result formatting.

==Generating tabular output==

===table===

{{DPL parameter
 |name   = table
 |purpose= A simple syntax to create standard tabular output; see also <code>{{DPL|tablerow}}</code>. Requires an <code>{{DPL|include}}</code> statement, and is a shortcut that implicitly sets values for other DPL3 parameters, namely <code>{{DPL|mode}}</code>, <code>{{DPL|listseparators}}</code> / <code>{{DPL|format}}</code>, <code>{{DPL|secseparators}}</code>, and <code>{{DPL|multisecseparators}}</code>.
}}


'''Syntax:'''<br>

{{syntax|table{{=}}''tableattr'', ''linkheader'', (column headlines) ..}}


The layout is less flexible than the individual use of all of the above parameters, but is probably be sufficient often, especially when used together with <code>{{DPL|tablerow}}</code>.


'''Parameters automatically set''' by <code>table</code> are:
* <code>{{DPL|mode}}=''userformat''</code>.
* <code>{{DPL|listseparators}}</code> is configured to produce '''table definition''' wiki syntax.
* <code>{{DPL|secseparators}}</code> is configured to produce '''table row''' wiki syntax.
** The first column always contains a hyperlink to the article of the query result (unless suppressed using '-' in the link header as described below).
* <code>{{DPL|multisecseparators}}</code> is configured to produce '''another table row''' wiki syntax, for multiple occurrences of the ''first'' <code>{{DPL|include}}</code> argument.
** For all other arguments:
*** '''Template parameters''' – A line break is used (because a table where each template invocation becomes a row in the table may be desired).
*** '''Page section contents'''– A line break is used ('''Note''': Formerly a ''horizontal separation line'' was noted, but this changed some time ago). 


'''It does not make sense''' to use one of the other parameters mentioned, if <code>{{DPL|table}}</code> is used in a DPL3 statement because '''their values are overwritten without notice'''.
* There is one exception to this rule, it can make sense to specify the '''third''' argument for <code>{{DPL|format}}</code> combined with <code>{{DPL|table}}</code>; therefore, this parameter is NOT overwritten by the <code>{{DPL|table}}</code> command. The third argument can be used to output metadata like <code>{{DPL|%COUNT%}}</code>, <code>{{DPL|%USER%}}</code> etc., as columns in an output table. To do so, the third parameter must contain wiki syntax for output columns like this:
<syntaxhighlight lang="wikitext" copy>
 include = {some template}:param1,#some-section-heading
 table   =,,tplparam,#sectionheading,#hits
 format  =,,\n%COUNT%
 </syntaxhighlight>

This provides a table which contains template parameters, article section/chapter contents, and the usage counter as a third column. Metadata can only be placed '''AFTER''' normal contents, the third argument of the <code>table</code> statement adds <code>{{DPL|%COUNT%}}</code> to add that value after that column's normal content. 


'''Important:'''
* An <code>{{DPL|include}}</code> statement is required to use <code>table</code>.
* Each argument of the <code>{{DPL|include}}</code> statement produces one or more values for the output described by the <code>{{DPL|table}}</code> statement.
* For reasons of readability and because the <code>include</code> and <code>table</code> statements correspond, the <code>include</code> statement should directly precede the <code>table</code> statement. 


'''<code>table</code> expects a comma-separated list of arguments''':

<syntaxhighlight lang="wikitext" copy>
|table = class="wikitable sortable",First column header,Second column header,...
</syntaxhighlight>

* '''The first argument''' assigns general properties for the table.
** It is recommended to make a CSS reference here, using something like <code>class="''wikitable sortable''"</code>, or <code>class="''mytable''"</code> if {{tt|mytable}} is defined in the [[Mediawiki:Common.css]] document.
** <code>class="''wikitable''"</code> is the '''default value''' if left empty.

* '''The second argument''' is the headline for the first column.
** A <code>-</code> hyphen in the second argument suppresses the automatically generated first column of output.
*** You can manually create a hyperlink to the article in any other column instead, using <code><nowiki>[[{{{%PAGE%}}}|{{{%TITLE%}}}]]</nowiki></code>, in a <code>{{DPL|tablerow}}</code> statement, or in a surrogate (also known as phantom) template. 
** If no header text is specified in second position, "Content page" appears. 
* '''All subsequent arguments''' specify the column headings, which correspond to the arguments of the <code>{{DPL|include}}</code> parameter. If a ''surrogate template'' is called (like {{tt|{Some Template}.dpl}}) in the <code>include</code> statement, as many headlines as the ''surrogate template'' produces columns needs to be provided. 


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: table (example 1)|Example}}
{{ViewTest|Examples|Parameter: table (example 1)}}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: table (example 2)|Example}}
{{ViewTest|Examples|Parameter: table (example 2)}}


When using ''surrogate'' templates (i.e., templates that format a single row of output, called during DPL3 execution, and then applied by DPL3 to subsequent rows), they must be written to produce output according to wiki table syntax. The <code>table</code> parameter already creates the beginning and end of a table, so when entering such a template, we are already at the beginning of a column (i.e., a preceding line with a <code>{{!}}</code> has already been put into the output stream). So, start directly with the contents of the first column. To add more columns, use a <code>{{!}}</code> on a separate line. 


'''Example:'''

<syntaxhighlight lang="wikitext" copy>
   some output for the first column: {{{1|}}}
   |
   some output for the next column: {{{2|}}}
   |
   some output for the next column: {{{3|}}}
</syntaxhighlight>

It may sound complicated, but is a ''huge'' improvement compared to the native use of <code>{{DPL|mode}}</code>, <code>{{DPL|listseparators}}</code>, <code>{{DPL|secseparators}}</code> and <code>{{DPL|multisecseparators}}</code>.

A typical DPL3 statement using the {{DPL|table}} parameter would contain:

<syntaxhighlight lang="wikitext" copy>
include =                            #Section X,   {T1}:param1   ,#Section Y,{T2}.dpl
table   = class="sortable", Article,      X    , Template param1 ,     Y    ,T2-a T2-b
</syntaxhighlight>

Note that we have written the above statement in a way to show the correspondence between <code>{{DPL|include}}</code> and <code>{{DPL|table}}</code>. You can see the first two arguments define the table characteristics and then the first column (for the hyperlink to the article) and headline. Then follow headlines for each argument of <code>{{DPL|include}}</code>. Note that there are '''two''' headlines which correspond to the last argument of the <code>{{DPL|include}}</code> statement (assuming that {{tt|Template:T2.dpl}} outputs '''two''' columns). {{tt|Template:T2}} itself might have more or less than 2 arguments – it only matters how many columns are output by {{tt|Template:T2.dpl}}).


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: table (example 3)|Example}}
{{ViewTest|Examples|Parameter: table (example 3)}}


'''See:''' the collection of [[Generating tabular output (examples)]] for '''more table examples''', and also <code>{{DPL|include}}</code> for more information on surrogate template use. 


===tablerow===

{{DPL parameter
 |name   = tablerow
 |purpose= A simple syntax to precisely position tabular data within formatting syntax; requires a <code>{{DPL|table}}</code> statement. '''Note:''' <code>{{DPL|tablerow}}</code> is incompatible with <code>{{DPL|format}}</code>
}}


'''Syntax:'''<br>

{{syntax|tablerow{{=}}''columnDefinition'', ..}} where {{tt|columnDefinition}} uses the symbol <code>%%</code> to precisely position content included by an <code>{{DPL|include}}</code> statement, within wikitext formatting code.


When it comes to simple tables using <code>{{DPL|tablerow}}</code>, an <code>{{DPL|include}}</code> statement first tells DPL3 what content to include in each column of a table, the <code>{{DPL|table}}</code> statement sets corresponding table syntax, styles, separators, table headers, and also determines if the first (automatically generated) column is included or suppressed. The job of the <code>{{DPL|tablerow}}</code> is to precisely position the column ''values'' <code>%%</code> of the corresponding <code>{{DPL|include}}</code>, within some supplied formatting for a single row of output. Whatever is supplied for formatting is then re-applied to every row of output.  


When defining the formatting, it's possible to start with cell styles/attributes like <code>style="background:grey;"¦</code> (followed by the value <code>%%</code>) or skipping such styles and just adding the value <code>%%</code>. All columns must be specified, meaning as many entries in the <code>{{DPL|tablerow}}</code> statement must exist as there are columns in the table. Skipping a column would suppress output for that column completely. 


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: tablerow (example 1)|Example}}
{{ViewTest|Examples|Parameter: tablerow (example 1)}}


'''Notes:'''
* You can add a leading <code>\n</code> or <code>¶</code> to make sure that the field contents are displayed correctly if it contains wiki syntax that depends on line breaks (e.g., numbered list).
* See [[Generating tabular output (examples)]] for '''many more examples''' of <code>{{DPL|tablerow}}</code> use (and other methods of generating tabular data).


===tablesortcol===

{{DPL parameter
 |name   = tablesortcol
 |purpose= Define a column to be used as a sort key (requires the <code>{{DPL|table}}</code> and <code>{{DPL|ordermethod}}</code> parameters.)
}}


'''Syntax:'''<br>

{{syntax|tablesortcol{{=}}''number''}}


''number'' is the position of the column that shall be used as sortkey when the result is initially displayed.
* Column numbering starts with ''1'';
* <code>tablesortcol = ''0''</code> means ''do not sort''; this is the default.
* Negative numbers are used to sort in descending order; e.g., {{tt|-3}} would sort according to the third column in descending order.
* Note that the rest of the row after the selected column are also part of the sortkey; so the contents of successive columns may serve as a secondary sort criterion if there are identical values in the selected column.
* Also note that the whole column contents is taken; this may include hidden contents or markup sequences if column formatting commands were used. For the same reason, numeric contents cannot be expected to sort ''numerically'' – sorting is always alphabetical.
* You can, of course, use something like <code>class="sortable"</code> or <code>class="wikitable sortable"</code> together with <code>{{DPL|tablesortcol}}</code>. The difference is that:
** Interactive sorting only works after the article has been initially displayed.
** Interactive sorting tries to guess the content type of column and sorts according to that (date, number, string)
* If <code>{{DPL|tablesortcol}}</code> is not used, the output order of table rows depends on the sort order by which the articles were analyzed. That order depends on other DPL3 commands like <code>{{DPL|ordermethod}}</code>. The default is "alphabetically by title". So, without <code>{{DPL|tablesortcol}}</code> table rows appear in alphabetical sequence of the article names where they come from. With <code>{{DPL|tablesortcol}}</code> these can be ordered by the column contents itself.


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: tablesortcol (example 1)|Example}}
{{ViewTest|Examples|Parameter: tablesortcol (example 1)}}


==Heading mode==

===headingmode===

{{DPL parameter
 |name   = headingmode
 |purpose= To control the output of the headings in a DPL3 with complex/multi-parameter <code>{{DPL|ordermethod}}</code> (has no effect with single-parameter ordermethods). For <code>{{DPL|ordermethod}}=''method1,method2,...''</code>, {{tt|method1}} is used for headings. E.g., In <code>{{DPL|ordermethod}}=''category,title''</code> a 2-parameter ordermethod, <code>{{DPL|headingmode}}</code> affects ''category'' headings. See also <code>{{DPL|headingcount}}</code>.
}}


'''Syntax:'''<br>

{{syntax|headingmode{{=}}''modename''}} where ''modename'' can be one of:
* <code>''ordered''</code> – outputs an [https://www.w3schools.com/tags/tag_ol.asp ordered (numbered) list] – HTML tag {{tt|ol}}
* <code>''unordered''</code> – outputs an [https://www.w3schools.com/tags/tag_ul.asp unordered (bulleted) list] – HTML tag {{tt|ul}}
* <code>''definition''</code> – outputs a [https://www.w3schools.com/tags/tag_dl.asp description list] – HTML tag {{tt|dl}}
* <code>''none''</code> – headings are not displayed, no heading – ('''default''', need not be set)
* <code>''H1''</code> – outputs [https://www.w3schools.com/tags/tag_hn.asp (heading)] sections – HTML tags {{tt|H1}}
* <code>''H2''</code> – outputs heading sections – HTML tags {{tt|H2}}
* <code>''H3''</code> – outputs heading sections – HTML tags {{tt|H3}}
* <code>''H4''</code> – outputs heading sections – HTML tags {{tt|H4}}
* <code>''H4''</code> – outputs heading sections – HTML tags {{tt|H5}}
* <code>''H4''</code> – outputs heading sections – HTML tags {{tt|H6}}


'''Important notes:'''
* If a single category is used to select articles for the result set, and those articles '''belong to more than one category''', all categories they belong to are displayed as headings and the articles themselves will repeat under each category they belong to, unless extra categories are deliberately filtered off with other [[Criteria for page selection|page selection parameters]]. The <code>{{DPL|distinct}}</code> parameter would have '''no effect''' on this behavior because the articles are already distinct to '''each''' category (and <code>{{DPL|distinct{{=}}true}}</code> is already the default, setting it would not change the result).
* <code>{{DPL|headingmode}}</code> can be used with multi-column output, but the length of the columns may vary more expected.


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: headingmode (example 1)|Example}}
{{ViewTest|Examples|Parameter: headingmode (example 1)}}


<code>headingmode</code>, which governs the mode of only headings, can also be combined with <code>mode=''ordered''</code> or <code>mode=''unordered''</code>, which can number or bullet the articles under those headings.


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: headingmode (example 2)|Example}}
{{ViewTest|Examples|Parameter: headingmode (example 2)}}


===hlistattr===

{{DPL parameter
 |name   = hlistattr
 |purpose= Add attributes to the HTML '''heading/top level''' elements, '''which enclose all other elements''' in the result, depending on <code>{{DPL|headingmode}}</code> (HTML element would be {{tt|ol}} for ordered, {{tt|ul}} for unordered, {{tt|dl}} for definition; or {{tt|div}} for others)

Not yet applicable to <code>{{DPL|headingmode}}{{=}}''none''</code>.
}}


'''Syntax:'''<br>

{{syntax|hlistattr{{=}} ''attribute1{{=}}"val1"'' ''attribute2{{=}}"val2"'' ...}}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: hlistattr (example 1)|Example}}
{{ViewTest|Examples|Parameter: hlistattr (example 1)}}


'''If''' there is one page output for each category, the HTML structure output is:

<!-- this causes html to appear highlighted -->
<syntaxhighlight lang="wikitext" copy>
<dl id="dl-example" class="dpl-orange-background">
  <dt>Category_1</dt>
  <dd>
    <ol>
      <li>Page 1</li>
    </ol>
  </dd>
  <dt>Category_1</dt>
  <dd>
    <ol>
      <li>Page 2</li>
    </ol>
  </dd>
</dl>
</syntaxhighlight><!-- this causes html to appear highlighted -->


'''Note:''' To format subsequent elements in the same result set, see also (in the corresponding order since the examples build on one another) <code>{{DPL|hitemattr}}</code>, <code>{{DPL|listattr}}</code>, <code>{{DPL|itemattr}}</code>.


===hitemattr===

{{DPL parameter
 |name   = hitemattr
 |purpose= Add attributes '''all''' list item headings''' in the result, depending on <code>{{DPL|headingmode}}</code> (HTML element would be {{tt|li}} for ordered/unordered, {{tt|div}} for others).

To be used with <code>{{DPL|headingmode}}=''unordered''</code> or ''ordered''. (Not yet applicable for others.) 
}}


'''Syntax:'''<br>

{{syntax|hitemattr{{=}} ''attribute1{{=}}"val1"'' ''attribute2{{=}}"val2"'' ...}}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: hitemattr (example 1)|Example}}

{{ViewTest|Examples|Parameter: hitemattr (example 1)|margintop=1em}}


'''If''' there is one page of output for each category, the HTML structure output is:

<!-- this causes html to appear highlighted -->
<syntaxhighlight lang="HTML">
<dl id="dl-example" class="dpl-orange-background">
  <dt>Category_1</dt>
  <dd id="list-item-heading" class="list-item-heading">
    <ol>
      <li>Page_1</li>
    </ol>
  </dd>
  <dt>Category_2</dt>
  <dd id="list-item-heading" class="list-item-heading">
    <ol>
      <li>Page_2</li>
    </ol>
  </dd>
</dl>
</syntaxhighlight><!-- this causes html to appear highlighted -->


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: hitemattr (example 2)|Example}}

{{ViewTest|Examples|Parameter: hitemattr (example 2)|margintop=1em}}


'''If''' there is one page of output for each category, the HTML structure output is:
<syntaxhighlight lang="HTML">
<ul id="dl-example" class="dpl-orange-background">
 <li id="list-item-heading" class="list-item-heading">Category_1</li>
   <ol>
	 <li>Page_1</li>
   </ol>
 </li>
 <li id="list-item-heading" class="list-item-heading">Category_2</li>
  <ol>
    <li>Page_2</li>
    <li>Page_3</li>
  </ol>
 </li>
</ul>
</syntaxhighlight><!-- this causes html to appear highlighted -->

'''Note:''' To format subsequent elements in the same result set, see also (in the corresponding order since the examples build on one another) <code>{{DPL|listattr}}</code>, <code>{{DPL|itemattr}}</code>.

===listattr===

{{DPL parameter
 |name   = listattr
 |purpose= Add attributes to HTML '''list ''type'' declaration''' elements, depending on <code>{{DPL|mode}}</code> (HTML element is {{tt|ol}} for ordered, {{tt|ul}} for unordered, {{tt|div}} for others). Can be used with '''pseudo''' <code>{{DPL|mode}}=''inline''</code> where inline text contains one or more {{tt|<nowiki><br/></nowiki>}}.
Only applicable to <code>{{DPL|mode}}=''ordered''</code> or <code>{{DPL|mode}}=''unordered''</code>. Not applicable to <code>{{DPL|mode}}=''category''</code> or <code>{{DPL|mode}}=''inline''</code> (with no {{tt|<nowiki><br/></nowiki>}} in inline text).
}}


'''Syntax:'''<br>

{{syntax|listattr{{=}} ''attribute1{{=}}"val1"'' ''attribute2{{=}}"val2"'' ...}}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: listattr (example 1)|Example}}
{{ViewTest|Examples|Parameter: listattr (example 1)}}


'''If''' there is one page output for each category, the HTML structure output is:

<!-- this causes html to appear highlighted -->
<syntaxhighlight lang="HTML">
<dl id="dl-example" class="dpl-orange-background">
  <dt>Category_1</dt>
  <dd id="list-item-heading-attrubite" class="list-item-heading-attrubite">
    <ol id="ol-example" class="dpl-blue-background">
      <li>Page_1</li>
    </ol>
  </dd>
  <dt>Category_2</dt>
  <dd id="list-item-heading-attrubite" class="list-item-heading-attrubite">
    <ol id="ol-example" class="dpl-blue-background">
      <li>Page_1</li>
      <li>Page_2</li>
    </ol>
  </dd>
</dl>
</syntaxhighlight><!-- this causes html to appear highlighted -->


'''Note:''' To format subsequent elements in the same result set, see also (in the corresponding order since the examples build on one another) <code>{{DPL|itemattr}}</code>.


===itemattr===

{{DPL parameter
 |name   = itemattr
 |purpose= Add attributes to HTML '''list items''', depending on <code>{{DPL|mode}}</code> (element is {{tt|li}} for ordered/unordered, {{tt|span}} for others).
Not applicable to <code>{{DPL|mode}}=category</code>.
}}


'''Syntax:'''<br>

{{syntax|itemattr{{=}} ''attribute1{{=}}"val1"'' ''attribute2{{=}}"val2"'' ...}}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: itemattr (example 1)|Example}}
{{ViewTest|Examples|Parameter: itemattr (example 1)}}


'''If''' there are multiple pages output for each category, the HTML structure output is:

<!-- this causes html to appear highlighted -->
<syntaxhighlight lang="HTML">
<dl id="dl-example" class="dpl-orange-background">
  <dt>Category_1</dt>
  <dd id="list-item-heading-attrubite" class="list-item-heading-attrubite">
    <ol id="ol-example" class="dpl-blue-background">
      <li id="li-example" class="li-example">Page_1</li>
    </ol>
  </dd>
  <dt>Category_2</dt>
  <dd id="list-item-heading-attrubite" class="list-item-heading-attrubite">
    <ol id="ol-example" class="dpl-blue-background">
      <li id="li-example" class="li-example">Page_1</li>
      <li id="li-example" class="li-example">Page_2</li>
    </ol>
  </dd>
</dl>
</syntaxhighlight><!-- this causes html to appear highlighted -->


===headingcount===

{{DPL parameter
 |name   = headingcount
 |purpose= Decides, combined with <code>{{DPL|headingmode}}</code>, whether to show a text line with the number of articles per group or not.
}}


'''Syntax:'''<br>

{{syntax|headingcount{{=}}''true''}}


'''Note:''' ('''default''' is <code>headingcount=false</code>, it need not be set)


===userdateformat===

{{DPL parameter
 |name   = userdateformat
 |purpose= Define a special layout for date formatting.
}}


'''Syntax:'''<br>

{{syntax|userdateformat{{=}}''formatstring''}} where {{tt|formatstring}} sets the date format. 

The {{tt|formatstring}} may contain letters like "y,Y,m,M,d,D,h,H,i,I,s" for year, month day. Other characters are printed as they are. See the documentation for PHP function date() for more details [http://www.php.net/manual/en/function.date.php]. The <code>{{DPL|userdateformat}}</code> applies to all date/time fields, see the parameters: <code>{{DPL|addeditdate}}</code>, <code>{{DPL|addpagetoucheddate}}</code>,<code>{{DPL|addfirstcategorydate}}</code>.


'''Example:'''

<code>userdateformat=''Y-m-d (D)''</code>

Default:

By default, DPL3 uses "Y-m-d H:i:s" to display date and time. Note that MediaWiki stores all dates/times in UTC format. When displaying a time stamp, DPL3 translates it according to:
# The timezone preference (difference to UTC/GMT) given by the user in his user settings.
# If no preference is given, and for all anonymous users, the local time on the server is used.

So, either time based on the user's local time (browser based), or based on the timezone in which the wiki server is running is seen.

The same kind of translation applies to dates specified when selecting articles by revision date/time.



==Control the way article names are displayed==

===shownamespace===

{{DPL parameter
 |name   = shownamespace
 |purpose= Restrict the appearance of the namespace name of a page before the page. As the switch is {{tt|true}} by default, it should be set to {{tt|false}} to avoid namespaces being shown in the output.
}}


'''Syntax:'''<br>

{{syntax|shownamespace{{=}}''false''}}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: shownamespace (example 1)|Example}}
{{ViewTest|Examples|Parameter: shownamespace (example 1)}}


'''Note:''' In <code>{{DPL|mode}}=''userformat''</code> there is a different way to decide whether output the title with or without namespace is desired; two built-in variables are provided which contain the page name including the namespace (<code>{{DPL|%PAGE%}}</code>) and the base title name (<code>{{DPL|%TITLE%}}</code>). Setting <code><nowiki>[[%PAGE%|%TITLE%]]</nowiki></code> links to the full page with namespace, but displays the link text without namespace. 


===escapelinks===

{{DPL parameter
 |name   = escapelinks
 |purpose= Determines if links are escaped as a link, or used directly as-is. When used to display ''File:'' namespace '''image''' names, or ''Category:'' namespace page names, this causes:
* A link to the image or to the category page to be produced (<code>{{DPL|escapelinks}}=''true''</code> – '''default''', need not be set).
* The image or category to be directly inserted (the former displays the image on-page, the latter categorizes the page it appears on, into the categories of the result set; <code>{{DPL|escapelinks}}=''false''</code>). 
}}


'''Syntax:'''<br>

{{syntax|escapelinks{{=}}''false''}}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: imagecontainer (example 1)|Example}}
{{ViewTest|Examples|Parameter: imagecontainer (example 1)}}


'''Notes:'''
* You can use this parameter to show images, the images are displayed at the largest size as will fit on the page (which may be larger than is appropriate).
* Another way to do this is to:
:* Use a format statement, such as: <code><nowiki>|format = ,[[File:%TITLE%|40px]]</nowiki></code> as in the second [[Images_used_(examples)#Gallery_syntax|example here]].
:* Use gallery syntax within a format statement, as in the [[Images used (examples)#Gallery syntax|example here]].


===titlemaxlength===

{{DPL parameter
 |name   = titlemaxlength
 |purpose= To limit the number of characters of the title to display. If the page title (this does not include the namespace or any other prefix before the title) is bigger than the {{DPL|titlemaxlength}} value, the title is truncated and ended by '...'.
}}


'''Syntax:'''<br>

{{syntax|titlemaxlength{{=}}''number of characters''}}


'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: titlemaxlength (example 1)|Example}}
{{ViewTest|Examples|Parameter: titlemaxlength (example 1)}}


===replaceintitle===

{{DPL parameter
 |name   = replaceintitle
 |purpose= execute a string replacement operation on the <code>{{DPL|%TITLE%}}</code> variable.
}}


'''Syntax:'''<br>

{{syntax|replaceintitle{{=}}''search for,replacement''}}


The ''search for'' argument must be an expression which can be used in a PHP [https://www.php.net/manual/en/function.preg-replace.php preg_replace()] function call.


To remove the string "demo" in article names, it must be written as:
: <syntaxhighlight lang="wikitext" copy>replaceintitle=/demo/,</syntaxhighlight>

'''Example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: replaceintitle (example 1)|Example}}
{{ViewTest|Examples|Parameter: replaceintitle (example 1)}}


'''Notes:'''
* Standard regexp rules apply.
* The regexp must start with a non-alphanumeric character – but not necessarily with a backslash! It is a good habit to use <code>/</code> if this character is not needed within the regexp itself.
{{regexpinfo}}


==Arranging article lists in columns and rows==

===columns===

{{DPL parameter
 |name   = columns
 |purpose= Defines a column layout for the output.

{{red|Currently non-working,}} though a '''workaround''' has been provided.
}}


'''Syntax:'''<br>

{{syntax|columns{{=}}''ncols''}} where {{tt|ncols}} is the number of desired columns.


{{note|'''Warning''': The <code>{{DPL|columns}}</code> parameter is currently bugged and is non-working {{#tag:ref|The <code>columns</code> parameter is currently bugged and [https://gitlab.com/hydrawiki/extensions/DynamicPageList/issues/81 does not work]|name="columnsbug"}} A workaround is provided below.|error}}


This (if it worked) lists pages in <code>{{DPL|category}}</code> [[:Category:Fruit examples|Fruit examples]], sets <code>{{DPL|includesubpages}}</code> to {{tt|false}} to exclude them. It arranges the content in '''3''' <code>{{DPL|columns}}</code> with <code>{{DPL|rowcolformat}}</code> set to make width 100%. Results are limited to a <code>{{DPL|count}}</code> of '''3'''.

{{DPL Code|<nowiki>
{{#dpl:
|category        = Fruit examples
|includesubpages = false
|columns         = 3              <!-- non-working -->
|rowcolformat    = width=100%     <!-- non-working -->
|count           = 3
}}
</nowiki>|noresult=y}}


'''Workaround example:'''<br><br><!-- transclude example from subpage-->{{#lsth:Examples/Parameter: columns (example 1)|Example}}
{{ViewTest|Examples|Parameter: columns (example 1)}}


'''Note:''' In <code>{{DPL|mode}}=''userformat''</code> the outer tags from <code>listseparators</code> are repeated for each column. This means that such a statement could create tables ''within'' columns, with something like:

<syntaxhighlight lang="wikitext" copy>
  addpagesize=true
  ordermethod=size
  listseparators={|class="wikitable sortable" id=2\n!Rank\n!Article\n!Bytes\n|-,\n|%NR%.\n|[[%PAGE%]]\n|style="text-align:right;|%SIZE%,\n|-,\n|}
</syntaxhighlight>


===rows===
{{DPL parameter
 |name   = rows
 |purpose= Define a row layout for the output. A "row" is a group of output lines for which the heading is repeated. If how big your result will be is unknown, it may be better to use the <code>{{DPL|rowsize}}</code> parameter.

{{red|Currently non-working.}}
}}


'''Syntax:'''<br>

{{syntax|rows{{=}}''nrows''}} where {{tt|nrows}} is the number of desired rows.


In <code>{{DPL|mode}}=''userformat''</code>, the outer tags from <code>{{DPL|listseparators}}</code> are repeated for each column. Thus, long lists can be created where the table heading is repeated from time to time.


This lists the largest pages in <code>{{DPL|category}}</code> [[:Category:Fruit examples|Fruit examples]], with <code>{{DPL|addpagesize}}</code> added to the results. 


arranged in two rows (dividing the list of lines equally into 2). Each row consists of a table which has itself three columns: rank, article name, and size. <code>{{DPL|ordermethod}}</code> sets sort order by page {{tt|size}}, the <code>{{DPL|%NR%}}</code> variable displays the number of each article in the first row. The <code>{{DPL|listseparators}}</code> line sets table styles and header, <code>{{DPL|rows}}</code> specifies '''2''' for how many results are displayed before the heading repeats. Results are limited to a <code>{{DPL|count}}</code> of '''6'''.

{{tempnote}}


'''Example:'''<br>
{{DPL Code|<nowiki>
{{#dpl:
|category        = Fruit examples
|addpagesize     = true
|ordermethod     = size
|listseparators  = {¦class="wikitable sortable" id=2\n!Rank\n!Article\n!Bytes\n¦-,\n¦%NR%.\n¦[[%PAGE%]]\n¦style="text-align:right;"¦%SIZE%,\n¦-,\n¦}
|rows            = 2
|count           = 6
}}
</nowiki>}}


===rowsize===

{{DPL parameter
 |name   = rowsize
 |purpose= Define a row layout for the output. A "row" is a group of n output lines for which the heading are repeated.

{{red|Currently non-working.}}
}}


'''Syntax:'''<br>

{{syntax|rowsize{{=}}''nrowsize''}} where {{tt|nrowsize}} is the desired row size.


In <code>{{DPL|mode}}=''userformat''</code> the outer tags from <code>{{DPL|listseparators}}</code> are repeated after each group of <code>{{DPL|rowsize}}</code> output lines.
Thus, long lists can be created where the table heading is repeated in regular intervals.


This lists all pages in <code>{{DPL|category}}</code> [[:Category:Fruit examples|Fruit examples]]. <code>{{DPL|addpagesize}}</code> adds page size to the output. <code>{{DPL|ordermethod}}</code> sets the order to order by {{tt|size}}. The <code>{{DPL|listseparators}}</code> row sets table formatting and uses the <code>{{DPL|%NR%}}</code> variable to list a number for each page. <code>{{DPL|rowsize}}</code> specifies the number of result pages ('''3''') after which the table heading is repeated. Results are limited to a <code>{{DPL|count}}</code> of '''6'''.

'''Example:'''<br>
{{tempnote}}
{{DPL Code|<nowiki>
{{#dpl:
|category        = Fruit examples
|addpagesize     = true
|ordermethod     = size
|listseparators  = {¦class="wikitable sortable" id=2\n!Rank\n!Article\n!Bytes\n¦-,\n¦%NR%.\n¦[[%PAGE%]]\n¦style="text-align:right;"¦%SIZE%,\n¦-,\n¦}
|rowsize         = 3
|count           = 6
}}
</nowiki>}}


===rowcolformat===

{{DPL parameter
 |name   = rowcolformat
 |purpose= Defines layout properties (using allowed [[mw:Help:HTML in wikitext|HTML table tag parameters]]) for the row/column grid.

{{red|Currently non-working.}}
}}


'''Syntax:'''<br>

{{syntax|rowcolformat{{=}}''HTML tags''}} where {{tt|HTML tags}} are the desired (allowed) [[mw:Help:HTML in wikitext|HTML tags]] to set. 



'''Example:'''<br>
{{tempnote}}
This lists pages in <code>{{DPL|category}}</code> [[:Category:Fruit examples|Fruit examples]], displayed in '''3''' <code>{{DPL|columns}}</code>, with <code>{{DPL|rowcolformat}}</code> setting more space around the columns. The result <code>{{DPL|count}}</code> is limited to '''6'''.

{{DPL Code|<nowiki>
{{#dpl:
|category        = Fruit examples
|columns         = 3
|rowcolformat    = cellspacing=20
|count           = 6
}}
</nowiki>}}


'''Example:'''
{{Tempnote}}
The ideal way to use <code>{{DPL|rowcolformat}}</code> is to assign a CSS class to the DPL3 table, which has been defined in the ''MediaWiki:Common.css'' article.

{{DPL Code|<nowiki>
{{#dpl:
|category        = Fruit examples
|includesubpages = false
|columns         = 3
|rowcolformat    = class="dpl3columns"
|count           = 6
}}
</nowiki>}}


In the {{tt|MediaWiki:Common.css}} page, something like the following might be written:

<syntaxhighlight lang="css" copy>
.dpl3columns td {
   background: #f2f2f2;
   padding: 0.5em;
   border: 3px;
   width: 33%;
}
</syntaxhighlight>


==References==
<references>
<ref name=hitcounters>The built-in features of hit counters were completely removed in MediaWiki 1.25, following a request for comment. See [[Hit counters removed]], though this functionality can be restored by adding the [[mw:Extension:HitCounters|HitCounters]] extension.</ref>
</references>
</div>
[[Category:Primary Module|02]]