Editing DPL3/Parameters: Controlling output format (section)

=====format=====

{{DPL parameter
 |name   = format
 |purpose= customize the output format completely. Implicitly sets {{dpl3|mode|=userformat}}. Uses variable references like {{tt|%PAGE%}} to describe the output format. See also the {{dpl3|secseparators}} parameter.
}}

Note1: {{dpl3|listseparators}} is an alias for {{dpl3|format}}.

Note2: the {{dpl3|format}} command is very flexible but somewhat complicated. If you want to create tabular output, you should have a look at the {{dpl3|table}} command.

Syntax:

{{DPL syntax|format=''Startall'',''Start'',''End'',''Endall''}}

''Startall'', ''Start'', ''End'' and ''Endall'' are wiki tags used to separate the list items.
* ''Startall'' and ''Endall'' define an outer frame for the whole list.
* ''Start'' and ''End'' build an inner frame for each article item.

Because wiki syntax depends on newline characters, {{code|\n}} or {{code|¶}} must be used to explicitly insert newline characters into the output.

As we want to be able to control output completely, we reference article names and other possible output by special {{dpl3|VARIABLES|%VARIABLES%}}:
{{anchor|VARIABLES}}
* {{tt|%NR%}} = the current article sequence number (starting from 1)
* {{tt|%PAGE%}} = the name of the article (including namespace)
* {{tt|%PAGEID%}} = the internal unique numeric ID of the article page
* {{tt|%IMAGE%}} = the physical path to an image (based on hash values, e.g. ''5/5d/myImage.jpg'')
* {{tt|%PAGESEL%}} = the name of a page which was used within the selection criteria (only applies to {{dpl3|linksfrom}} and {{dpl3|linksto}})
* {{tt|%IMAGESEL%}} = the name of an image which was used within the selection criteria (only applies to {{dpl3|imageused}})
----
* {{tt|%TITLE%}} = the title of the page (without the namespace)
* {{tt|%NAMESPACE%}} = the namespace of the page
----
* {{tt|%SIZE%}} = the article size (requires {{dpl3|addpagesize|=true}})
* {{tt|%SIZEFS%}} = a font size number which is based on the article size (logarithm of square root of counter)
* {{tt|%COUNT%}} = the usage counter (requires {{dpl3|addpagecounter|=true}}) {{red|Removed in MediaWiki 1.25}}<ref name=hitcounters/>
* {{tt|%COUNTFS%}} = a font size number which is based on the usage counter (currently this is the logarithm of the usage counter) {{red|Removed in MediaWiki 1.25}}<ref name=hitcounters/>
* {{tt|%COUNTFS2%}} = similar to {{tt|%COUNTFS%}}, but based on the logarithm of the square root of the usage counter {{red|Removed in MediaWiki 1.25}} <ref name=hitcounters/>
----
* {{tt|%DATE%}} = the date selected, eg. {{tt|lastedit}}; requires {{dpl3|addeditdate|=true}} or similar; the formatting of the date can be influenced using {{dpl3|userdateformat|=}}
* {{tt|%USER%}} = the user who changed the document last; requires {{dpl3|adduser|=true}}
----
* {{tt|%CONTRIBUTOR%}} = the user who made a contribution; requires {{dpl3|addcontribution|=true}}
* {{tt|%CONTRIBUTION%}} = the number of bytes changed; requires {{dpl3|addcontribution|=true}}
* {{tt|%CONTRIB%}} = an asterisk bar to indicate the amount of change; requires {{dpl3|addcontribution|=true}}
----
* {{tt|%CATLIST%}} = a pipe-separated list of links to all categories to which the article belongs (requires {{dpl3|addcategories|=true}})
* {{tt|%CATBULLETS%}} = a bullet point list of links to all categories to which the article belongs (requires {{dpl3|addcategories|=true}})
* {{tt|%CATNAMES%}} = a comma-separated list of all categories to which the article belongs (requires {{dpl3|addcategories|=true}})
----
* {{tt|%REVISION%}} = the name of the revision of the article; only accessible if the DPL query is based on {{dpl3|REVISION|revisions}}
* {{tt|%EDITSUMMARY%}} = the change log message of a revision; only accessible if the DPL query is based on {{dpl3|REVISION|revisions}}
----
* {{tt|%EXTERNALLINK%}} = the external hyperlink found as a consequence of the {{dpl3|linkstoexternal}} statement
----

These variables will be replaced by the corresponding values if they occur within ''Start'' or ''End'' or within the corresponding tags of the {{dpl3|secseparators|=}} parameter.

----

In addition there are some symbolic variables which can ONLY be used in {{dpl3|resultsheader}} and {{dpl3|resultsfooter}}:
* {{tt|%PAGES%}} = number of articles in the result set
* {{tt|%TOTALPAGES%}} = total number of articles in the result set, regardless of count limits; will only be calculated if used
* {{tt|%VERSION%}} = the current DPL version
----
* {{tt|%DPLTIME%}} = contains the amount of time (in seconds + milliseconds) spent within DPL; this can be helpful if you observe slow response times for wiki pages that contain DPL statements.  Example: ''2 (2009/06/13 09:27:43)'' would mean that DPL spent two seconds of the whole response time, starting at the time given in brackets.
----
* {{tt|%FIRSTNAMESPACE%}}, {{tt|%FIRSTTITLE%}}, {{tt|%LASTNAMESPACE%}}, {{tt|%LASTTITLE%}} = namespace and title of the first / last article in the result set; the information is intended to be used for page scrolling
* {{tt|%SCROLLDIR%}} = set by the URL parameter {{tt|DPL_scrollDir}}; it is passed to the scroll helper template which uses it to produce its links for scrolling

----

For example, the classical default output of DPL can also be produced with the following statements:

<!-- originally, category=Africa, and there was no titlematch/nottitlematch-->
{| style="border-spacing: 10px 0;"
| align=center| default || align=center| formatted
|- style="vertical-align:top;"
|<pre><nowiki>
<dpl>
  titlematch	  = %Help%
  nottitlematch	  = %o%
  includesubpages = false
</dpl>
</nowiki></pre>
|<pre><nowiki>
<dpl>
  titlematch	  = %Help%
  nottitlematch	  = %o%
  includesubpages = false
  format	  = ,\n* [[%PAGE%]],,
</dpl>
</nowiki></pre>
|-
|<dpl>
  titlematch		= %Help%
  nottitlematch		= %o%
  includesubpages	= false
</dpl>
|<dpl>
  titlematch		= %Help%
  nottitlematch		= %o%
  includesubpages	= false
  format			= ,\n* [[%PAGE%]],,
</dpl>
|}
Note that a bullet point list in wiki syntax is defined by a {{code|*}} at the ''beginning of a line'' &mdash; therefore we have to use a special symbol {{code|\n}} or {{code|¶}} to refer to the beginning of a new line of wiki text. Replace the {{code|*}} with a {{code|#}} and you will get a numbered list. {{tt|Startall}} and {{tt|Endall}} are empty (note that we start with a comma, note the two commas at the end), the {{tt|Start}} tag is used to create a new line with an initial <code>* </code> followed by the page name, written as a link. That's all.

Creating a top-five hitlist with access rates and bold article names of varying size could be done like this:
<pre><nowiki>
<dpl>
  category	 = Help
  ordermethod	 = counter
  order		 = descending
  addpagecounter = true
  count		 = 5
  format	 = ,\n%COUNT%  --- <font size="%COUNTFS%">'''[[%PAGE%]]'''</font>,<br/>,
</dpl>
</nowiki></pre>
However, {{dpl3|addpagecounter}}, {{dpl3|ordermethod|=counter}}, {{tt|%COUNT%}}, and {{tt|%COUNTFS%}} were removed in MediaWiki 1.25.<br/>
Below is an example of how to use {{tt|%NR%}} to set the font size.
<pre><nowiki>
<dpl>
  category	 = Help
  order		 = descending
  addpagecounter = true
  count		 = 4
  format	 = ,\n<font size="%NR%">'''[[%PAGE%]]'''</font>,<br/>,
</dpl>
</nowiki></pre>
<dpl>
  category		 = Help
  order			 = descending
  addpagecounter = true
  count			 = 4
  format		 = ,\n<font size="%NR%">'''[[%PAGE%]]'''</font>,<br/>,
</dpl>

You can also use HTML syntax for the tags, although this is discouraged.
<pre><nowiki>
<dpl>
  linksto  = DPL
  format   = <ul type="disc">,<li>[[%PAGE%]],</li>,</ul>
</dpl>
</nowiki></pre>
<dpl>
  linksto	= DPL
  format	= <ul type="disc">,<li>[[%PAGE%]],</li>,</ul>
</dpl>

Now let us create a table using wiki syntax:
<pre><nowiki>
<dpl>
  linksto  = DPL
  format   = {| class="wikitable"¶!pages found,¶|-¶|[[%PAGE%]],,¶|}
</dpl>
</nowiki></pre>
We use {{tt|Startall}} to define the table header and {{tt|Endall}} for the footer.
Each article is presented in a table row using wiki syntax for table layout.
<dpl>
  linksto	= DPL
  format	= {| class="wikitable"¶!pages found,¶|-¶|[[%PAGE%]],,¶|}
</dpl>

We could also produce image galleries:
<pre><nowiki>
<dpl>
  namespace = File
  category  = Hydra images|Template images
  count	    = 6
  format    = <gallery widths=20px heights=20px>,%PAGE%\n,,</gallery>
</dpl>
</nowiki></pre>
<dpl>
  namespace	= File
  category	= Hydra images|Template images
  count		= 6
  format	= <gallery widths=20px heights=20px>,%PAGE%\n,,</gallery>
</dpl>