DPL:Manual - DPL parameters: Controlling output format
You can select one of several default formats or define your own format("mode=userformat"); output can be grouped in columns or rows.
Contents
General approach to output formatting
The general approach to output formatting is two-fold:
- There are a couple of simple predefined output formats which generate lists of articles
- You will understand their meaning directly from reading
- There is a mode called "userformat" 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 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 forth 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 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:
- listseparators = liststart,itemstart,itemend,listend
- secseparators = sec-1-start,sec-1-end,sec-2-start,sec-2-end, .. , ..
- multisecseparators = multi-sep
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 mode userformat 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 (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, you may want to create an output table where each of the calls of template y is used to create a separate output row. Using a sortable table you could then easily rearrange the output.
+------+---------------------+ +------+---------------------+ | 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) | +------+---------------------+ +------+---------------------+
There is a special parameter called "dominantsection" which you can use to mark one section of your includepage statement as "dominant" (in our example: "dominatsection=2" as {y}.dpl is the second argument of our includepage statement). You can only have one dominant section in a DPL statement. Marking a section as "dominant" makes only sense if you have multiple calls of the same template (or multiple chapters with the same heading) in your documents. Each piece of contents in the dominant section will generate an individual output row with the values of all other columns being repeated.
mode
| mode | Provide basic control over the output of DPL. |
Syntax:
mode=modename
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 symbol defined by the inlinetext parameter to separate items.
- category
- outputs resulting articles in a way category-pages are shown (you have to use
ordermethod = title | titlewithoutnamespace | category,title | user,titlewith this option!)
- userformat
- will leave output control completely to the user;
see parameter listseparators and secseparators; in this mode DPL2 will offer built-in variables which must be referenced in the output format description provided by the user. mode=userformat is quite important if you want to have complete control over the output.
For advanced use of DPL it is important to understand mode=userformat. Note that this mode is automatically implied when you use listseparators= or format=.
Example1
<DPL> category=Africa mode=ordered </DPL> | This list will output pages that have [[Category:Africa]] shown in an <ol>...</ol> list:
|
Example2
<DPL> titlematch=%frica% mode=category ordermethod=titlewithoutnamespace </DPL>
This list will output pages that have 'frica' 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)
Related extension variable(s): $wgDPL2CategoryStyleListCutoff.
inlinetext
| inlinetext | To define the inline text used in mode=inline
|
Syntax:
inlinetext=wikitext, with wikitext some wiki text
default is ' - ' except for mode=userformat where inlinetext is empty by default.
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 ' ', or use 'nowiki' tags like in '<nowiki> - </nowiki>' which has same effect as ' - '.
Example:
<DPL> category=Africa mode=inline inlinetext= • </DPL>
This list will output pages that have [[Category:Africa]] shown like Item1 • Item2 • Item3 • ...
format
| format (alias for listseparators) | see the listseparators parameter. |
Note that format= automatically implies mode=userformat.
listseparators
| listseparators | customize the output format completely. Requires "mode=userformat". Uses variable references like %PAGE% to describe the output format. See also the secseparators parameter. |
Note that listseparators= automatically implies mode=userformat.
Syntax:
listseparators=Startall,Start,End,Endall
'Startall', 'Start', 'End' and 'Endall' are wiki tags used to separate the list items.
- 'Startall' and 'Endall' define an outer frame for the whole list.
- 'Start' and 'End' build an inner frame for each article item.
Because wiki syntax depends on newline characters the string '\n' 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 symbols:
- %NR% = the current article sequence number (starting from 1)
- %PAGE% = the name of the article (including namespace)
- %PAGES% = number of articles in category (only available in resultsheader)
- %TITLE% = the title of the page (without the namespace)
- %COUNT% = the usage counter (requires addpagecounter=true)
- %SIZE% = the article size (requires addsize=true)
- %SIZEFS% = a font size number which is based on the article size (logarithm of square root of counter)
- %COUNTFS% = a font size number which is based on the usage counter (currently this is the logarithm of the usage counter)
- %COUNTFS2% = similar to %COUNTFS%, but based on the logarithm of the square root of the usage counter.
- %DATE% = the date selected, eg. "lastedit"; requires addeditdate=true or similar; the formatting of the date can be influenced using userdateformat=
- %USER% = the user who changed the document last; requires adduser=true
- %CATLIST% = a pipe separated list of links to all categories to which the article belongs
- %CATNAMES% = a comma separated list of all categories to which the article belongs
- %REVISION% = the name of the revision of the article; this will only be available if you made a selection based on revisions
These symbols will be replaced by the corresponding values if they occur within 'Start' or 'End' or within the corresponding tags of the "secseparators=" parameter.
This means that the classical default output of DPL2 can also be produced with the following statements:
Example:
<DPL> category = Africa mode = userformat listseparators = ,\n* [[%PAGE%|%TITLE%]],, </DPL>
Note that a bullet point list in wiki syntax is defined by a "*" at the beginning of a line -- therefore we have to use a special symbol '\n' or '¶' to refer to the beginning of a new line of wiki text. Replace the "*" by a "#" and you will get a numbered list. 'Startall' and 'Endall' are empty (note that we start with a comma, note the two commas at the end), the 'Start' 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 = Africa ordermethod = counter order = descending addpagecounter = true count = 5 mode = userformat listseparators =,\n%COUNT% --- <font size="%COUNTFS%">'''[[%PAGE%]]'''</font>,<br/> </DPL>
You can also use html syntax for the tags, although this is discouraged ..
<DPL> linksto = Africa mode = userformat listseparators = <ul type="disc">,<li>[[%PAGE%]],</li>,</ul> </DPL>
Now let us create a table using wiki syntax:
<DPL>
linksto = Africa
mode = userformat
listseparators = {| class="wikitable"¶!pages found,¶|-¶|[[%PAGE%]],,¶|}
</DPL>
We use 'Startall' to define the table header and 'Endall' for the footer. Each article is presented in a table row using wiki syntax for table layout.
we could also produce image galleries:
<DPL> namespace=Image mode=userformat listseparators=<gallery>,%PAGE%\n,,</gallery> </DPL>
secseparators
| 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
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 secseparator statements.
In the first syntax variant, specify pairs of tags which correspond the the includepage statement. 'StartN and 'EndN' are HTML strings or wiki tags which will be put around each transcluded section (see 'includepage=name1,name2,...').
In the second syntax variant, specify just one element which will then be 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 symbol %SECTION% 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 'secseparator tags' will only be put once around the whole block (but see dominantsection).
Example
<DPL>
linksto = Africa
mode = userformat
listseparators = {|¶!pages found¶!fruit¶!color,¶|-¶|[[%PAGE%]],,¶|}
includepage = #fruit,#color
secseparators = ¶|,,¶|,,
</DPL>
Use listseparators to define a table with three columns and put a link to the article in the first column of each row. Use secseparators 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 '¶' symbols ('\n' 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 "fruit", it will result in an empty cell in the table.
As mentioned above, a single element can be used in the secseparators statement in order to apply this as a start tag to all transcluded sections; so it could have also been written:
Example 2
<DPL>
linksto = Africa
mode = userformat
listseparators = {|\n!pages found\n!fruit\n!color,\n|-\n|[[%PAGE%]],,\n|}
includepage = #fruit[50],#color[100 more..]
secseparators = \n|
</DPL>
Assuming that the chapters on fruit and color contain long texts, they can be truncated to 50 or 100 characters. A link which refers directly to those chapters will be generated automatically if needed.
multisecseparators
| multisecseparators | put a tag between multiple transcluded parts which refer to the same template 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 symbol %SECTION% can be used to refer to the section found (works only for chapter headings).
If an article uses the same template more than once you will get all references with "sepN" as a separator.
Example:
<DPL>
category=TestSSt
includepage={interfaces_overview} dpl
mode=userformat
listseparators=¶{|class=sortable ¶!Interface ¶!Source system ¶!Target system ¶!Technology,¶|-¶|[[%PAGE%]] ¶,¶,¶|}
secseparators = \n|
multisecseparators=¶|-¶| |
</DPL>
dominantsection
| dominantsection | define a section with multiple occurencies as dominant, i.e. each piece of contents of this section (which is associated with a template call or a chapter within the original document) will create a separate output line. |
Syntax:
dominantsection=number between 1 and the number of arguments in your includepage= 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.
headingmode
| headingmode | To control the output of the headings in a DPL with complex/multi-parameter ordermethods. (No effect with single-param ordermethods.) For ordermethod=method1,method2,..., method1 is used for headings. E.g. headingmode affects category headings in ordermethod=category,title (2-param ordermethod). See also headingcount=
|
Syntax:
headingmode=modename
modename can be one of:
- none — headings are not displayed, no heading — (default)
- unordered — outputs an unordered list — HTML tag "ul"
- ordered — outputs an ordered list — HTML tag "ol"
- definition — outputs a definition list — HTML tag "dl"
- H2 — outputs sections — HTML tags "H2"
- H3 — outputs sections — HTML tags "H3"
H4 — outputs sections — HTML tags "H4"
Example:
<DPL> category=Africa|Europe ordermethod=category,title headingmode=definition mode=ordered </DPL>
This list will output pages that belong to one of the categories Africa, Europe in a list similar to this (HTML source), with Pages 1 and 2 in the Africa category, Page 1 in the Europe category as well (in fact, the titles are replaced with the appropriate links):
<dl>
<dt>Africa</dt>
<dd>
<ol>
<li>Page1</li>
<li>Page2</li>
</ol>
</dd>
<dt>Europe</dt>
<dd>
<ol>
<li>Page1</li>
</ol>
</dd>
</dl>
headingcount
| headingcount | In combination with headingmode this parameter decides whether we show a text line with the number of articles per group or not. |
Syntax:
headingcount=true
default is headingcount=false</count>
minoredits
| minoredits | Controls the inclusion or exlusion of minor edits in lists. |
Requires: ordermethod=[...]firstedit|lastedit
Example:
<code>minoredits=criteria
criteria can be one of:
- exclude — ignore minor edits when sorting lists
- include — includes minor edits to sort lists — (default)
Example:
<DPL> category=Africa ordermethod=lastedit minoredits=exclude </DPL>
This list will order pages tagged with [[Category:Africa]] by lastedit, but minor edits will be ignored in the ordering.
listattr
| listattr | Adds attributes to HTML list elements, depending on 'mode' (html element is 'ol' for ordered, 'ul' for unordered, 'div' for others). Can be used with pseudo 'mode=inline' where 'inlinetext' contains one or more <BR/>.
|
Syntax: <code>listattr= attribute1="val1" attribute2="val2" ...
Examples:
| Input | (HTML) Output | Actual Output |
|---|---|---|
<DPL> ordermethod=category,title headingmode=ordered mode=none listattr= class="submenul" itemattr= class="submenuli" style="font-style: italic;" </DPL> |
<ol>
<li> 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> 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>
|
|
<DPL> ordermethod=category,title headingmode=ordered mode=unordered listattr= class="submenul" itemattr= class="submenuli" style="font-weight: bold;" </DPL> |
<ol>
<li> Cat1 (link)
<ul class="submenul">
<li class="submenuli" style="font-weight: bold;"> Page1_1 </li>
<li class="submenuli" style="font-weight: bold;"> Page1_2 </li>
</ul>
</li>
<li> Cat2 (link)
<ul class="submenul">
<li class="submenuli" style="font-weight: bold;"> Page2_1 </li>
<li class="submenuli" style="font-weight: bold;"> Page2_2 </li>
</ul>
</li>
</ol>
|
|
itemattr
| itemattr | Adds 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: see listitemattr.
hlistattr
| hlistattr | Adds attributes to the HTML list element at the heading/top level, depending on 'headingmode' (HTML element would be 'ol' for ordered, 'ul' for unordered, 'dl' for definition, 'div' for others)
Not yet applicable to 'headingmode=none'. |
Syntax:
hlistattr= attribute1="val1" attribute2="val2" ...
Example:
| Input | (HTML) Output | Actual Output |
|---|---|---|
<DPL> ordermethod=category,pagetouched headingmode=H2 mode=ordered hlistattr= class="topmenul" id="dmenu" </DPL> |
<div class="topmenul" id="dynamicmenu">
<H2> Category 1 (link) </H2>
<ol>
<li>Page1_1</li>
<li>Page1_2</li>
</ol>
<H2> Category 2 (link) </H2>
<ol>
<li>Page2_1</li>
</ol>
</div>
|
See also hitemattr.
hitemattr
| hitemattr | Adds attributes to HTML list items (headings) at the heading level, 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:
| Input | (HTML) Output | Actual Output |
|---|---|---|
<DPL> ordermethod=category,title headingmode=unordered mode=ordered hlistattr= class="topmenul" id="dmenu" hitemattr= class="topmenuli" style="color: red;" </DPL> |
<ul class="topmenul" id="dmenu">
<li class="topmenuli" style="color: red;"> Category 1 (link)
<ol>
<li>Page1_1</li>
<li>Page1_2</li>
</ol>
</li>
<li class="topmenuli" style="color: red;"> Category 2 (link)
<ol>
<li>Page2_1</li>
</ol>
</li>
</ul>
|
columns
| columns | Define a column layout for the output. |
Syntax:
column=ncols
In "mode=userformat" the outer tags from "listseparators" will be repeated for each column.
Example:
<DPL>
category=Africa
addpagesize=true
ordermethod=size
mode=userformat
listseparators={|class=sortablewikitable id=2\n!Rank\n!Article\n!Bytes\n|-,\n|%NR%.\n|[[%PAGE%]]\n|align=right|%SIZE%,\n|-,\n|}
count=12
columns=3
</DPL>
The output will contain a list of the 12 largest articles on Africa, arranged in three columns. Each column consists of a table which has itself three columns: rank, article name and size.
rows
| rows | Define a row layout for the output. A "row" is a group of output lines for which the heading is repeated. If you do not know how big your result will be, it may be better to use the "rowsize" parameter. |
Syntax:
rows=nrows
In "mode=userformat" the outer tags from "listseparators" 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=Africa
addpagesize=true
ordermethod=size
mode=userformat
listseparators={|class=sortablewikitable id=2\n!Rank\n!Article\n!Bytes\n|-,\n|%NR%.\n|[[%PAGE%]]\n|align=right|%SIZE%,\n|-,\n|}
count=12
rows=2
</DPL>
The output will contain a list of the 12 largest articles on Africa, arranged in two rows (of 6 lines each). Each row consists of a table which has itself three columns: rank, article name and size.
rowsize
| rowsize | Define a row layout for the output. A "row" is a group of n output lines for which the heading will be repeated. |
Syntax:
rowsize=nrowsize
In "mode=userformat" the outer tags from "listseparators" will be repeated after each group of "rowsize" output lines. Thus you can create long lists where the table heading is repeated in regular intervals.
Example:
<DPL>
category=Africa
addpagesize=true
ordermethod=size
mode=userformat
listseparators={|class=sortablewikitable id=2\n!Rank\n!width=200px|Article\n!Bytes\n|-,\n|%NR%.\n|[[%PAGE%]]\n|align=right|%SIZE%,\n|-,\n|}
rowsize=20
</DPL>
The output will contain a list of all articles on Africa. After each group of 20 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 havce equal width.
rowcolformat
| rowcolformat | Define layout properties (table tags) for the row/column grid. |
Syntax:
rowcolformat=html tags
Example:
<DPL> category=Africa columns=3 rowcolformat=cellspacing=20 </DPL>
There will be more space around the columns than normal.
userdateformat
| userdateformat | Define a special layout for date formatting. |
Syntax:
userdateformat=formatstring
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 gmdate() for more details. The "userdateformat" applies to all date/time fields, see the parameters: addeditdate,addpagetoucheddate,addfirstcategorydate
Example:
userdateformat=Y-m-d (D)
titlemaxlength
| 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
replaceintitle
| replaceintitle | execute a string replacement operation on the %TITLE% var |
Syntax:
replaceintitle=search for,replacement
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 charactter -- but not wioth 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.
