Extension:DPL3/Parameters: Controlling output format

Template:DPL manual

You can select one of several default formats or define your own format (Template:Dpl3); output can be grouped in columns or rows.

In the examples that follow, the DPL output has been kept small to reduce page load time and page size, most notably using Template:Dpl3, Template:Dpl3, Template:Dpl3, and Template:Dpl3.

## General approach to output formatting

The general approach to output formatting is two-fold:

1. There are a couple of simple predefined output formats which generate lists of articles.
You will understand their meaning directly from reading.
2. There is a mode called Template:Dpl3 which puts complete control into your hands.
This is somewhat complicated.

While the standard output formats are meant to be used for fast generation of simple page lists, the Template:Dpl3 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 (a) the whole output, (b) each item, (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 which use templates Template:Tt and Template:Tt with varying arguments; while Template:Tt is being used once within each document, Template:Tt is used several times. In very short notation the structure might look as follows:

```
 A: x(a) y(3) y(5)
 B: x(b) y(4) y(1) y(2)
```

The following DPL parameters are used to define a set of tags which are used to construct the output:

* Template:Dpl3 = *liststart*,*itemstart*,*itemend*,*listend*
* Template:Dpl3 = *sec-1-start*,*sec-1-end*,*sec-2-start*,*sec-2-end*, .. , ..
* Template:Dpl3 = *multi-sep*

The arguments of the above statements can contain **references to Template:Dpl3**. So *sec-1-start* might contain a reference like Template:Tt to output the page name. See Template:Dpl3 for more details on variable substitution.

Now think of the following page inclusion statement:

```
  includepage={x}.dpl,{y}.dpl
```

The output will then look like this:

```
  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
```

Assuming that the tags (Template:Tt, Template:Tt, etc.) contain wiki syntax for table definitions and Template:Tt defines a horizontal line, the output might look like this:

```
  +------+---------------------+
  +------+----------+----------+
  +------+----------+----------+
```

In some situations, however, you may want to create an output table where each of the calls of template Template:Tt is used to create a separate output row. Using a sortable table you could then easily rearrange the output.

```
  +------+---------------------+       +------+---------------------+
  +------+---------------------+       +------+---------------------+
  +------+---------------------+       +------+---------------------+
  +------+---------------------+       +------+---------------------+
  +------+---------------------+       +------+---------------------+
  +------+---------------------+       +------+---------------------+
```

There is a special parameter called Template:Dpl3 which you can use to mark one section of your Template:Dpl3 statement as "dominant" (in our example: Template:Dpl3 as Template:Tt is the second argument of our Template:Dpl3 statement). You can only have one dominant section in a DPL statement. Marking a section as "dominant" only makes sense if you have multiple calls of the same template (or multiple chapters with the same heading) in your documents. Each piece of content in the dominant section will generate an individual output row with the values of all other columns being repeated.

As all of the above is not very easy to understand there are additional DPL commands (Template:Dpl3, Template:Dpl3) which make it fairly easy to create tabular output.

## Setting the basic output mode

### mode

Template:DPL parameter

Syntax:

Template:DPL syntax

*modename* can be one of:

*unordered*
outputs an unordered list — HTML tag Template:Tt — **(default)**
*ordered*
outputs an ordered list — HTML tag Template:Tt
*none*
outputs a list using newlines and HTML tags Template:Tt to separate each item
*inline*
outputs a list using symbols defined by the Template:Dpl3 parameter to separate items
*category*
outputs resulting articles in a way category-pages are shown (**you must use Template:Dpl3 with this option!**)
*userformat*
will leave output control completely to the user;
 see parameters Template:Dpl3 and Template:Dpl3; in this mode DPL offers built-in variables which must be referenced in the output format description provided by the user. **Template:Dpl3** is quite important to have complete control over the output.
For advanced use of DPL it is important to understand Template:Dpl3. Note that this mode is **automatically implied** when Template:Dpl3 or Template:Dpl3 are used.

#### mode 'ordered', 'unordered', 'none' (Example1)

These create abbreviated lists of Category:DPL3 pages:

```
<dpl>
  category=DPL3
  titlematch=%o%
  nottitlematch=%nt%|%ow%|%ec%
  mode=ordered
</dpl>

```
```
<dpl>
  category=DPL3
  titlematch=%o%
  nottitlematch=%nt%|%ow%|%ec%
  mode=unordered
</dpl>

```
```
<dpl>
  category=DPL3
  titlematch=%o%
  nottitlematch=%nt%|%ow%|%ec%
  mode=none
</dpl>

 <dpl>

```
 category=DPL3
 titlematch=%o%
 nottitlematch=%nt%|%ow%|%ec%
 mode=ordered

```

</dpl>

```
 category=DPL3
 titlematch=%o%
 nottitlematch=%nt%|%ow%|%ec%
 mode=unordered

```

</dpl>

```
 category=DPL3
 titlematch=%o%
 nottitlematch=%nt%|%ow%|%ec%
 mode=none

```

</dpl>

#### mode 'category' (Example2)

```
<dpl>
  titlematch=%Help%
  includesubpages=false
  mode=category
  ordermethod=titlewithoutnamespace
</dpl>

```

This list will output pages that have 'Help' in their name; pages will be ordered by their name regardless of category, the output will be shown in category style (i.e. with chapter capitals).
<dpl>

```
 titlematch=%Help%
 includesubpages=false
 mode=category
 ordermethod=titlewithoutnamespace

```

</dpl>

Related configuration option (see Extension:DynamicPageList3 on MediaWiki Wiki: `$wgDPL2CategoryStyleListCutoff`.

#### mode 'inline'

##### inlinetext

Template:DPL parameter

Syntax:

Template:DPL syntax, with *wikitext* as some wiki text;
**default is `Template:&-Template:&`** except for Template:Dpl3 where Template:Dpl3 is empty by default.

If you want normal "breaking spaces" (and not the NON-breaking spaces) you should use `Template:&-Template:&`.

Extra whitespaces are stripped by DPL from the beginning and end of *wikitext*. If you want to show one or multiple spaces, use one or multiple `Template:&`, or use 'nowiki' tags Template:Tag which has the same effect as `Template:&-Template:&`.

Bullets can be displayed with either `Template:&` or Template:Tl.

Example:

```
<dpl>
  category	= Help
  includesubpages= false
  count		= 10
  mode		= inline
  inlinetext	= &nbsp; &bull; &nbsp;
</dpl>

```

This list outputs pages that have Category:Help shown like Item1 • Item2 • Item3 • ...

<dpl>

```
 category		= Help
 includesubpages = false
 count			= 10
 mode			= inline
 inlinetext	=   •

```

</dpl>

#### Template:Anchormode 'userformat'

##### format

Template:DPL parameter

Note1: Template:Dpl3 is an alias for Template:Dpl3.

Note2: the Template:Dpl3 command is very flexible but somewhat complicated. If you want to create tabular output, you should have a look at the Template:Dpl3 command.

Syntax:

Template:DPL syntax

*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, Template:Code or Template: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 Template:Dpl3:
Template:Anchor

* Template:Tt = the current article sequence number (starting from 1)
* Template:Tt = the name of the article (including namespace)
* Template:Tt = the internal unique numeric ID of the article page
* Template:Tt = the physical path to an image (based on hash values, e.g. *5/5d/myImage.jpg*)
* Template:Tt = the name of a page which was used within the selection criteria (only applies to Template:Dpl3 and Template:Dpl3)
* Template:Tt = the name of an image which was used within the selection criteria (only applies to Template:Dpl3)

* Template:Tt = the title of the page (without the namespace)
* Template:Tt = the namespace of the page

* Template:Tt = the article size (requires Template:Dpl3)
* Template:Tt = a font size number which is based on the article size (logarithm of square root of counter)
* Template:Tt = the usage counter (requires Template:Dpl3) Template:Red
* Template:Tt = a font size number which is based on the usage counter (currently this is the logarithm of the usage counter) Template:Red
* Template:Tt = similar to Template:Tt, but based on the logarithm of the square root of the usage counter Template:Red

* Template:Tt = the date selected, eg. Template:Tt; requires Template:Dpl3 or similar; the formatting of the date can be influenced using Template:Dpl3
* Template:Tt = the user who changed the document last; requires Template:Dpl3

* Template:Tt = the user who made a contribution; requires Template:Dpl3
* Template:Tt = the number of bytes changed; requires Template:Dpl3
* Template:Tt = an asterisk bar to indicate the amount of change; requires Template:Dpl3

* Template:Tt = a pipe-separated list of links to all categories to which the article belongs (requires Template:Dpl3)
* Template:Tt = a bullet point list of links to all categories to which the article belongs (requires Template:Dpl3)
* Template:Tt = a comma-separated list of all categories to which the article belongs (requires Template:Dpl3)

* Template:Tt = the name of the revision of the article; only accessible if the DPL query is based on Template:Dpl3
* Template:Tt = the change log message of a revision; only accessible if the DPL query is based on Template:Dpl3

* Template:Tt = the external hyperlink found as a consequence of the Template:Dpl3 statement

These variables will be replaced by the corresponding values if they occur within *Start* or *End* or within the corresponding tags of the Template:Dpl3 parameter.

In addition there are some symbolic variables which can ONLY be used in Template:Dpl3 and Template:Dpl3:

* Template:Tt = number of articles in the result set
* Template:Tt = total number of articles in the result set, regardless of count limits; will only be calculated if used
* Template:Tt = the current DPL version

* Template:Tt = 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.

* Template:Tt, Template:Tt, Template:Tt, Template:Tt = namespace and title of the first / last article in the result set; the information is intended to be used for page scrolling
* Template:Tt = set by the URL parameter Template:Tt; 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:

```
<dpl>
  titlematch	  = %Help%
  nottitlematch	  = %o%
  includesubpages = false
</dpl>

```
```
<dpl>
  titlematch	  = %Help%
  nottitlematch	  = %o%
  includesubpages = false
  format	  = ,\n* [[%PAGE%]],,
</dpl>

 <dpl>

```
 titlematch		= %Help%
 nottitlematch		= %o%
 includesubpages	= false

```

</dpl>

```
 titlematch		= %Help%
 nottitlematch		= %o%
 includesubpages	= false
 format			= ,\n* %PAGE%,,

```

</dpl>

Note that a bullet point list in wiki syntax is defined by a Template:Code at the *beginning of a line* — therefore we have to use a special symbol Template:Code or Template:Code to refer to the beginning of a new line of wiki text. Replace the Template:Code with a Template:Code and you will get a numbered list. Template:Tt and Template:Tt are empty (note that we start with a comma, note the two commas at the end), the Template:Tt tag is used to create a new line with an initial `*`  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:

```
<dpl>
  category	 = Help
  ordermethod	 = counter
  order		 = descending
  addpagecounter = true
  count		 = 5
  format	 = ,\n%COUNT%  --- <font size="%COUNTFS%">'''[[%PAGE%]]'''</font>,<br/>,
</dpl>

```

However, Template:Dpl3, Template:Dpl3, Template:Tt, and Template:Tt were removed in MediaWiki 1.25.

Below is an example of how to use Template:Tt to set the font size.

```
<dpl>
  category	 = Help
  order		 = descending
  addpagecounter = true
  count		 = 4
  format	 = ,\n<font size="%NR%">'''[[%PAGE%]]'''</font>,<br/>,
</dpl>

```

<dpl>

```
 category		 = Help
 order			 = descending
 addpagecounter = true
 count			 = 4
 format		 = ,\n**%PAGE%**,
,

```

</dpl>

You can also use HTML syntax for the tags, although this is discouraged.

```
<dpl>
  linksto  = DPL
  format   = <ul type="disc">,<li>[[%PAGE%]],</li>,</ul>
</dpl>

```

<dpl>

```
 linksto	= DPL

```

 format = ,* %PAGE%,
,

</dpl>

Now let us create a table using wiki syntax:

```
<dpl>
  linksto  = DPL
</dpl>

```

We use Template:Tt to define the table header and Template:Tt for the footer.
Each article is presented in a table row using wiki syntax for table layout.
<dpl>

```
 linksto	= DPL

```

</dpl>

We could also produce image galleries:

```
<dpl>
  namespace = File
  category  = Hydra images|Template images
  count	    = 6
  format    = <gallery widths=20px heights=20px>,%PAGE%\n,,</gallery>
</dpl>

```

<dpl>

```
 namespace	= File
 category	= Hydra images|Template images
 count		= 6

```

 format = ,%PAGE%\n,,
</dpl>

##### secseparators

Template:DPL parameter

Syntax:

Template:DPL syntax

or

Template:DPL syntax

*Please note that the semantics of this parameter **have changed with version 0.9.6!**. When upgrading to 0.9.6 it will probably be necessary to change the Template:Dpl3 statements.*

In the first syntax variant, specify *pairs of tags* which correspond to the Template:Dpl3 statement. Template:Tt and Template:Tt are HTML strings or wiki tags which will be put around each transcluded section (see Template:Dpl3).

In the second syntax variant, specify just one element which will then be used as Template:Tt for all sections; in this case the second tag (Template:Tt) will be empty for all transcluded sections.

Symbolic replacements of Template:Tt etc. take place as described in Template:Dpl3. In addition, the variable Template:Tt can be used to refer to the section found (works only for 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 occurences will be transcluded as a block and the Template:Dpl3 tags will only be put once around the whole block (but see Template:Dpl3).

###### Example

```
<dpl>
  titlematch     = DPL3/d%
  ignorecase     = true
  linksto        = Extension:DPL3/Manual
  includepage    = #Syntax,##Example.*
  secseparators  = ¶|,,¶|,,
  count          = 2
</dpl>

```

<dpl>

```
 titlematch     = DPL3/d%
 ignorecase     = true
 linksto        = Extension:DPL3/Manual
 includepage    = #Syntax,##Example.*
 secseparators  = ¶|,,¶|,,
 count          = 2

```

</dpl>
Use Template:Dpl3 to define a table with three columns and put a link to the article in the first column of each row. Use Template:Dpl3 to add more columns for each section found. There are two pairs for each transcluded section; the first element of each pair is a linefeed and a pipe (which define a new column in the table) and the second element of each pair is empty. Have a careful look at the Template:Code symbols (Template:Code can be used as an alternative). They always appear before a wiki syntax element which must be placed at the beginning of a new line. Thus, make sure that the wiki parser will understand them. Note: if an article does not contain a section named "Example", it will result in an empty cell in the table.

As mentioned above, a single element can be used in the Template:Dpl3 statement in order to apply this as a start tag to all transcluded sections; so it could have also been written:

###### Example 2

```
<dpl>
  titlematch     = DPL3/d%
  ignorecase     = true
  linksto        = Extension:DPL3/Manual
  includepage    = #Syntax[84],##Example.*[180 more..]
  count          = 3
</dpl>

```

Assuming that the chapters on *Syntax* and *Example* contain long texts, they can be truncated (eg. to 84 or 180 characters). A link which refers directly to those chapters will be generated automatically if needed. Be aware that truncating with Template:Codecan break text formatted with wikitext or tags such as Template:Tag.
<dpl>

```
 titlematch     = DPL3/d%
 ignorecase     = true
 linksto        = Extension:DPL3/Manual
 includepage    = #Syntax[84],##Example.*[180 more..]
 count          = 3

```

</dpl>

##### multisecseparators

Template:DPL parameter

Syntax:

Template:DPL syntax

The tags correspond to the transcluded section (see Template:Dpl3).

Symbolic replacements of Template:Tt etc. take place as described in Template:Dpl3. In addition, the variable Template:Tt can be used to refer to the section found (works only for chapter headings). It will give you the precise name of each heading even if you used a regular expression (double ##) in the include statement.

If an article uses the same template more than once you will get all references with Template:Tt as a separator.

Example:

```
<dpl>
  titlematch	    = DPL%
  nottitlematch	    = %volume%|%page selection%
  uses		    = Template:DPL Parameter
  include	    = {dpl manual}:[[%PAGE%|%TITLE%]],{dpl parameter}:name:purpose[50]
  mode		    = userformat
  secseparators	    = ¶|,,¶|class="dpl dark-background"|,
</dpl>

```
 titlematch		= DPL%
 nottitlematch		= %volume%|%page selection%
 uses				= Template:DPL Parameter
 include			= {dpl manual}:%TITLE%,{dpl parameter}:name:purpose[50]
 mode				= userformat
 secseparators		= ¶|,,¶|class="dpl dark-background"|,

```

</dpl>
 Values cannot be formatted within Template:Dpl3, as formatting can only occur in formatting statements (in these examples Template:Dpl3, Template:Dpl3, and Template:Dpl3). Template:Tt can be omitted from the Template:Dpl3, and instead be placed in these formatting statements, for further formatting.

```
 include	= {dpl manual}:Template:Code,{dpl parameter}:name:purpose[50]
 secseparators  = ¶|Template:Code,¶|class="dpl dark-background"|,

```
```
 include	= {dpl manual}:Template:Code,{dpl parameter}:name:purpose[50]
 secseparators  = Template:Code,,¶|class="dpl dark-background"|,Template:Code

 <dpl>

```
 titlematch		= DPL%
 nottitlematch		= %volume%|%page selection%
 uses				= Template:DPL Parameter
 include			= {dpl manual}:%TITLE%,{dpl parameter}:name:purpose[50]
 mode				= userformat

```

</dpl>

```
 titlematch		= DPL%
 nottitlematch		= %volume%|%page selection%
 uses				= Template:DPL Parameter
 include			= {dpl manual}:,{dpl parameter}:name:purpose[50]
 mode				= userformat
 secseparators		= ,,¶|class="dpl dark-background"|,,¶|,

```

```
  titlematch	    = DPL%
  nottitlematch	    = %volume%|%page selection%
  uses		    = Template:DPL Parameter
  include	    = {dpl manual}:,{DPL parameter} dpl
  mode		    = userformat
  secseparators	    = ,,¶|class="dpl dark-background"|,,¶|,

 <dpl>

```
 titlematch		= DPL%
 nottitlematch		= %volume%|%page selection%
 uses				= Template:DPL Parameter
 include			= {dpl manual}:,{DPL parameter} dpl
 mode				= userformat
 secseparators		= ,,¶|class="dpl dark-background"|,,¶|,

```

</dpl>

```
 titlematch		= DPL%
 nottitlematch		= %volume%|%page selection%
 uses				= Template:DPL Parameter
 include={dpl manual}:,{DPL parameter} dpl.nowordbreak
 mode				= userformat
 secseparators		= ,,¶|class="dpl dark-background"|,,¶|,

```

</dpl>

As you can see, the results resemble the list generated on the title page of this manual, whose dpl is as follows:

```
<dpl>
  nottitlematch=%volume%|%page selection%
  namespace = Help
  uses = Template:DPL parameter
  mode = userformat
  replaceintitle = @DPL Manual/@,
  include = {DPL Manual}:[[%PAGE%|%TITLE%]],{DPL parameter}/dpl
  allowcachedresults = true
</dpl>

```

<dpl>

```
 nottitlematch=%volume%|%page selection%
 namespace = Help
 uses = Template:DPL parameter
 mode = userformat
 replaceintitle = @DPL Manual/@,
 include = {DPL Manual}:%TITLE%,{DPL parameter}/dpl
 allowcachedresults = true

```

</dpl>

See also Template:Dpl3.

##### dominantsection

Template:DPL parameter

Syntax:

Template:DPL syntax between 1 and the number of arguments in your Template:Dpl3 statement

If there is only 0 or 1 piece of contents for the dominant section you will see no difference from normal DPL behaviour.

Example:

See the explanations at the top of this document to understand the meaning of dominantsection.

Note:
Using Template:Dpl3 together with Template:Dpl3 may lead to strange result formatting.

## Generating tabular output

### table

Template:DPL parameter

Syntax:

Template:DPL syntax

The Template:Dpl3 statement is a shortcut which implicitly sets certain values for other DPL parameters, namely Template:Dpl3, Template:Dpl3 / Template:Dpl3, Template:Dpl3, and Template:Dpl3.

The layout is less flexible than the individual use of all of the above parameters but will probably be sufficient in many cases, especially when used together with Template:Dpl3.

If you use Template:Dpl3 in a DPL statement, it does not make sense to use one of the other options mentioned because their values will be overwritten without notice. There is one exception of this rule: It can make sense to specify the THIRD argument for Template:Dpl3 in combination with Template:Dpl3. Therefore this parameter is NOT overwritten by the Template:Dpl3 command. The third argument can be used to output meta data like Template:Tt, Template:Tt etc. as columns in an output table. If you want to do so, the third parameter must contain wiki syntax for output columns like this:

```
include = {some template}:parm1,#some heading
table   =,,tplparm,chapter,#hits
format  =,,\n%COUNT%

```

Do not forget to escape the '|' symbol if your DPL statement uses parser function syntax. You will get a table which contains template parameters, chapter contents and the usage counter as a third column. Meta data can only be placed AFTER normal contents as we use the THIRD parameter of the Template:Dpl3 statement.

The use of Template:Dpl3 requires an Template:Dpl3 statement which should, for reasons of readability, directly precede the Template:Dpl3 statement). Each argument of the Template:Dpl3 statement will produce one or more columns in the output table described in the Template:Dpl3 statement.

**Template:Dpl3 expects a comma-separated list of parameters**:

* The first parameter will be used to describe general parameters for the table
	+ it is recommended to make a CSS reference here, using something like Template:Tt or Template:Tt if *mytable* is defined in the Mediawiki:Common.css document.
	+ Template:Tt is the **default value**. Use double-quotes to specify multiple classes, e.g., Template:Tt.

* The **second parameter** is the headline for the first column.
	+ The first column will automatically contain a reference to the article, so something like *Article* should be o.k.
	+ Template:Tt is the **default value**.
	+ if you use a single Template:Tt (dash), the column with the hyperlink to the article will be *suppressed*. You can supply a hyperlink to the article in any other column if you use Template:Tt within a phantom template.

* All subsequent parameters are column headings which correspond to the arguments of the Template:Dpl3 parameter. Note that if you call a *phantom template* (like Template:Tt) in the include statement, you will have to provide as many headlines as the *phantom template* produces columns.

* Template:Dpl3 will be set to *userformat*

* Template:Dpl3 will be configured to produce wiki syntax which defines a table

* Template:Dpl3 will be configured to produce wiki syntax which creates a table row. The first column will always contain a hyperlink to the article of the query result (except you set the link header to '-' as described above.

* Template:Dpl3 will be configured to produce wiki syntax which creates another table row for multiple occurrences of the *first* Template:Dpl3 argument. For all other arguments a linebreak will be used if we are dealing with template parameters and a horizontal separation line will be used when dealing with chapter contents. The background for this is the following: If you have an article which calls the same template several times, you may want to have a table where each template invocation becomes a row in your table.

When using *phantom templates* (i.e. templates which are called during DPL execution instead of the original template) they must be written to produce output according to wiki table syntax. When entering such a template we are already at the beginning of a column (i.e. a preceding line with a Template:Tt has already been put into the output stream). So start directly with the contents of the first column. To add more columns use a Template:Tt in a separate line. Example:

```
   some output for the first column: {{{1|}}}
   some output for the next column: {{{2|}}}
   some output for the next column: {{{3|}}}

```

It may sound complicated, but is a *huge* improvement compared to the native use of Template:Dpl3, Template:Dpl3, Template:Dpl3 and Template:Dpl3.

A typical DPL statement using the Template:Dpl3 parameter would contain:

```
include =                          #Chapter X,{T1}:parm1,#Chapter Y,{T2}.dpl
table   = class=sortable, Article,      X    ,     t-p  ,     Y    , T2-a, T2-b

```

Note that we have written the above statement in a way to show the correspondence between Template:Dpl3 and Template:Dpl3. You can see the first two parameters which define the table characteristics and a headline for the hyperlink to the article. Then follow headlines for each argument of Template:Dpl3. Note that there are TWO headlines which correspond to the last argument of the Template:Dpl3 statement (assuming that Template:T2.dpl outputs TWO columns). *Template:T2* itself might have more or less than 2 arguments -- it only matters how many columns are output by *Template:T2.dpl*).

Now look at the Template:Dpl3

### tablerow

Template:DPL parameter

Syntax:

Template:DPL syntax

Where *coldef* contains wiki code which uses the symbol '%%' to refer to the corresponding element of an Template:Dpl3 statement.

The Template:Dpl3 statement (which **must** be used as a prerequisite for Template:Dpl3) cares for the basics of table generation. So, when you define a column definition, you only need to specify the code for the field contents itself. You can start with field attributes like "bgcolor" or skip them. You can add a leading Template:Code or Template:Code to make sure that the field contents are displayed correctly if it contains wiki syntax that depends on linebreaks (e.g. enumeration list).
You must specify all columns. i.e. you must have as many entries in the Template:Dpl3 statement as there are columns in your table. Skipping a column would suppress output for that column completely.

The Template:Dpl3 command is best explained by an example:

```
<dpl>
  category=Help
  titlematch=DPL%
  count=4
  includepage ={DPL Manual}:section,%-1[25]
  table       =,Title,Sub Title,Last Section (25 chars)
  tablerow    =style="text-align:center;background-color:lightyellow;"|%%,|%%,
</dpl>

```

<dpl>

```
 category=Help
 titlematch=DPL%
 count=4
 includepage ={DPL Manual}:section,%-1[25]
 table       =,Title,Sub Title,Last Section (25 chars)
 tablerow    =style="text-align:center;background-color:lightyellow;"|%%,|%%,

```

</dpl>
The following example includes the use of Template:Dpl3 and Template:Tt, both of which were removed in MediaWiki 1.25.

```
<dpl>
  category=African Union member states
  nottitlematch=Sudan
  addpagecounter=true
  includepage ={Infobox Country or territory}:area:population_estimate,%0[100]
  format      =,,\n|style="text-align:right;"|²{#ifexpr:%COUNT%>300¦<big>'''%COUNT%'''</big>¦%COUNT%}²,
  table       =,Country,Area,Population,Text,#hits
</dpl>

```

* We select some African countries, we exclude Sudan
* We acquire a piece of meta data about the articles we will find (in our case the usage counter)
* We include two named parameters from a template call, {{Infobox Country or territory}}
* We include a short text passage from the text before the first chapter
* We use the third parameter of Template:Dpl3 to output the usage counter (we could even highlight values above 100 here, for example)
* We highlight usage values above 300
* We define a standard wiki table with the article name in the first column (named "Country")
* We define column headers for transcluded contents and for the usage counter
* We care for right alignment of the numerical values and define a bgcolor for the text

### tablesortcol

Template:DPL parameter

Syntax:

Template:DPL syntax

*number* is the position of the column that shall be used as sortkey when the result is initially displayed.

* column numbering starts with *1*;
* *tablesortcol = 0* means *do not sort*; this is the default.
* Negative numbers are used to sort in descending order; e.g. *-3* would sort according to the third column in descending order.
* Note that the rest of the row after the selected column will also be 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 you used column formatting commands. For the same reason you cannot expect numeric contents to be sorted 'numerically' - sorting will always be alphabetical.
* you can of course use something like 'class=sortable' together with Template:Dpl3. The difference is that ..
	+ interactive sorting only works after the article has been initially displayed
	+ interactive sorting tries to guess the content type of a column and sorts according to that (date, number, string)
* If you do not use Template:Dpl3 the output order of your table rows will depend on the sort order by which the articles were analysed. That order depends on other DPL commands like Template:Dpl3. The default is "alphabetically by title". So, without Template:Dpl3 you get the tablerows in alphabetical sequence of the article names where they come from. With Template:Dpl3 you can order them by the column contents itself.

## Heading mode

### headingmode

Template:DPL parameter

Syntax:

Template:DPL syntax

*modename* can be one of:

* *none* — headings are not displayed, no heading — **(default)**
* *unordered* — outputs an unordered list — HTML tag Template:Tt
* *ordered* — outputs an ordered list — HTML tag Template:Tt
* *definition* — outputs a definition list — HTML tag Template:Tt
* *H2* — outputs sections — HTML tags Template:Tt Template:Red
* *H3* — outputs sections — HTML tags Template:Tt Template:Red
* *H4* — outputs sections — HTML tags Template:Tt Template:Red

Example:

```
<dpl>
  category=Terraria Wiki|Community
  notcategory=Games
  nottitlematch=%d%|Disambiguations
  count=7
  ordermethod=category,title
  headingmode=definition
  mode=ordered
</dpl>

```

This list will output pages that belong to one of the categories Terraria Wiki, Community in a list similar to this (HTML source). The categories are listed in sorted order, and the titles are replaced with the appropriate links (Template:Dpl3 and Template:Dpl3 are simply used to reduce the output size):

```
<dl>
  <dt>Category</dt>
  <dd>
    <ol>
      <li>Page1</li>
      <li>Page2</li>
    </ol>
  </dd>
</dl>

```

```
 category=Terraria Wiki|Community
 notcategory=Games
 nottitlematch=%d%|Disambiguations
 count=7
 ordermethod=category,title
 headingmode=definition
 mode=ordered

```

</dpl>

Headingmode can be used with multi-column output but the length of the columns may in this case vary more than you would expect.

### headingcount

Template:DPL parameter

Syntax:

Template:DPL syntax

default is `headingcount=false`

### listattr

Template:DPL parameter

Syntax:

Template:DPL syntax

Examples:

```
<dpl>
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=none
listattr= class="submenul" class="dpl light-background"
itemattr= class="submenuli" style= "font-style: italic;"
</dpl>

```
```
<ol>
  <li class="submenul" class="dpl light-background"> Cat1 (link)
    <div class="submenul">
      <span class="submenuli" style="font-style: italic;"> Page1_1 </span> <br/>
      <span class="submenuli" style="font-style: italic;"> Page1_2 </span>
    </div>
  </li>
  <li class="submenul" class="dpl light-background"> Cat2 (link)
    <div class="submenul">
      <span class="submenuli" style="font-style: italic;"> Page2_1 </span> <br/>
      <span class="submenuli" style="font-style: italic;"> Page2_2 </span>
    </div>
  </li>
</ol>

```
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=none
listattr= class="submenul" class="dpl light-background"
itemattr= class="submenuli" style="font-style: italic;"

```
<dpl>
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=unordered
listattr= class="submenul" class="dpl light-background"
itemattr= class="submenuli" style= "font-style: italic;"
</dpl>

```
```
<ol>
  <li> Cat1 (link)
    <ul class="submenul" class="dpl light-background">
      <li class="submenuli" style="font-style: italic;"> Page1_1 </li>
      <li class="submenuli" style="font-style: italic;"> Page1_2 </li>
    </ul>
  </li>
  <li> Cat2 (link)
    <ul class="submenul" class="dpl light-background">
      <li class="submenuli" style="font-style: italic;"> Page2_1 </li>
      <li class="submenuli" style="font-style: italic;"> Page2_2 </li>
    </ul>
  </li>
</ol>

```
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=unordered
listattr= class="submenul" class="dpl light-background"
itemattr= class="submenuli" style="font-style: italic;"
</dpl>

### itemattr

Template:DPL parameter

Syntax:

Template:DPL syntax

### hlistattr

Template:DPL parameter

Syntax:

Template:DPL syntax

Example:

```
<dpl>
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,pagetouched
headingmode=definition
mode=ordered
hlistattr= class="topmenul" id="dmenu" style= "font-size:17px;"
</dpl>

```
```
<div class="topmenul" id="dmenu" style="font-size:17px;">
  <li> Category 2 (link) </li>
  <ol>
      <li>Page1_1</li>
      <li>Page1_2</li>
  </ol>
  <li> Category 2 (link) </li>
  <ol>
      <li>Page2_1</li>
  </ol>
</div>

```
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,pagetouched
headingmode=definition
mode=ordered
hlistattr= class="topmenul" id="dmenu" style="font-size:17px;"
</dpl>

These examples compare Template:Dpl3, Template:Dpl3, and Template:Dpl3

```
<dpl>
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=unordered
listattr= class="submenul" class="dpl light-background"
itemattr= class="submenuli" style= "font-style: italic;"
</dpl>

```
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=unordered
listattr= class="submenul" class="dpl light-background"
itemattr= class="submenuli" style="font-style: italic;"

```
<dpl>
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=unordered
listattr= class="submenul"
itemattr= class="submenuli" class="dpl light-background" style= "font-style: italic;"
</dpl>

```
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=unordered
listattr= class="submenul"
itemattr= class="submenuli" class="dpl light-background" style="font-style: italic;"

```
<dpl>
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=unordered
hlistattr= class="topmenul" id="dmenu" class="dpl light-background"
listattr= class="submenul"
itemattr= class="submenuli" style="font-style: italic;"
</dpl>

```
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=definition
mode=unordered
hlistattr= class="topmenul" id="dmenu" class="dpl light-background"
listattr= class="submenul"
itemattr= class="submenuli" style="font-style: italic;"
</dpl>

See also Template:Dpl3.

### hitemattr

Template:DPL parameter

Syntax:

Template:DPL syntax

Example:

```
<dpl>
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=unordered
mode=ordered
hlistattr= class="topmenul" id="dmenu"
hitemattr= class="topmenuli" class="dpl light-background"
</dpl>

```
```
<ul class="topmenul" id="dmenu">
  <li class="topmenuli" class="dpl light-background"> Category 1 (link)
    <ol>
      <li>Page1_1</li>
      <li>Page1_2</li>
    </ol>
  </li>
  <li class="topmenuli" class="dpl light-background"> Category 2 (link)
    <ol>
      <li>Page2_1</li>
    </ol>
  </li>
</ul>

```
	1. Page1\_1
	2. Page1\_2
* Category 2 (link)
	1. Page2\_1
category=Community
nottitlematch=%Forums%|Admin%
ordermethod=category,title
headingmode=unordered
mode=ordered
hlistattr= class="topmenul" id="dmenu"
hitemattr= class="topmenuli" class="dpl light-background"
</dpl>

### userdateformat

Template:DPL parameter

Syntax:

Template:DPL syntax

The *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 [1]. The *userdateformat* applies to all date/time fields, see the parameters: Template:Dpl3,Template:Dpl3,Template:Dpl3.

Example:

userdateformat=Y-m-d (D)

Default:

By default DPL 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 DPL will translate it according to

1. the timezone preference (difference to UTC/GMT) given by the user in his user settings.
2. if no preference is given and for all anonymous users the local time on the server will be used.

So you will either see a time based on your local time (browser based) or based on the timezone in which the wiki server is running.

The same kind of translation applies to dates you specify when selecting articles by revsion date/time.

## Control the way article names are displayed

### shownamespace

Template:DPL parameter

Syntax:

Template:DPL syntax

Example:

```
<dpl>
  category      = Help
  namespace     = Help_talk
  shownamespace = false
</dpl>

```

This list will output all Talk pages in Category:Help, listed without the 'Help talk:' prepended to page names.

The namespace 'Talk' refers to talk pages within the main namespace; all other talk namespaces, such as 'Help' or 'Guide' talk pages, would need the format '*namespace*\_talk'.

Only talk pages that have been added to the category (by placing [[Category:Help]] on the talk page) will be listed.

<dpl>

```
 category      = Help
 namespace     = Help_talk
 shownamespace = false

```

</dpl>

Note that in Template:Dpl3 there is a different way to decide whether you want to output the title with or without namespace. In Template:Dpl3 two built-in variables are provided which contain the page name including the namespace (Template:Tt) and the base title name (Template:Tt).

### escapelinks

Template:DPL parameter

Syntax:

Template:DPL syntax

Note: You can use this parameter to show images; another way to do this is to use the gallery extension in combination with DPL; there is an Template:Dpl3 for this on the dpldemo website.

### titlemaxlength

Template:DPL parameter

Syntax:

Template:DPL syntax

### replaceintitle

Template:DPL parameter

Syntax:

Template:DPL syntax

The *search for* argument must be an expression which can be used in a php preg\_replace() function call.

Example:

to remove the string "demo" in article names, you must write

`replaceintitle=/demo/,`
Note that standard regexp rules apply. The regexp must start with a non-alphanumeric character -- but not with a backslash!
It is good habit to use a '/' if this character is not needed within the regexp itself. Read the php manual to understand the details of regular expressions.

## Arranging article lists in columns and rows

### columns

Template:DPL parameter

Syntax:

Template:DPL syntax

**Example:**

```
<dpl>
  category	  = Help
  nottitlematch	  = %DPL%
  includesubpages = false
  columns	  = 3
  rowcolformat	  = width=100%
  count		  = 6
</dpl>

```

Simply displays non-DPL articles and subcategories in Category:Help in 3 columns (Template:Dpl3 is used to make the table width 100%).
<dpl>

```
 category		  = Help
 nottitlematch	  = %DPL%
 includesubpages = false
 columns		  = 3
 rowcolformat	  = width=100%
 count			  = 6

```

</dpl>
Note: Template:Dpl3 is currently bugged (possible combatibility issue between Mediawiki 1.31.2 and DPL3 v3.3.3) .

For a 3-column dpl, css can be used to achieve the desired results:

```
<div style="-webkit-column-count:3;column-count:3;">
<dpl>
  category	  = Help
  nottitlematch	  = %DPL%
  includesubpages = false
  columns	  = 3
  rowcolformat	  = width=100%
  count		  = 6
</dpl></div>
```

<dpl>

```
 category		  = Help
 nottitlematch	  = %DPL%
 includesubpages = false
 columns		  = 3
 rowcolformat	  = width=100%
 count			  = 6

```

</dpl>
**More complex example:**

In Template:Dpl3 the outer tags from Template:Dpl3 will be repeated for each column.

```
<div style="-webkit-column-count:3;column-count:3;">
<dpl>
  category	  = Help
  nottitlematch	  = %DPL%
  includesubpages = false
  addpagesize	  = true
  ordermethod	  = size
  columns	  = 2
  count		  = 6
</dpl></div>

```

This output contains a list of the largest non-DPL articles in Category:Help. Each column consists of a table which has itself three columns: rank, article name and size.

<dpl>

```
 category		  = Help
 nottitlematch	  = %DPL%
 includesubpages = false
 addpagesize	  = true
 ordermethod	  = size
 columns		  = 2
 count			  = 6

```

</dpl>
### rows

Template:DPL parameter

Syntax:

Template:DPL syntax

In Template:Dpl3, the outer tags from Template:Dpl3 will be repeated for each column. Thus you can create long lists where the table heading is repeated from time to time.

Example:

```
<dpl>
  category	  = Help
  nottitlematch	  = %DPL%
  includesubpages = false
  addpagesize	  = true
  ordermethod	  = size
  rows		  = 2
  count		  = 6
</dpl>

```

The output will contain a list of the largest non-DPL articles in Category:Help, 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.

<dpl>

```
 category		  = Help
 nottitlematch	  = %DPL%
 includesubpages = false
 addpagesize	  = true
 ordermethod	  = size
 rows			  = 2
 count			  = 6

```

</dpl>

### rowsize

Template:DPL parameter

Syntax:

Template:DPL syntax

In Template:Dpl3 the outer tags from Template:Dpl3 will be repeated after each group of Template:Dpl3 output lines.
Thus you can create long lists where the table heading is repeated in regular intervals.

Example:

```
<dpl>
  category	  = Help
  nottitlematch	  = %DPL%
  includesubpages = false
  addpagesize	  = true
  ordermethod	  = size
  rowsize	  = 3
  count		  = 6
</dpl>

```

The output will contain a list of all non-DPL articles in Category:Help. After each group of 3 entries (article names) the table heading will be repeated. It may be useful to set the width of the column with the article names explicitly, so that the tables in each row have equal width.
<dpl>

```
 category		  = Help
 nottitlematch	  = %DPL%
 includesubpages = false
 addpagesize	  = true
 ordermethod	  = size
 rowsize		  = 3
 count			  = 6

```

</dpl>

### rowcolformat

Template:DPL parameter

Syntax:

Template:DPL syntax

Example:

```
<dpl>
  category	  = Help
  nottitlematch	  = %DPL%
  includesubpages = false
  columns	  = 3
  rowcolformat	  = cellspacing=20
  count		  = 6
</dpl>

```

There will be more space around the columns than normal. See Template:Dpl3 above for another example.
<dpl>

```
 category		  = Help
 nottitlematch	  = %DPL%
 includesubpages = false
 columns		  = 3
 rowcolformat	  = cellspacing=20
 count			  = 6

```

</dpl>

The ideal way to use Template:Dpl3 is to assign a CSS class to your DPL table which has been defined in your *mediawiki:Common.css* article.

Example:

```
<dpl>
  category	  = Help
  nottitlematch	  = %DPL%
  includesubpages = false
  columns	  = 3
  rowcolformat	  = class=dpl3columns
  count		  = 6
</dpl>

```

In your *Common.css* article you might have written something like

```
table.dpl3columns td {
  background: #f2f2f2;
  padding: 0.5em;
  border: 3px;
  width: 33%;
}

```

## References

1. ↑ 1.0 1.1 1.2 This feature was completely removed in MediaWiki 1.25, following a request for comment. See Template:Dpl3.
2. ↑ The columns attribute does not work https://gitlab.com/hydrawiki/extensions/DynamicPageList/issues/81