Jump to content

Controlling output format

From DynamicPageList3 Manual
v·t·e
DPL3 Manual (Main Page)
General Use & Syntax, Parameter Quick Reference, Examples
Primary DPL Documentation
Other DPL Modules
dplchapter  •  dplvar  •  dplreplace  •  dplnum  •  dplmatrix
Handy characters

²{ (Alt+0 1 7 8 • {) • }² (} • Alt+0 1 7 8) • « (Alt+0 1 7 1) • » (Alt+0 1 8 7) • <&> • ¦ (Alt+0 1 6 6) •  Alt+0 1 8 2

Manual Parameters Controlling output format


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 (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 titlematch, nottitlematch, count, and includesubpages=false.


General approach to output formatting

[edit source]

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 userformat which puts complete control into your hands.
    • You will understand their meaning directly from reading.


Setting the basic output mode

[edit source]
mode Provide basic control over the output of DPL3.

Syntax:

mode=modename where modename can be one of:

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


For advanced use of DPL3, it is important to understand mode=userformat. Note that this mode is automatically implied when listseparators or format are used.


mode 'ordered', 'unordered', 'none'

[edit source]


Example:

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 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 ordered list (numbered), an unordered list (bulleted), or the none list style (no list item markers).

Test in sandbox

View Result


In an <ol>...</ol> list: In a <ul>...</ul> list: In a <br/> list:
Code
{{#dpl:
|category      = Fruit examples
|titlematch    = %a%
|nottitlematch = %pl%¦%go%
|mode          = ordered
|count           = 3
}}
Code
{{#dpl:
|category      = Fruit examples
|titlematch    = %a%
|nottitlematch = %pl%¦%go%
|mode          = unordered
|count           = 3
}}
Code
{{#dpl:
|category      = Fruit examples
|titlematch    = %a%
|nottitlematch = %pl%¦%go%
|mode          = none
|count           = 3
}}
  1. Grape
  2. Orange
  3. Banana

mode 'category'

[edit source]


Example:

This lists pages that titlematch the letters "Appl" anywhere in the name, with includesubpages set to false to exclude subpages. mode set to category outputs pages in category style (with capitals as headers, sorted by name regardless of category). The ordermethod parameter is required when mode=category is set (so DPL3 knows how to order the category listing style), and the titlewithoutnamespace value makes the first letter of the page title the category heading. Note that using title instead would cause use of the first letter of the namespace if it exists, and just the title if it doesn't (such as for pages in the Main namespace).

Code
{{#dpl:
|titlematch      = %Appl%
|includesubpages = false
|mode            = category
|ordermethod     = titlewithoutnamespace
|count           = 3
}}

Test in sandbox

View Result


Note: You must use ordermethod =  with one of: title / titlewithoutnamespace / category,title / user,title with this option.


mode 'inline'

[edit source]
inlinetext To define the inline text used in mode=inline.


Syntax:
inlinetext=wikitext, where wikitext is the text to be set.


The default formatting is &nbsp;-&nbsp; which results in  -  except when mode=userformat where inlinetext is empty by default.


Notes:

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


Example:

This lists pages in category Fruit examples as the format mode inline (in paragraph) text. The inlinetext parameter defines the inline text used &nbsp; • &nbsp; to create formatting like "Item1 • Item2 • Item3". Results are restricted to a count of 5.

Code
{{#dpl:
|category   = Fruit examples
|mode       = inline
|inlinetext = &nbsp; • &nbsp;
|count      = 5
}}
Result
Apple  •  Grape  •  Orange  •  Plum  •  Banana

Test in sandbox

View Result

mode 'gallery'

[edit source]
gallerymode To define the mode for the gallery tag, such as traditional, nolines, or packed.
imageheight To define the heights attribute for the gallery tag.
imagewidth To define the widths attribute for the gallery tag.

mode 'userformat'

[edit source]


Note: As the below information is difficult to understand, there are additional DPL3 commands (table, tablerow) which make it fairly quick/easy to create tabular output. If tabular output is needed, skip to the table section.


While the standard output formats are meant for fast generation of simple page lists, the 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 (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 A and B which use templates x and y with varying arguments; while x is being used once within each document, y 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:

The arguments of the above statements can contain references to %VARIABLES%. So, sec-1-start might contain a reference like %PAGE% to output the page name. See format for more details on variable substitution.


Now think of the following page inclusion statement: 

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


The output then looks 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 (liststart, itemstart, etc.) contain wiki syntax for table definitions and multi-sep defines a horizontal line, the output might look like this: 

  +------+---------------------+
  |      |          | y.dpl(3) |
  |  A   | x.dpl(a) |  ----    |
  |      |          | y.dpl(5) |
  +------+----------+----------+
  |      |          | y.dpl(4) |
  |      |          |  ----    |
  |  B   | x.dpl(b) | y.dpl(1) |
  |      |          |  ----    |
  |      |          | y.dpl(2) |
  +------+----------+----------+

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

  +------+---------------------+       +------+---------------------+
  |  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) |
  +------+---------------------+       +------+---------------------+


A special parameter called dominantsection is used to mark one section of the includepage statement as "dominant" (in our example: "dominantsection=2" as {y}.dpl is the second argument of the includepage 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

[edit source]
format Customize the output format completely. Implicitly sets "mode=userformat". Uses variable references like %PAGE% to describe the output format. See also the secseparators parameter. Note: format is incompatible with tablerow.


Syntax:

format=Startall,Start,End,Endall where Startall, Start, End and Endall are wiki tags used to separate the list items:
  • Startall before all — e.g., may specify wikitext to begin a table (including headers).
  • Start before each — e.g., may specify wikitext to begin row, its cell and cell content.
  • End after each — e.g., may specify content to end a cell or row.
  • Endall after all — e.g., may specify content to end a table.
Note: |debug = 5 can be added to view any resultant wikitext given, and should always be put at the top of the statement, a value of 0 disables it.


Notes:

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


Example:
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 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 format with the following statements (last example and result).

This selects pages whose titlematch has "ntries" anywhere in it, it excludes pages that have "f" in the title, and it also excludes subpages. The format statement's Startall (before all), End (after each), and Endall (after all) arguments are empty, only the 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.

Test in sandbox

View Result

default formatted
Code
<dpl>
  titlematch	  = %ntries%
  nottitlematch	  = %f%
  includesubpages = false
</dpl>
Code
<dpl>
  titlematch	  = %ntries%
  nottitlematch	  = %f%
  includesubpages = false
  format	  = ,\n* [[%PAGE%|%TITLE%]],,
</dpl>


Example:

The following is an example of how to use the variable %NR% to set font size. This lists articles in category Fruit examples, with ordermethod set to title and order descending. The format parameter wraps the page name in a span element, using an Extension:ParserFunctions expression #expr to multiply the font size of the current page name (starting from 1) by 0.5em for each subsequent result. The results count is limited to 3.

This example requires the ParserFunctions extension to be enabled; on Miraheze, ParserFunctions is already installed and if not enabled can be enabled in ManageWiki.


Code
{{#dpl:
|category    = Fruit examples
|ordermethod = title
|order       = descending
|format      = ,\n<span style="font-size: ²{#expr:%NR% * 0.5}²em;">'''[[%PAGE%]]'''</span>,\n,
|count       = 3
}}
Result


Plum

Pear

Orange

Test in sandbox

View Result


Notes:

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


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


Example:

Using debug suppresses debug output (and should always go at the top). This lists pages in category Number examples that linksto the article named Two. The results are limited to a count of 5, and the format syntax is used to create a table.
format=Startall,Start,End,Endall where Startall, Start, End and Endall are wiki tags used to separate the list items:
  • Startall before all — e.g., may specify wikitext to begin a table (including headers).
  • Start before each — e.g., may specify wikitext to begin row, its cell and cell content.
  • End after each — e.g., may specify content to end a cell or row.
  • Endall after all — e.g., may specify content to end a table.
Note: |debug = 5 can be added to view any resultant wikitext given, and should always be put at the top of the statement, a value of 0 disables it.


Code
{{#dpl:
|debug    = 0
|category = Number examples
|linksto  = Two
|count    = 5
|format   = {¦ class="wikitable" ¶!Pages found,¶¦-¶¦[[%PAGE%]],,¶¦}
}}
Result
Pages found
One
Five

Test in sandbox

View Result


Notes:

  • The Start position of the format= 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 namespace, such as in the "Category" namespace, if "Category:" is not desired in the page title/link, [[%PAGE%|%TITLE%]] can be used instead.
  • The table parameter, with tablerow and the include/includepage parameter, can also be used to output table syntax.


Image galleries can also be produced using the format syntax.


Example:

This lists pages in the namespace File, and applies the format of manually specified gallery code, using the Startall (before all) and Endall (after all) arguments of gallery syntax for the open and close tags. The Start and End arguments are applied to each result in between, in this case the file page names generated by the dpl3 statement, and puts each on a new line to complete the gallery statement. Results are limited to a count of 3.

Note: When DPL3 parser function syntax is used to create a gallery, the < and > characters must be replaced by « and » respectively (to escape them).

Code
{{#dpl:
|namespace = File
|format    = «gallery mode="packed" widths="80px" heights="80px"»,%PAGE%\n,,«/gallery»
|count     = 3
}}
Result

Test in sandbox

View Result




Variables
[edit source]

As we want to be able to control output completely, we reference article names and other possible output by special %VARIABLES%:

Variable Description
%PAGE% Outputs the name of the article (including namespace), corresponds to the Magic Word {{FULLPAGENAME}}.
%TITLE% Outputs the title of the article (without the namespace), corresponds to the Magic Word {{PAGENAME}}.
%NAMESPACE% Outputs the namespace of the article.
%PAGEID% Outputs the internal unique numeric ID of the article page.
%NR% Outputs the current article sequence number (starting from 1).
%IMAGE% Outputs the physical path to an image (based on hash values, e.g., 5/5d/myImage.jpg).
%PAGESEL% Outputs the name of an article which was used within the selection criteria (only applies to linksfrom and linksto).
%IMAGESEL% Outputs the name of an image which was used within the selection criteria (only applies to imageused).
%SIZE% Outputs the article size (requires addpagesize=true).
%SIZEFS% Outputs a font size number which is based on the article size (logarithm of square root of counter).
%DATE% Outputs the date selected, e.g., ordermethod=lastedit; requires addeditdate=true or similar; the formatting of the date can be influenced using userdateformat=.
%EXTERNALLINK% Outputs the external hyperlink found as a consequence of the linkstoexternal statement.
Relating to categories
%CATLIST% Outputs a pipe-separated list of links to all categories to which the article belongs (requires addcategories=true).
%CATBULLETS% Outputs a bullet point list of links to all categories to which the article belongs (requires addcategories=true).
%CATNAMES% Outputs a comma-separated list of all categories to which the article belongs (requires addcategories=true).
Relating to Revisions and Contributors
%REVISION% Outputs the name of the article revision; only accessible if the DPL query selects articles based on revision dates.
%USER% Outputs the user who changed the article last; requires adduser=true or addlasteditor=true.
%CONTRIBUTOR% Outputs the user who made a contribution; requires addcontribution=true.
%CONTRIBUTION% Outputs the number of bytes changed; requires addcontribution=true.
%CONTRIB% Outputs asterisk * bar to indicate the amount of change; requires addcontribution=true.

Note: The above variables are replaced by the corresponding values if they occur within Start or End or within the corresponding tags of the secseparators= parameter.

Variable Description
Symbolic variables for use in resultsheader and/or resultsfooter
%PAGES% Outputs the number of articles in the result set. If the query result is limited (by system settings or by the count parameter) %PAGES% only shows the upper limit.
%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.
%VERSION% Displays the current DPL3 version (see also Special:Version).
%DPLTIME% Outputs the amount of time that the DPL3 call itself took (in seconds + milliseconds).
  • This useful to find out if or which DPL3 call, on a page, is taking a long time (if long loading times are noticed).
  • 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.
Variables for scrolling

%FIRSTNAMESPACE%
%FIRSTTITLE%
%LASTNAMESPACE%
%LASTTITLE%

Variables used for page scrolling, that produce the output described in their names. These variables
correspond to %NAMESPACE% and %TITLE% of the first / last article in the result set, respectively.
%SCROLLDIR% Outputs the value set by the URL parameter DPL_scrollDir (up or down);
it is passed to the scroll helper template, which uses it to produce its links for scrolling.
Removed parameters
%COUNT% The usage counter (requires addpagecounter=true). The built-in feature for this was removed in MediaWiki 1.25.[1]
Note: Requires the HitCounters extension.
%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 removed in MediaWiki 1.25.[1]
Note: Requires the HitCounters extension.
%COUNTFS2% Similar to %COUNTFS%, but based on the logarithm of the square root of the usage counter. The built-in feature for this was removed in MediaWiki 1.25.[1]
Note: Requires the HitCounters extension.


listseparators

[edit source]
listseparators An alias for format, see the format parameter. Implicitly sets mode=userformat.


secseparators

[edit source]
secseparators Customize the output format of included sections. Can be used with standard output modes and with mode=userformat.

Syntax:

secseparators=Start1,End1,Start2,End2,..,..

or

secseparators=Start


In the first syntax variant, specify pairs of tags which correspond to the includepage statement. StartN and EndN are HTML strings or wiki tags which are put around each transcluded section (see includepage=name1,name2,...).

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

Symbolic replacements of %PAGE% etc. take place as described in listseparators. In addition, the variable %SECTION% 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 secseparators tags are only put once around the whole block (but see dominantsection).


Example:

Using debug=0 supresses debug output. This lists pages in category Fruit examples using listseparators (an alias for format) to define a table start and headers with three columns, and to put a link to the page in the first column of each row. The includepage parameter specifies the template used on each page to pull the remaining data from, and their parameter names.
format=Startall,Start,End,Endall where Startall, Start, End and Endall are wiki tags used to separate the list items:
  • Startall before all — e.g., may specify wikitext to begin a table (including headers).
  • Start before each — e.g., may specify wikitext to begin row, its cell and cell content.
  • End after each — e.g., may specify content to end a cell or row.
  • Endall after all — e.g., may specify content to end a table.
Note: |debug = 5 can be added to view any resultant wikitext given, and should always be put at the top of the statement, a value of 0 disables it.


The secseparators statement adds columns and cell formatting for each result. There are two pairs for each transcluded section; the first element of each pair is a linefeed and a pipe/split-pipe (which define a new column in the table) and the second element of each pair is empty. Look carefully at the symbols (\n can be used as an alternative), which always appear before a wiki syntax element and must be placed at the beginning of a new line ensuring the wiki parser understands them. The result is limited to a count of 3.

Note: If an article does not contain a value for the parameter named "grows", it results in an empty cell in the table.

Code
{{#dpl:
|debug          = 0
|category       = Fruit examples
|listseparators = {¦class="wikitable" ¶!Fruit ¶!Image Filename ¶!Grows on,¶¦-¶¦[[%PAGE%|%TITLE%]],,¶¦}
|includepage    = {Fruit-Infobox}:image:grows
|secseparators  = ¶¦,,¶¦,,
|count          = 3
}}
Result
Fruit Image Filename Grows on
Apple Red Apple Fruit With Black Background.jpeg On trees
Grape Grapes on White Table.jpeg On vines
Orange Orange, orange peel.jpg On trees

Test in sandbox

View Result


As mentioned above, a single element can be used in the secseparators 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:

This list pages in category Fruit examples using listseparators (alias for format) to define a table with three columns and headers. It also specifies the content for the first column as the page name. The includepage parameter specifies a template used on each page, along with the "grows" and "notes" parameter value for each row.
format=Startall,Start,End,Endall where Startall, Start, End and Endall are wiki tags used to separate the list items:
  • Startall before all — e.g., may specify wikitext to begin a table (including headers).
  • Start before each — e.g., may specify wikitext to begin row, its cell and cell content.
  • End after each — e.g., may specify content to end a cell or row.
  • Endall after all — e.g., may specify content to end a table.
Note: |debug = 5 can be added to view any resultant wikitext given, and should always be put at the top of the statement, a value of 0 disables it.


Assuming the chapter on "Notes" contains a long text, it can be truncated (e.g., shortened to 40 characters) by specifying the text for truncation after the number to truncate ([40 more...]. A link direct to those chapters is generated automatically. Be aware that truncating with [ ] can break text formatted with wikitext or tags such as <nowiki>.

Code
{{#dpl:
|category       = Fruit examples
|listseparators = {¦class="wikitable" ¶!Fruit ¶!Grows on ¶!Notes,¶¦-¶¦[[%PAGE%|%TITLE%]],,¶¦}
|includepage    = {Fruit-Infobox}:grows,#Notes[40 more...]
|secseparators  = \n¦
|count          = 5
}}
Result
Fruit Grows on Notes
Apple On trees

There are multiple varieties of more... Apples skins contain more fiber more...

Grape On vines
Orange On trees
Plum
Banana On a tree-like plant

Test in sandbox

View Result


multisecseparators

[edit source]
multisecseparators Put a tag between multiple transcluded parts which refer to (use) the same template or page section or chapter.


Syntax:

multisecseparators=sep1,sep2,...

The tags correspond to the transcluded section (see includepage=name1,name2,...).

Symbolic replacements of %PAGE% etc. take place as described in listseparators. In addition, the variable %SECTION% 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 sepN as a separator.


Example:

This lists pages in category Primary Module (manual pages) that don't have "volume" or "page selection" in the title (nottitlematch), and each uses Template:DPL parameter. The include statement includes content from two templates from the pages, the page name of the page using the {DPL manual} template, and the {dpl parameter} parameter template's "name" and "purpose" parameter values, with the latter truncated to 50 characters.
format=Startall,Start,End,Endall where Startall, Start, End and Endall are wiki tags used to separate the list items:
  • Startall before all — e.g., may specify wikitext to begin a table (including headers).
  • Start before each — e.g., may specify wikitext to begin row, its cell and cell content.
  • End after each — e.g., may specify content to end a cell or row.
  • Endall after all — e.g., may specify content to end a table.
Note: |debug = 5 can be added to view any resultant wikitext given, and should always be put at the top of the statement, a value of 0 disables it.


Since the "DPL parameter" template is used multiple times on the same article, it lists the first and then each subsequent template use with its corresponding values. The listseparators parameter (an alias for format) sets the table wikitext along with an extra row between separate articles colored dark (navy), secseparators adds more columns for each section found and colors the first instance of template use orange, and since multisecseparators puts a tag between multiple transcluded parts which refer to (use) the same template or chapter, it colors the rest of of the "dpl parameter" template values, after the first, light blue.

Code
{{#dpl:
|category           = Primary Module
|nottitlematch      = %volume%¦%page selection%
|uses               = Template:DPL Parameter
|include            = {DPL manual}:[[%PAGE%]],{dpl parameter}:name:purpose[50]
|mode               = userformat
|listseparators     = ¶{¦class="wikitable sortable" ¶!colspan=3¦Fields cannot be formatted within the include¶¦-¶!Page ¶!Name ¶!Purpose,¶¦-,¶¦-¶¦class="dpl-dark-background" colspan=3¦¶¦-,¶¦}
|secseparators      = ¶¦,,¶¦class="dpl-orange-background"¦
|multisecseparators = ,¶¦-¶¦¶¦class="dpl-blue-background"¦
}}
Result


Fields cannot be formatted within the include
Page Name Purpose
Other parameters debug Sets debugging level.
allowcachedresults Cache query results to improve performance, keep
cacheperiod Defines the expiration period for the DPL3 cache.
goal Set the goal for DPL3 to either show pages
eliminate Suppress references to pages, templates, images,
reset Suppress references to pages, templates, images,
fixcategory Assign the article containing a DPL3 statement to
execandexit Process the command given as an argument and then
updaterules Define a set of rules which are executed to
deleterules Allow the mass deletion of wiki pages
Controlling output order ordermethod Sets the criteria used to order the list by;
order Controls the sort direction of the list;
ordercollation Defines the collating sequence for ordering.
tablesortmethod Improves DPL's sorting behavior for table columns

Test in sandbox

View Result


Values cannot be formatted within include, as formatting can only occur in formatting statements (this can be done in listseparators or secseparators, and multisecseparators). Variables can be omitted from the include, and instead be placed in these formatting statements, for further formatting.

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


Example:

This example is the same as the prior one, only it adds new line formatting and an asterisk resulting in a bullet inserted before each page link.

Code
{{#dpl:
|category           = Primary Module
|nottitlematch      = %volume%¦%page selection%
|uses               = Template:DPL Parameter
|include            = {DPL manual}:[[%PAGE%]],{dpl parameter}:name:purpose[50]
|mode               = userformat
|listseparators     = ¶{¦class="wikitable sortable" ¶!colspan=3¦Fields cannot be formatted within the include¶¦-¶!Page ¶!Name ¶!Purpose,¶¦-,¶¦-¶¦class="dpl-dark-background" colspan=3¦¶¦-,¶¦}
|secseparators      = ¶¦¶* ,,¶¦class="dpl-orange-background"¦,
|multisecseparators = ,¶¦-¶¦¶¦class="dpl-blue-background"¦
}}
Result


Fields cannot be formatted within the include
Page Name Purpose
debug Sets debugging level.
allowcachedresults Cache query results to improve performance, keep
cacheperiod Defines the expiration period for the DPL3 cache.
goal Set the goal for DPL3 to either show pages
eliminate Suppress references to pages, templates, images,
reset Suppress references to pages, templates, images,
fixcategory Assign the article containing a DPL3 statement to
execandexit Process the command given as an argument and then
updaterules Define a set of rules which are executed to
deleterules Allow the mass deletion of wiki pages
ordermethod Sets the criteria used to order the list by;
order Controls the sort direction of the list;
ordercollation Defines the collating sequence for ordering.
tablesortmethod Improves DPL's sorting behavior for table columns

Test in sandbox

View Result


Example:

This lists pages in category Primary Module whose page title does nottitlematch "volume" OR "page selection". A selected page also uses Template:DPL Parameter and the results include an empty parameter from the {{DPL manual}} template (as none exist, creates the first column with page name automatically unless suppressed), and all contents and parameters of the {{DPL parameter}} surrogate (also known as phantom) template to format the second and third column of results. The mode is set to userformat, with listseparators specifying the table's opening wikitext and headers, and closing table code. secseparators specifies formatting for the first parameter name in the table, then uses the surrogate formatting template for additional rows in the same column. The multisecseparators parameter sets a dark blue background between multiple transcluded parts.

This example is advanced, for more simple examples of surrogate template use see include examples as related to including contents from templates, see the table and tablerow parameters for straightforward table examples.

Code
{{#dpl:
|category           = Primary Module
|nottitlematch	    = %volume%¦%page selection%
|uses               = Template:DPL Parameter
|include            = {DPL manual}:,{DPL parameter}.surrogateexample
|mode               = userformat
|listseparators     = ¶{¦class="wikitable sortable" ¶!colspan=3¦Includes a surrogate (phantom) template¶¦-¶!Page ¶!Name ¶!Purpose,¶¦-¶¦[[%PAGE%]]¶,¶¦-¶¦class="dpl-dark-background" colspan=3¦,¶¦}
|secseparators      = ,¶¦class="dpl-orange-background"¦,
|multisecseparators = ,¶¦-¶¦¶¦class="dpl-blue-background"¦
}}
Result


Includes a surrogate (phantom) template
Page Name Purpose
Other parameters debug Sets debugging level.
allowcachedresults Cache query results to improve performance, keep s more ...
cacheperiod Defines the expiration period for the DPL3 cache.
goal Set the goal for DPL3 to either show pages ( more ...
eliminate Suppress references to pages, templates, images, c more ...
reset Suppress references to pages, templates, images, c more ...
fixcategory Assign the article containing a DPL3 statement to more ...
execandexit Process the command given as an argument and then more ...
updaterules Define a set of rules which are executed to perfor more ...
deleterules Allow the mass deletion of wiki pages
Controlling output order ordermethod Sets the criteria used to order the list by; often more ...
order Controls the sort direction of the list; requir more ...
ordercollation Defines the collating sequence for ordering. Allow more ...
tablesortmethod Improves DPL's sorting behavior for table columns more ...

Test in sandbox

View Result


Formatting handled by a surrogate (also known as phantom) template (e.g., Template:DPL parameter.surrogateexample) applies to both secseparators and multisecseparators.


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 table and tablerow parameters for more information.


dominantsection

[edit source]
dominantsection 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:

dominantsection=number between 1 and the number of arguments in the includepage= 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 top of this document to understand the meaning of dominantsection.


Note: Using dominantsection together with table may lead to strange result formatting.

Generating tabular output

[edit source]

table

[edit source]
table A simple syntax to create standard tabular output; see also tablerow. Requires an include statement, and is a shortcut that implicitly sets values for other DPL3 parameters, namely mode, listseparators / format, secseparators, and multisecseparators.


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 tablerow.


Parameters automatically set by table are:

  • mode=userformat.
  • listseparators is configured to produce table definition wiki syntax.
  • secseparators 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).
  • multisecseparators is configured to produce another table row wiki syntax, for multiple occurrences of the first include 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 table 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 format combined with table; therefore, this parameter is NOT overwritten by the table command. The third argument can be used to output metadata like %COUNT%, %USER% etc., as columns in an output table. To do so, the third parameter must contain wiki syntax for output columns like this:
 include = {some template}:param1,#some-section-heading
 table   =,,tplparam,#sectionheading,#hits
 format  =,,\n%COUNT%

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 table statement adds %COUNT% to add that value after that column's normal content.


Important:

  • An include statement is required to use table.
  • Each argument of the include statement produces one or more values for the output described by the table statement.
  • For reasons of readability and because the include and table statements correspond, the include statement should directly precede the table statement.


table expects a comma-separated list of arguments: 

|table = class="wikitable sortable",First column header,Second column header,...
  • The first argument assigns general properties for the table.
    • It is recommended to make a CSS reference here, using something like class="wikitable sortable", or class="mytable" if mytable is defined in the Mediawiki:Common.css document.
    • class="wikitable" is the default value if left empty.
  • The second argument is the headline for the first column.
    • A - 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 [[{{{%PAGE%}}}|{{{%TITLE%}}}]], in a tablerow 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 include parameter. If a surrogate template is called (like {Some Template}.dpl) in the include statement, as many headlines as the surrogate template produces columns needs to be provided.


Example:

This lists pages in category Fruit examples, and includes from the {{Fruit-Infobox}} template's the "grows" and "image" parameter values in the output. DPL automatically creates the first column linked to the page (unless suppressed with - in the table statement), so the parameter values appear in the second and third columns respectively. The table statement sets the table styles and headers, and the count is limited to 3.

Code
{{#dpl:
|category = Fruit examples
|include  = {Fruit-Infobox}:grows:image
|table    = class="wikitable sortable",Page,Grows,Image
|count    = 3
}}
Result
Page Grows Image
Apple On trees Red Apple Fruit With Black Background.jpeg
Grape On vines Grapes on White Table.jpeg
Orange On trees Orange, orange peel.jpg

Test in sandbox

View Result


Example:

This selects pages in category Fruit examples and include the values of the {{Fruit-Infobox}} template's "image" and "grows" parameters, with the page title as a link in between the two template parameter values. The table statement sets its styles to "wikitable" and "sortable", then most importantly uses the - character in second position to suppress the automatic linked page name first column (so it can be moved to a different column). That same statement also sets the table header text. The list output count is limited to 5 results.

Note: In this case, the [[%PAGE%|%TITLE%]] formatting is applied directly in the include statement, where most other formatting (such as turning the image name into a rendered image) cannot be.

Code
{{#dpl:
|category = Fruit examples
|include  = {Fruit-Infobox}:image:[[%PAGE%|%TITLE%]]:grows
|table    = class="wikitable sortable",-, Image used on page, Page, Value of "grows" parameter
|count    = 5
}}
Result
Image used on page Page Value of "grows" parameter
Red Apple Fruit With Black Background.jpeg Apple On trees
Grapes on White Table.jpeg Grape On vines
Orange, orange peel.jpg Orange On trees
Plum on tree.jpg Plum
Banana-Single.jpg Banana On a tree-like plant

Test in sandbox

View Result


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 table 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 | has already been put into the output stream). So, start directly with the contents of the first column. To add more columns, use a | on 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 mode, listseparators, secseparators and multisecseparators.

A typical DPL3 statement using the table parameter would contain: 

include =                            #Section X,   {T1}:param1   ,#Section Y,{T2}.dpl
table   = class="sortable", Article,      X    , Template param1 ,     Y    ,T2-a T2-b

Note that we have written the above statement in a way to show the correspondence between include and table. 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 include. Note that there are two headlines which correspond to the last argument of the 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).


Example:

This lists pages in category Fruit examples and includes the contents of the {{Fruit-Infobox.templatevalues}} surrogate formatting template. The table parameter sets the tale styles and headers, and since it does not include a - in second place to suppress the automatically linked page titles in first place, it formats only the second and third columns of results.

If - was in second position for table, the first column would drop off and the page name would need to be added to table statement or surrogate template, its value could be called or used like a normal parameter {{{%PAGE%}}} using it variable name.

Code
{{#dpl:
|category = Fruit examples
|include  = {Fruit-Infobox}.templatevalues
|table    = class="wikitable sortable",Page,Grows,Image
|count    = 2
}}
Result
Page Grows Image
Apple On trees
Grape On vines

Test in sandbox

View Result


See: the collection of Generating tabular output (examples) for more table examples, and also include for more information on surrogate template use.


tablerow

[edit source]
tablerow A simple syntax to precisely position tabular data within formatting syntax; requires a table statement. Note: tablerow is incompatible with format


Syntax:

tablerow=columnDefinition, .. where columnDefinition uses the symbol %% to precisely position content included by an include statement, within wikitext formatting code.


When it comes to simple tables using tablerow, an include statement first tells DPL3 what content to include in each column of a table, the table 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 tablerow is to precisely position the column values %% of the corresponding include, 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 style="background:grey;"¦ (followed by the value %%) or skipping such styles and just adding the value %%. All columns must be specified, meaning as many entries in the tablerow statement must exist as there are columns in the table. Skipping a column would suppress output for that column completely.


Example:

This lists pages in category Fruit examples, article titles automatically placed in the first column as a link (unless suppressed). It then include to include the {{Fruit-Infobox}} template's "grows" parameter value for each article, in the second column. The table statement's first argument sets the table styles, the rest set the remaining header text. Since the first column was automatically generated (not intentionally suppressed using - in the second table argument), the first argument of tablerow corresponds to, and formats, the second column; it sets the cell background style (green) and then uses %% to position the value after the formatting and results are limited to a count of 5.

Code
{{#dpl:
|category = Fruit examples
|include  = {Fruit-Infobox}:grows
|table    = class="wikitable sortable",Page,The first parameter<br>value of template used
|tablerow = class="dpl-green-background"¦%%
|count    = 5
}}
Result
Page The first parameter
value of template used
Apple On trees
Grape On vines
Orange On trees
Plum
Banana On a tree-like plant

Test in sandbox

View Result


Notes:

  • You can add a leading \n or 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 tablerow use (and other methods of generating tabular data).


tablesortcol

[edit source]
tablesortcol Define a column to be used as a sort key (requires the table and ordermethod parameters.)


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 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 class="sortable" or class="wikitable sortable" together with 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 column and sorts according to that (date, number, string)
  • If tablesortcol 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 ordermethod. The default is "alphabetically by title". So, without tablesortcol table rows appear in alphabetical sequence of the article names where they come from. With tablesortcol these can be ordered by the column contents itself.


Example:

This lists pages in category Fruit examples, and include includes the page name (automatic unless suppressed) and the "grows" parameter values. The result is set to display as a simple table with the ordermethod set to sort by Title and tablesortcol set to -1, which sorts the first column by reverse (descending) order. Results are limited to a count of 5.

Code
{{#dpl:
|category     = Fruit examples
|include      = {Fruit-Infobox}:grows
|table        = class="wikitable sortable",Page,Location
|ordermethod  = Title
|tablesortcol = -1
|count        = 5
}}
Result
Page Location
Plum
Orange On trees
Grape On vines
Banana On a tree-like plant
Apple On trees

Test in sandbox

View Result


Heading mode

[edit source]

headingmode

[edit source]
headingmode To control the output of the headings in a DPL3 with complex/multi-parameter ordermethod (has no effect with single-parameter ordermethods). For ordermethod=method1,method2,..., method1 is used for headings. E.g., In ordermethod=category,title a 2-parameter ordermethod, headingmode affects category headings. See also headingcount.


Syntax:

headingmode=modename where modename can be one of:

  • ordered – outputs an ordered (numbered) list – HTML tag ol
  • unordered – outputs an unordered (bulleted) list – HTML tag ul
  • definition – outputs a description list – HTML tag dl
  • none – headings are not displayed, no heading – (default, need not be set)
  • H1 – outputs (heading) sections – HTML tags H1
  • H2 – outputs heading sections – HTML tags H2
  • H3 – outputs heading sections – HTML tags H3
  • H4 – outputs heading sections – HTML tags H4
  • H4 – outputs heading sections – HTML tags H5
  • H4 – outputs heading sections – HTML tags 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 page selection parameters. The distinct parameter would have no effect on this behavior because the articles are already distinct to each category (and distinct=true is already the default, setting it would not change the result).
  • headingmode can be used with multi-column output, but the length of the columns may vary more expected.


Example:

This selects pages in category Country examples, with ordermethod set to specify sorting by category, title. Setting headingmode to ordered displays numbered category headings as output titles, with the results count restricted to 3'.

Code
{{#dpl:
|category    = Country examples
|ordermethod = category,title
|headingmode = ordered
|count       = 3
}}
Result
  1. Countries in Africa
  2. Countries in Europe

Test in sandbox

View Result


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


Example:

This selects pages in the category Country examples, with ordermethod set to order by category, title. Setting headingmode to definition, puts category titles as headings in the output, in definition mode, which creates a description list using dl HTML tags. The mode set to ordered makes the pages listed below each header numbered, and the results are limited to a count of 3 (headings aren't included in that limit).

Code
{{#dpl:
|category    = Country examples
|ordermethod = category,title
|headingmode = definition
|mode        = ordered
|count       = 3
}}
Result
Countries in Africa
  1. Madagascar
Countries in Europe
  1. England
  2. Finland

Test in sandbox

View Result


hlistattr

[edit source]
hlistattr Add attributes to the HTML heading/top level elements, which enclose all other elements in the result, depending on headingmode (HTML element would be ol for ordered, ul for unordered, dl for definition; or div for others)

Not yet applicable to headingmode=none.


Syntax:

hlistattr= attribute1="val1" attribute2="val2" ...


Example:

This lists pages in category Countries in Africa OR Countries in Europe and sets the ordermethod to category,pagetouched which adds a category header and sorts results by pagetouched. The headingmode set to definition defines list items using dl HTML tags. The mode set to ordered causes the pages listed under categories to be numbered. The hlistattr parameter adds formatting at the heading/top level, which encloses all other items; a CSS class ID and class are given, to set the color orange, and a border and padding. The result count is limited to 2.

Code
{{#dpl:
|category    = Countries in Africa¦Countries in Europe
|ordermethod = category,pagetouched
|headingmode = definition
|mode        = ordered
|hlistattr   = id="dl-example" class="dpl-orange-background"
|count       = 2
}}
Result
Countries in Africa
  1. Madagascar
Countries in Europe
  1. Finland

Test in sandbox

View Result


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

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


Note: To format subsequent elements in the same result set, see also (in the corresponding order since the examples build on one another) hitemattr, listattr, itemattr.


hitemattr

[edit source]
hitemattr Add attributes all list item headings in the result, depending on headingmode (HTML element would be li for ordered/unordered, div for others).

To be used with headingmode=unordered or ordered. (Not yet applicable for others.)


Syntax:

hitemattr= attribute1="val1" attribute2="val2" ...


Example:

This selects pages in category Countries in Africa OR Countries in Europe and sets the ordermethod to sort by category,pagetouched. The headingmode as definition puts the category as headers in the output using dl HTML tags. mode being set to ordered causes pages listed under categories to be numbered. The hlistattr line specifies CSS formatting at the heading/top level, enclosing all other items and being orange. The hitemattr parameter adds styles for pink/red formatting for all list items).

Code
{{#dpl:
|category    = Countries in Africa¦Countries in Europe
|ordermethod = category,pagetouched
|headingmode = definition
|mode        = ordered
|hlistattr   = id="dl-example" class="dpl-orange-background"
|hitemattr   = id="list-item-heading" class="list-item-heading"
|count       = 2
}}
Result
Countries in Africa
  1. Madagascar
Countries in Europe
  1. Finland

Test in sandbox

View Result


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

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


Example:

This selects pages in category Countries in Africa OR Countries in Europe, with an ordermethod of category,pagetouched. The headingmode set to unordered causes category headings to be bulleted and mode set to ordered makes the pages under them be numbered. The hlistattr parameter applies CSS to the heading content wrapping it in orange, where the hitemattr parameter sets CSS to wrap list items in red/pink. Results are limited to a count of 3.

Code
{{#dpl:
|category    = Countries in Africa¦Countries in Europe
|ordermethod = category,pagetouched
|headingmode = unordered
|mode        = ordered
|hlistattr   = id="dl-example" class="dpl-orange-background"
|hitemattr   = id="list-item-heading" class="list-item-heading"
|count       = 3
}}
Result

Test in sandbox

View Result


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

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

Note: To format subsequent elements in the same result set, see also (in the corresponding order since the examples build on one another) listattr, itemattr.

listattr

[edit source]
listattr Add attributes to HTML list type declaration elements, depending on mode (HTML element is ol for ordered, ul for unordered, div for others). Can be used with pseudo mode=inline where inline text contains one or more <br/>.

Only applicable to mode=ordered or mode=unordered. Not applicable to mode=category or mode=inline (with no <br/> in inline text).


Syntax:

listattr= attribute1="val1" attribute2="val2" ...


Example:

This selects pages in category Countries in Africa OR Countries in Europe and sets their ordermethod tp category,pagetouched (which is used in combination with headingmode to display category headings in the output, and pages sorted by mode ordered which causes the pages to be numbered. The hlistattr adds CSS formatting at the heading/top level enclosing all other items (and orange in color), and hitemattr adds styles to list items wrapping them in pink/red. listattr applies to type declaration elements, in this case the ordered (ol, or numbered) list elements, coloring them blue, and results are limited to a count of 3.

Code
{{#dpl:
|category    = Countries in Africa¦Countries in Europe
|ordermethod = category,pagetouched
|headingmode = definition
|mode        = ordered
|hlistattr   = id="dl-example" class="dpl-orange-background"
|hitemattr   = id="list-item-heading-attrubite" class="list-item-heading-attrubite"
|listattr    = id="ol-example" class="dpl-blue-background"
|count       = 3
}}
Result
Countries in Africa
  1. Madagascar
Countries in Europe
  1. Finland
  2. England

Test in sandbox

View Result


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

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


Note: To format subsequent elements in the same result set, see also (in the corresponding order since the examples build on one another) itemattr.


itemattr

[edit source]
itemattr Add attributes to HTML list items, depending on mode (element is li for ordered/unordered, span for others).

Not applicable to mode=category.


Syntax:

itemattr= attribute1="val1" attribute2="val2" ...


Example:

This lists pages in category Countries in Africa OR Countries in Europe and sets ordermethod to category,pagetouched used by headingmode lists categories as header, with pages sorted by pagetouched. mode is set to ordered, which pages listed to be numbered. The hlistattr adds CSS formatting at the heading/top level, enclosing all heading items and making them orange, where the hitemattr adds styles to list items making them pink/red. The listattr parameter applies around type declaration elements, wrapping them in blue, and itemattr sets white styles around individual list items.

Code
{{#dpl:
|category    = Countries in Africa¦Countries in Europe
|ordermethod = category,pagetouched
|headingmode = definition
|mode        = ordered
|hlistattr   = id="dl-example" class="dpl-orange-background"
|hitemattr   = id="list-item-heading" class="list-item-heading"
|listattr    = id="ol-example" class="dpl-blue-background"
|itemattr    = id="li-example" class="li-example"
|count       = 3
}}
Result
Countries in Africa
  1. Madagascar
Countries in Europe
  1. Finland
  2. England

Test in sandbox

View Result


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

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


headingcount

[edit source]
headingcount Decides, combined with headingmode, whether to show a text line with the number of articles per group or not.


Syntax:

headingcount=true


Note: (default is headingcount=false, it need not be set)


userdateformat

[edit source]
userdateformat Define a special layout for date formatting.


Syntax:

userdateformat=formatstring where formatstring sets the date format.

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: addeditdate, addpagetoucheddate,addfirstcategorydate.


Example:

userdateformat=Y-m-d (D)

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:

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

[edit source]

shownamespace

[edit source]
shownamespace Restrict the appearance of the namespace name of a page before the page. As the switch is true by default, it should be set to false to avoid namespaces being shown in the output.


Syntax:

shownamespace=false


Example:

This lists pages in category Number examples also in namespace Talk (Talk pages within the Main namespace). Only talk pages added to the category (by placing [[Category:Number examples]] on the talk page) are listed. The shownamespace parameter set to false suppresses namespace prefix display in the results, which are limited to a count of 1.

In DPL3 (versions older than 4.0.0), excluding a namespace with spaces in its name (such as "Help talk") requires replacing the space with an underscore — e.g. "Help_talk". If you use a space instead, exclusions won't work as expected and pages like Help talk:Three is not excluded. This is due to MediaWiki namespaces internally using underscores.

This is not an issue in DPL4 4.0.0 and later, where spaces in namespace names are handled correctly for exclusions.


Code
{{#dpl:
|category      = Number examples
|namespace     = Talk
|shownamespace = false
|count         = 1
}}
Result

Test in sandbox

View Result


Note: In mode=userformat 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 (%PAGE%) and the base title name (%TITLE%). Setting [[%PAGE%|%TITLE%]] links to the full page with namespace, but displays the link text without namespace.


[edit source]
escapelinks 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 (escapelinks=true – 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; escapelinks=false).


Syntax:

escapelinks=false


Example:

This displays images contained (displayed, using imagecontainer) within the Apple page. Setting escapelinks=false causes direct image display (at full-size), rather than a file page link. Setting mode=none removes the default (bulleted list) formatting, displaying the image plain. Note that using format may give greater output control (see Images used (examples)).

Code
{{#dpl:
|imagecontainer = Apple
|escapelinks    = false
|mode           = none
}}
Result
File:Red Apple Fruit With Black Background.jpeg

Test in sandbox

View Result


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: |format = ,[[File:%TITLE%|40px]] as in the second example here.
  • Use gallery syntax within a format statement, as in the example here.


titlemaxlength

[edit source]
titlemaxlength 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 titlemaxlength value, the title is truncated and ended by '...'.


Syntax:

titlemaxlength=number of characters


Example:

This list pages in category Country examples that are in notnamespace Category (not in it). Each result is shortened to titlemaxlength of 5 characters, meaning those with more display ... after them, and results are limited to a count of 3.

Code
{{#dpl:
|category       = Country examples
|notnamespace   = Category
|titlemaxlength = 5
|count          = 3
}}
Result

Test in sandbox

View Result


replaceintitle

[edit source]
replaceintitle execute a string replacement operation on the %TITLE% variable.


Syntax:

replaceintitle=search for,replacement


The search for argument must be an expression which can be used in a PHP preg_replace() function call.


To remove the string "demo" in article names, it must be written as: 

replaceintitle=/demo/,

Example:

This select pages in category Examples, that are in the namespace Category, and whose titlematch contains (examples) anywhere in it. The first argument of replaceintitle searches for the word examples and replaces it with various examples so their content in brackets displays as (various examples). Results are limited to a count of 3.

Code
{{#dpl:
|category       = Examples
|namespace      = Category
|titlematch     = %(examples)%
|replaceintitle = /examples/,various examples
|count          = 3
}}
Result

Test in sandbox

View Result


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 / if this character is not needed within the regexp itself.

If you are not familiar with regular expressions and/or do not know the specifics of Perl regexp used in PHP, it may be helpful to see:


Arranging article lists in columns and rows

[edit source]

columns

[edit source]
columns Defines a column layout for the output.

Currently non-working, though a workaround has been provided.


Syntax:

columns=ncols where ncols is the number of desired columns.


Warning: The columns parameter is currently bugged and is non-working [2] A workaround is provided below.


This (if it worked) lists pages in category Fruit examples, sets includesubpages to false to exclude them. It arranges the content in 3 columns with rowcolformat set to make width 100%. Results are limited to a count of 3.

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


Workaround example:

This list pages in category Fruit examples, arranged in 3 columns, with rowcolformat used to make the width 100%.

Note: This example uses a workaround; a div tag is used to wrap around the DPL3 statement, applying CSS column-count, to make the example function as described.


Code
<div class="optional-col-3" style="column-count: 3; "><!-- workaround start -->
{{#dpl:
|category     = Fruit examples
|columns      = 3              <!-- non-working -->
|rowcolformat = width=100%     <!-- non-working -->
|count        = 3
}}
</div><!-- workaround end -->
Result

Test in sandbox

View Result


Note: In mode=userformat the outer tags from listseparators are repeated for each column. This means that such a statement could create tables within columns, with something like: 

  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

[edit source]
rows 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 rowsize parameter.

Currently non-working.


Syntax:

rows=nrows where nrows is the number of desired rows.


In mode=userformat, the outer tags from listseparators 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 category Fruit examples, with addpagesize 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. ordermethod sets sort order by page size, the %NR% variable displays the number of each article in the first row. The listseparators line sets table styles and header, rows specifies 2 for how many results are displayed before the heading repeats. Results are limited to a count of 6.

This example is currently non-working, it may be replaced or removed at a later date to improve the clarity of this manual. As this needs to be done at a deliberate pace, the Gamepedia DPL3 Manual can be used in the interim, keeping in mind some functions may have changed.


Example:

Code
{{#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
}}
Result
Rank Article Bytes
1. Plum 134
2. Mango 153
3. Orange 234
4. Apricot 288
5. Banana 379
6. Pear 455


rowsize

[edit source]
rowsize Define a row layout for the output. A "row" is a group of n output lines for which the heading are repeated.

Currently non-working.


Syntax:

rowsize=nrowsize where nrowsize is the desired row size.


In mode=userformat the outer tags from listseparators are repeated after each group of rowsize output lines. Thus, long lists can be created where the table heading is repeated in regular intervals.


This lists all pages in category Fruit examples. addpagesize adds page size to the output. ordermethod sets the order to order by size. The listseparators row sets table formatting and uses the %NR% variable to list a number for each page. rowsize specifies the number of result pages (3) after which the table heading is repeated. Results are limited to a count of 6.

Example:

This example is currently non-working, it may be replaced or removed at a later date to improve the clarity of this manual. As this needs to be done at a deliberate pace, the Gamepedia DPL3 Manual can be used in the interim, keeping in mind some functions may have changed.

Code
{{#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
}}
Result
Rank Article Bytes
1. Plum 134
2. Mango 153
3. Orange 234
4. Apricot 288
5. Banana 379
6. Pear 455


rowcolformat

[edit source]
rowcolformat Defines layout properties (using allowed HTML table tag parameters) for the row/column grid.

Currently non-working.


Syntax:

rowcolformat=HTML tags where HTML tags are the desired (allowed) HTML tags to set.


Example:

This example is currently non-working, it may be replaced or removed at a later date to improve the clarity of this manual. As this needs to be done at a deliberate pace, the Gamepedia DPL3 Manual can be used in the interim, keeping in mind some functions may have changed.

This lists pages in category Fruit examples, displayed in 3 columns, with rowcolformat setting more space around the columns. The result count is limited to 6.

Code
{{#dpl:
|category        = Fruit examples
|columns         = 3
|rowcolformat    = cellspacing=20
|count           = 6
}}
Result


Example:

This example is currently non-working, it may be replaced or removed at a later date to improve the clarity of this manual. As this needs to be done at a deliberate pace, the Gamepedia DPL3 Manual can be used in the interim, keeping in mind some functions may have changed.

The ideal way to use rowcolformat is to assign a CSS class to the DPL3 table, which has been defined in the MediaWiki:Common.css article.

Code
{{#dpl:
|category        = Fruit examples
|includesubpages = false
|columns         = 3
|rowcolformat    = class="dpl3columns"
|count           = 6
}}
Result


In the MediaWiki:Common.css page, something like the following might be written: 

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


References

[edit source]
  1. ↑ 1.0 1.1 1.2 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 HitCounters extension.
  2. ↑ The columns parameter is currently bugged and does not work
Retrieved from "https://dpl3.wikitide.org/wiki/Controlling_output_format?oldid=3684"
Cookies help us deliver our services. By using our services, you agree to our use of cookies.
More information