Editing DPL3/Parameters: Controlling output format (section)

== Generating tabular output ==

===table===

{{DPL parameter
 |name   = table
 |purpose= a simple syntax to create standard tabular output; see also {{dpl3|tablerow}}
}}

Syntax:

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

The {{dpl3|table}} statement is a shortcut which implicitly sets certain values for other DPL parameters, namely {{dpl3|mode}}, {{dpl3|listseparators}} / {{dpl3|format}}, {{dpl3|secseparators}}, and {{dpl3|multisecseparators}}.

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 {{dpl3|tablerow}}.

If you use {{dpl3|table}} 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 {{dpl3|format}} in combination with {{dpl3|table}}. Therefore this parameter is NOT overwritten by the {{dpl3|table}} command. The third argument can be used to output meta data like {{tt|%COUNT%}}, {{tt|%USER%}} 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 {{dpl3|format}} statement.

The use of {{dpl3|table}} requires an {{dpl3|include}} statement which should, for reasons of readability, directly precede the {{dpl3|table}} statement). Each argument of the {{dpl3|include}} statement will produce one or more columns in the output table described in the {{dpl3|table}} statement.

'''{{dpl3|table}} 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 {{tt|<nowiki>class=wikitable</nowiki>}} or {{tt|<nowiki>class=mytable</nowiki>}} if ''mytable'' is defined in the [[Mediawiki:Common.css]] document.
** {{tt|<nowiki>class=wikitable</nowiki>}} is the '''default value'''.  Use double-quotes to specify multiple classes, e.g., {{tt|<nowiki>class="wikitable sortable"</nowiki>}}.

* 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.
** {{tt|Article}} is the '''default value'''.
** if you use a single {{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 {{tt|<nowiki>[[{{{%PAGE%}}}|{{{%TITLE%}}}]]</nowiki>}} within a phantom template.

* All subsequent parameters are column headings which correspond to the arguments of the {{dpl3|include}} parameter. Note that if you call a ''phantom template'' (like {{tt|{Some Template}.dpl}}) in the include statement, you will have to provide as many headlines as the ''phantom template'' produces columns. 

* {{dpl3|mode}} will be set to ''userformat''

* {{dpl3|listseparators}} will be configured to produce wiki syntax which defines a table

* {{dpl3|secseparators}} 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.

* {{dpl3|multisecseparators}} will be configured to produce wiki syntax which creates another table row for multiple occurrences of the ''first'' {{dpl3|include}} 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 {{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 {{tt|{{!}}}} in a separate line. Example:

<pre><nowiki>
   some output for the first column: {{{1|}}}
   |
   some output for the next column: {{{2|}}}
   |
   some output for the next column: {{{3|}}}
</nowiki></pre>

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

A typical DPL statement using the {{dpl3|table}} 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 {{dpl3|include}} and {{dpl3|table}}. 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 {{dpl3|include}}. Note that there are TWO headlines which correspond to the last argument of the {{dpl3|include}} 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 {{dpl3|Test table|examples}}

===tablerow===

{{DPL parameter
 |name   = tablerow
 |purpose= a simple syntax to create customized tabular output; see also {{dpl3|table}}
}}

Syntax:

{{DPL syntax|tablerow=''coldef'', ..}}

Where ''coldef'' contains wiki code which uses the symbol '%%' to refer to the corresponding element of an {{dpl3|include}} statement.

The {{dpl3|table}} statement (which '''must''' be used as a prerequisite for {{dpl3|tablerow}}) 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 {{code|\n}} or {{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 {{dpl3|tablerow}} statement as there are columns in your table. Skipping a column would suppress output for that column completely.

The {{dpl3|tablerow}} command is best explained by an example:
<pre><nowiki>
<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>
</nowiki></pre>
<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 {{dpl3|addpagecounter}} and {{tt|%COUNT%}}, both of which were removed in MediaWiki 1.25.
<pre><nowiki>
<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
  tablerow    =style="text-align:right;"|%%,style="text-align:right;"|%%,style="background-color:lightyellow;"|<small>%%</small>,\n|style="text-align:right;"|%%
</dpl>
</nowiki></pre>
* 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, <nowiki>{{Infobox Country or territory}}</nowiki>
* We include a short text passage from the text before the first chapter
* We use the third parameter of {{dpl3|format}} 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===

{{DPL parameter
 |name   = tablesortcol
 |purpose= define a column to be used as sort key (see also {{dpl3|table}} )
}}

Syntax:

{{DPL 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'';
* ''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 {{dpl3|tablesortcol}}. 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 {{dpl3|tablesortcol}} 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 {{dpl3|ordermethod}}. The default is "alphabetically by title". So, without {{dpl3|tablesortcol}} you get the tablerows in alphabetical sequence of the article names where they come from. With {{dpl3|tablesortcol}} you can order them by the column contents itself.