DynamicPageList2

来自Org
跳转至: 导航搜索

模板:MoveToMediaWiki 模板:Extension

DynamicPageList2 is a Mediawiki extension developed for use on Wikinews (but not yet installed there), but it can be installed on any wiki. It allows wiki users to dynamically create lists of pages based on a variety of selection criteria like categories, namespaces, title, references to other articles, usage of templates. Selection criteria can be combined using logical AND and OR. Contents of the pages can be included in the output of DPL2.

Source Code and Examples for Release 0.9 (which has not been officially released so far) 
can be found on a separate dpl demo web site.

DynamicPagelist2 vs. DynamicPageList

This extension - DynamicPageList2 is a hack of the original DynamicPageList extension featuring many improvements (see Usage of DynamicPageList2). Note that it's called DynamicPageList2 for distinction of DynamicPageList. You can use both extensions at the same time, because the new tag is DPL instead of DynamicPageList.

With DPL2 you have much more freedom when generating dynamic article lists by using AND and OR with categories. Moreover, there are much more display options to set.

Release 0.9 has some major improvements compared to former versions. As a consequence, there are some minor incompatibilities with older versions (mainly in the area of parameter expansion -- see the chapter on #General Usage of DynamicPageList2).

Main Authors / Contacts

Source and Installation

Get code/file

First download the source from:

  • Release 0.9
  • older releases
    • svn.wikimedia.org (for latest/development version)
DynamicPageList2.php: Main file.
DynamicPageList2.i18n.php: Required by DynamicPageList2.php, internationalization file used for all DPL messages.
    • Alternative location: svnweb.tuxfamily.org (for latest or older releases)
Development version: Browse - Tarball
Older releases: Browse. RELX_Y_Z means version X.Y.Z. Use the Tarball link on the right to download.

Installation

To install it,

  1. put the file in your extensions/ directory
  2. edit your LocalSettings.php file and add the following line:
require_once("extensions/DynamicPageList2.php"); 

Labeled Section Transclusion is another extension which is used by DPL2.

If you installed release 0.9 there is nothing else to do because a special version of that extension has been integrated into release 0.9.

If you installed release 0.8.x, you have to install the Labeled Section Transclusion extension too (both lst.php and lsth.php files).

For v0.7.0 and above, if you want to apply the 'category' parameter on the Uncategorized pages, you are required to execute this manual query on your MediaWiki database, replacing prefix with your prefix if any:

CREATE VIEW prefix_DPL_clview AS 
 SELECT IFNULL(cl_from, page_id) AS cl_from, IFNULL(cl_to, '') AS cl_to, cl_sortkey 
  FROM prefix_page LEFT OUTER JOIN prefix_categorylinks ON page_id=cl_from

If you are using this extension with IIS on a Windows box, make sure to give Read & Execute rights to the user IUSR_MACHINENAME (Anonymous Internet Guest Account) for the extensions directory and the DynamicPageList2.php file itself.

System requirements

Not compatible with Mediawiki 1.5.x. The extension uses (needs) more than two parameters and WikiMedia 1.5.x provides only two.

Sites using DPL2

Please supply the list below with links to wikis where DynamicPageList2 is installed, and if possible, specific pages where we can see it in action. This is useful for users who do not have their own wiki installation to have a live demo of its features. We appreciate it.

Here are some links where DynamicPageList2 is being used (check the Special:Version page to get the version):

General Usage of DynamicPageList2

DPL2 can be used as a parser extension or as a parser function. There is no general rule which one is better. The next two sections describe the differences.

If in doubt, you may want to use the parser function syntax as it is more powerful.

Using DPL2 as a parser extension

Parser extensions define a specific tag (in our case <DPL>) and a corresponding end tag (</DPL>). Case doesn´t matter, so you can also write <dpl>. The text between these tags is handed over to the extension module just as it is. The extension module takes this text as a series of commands, executes them and inserts the output right at the place where it found the two tags.

  • every parameter assignment (=command) has to be on a separate line
  • generally the syntax looks fairly simple and intuitive as it doesn´t contain special characters (except for the two embracing tags).
  • Wiki markup expansion does not take place before the commands are handed over to the extension module.
    • this may be useful if you want to pass wiki syntax elements to DPL2 as arguments (see the listseparators option, for example)
    • you cannot use something like {{PAGENAME}} or {{CURRENTDAY}}
    • you cannot use template parameters
    • you cannot use parser funtion calls like {{#if:...|...|...}} within the arguments

In many cases there is no need to have macro expansion within the parameter list. For example:

 <DPL>
    category = cat1|cat2
    linksto  = myPage
 </DPL>

The example will produce a list of all articles which belong to cat1 or cat2 and which contain a reference to myPage. Note that the pipe character (which is used to define a logical OR between the two categories) can be written as it is. The name of the page (myPage), however, must be a hardcoded constant. The output of this DPL call would be something like

Using DPL2 as a parser function

Parser functions are more closely integrated with the wiki system. They are more powerful but their syntax looks a bit more complicated. In our case you can write {{#dpl:...|...}} just the way you would use {{#if:...|...}}. The text between the double curly braces is interpreted and expanded according to wiki syntax rules before it is handed over to the extension module. This means:

  • All kind of wiki markup expansions take place before the commands are handed over to the extension module.
    • If you want to use wiki characters as arguments you must define special templates to "escape" them.
  • the text can (but needs not) be written in one line of text, parameters are separated by pipe characters.

Example:

 {{#dpl: category = cat1{{!}}cat2 | linksto=={{{1}}} }}
 
                  or
 
 {{#dpl:
   |category = cat1{{!}}cat2
   |linksto  = {{{1}}}
 }}

Both examples will produce an identical list of all articles which belong to cat1 or cat2 and which contain a reference to a certain page. We assume that the above invocation of #dpl is contained within a template. The desired page name will be passed as a parameter when calling the template. Within the template the page name can be referred to as {{{1}}}.
Note that the pipe character which is used to define a logical OR for the two categories must be represented as a call of a special template which would typically be called "Template:!" and which has a single pipe character as its contents. You will find the same kind of trick also outside DPL in other templates.
You may note that the second example is not literally equivalent to the first one as there is an additional pipe character before the first parameter. This creates an empty parameter which is silently ignored by DPL.

Syntax used in this manual

If we give complete examples we will typically use the tag based parser extension syntax in this manual. Except when we want to make use of variable expansion.

Most of the manual deals with the explanation of individual parameters. This is independant from the two variants described above. So, if you read something like

  • parameter = value

you should have in mind that you must either place DPL tags around (using a separate line for each parameter) or use the parser function syntax and separate parameters by pipe characters.


Interaction between your wiki text and DPL2 output

As mentioned before DPL2 will insert its output exactly at the position where you placed the DPL2 call. This means that you can put wiki syntax around your DPL call, like e.g.:

  {| class=wikitable
  |a table field
  |<DPL>
     linksto=myPage
   </DPL>
  |-
  |another table field
  |...
  |}

You could also use html syntax to surround DPL output as in the following example:

<ul>
  <li>Item1</li>
  <li>Item2
    <DPL>
      ...parameters...
    </DPL>
  </li>
</ul>



Usage of DPL2: Criteria for page selection

  • You can select articles based on
    • the category/categories they are assigned to
    • the number of categories they are assigned to
    • their namespace
    • their usage of templates
    • their title
    • their references to other articles
    • their character (#redirect or normal article)
  • You can restrict the number of articles to a certain limit
    • via configuration settings within the DPL2 source
    • via a specific parameter for a given invocation of DPL2
  • You can select a subset from the result list by random


category

Purpose:

Select articles based on categories. You can specify more than one category with the pipe '|' as a separator, with the effect that the pages listed have to be at least in one of the categories (logical OR). If you specify the 'category=' parameter more than once, the pages listed have to match all these parameters (logical AND).

Syntax:

category=1st category name|2nd category name|3rd category name|...


Example 1:

<DPL>
  category=Africa|Europe
  category=Politics and conflicts
</DPL>

This list will output pages that have [[Category:Africa]] OR [[Category:Europe]], AND [[Category:Politics and conflicts]] listed.

v0.7.0 - You can specify the set of Uncategorized pages as a normal category, with an empty string (e.g. 'category=' for uncategorized pages only, 'category=|Animals' or 'namespace=Animals|' for the Uncategorized or the Animals category, 'category=Mammals||Insects' for the Mammals category, uncategorized pages or the Insects category, etc.). See Source and Installation for the extra required installation steps.

v0.7.7 - If ordermethod=category,... and headingmode are enabled, you can restrict the categories you want as headings in the result by preceding the list of categories (specified with the category parameter) with a '+'. See the example below.

Example 2:

<DPL>
  category=+Africa|Europe
  category=Politics and conflicts
  ordermethod=category,sortkey
  headingmode=ordered
</DPL>

This list will output pages that have [[Category:Africa]] OR [[Category:Europe]], AND [[Category:Politics and conflicts]] listed. The list will be ordered (OL tag) and organized in 2 main items/headings: the Africa one and the Europe one (Politics and conflicts will not be used as a heading). Under each item/heading, a sublist of pages ordered by their sortkey for the category used as heading.

Notes:

If you want to use magic words like {{CURRENTMONTHNAME}}, {{CURRENTDAY}}, {{CURRENTYEAR}} etc in the category name, you must use the parser function syntax variant.

To prevent a DPL query from returning huge output (or consuming too many resources) there are some configuration variables in the source code of the extension module like $wgDPL2MaxCategoryCount, $wgDPL2AllowUnlimitedCategories, $wgDPL2MinCategoryCount.

notcategory

Purpose:

Much like the category parameter, but requires that every page listed not be in a particular category. Unlike in 'category' you cannot combine several categories using logical OR in this parameter.

Syntax:

notcategory=category name

Example:

<DPL>
  category=Africa
  notcategory=Zimbabwe
  notcategory=Kenya
</DPL>

This list will output pages that have [[Category:Africa]] but do not have either [[Category:Zimbabwe]] or [[Category:Kenya]] listed.

Notes:

If you use the parser function syntax you will be able to use Magic words like {{CURRENTMONTHNAME}}, {{CURRENTDAY}}, {{CURRENTYEAR}} etc in the category name.

Related extension variables (more info): $wgDPL2MaxCategoryCount, $wgDPL2AllowUnlimitedCategories, $wgDPL2MinCategoryCount.

categoriesminmax

Purpose:

To restrict the search to articles which are assigned to at least [min] and at most to [max] categories.

Syntax:

categoriesminmax=[min],[max]

Example:

<DPL>
  category=Africa
  categoriesminmax=3
</DPL>

The list will only contain articles which belong to category "Africa" and at least to two other categories

<DPL>
  category=Africa
  categoriesminmax=,1
</DPL>

The list will only contain articles which belong to category "Africa" and are not assigned to any other category.


namespace

Purpose:

To restrict the articles in the list to only be in one of the given namespaces.

v0.7.7 - Magic words supported. See Help:Magic_words#Page_names_and_related_info and Help:Magic_words#Namespaces_and_URLs for relevant magic words.

Syntax:

namespace=1st namespace name|2nd namespace name|3rd namespace name|...

The namespace name may be anyone, assuming it represents a valid namespace in the system, including custom ones, BUT no pseudo-namespace such as Media, Special which have negative namespace ids. See Help:Namespace. The empty string is the main article namespace (e.g. 'namespace=' for pages in Main ns only, 'namespace=|Help' or 'namespace=Talk|' for Main or Talk ns, 'namespace=User||Category' for User, Main or Category, etc.).

Name spaces are case sensitive namespace=User_talk will work, but namespace=User_Talk will not.

Namespace ids are no longer allowed as namespace arguments, because it caused a conflict between namespace given a number as name on one hand, and namespace with that same number as namespace id on the other hand. E.g. if you created a custom namespace with '1' as title (yes, it's possible), namespace=1 would give you pages in '1' and not pages in namespace with id=1 (Talk). In that case, you could not get pages in the Talk ns anymore. Solution: use only ids or only names. Names are more user-friendly.

Example 1:

<DPL>
  category=Policy
  namespace=Wikinews|Discussion
</DPL>

This list will output pages that are in the Wikinews or Discussion namespace and belong to [[Category:Policy]].

Example 2 (with magic word):

  {{#dpl: category = Policy | namespace= {{NAMESPACE}} }}

This list will output pages that are in the namespace the current page is in - whatever it is - and belong to [[Category:Policy]].

notnamespace

Purpose:

Much like the notcategory parameter, but for namespaces. Requires that every page listed not be in one of given namespaces.

v0.7.7 - Magic words supported (when using parser function syntax). See Help:Magic_words#Page_names_and_related_info and Help:Magic_words#Namespaces_and_URLs for relevant magic words.

Syntax:

notnamespace=namespace name

Example 1:

<DPL>
  notnamespace=Wikinews
  notnamespace=Discussion
</DPL>

This list will output pages that are NEITHER in the Wikinews NOR in the Discussion namespace.

Example 2 (with magic word):

  {{#dpl: notnamespace = Wikinews | notnamespace = {{NAMESPACE}} }}

This list will output pages that are NEITHER in the Wikinews NOR in the namespace the current page is in.

linksto

Introduced in v0.7.7.

Purpose:

Selects articles which link to a certain page.

Syntax:

linksto=full page name

Example 1:

<DPL>
  category = Poets
  linksto  = Dublin
</DPL>

This list will output pages that are in category "Poets" and link to the page with title Dublin in the Main namespace.

Example 2 (with magic word):

  {{#dpl: category = Poets | linksto = {{FULLPAGENAME}} }}

This list will output pages that are in category "Poets" and link to the current page, whatever it is.

notlinksto

Purpose:

Selects articles which do NOT link to a certain page.

Syntax:

notlinksto=full page name

Example:

<DPL>
  category   = Poets
  notlinksto = London
</DPL>

This list will output pages that are in category "Poets" and have no link pointing to the page with title London in the Main namespace.

Note:

The implementation of this feature is not very efficient. Use with care and avoid huge result sets.


uses

Introduced in v0.9.

Purpose:

Selects articles which use a certain template ( wiki syntax: {{...}} ).

Syntax:

uses=Template:name

Example 1:

<DPL>
  uses = Template:Poet
</DPL>

This list will output pages that use a template called Poet.

notuses

Introduced in v0.9.

Purpose:

Selects articles which do not use a certain template.

Syntax:

notuses=Template:name

Example 1:

<DPL>
  category = Poet
  notuses = Template:Poet
</DPL>

This list will output pages about poets which do not use the corresponding template.

Caution:

The implementation of this feature is not very efficient. Use with care and avoid huge result sets.

titlematch

Purpose:

Select pages with a title matching a certain pattern. "pattern" is used as a LIKE argument in a SQL query. Namespaces are ignored as the namespace= parameter can be used to further narrow the selection.

Syntax:

titlematch=pattern

Example:

<DPL>
  titlematch=%foo%
</DPL>

This will output all pages (regardless of namespace) which have a name that contains "foo" somewhere in the title.

Example:

<DPL>
  namespace=
  titlematch=A%
</DPL>

This will output all pages in the main namespace which begin with "A".

nottitlematch

Select pages with a title NOT matching a certain pattern. "pattern" is used as a LIKE argument in a SQL query. Namespaces are ignored as the namespace= parameter can be used to further narrow the selection. Normally you would want to use this selection only in combination with other criteria. Otherwise output could become huge.

Syntax:

nottitlematch=pattern

Example:

<DPL>
  nottitlematch=%e%
</DPL>

This will output all pages (regardless of namespace) which do not contain "e" in their title.


redirects

Purpose:

Controls the inclusion or exlusion of redirect pages in the output. By default redirections are NOT shown.

Syntax:

redirects=criteria

criteria can be one of:

  • exclude — excludes redirect pages from lists — (default)
  • include — allows redirect pages to appear in lists
  • only — lists only redirect pages in lists

Example:

<DPL>
  category  = Africa
  redirects = include
</DPL>

The result will consist of content pages and redirect pages tagged with [[Category:Africa]].


count

Purpose:

Controls the number of results that are shown.

Syntax:

count=n, with n a positive integer

A blank value (count=) for unlimited. It is unlimited by default, depending on extension variables: $wgDPL2MaxResultCount, $wgDPL2AllowUnlimitedResults.

Example:

<DPL>
category=Africa
ordermethod=pagetouched
count=2
</DPL>

This list will output the two pages most recently changed that have [[Category:Africa]].


randomcount

Purpose:

create the complete result set and then select a subset for display by random.

Syntax:

randomcount=n, with n a positive integer

If randomcount is larger than the number of results, the complete result set will be displayed.

Example:

<DPL>
  category=Africa
  ordermethod=size
  count=20
  randomcount=3
</DPL>

This list will output three random articles from the group of the 20 largest articles on Africa.

Usage of DPL2: controlling output order

You can influence the order in which articles are listed.

ordermethod

Purpose:

Determines what criterium (resp. criteria) is (resp. are) used to order the list.

Syntax:

ordermethod=method1,method2,... means ordered by method1 first, then by method2, etc. (like the ORDER clause in SQL)

methodN can be one of:

  • categoryadd — outputs list based on most recent addition to the first category (requires to include one category and one only using 'category' parameter)
  • counter — outputs list based on the number of times the page has been viewed (by ~popularity)
  • size — outputs list based on the size of the article (bytes of wiki text)
  • firstedit — outputs list based on first edit to the pages (creation)
  • lastedit — outputs list based on most recent edit to the pages
  • pagetouched — outputs list based on 'page_touched' timestamp. Read comment on page_touched field in Page_table to see the difference from most recent edit by an author.
  • title — outputs list sorted by article (prefix +) title — (default)

Multi-param ordermethods (see also headingmode option):

  • category,firstedit — outputs list sorted by category, then by first edit
  • category,lastedit — outputs list sorted by category, then by last edit within a category
  • category,pagetouched — outputs list sorted by category, then by pagetouched
  • category,title — outputs list sorted by category, then by title
Replaced by category,sortkey in v0.7.7 to customize the order with sortkeys from category tags, like in MediaWiki category pages.
  • user,firstedit — outputs list sorted by user, then by firstedit by the user
  • user,lastedit — outputs list sorted by user, then by lastedit by the user

Example:

<DPL>
  category=Africa
  ordermethod=lastedit
</DPL>

This list will output pages that have [[Category:Africa]] showing most recently edited articles at the top.

order

Purpose:

Controls the sort direction of the list.

Example:

order=orderdirection

orderdirection can be one of:

  • descending — outputs list from most recent to least recent — (default)
  • ascending — outputs list from least recent to most recent

Example:

<DPL>
  category    = Africa
  ordermethod = lastedit
  order       = ascending
  addeditdate = true
</DPL>

This list will output pages that have [[Category:Africa]] shown ordered from oldest to newest. In addition the edit date will be presented with each article.


Usage of DPL2: controlling output volume

Per default DPL2 will show the name of each article, including its namespace. The name will serve as a link to the article.

You can

  • show the number of articles found
  • suppress the namespace part of the articles´ names
  • cut off the articles´ names at a certain length
  • add edit data (size, author, last edited by, date of last change, ..)
  • add access date (frequency, date of last access)
  • add the articles´ contents or parts of it

Furthermore you can add a heading if there are some articles to display.

And you can define an alternate text which will be shown if there are no articles to display.


resultsheader

Purpose: output a headline if there is at least one article to display.

Syntax: resultsheader=some wiki text

Note: The symbol %PAGES% will be replaced by the number of pages found.

Example:

<DPL>
   category=Africa
   mode=userformat
   resultsheader=There are %PAGES% pages on Africa.
</DPL>

With "mode=userformat" we get complete control over the output. We do not specify "listseparators=" - so nothing will be displayed except the results header. The only thing we will get is a message about the existing number of articles.

noresultsheader

Purpose: output a headline if there is no article to display (empty result).

Syntax: noresultsheader=some wiki text

Note:

Setting noresultsheader to the empty string ("noresultsheader=") will suppress the warning message from DPL" which is normally issued if no articles were found.

shownamespace

Purpose:

To 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 if you want to avoid namespaces to be shown in the output.

Syntax:

shownamespace=false

Example:

<DPL>
  category      = Africa
  namespace     = Talk
  shownamespace = false
</DPL>

This list will output all Talk pages in [[Category:Africa]], listed without the Talk: prepended to page names.

titlemaxlength

Purpose:

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:

Same syntax as the count parameter.


addpagecounter

Purpose:

Shows number of times the page has been viewed according to the definition of the 'page_counter' field on Page_table.

Example:

<DPL>
  category       = Africa
  ordermethod    = counter
  order          = descending
  addpagecounter = true
  counter        = 5
</DPL>

This will show the 5 most popular articles about Africa.

Note: in 'mode=userformat' the access counter can also be referenced as a built-in variable.


addpagesize

Purpose:

Shows the size of the page.

Example:

<DPL>
  category       = Africa
  ordermethod    = size
  order          = descending
  addpagesize    = true
  counter        = 5
</DPL>

This will show the 5 biggest articles about Africa.

Note: in 'mode=userformat' the size can also be referenced as a built-in variable.

adduser

Requires ordermethod=[...,]firstedit or ordermethod=[...,]lastedit. ([...,] means complex ordermethods with extra param.)

Purpose:

If firstedit (resp. lastedit), 'adduser=true' shows the date of the the first revision/creation (resp. last revision) of the page.

Example:

adduser=true

If omitted, the default is false.

Example:

<DPL>
  category    = Africa
  ordermethod = lastedit
  adduser     = true
</DPL>

This will output a list of pages belonging to [[Category:Africa]], prepending each result with the author of the last revision.

Note: in 'mode=userformat' the user can also be referenced as a built-in variable.


addpagetoucheddate

Requires ordermethod=[...,]pagetouched or ordermethod=[...,]title. ([...,] means complex ordermethods with extra param before are allowed.)

Purpose:

Shows date/time of last change to the page according to the definition of the 'page_touched' field on Page_table.

Example:

addpagetoucheddate=true

If omitted, the default is false.

Example:

<DPL>
  category=Africa
  ordermethod=pagetouched
  addpagetoucheddate=true
</DPL>

This list will output a list of pages belonging to [[Category:Africa]], prepending each result with the date of last change (formatted according to your local mediawiki date display preferences or the user's preferences if logged in).

Note: in 'mode=userformat' this date can also be referenced as a built-in variable.

addeditdate

Requires ordermethod=[...,]firstedit or ordermethod=[...,]lastedit. ([...,] means complex ordermethods with extra param before firstedit|lastedit are allowed.)

Conflicts with other "add*date" (addpagetoucheddate, etc.) parameters.

Purpose:

If firstedit (resp. lastedit), 'addeditdate=true' shows the date of the first revision/creation (resp. last revision) of the page.

Example:

addeditdate=true

If omitted, the default is false.

Example:

<DPL>
  category=Africa
  ordermethod=lastedit
  addeditdate=true
</DPL>

This list will output a list of pages belonging to [[Category:Africa]], prepending each result with the date of last revision (formatted according to your local mediawiki date display preferences or the user's preferences if logged in).

Note: in 'mode=userformat' this date can also be referenced as a built-in variable.

addfirstcategorydate

Requires to include one and one category only, with 'category' parameter.

Conflicts with other "add*date" (addeditdate, etc.) parameters to avoid confusion.

Purpose:

Shows the date/time the article got added to the first listed include category.

Example:

addfirstcategorydate=true

If omitted, the default is false.

Example:

<DPL>
  category             = Africa
  addfirstcategorydate = true
</DPL>

This list will output a list of pages belonging to [[Category:Africa]], prepending each result with the time and date (formatted according to your local mediawiki date display preferences or the user preferences if user logged in).

Note: in 'mode=userformat' this date can also be referenced as a built-in variable.


includepage

Purpose: include pages (whole content) or include certain sections of articles.

Requires lst.php from mw:Extension:Labeled_Section_Transclusion Labeled Section Transclusion

Syntax:

  • To include the whole page, use a wildcard:
includepage=*
you can use includemaxlength=[n] to restrict the included text to a portion of the article.
includepage=sec1,sec2,...
  • To include sections (chapters) by a reference to their headings: use the heading name with a "#" as prefix. This will include text from the first occurrence of the heading 'heading1' (resp. 'heading2') until the next heading of the same or lower level. (Refer to Transcluding visual headings.). Note that the text comparison is case insensitive. Add a limit and an optional link text in square brackets to delimit the size of the included text portion to a certain number of characters. If text is cut off a link will appear which points directly to the chapter which was included. Using "0" as limit will only show the link (if the correpsonding chapter in the article is not empty). When truncating included text portions care is taken not to spoil wiki syntax (i.e. maintain a symmetry of brackets and braces). Therefore the size of the included text can deviate from what you specified.
includepage = #heading1,#heading2[limit linktext],....

linktext can be

plain text
then this text will be used as a link
text starting with "img="
then the link will appear as an image link (you must provide the image in a suitable size; no scaling will happen); note that image linking only works if there is another mediawiki extension installed (LinkedImages).
a text containing %SECTION%";
this symbol will be replaced by "article#heading". It is up to you to create a link from this text using normal wiki syntax if you wish.
  • To include variables which are used in a template call, specify the original template name within single curly braces and add a suffix; the template name including the suffix will be called instead of the original template and the result will contain just the output of your alternate template:
includepage = {template1}suffix1,{template1}suffix2,{template2}suffix3,....
  • You can combine all of the above variants:
includepage = sec1,#heading1,{template1}ext1,....
  • To include nothing from the page (no inclusion), leave blank (this is default):
includepage=

Example: includepage = foo,#bar[200 ..more..],#bang[0 img=my.gif],{boo}.dpl

This will include

  • a text portion which is marked by special tags named "foo"
  • the contents of a chapter named "bar"; only the first 200 characters of wiki text will be shown; if the chapter is larger than that, a link with the text "..more.." will point to the source
  • an image link based on "my.gif" to the chapter "bang" in the article - if there is such a chapter and it is not empty
  • the output of template "boo.dpl" being called with the same parameters that were used to call template "boo" in the original page.

includemaxlength

Purpose:

Delimit the size of an included article to a maximum of [n] characters of wiki source text or less. Care is taken to respect pairs of braces and brackets as far as possible. Otherwise we might confuse the result by half-cut syntax elements of transcluded sections. Therefore the output might be shorter or even larger than [n] characters.

Syntax:

includemaxlength=[n]

Note: this parameter is only used in combination with includepage=*; truncation of included chapter contents is specified by adding a limit in sqauare brackets within the 'includepage=' statement.

Usage of DPL2: controlling output format

  • You can select one of several default formats or define your own format("mode")
  • output can be grouped in columns or rows

mode

Purpose:

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. See inlinetext for more info.
  • category — outputs resulting articles in a way category-pages are shown (you have to use ordermethod=title|category,title|user,title with 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.

Example:

<DPL>
  category=Africa
  mode=ordered
</DPL>

This list will output pages that have [[Category:Africa]] shown in an <ol>...</ol> list.

Related extension variable(s): $wgDPL2CategoryStyleListCutoff.

inlinetext

This replaced 'inlinesymbol'.

Purpose:

To define the inline text used in mode=inline.

Syntax:

inlinetext=wikitext, with wikitext some wiki text default is '&nbsp;-&nbsp;' 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 '&nbsp;', or use 'nowiki' tags like in '<nowiki> - </nowiki>' which has same effect as '&nbsp;-&nbsp;'.

Example:

<DPL>
  category=Africa
  mode=inline
  inlinetext= &nbsp; &bull; &nbsp;
</DPL>

This list will output pages that have [[Category:Africa]] shown like Item1 • Item2 • Item3 • ...


listseparators

Purpose: customize the output format completely. Requires "mode=userformat". Uses variable references like %PAGE% to describe the output format. See also the secseparators parameter.

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)
  •  %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. lasteditr; requires addeditdate=true or similar
  •  %USER% = the user who changed the document last; requires adduser=true

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%]],,
</DPL>

Note that a bullet point list in wiki syntax is derfined 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

Purpose: customize the output format of included sections. Can be used with standard output modes and with mode=userformat.

Syntax:

secseparators=Startall,Start,End,Endall

'Startall', 'Start', 'End' and 'Endall' are HTML strings or wiki tags used to separate the transcluded sections in the output (see 'includepage=name1,name2,...').
'Startall' and 'Endall' define an outer frame for sections of a page;
'Start' and 'End' build an inner frame for each section.

The symbol %SECTION% can be used to refer to the section found (works only for chapter headings).

Example:

<DPL>
  linksto        = Africa
  mode           = userformat
  listseparators = {|¶!pages found¶!fruit¶!color,¶|-¶|[[%PAGE%]],,¶|}
  includepage    = #fruit,#color
  secseparators  = ,¶|,,
</DPL>

We use the listseparators to define a table with three columns and put a link to the article in the first column of each row. We use the secseparators to add more columns for each section we find. 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 we make sure that the wiki parser will understand them. Note that if an article does not contain a section named "fruit" you will see an empty cell in your table.

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 we truncate them to 50 or 100 characters. A link which refers directly to those chapters will be generated automatically if needed.

headingmode

Purpose:

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

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>



minoredits

Purpose:

Controls the inclusion or exlusion of minor edits in lists.

Requires: ordermethod=[...]firstedit|lastedit

Example:

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

Purpose: 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/>.

Not applicable to 'mode=category' or mode='inline' (with no <code><BR/> in inlinetext).

Syntax: <code>listattr= attribute1="val1" attribute2="val2" ...

Examples:

Input (HTML) 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

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

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

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

Purpose:

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

Purpose:

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

Purpose:

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.

Usage of DPL2: other parameters

debug

Purpose:

Sets debugging level.

Syntax:

debug=n, where n is one of:

  • 0 — silent mode, shows nothing
  • 1 — quiet mode, shows (fatal) errors
  • 2 — default mode, like 1 + shows warnings; — (default)
  • 3 — verbose mode, like 2 + shows SQL query.

If you use debug param but not in first position in the DPL element, the new debug settings are not applied before all previous parameters have been parsed and checked. This will generate a warning for debug=2 and above.

Example:

<DPL>
  namespace=Media
  debug=0
  namespace=Special
</DPL>

This list will output the error for the first namespace: Media is not a valid namespace value (pseudo-namespace). Assuming you haven't changed the default debug value (2), you will also get a warning: debug=1 is not input first (before namespace=Media). So it did not apply to namespace=Media but only to what's after. Indeed, you won't get the warning for the second namespace (Special) since debug=0 changed debug settings to silent mode.

DPL debug messages are translatable in DynamicPageList2.i18n.php. See also DynamicPageList2#Internationalization.

Server-Wide Configuration

Extension options

You can set the following global variables, preferably in your LocalSettings.php (after including DynamicPageList2.php) or in DynamicPageList2.php directly, to configure and restrict the usage of the DPL extension server-wide.

$wgDPL2MaxCategoryCount Maximum number of categories specified in a DPL with 'category' or 'notcategory' parameters = Maximum number of categories allowed in the SQL-query. To prevent too complex queries.

$wgDPL2AllowUnlimitedCategories Allows unlimited categories in the query. ($wgDPLMaxCategoryCount will be ignored)

$wgDPL2MinCategoryCount Minimum number of categories specified in a DPL with 'category' or 'notcategory' parameters = Minimum number of categories needed in the SQL-query for setting limits. To prevent output of a gigantic list.

$wgDPL2MaxResultCount Maximum number of results to allow.

$wgDPL2AllowUnlimitedResults Allow unlimited results to be shown. ($wgDPLMaxResultCount will be ignored)

$wgDPL2CategoryStyleListCutoff Max length to format a list of articles chunked by letter as bullet list, if list bigger, columnar format user (same as cutoff arg for CategoryPage::formatList()). Used by mode=category.

$wgDPL2Options Gives control on the extension parameters (see Usage of DynamicPageList2 for the list). The best way to get familiar with it is to look at its declaration in DynamicPageList2.php (beginning). Use it at your own risk. Anyway, below are some usage examples:

  • Change default parameter values: $wgDPL2Options['param']['default']='val'. Make sure val is a valid param value.
Example: $wgDPL2Options['shownamespace']['default']='false' to change the shownamespace default value to 'false'.
  • Restrict parameter options: if the parameter param has options option0, ... , optionN (according to the definition of $wgDPL2Options in DynamicPageList2.php), $wgDPL2Options['param'] = array('option0',...,'optionn-1','optionn+1',...,'optionN') will disable optionn for users (not allowed). If you disable an option currently defined as default parameter value, make sure you change the default value to another option as well (see previous item).

Internationalization

Since MediaWiki 1.7.1, extension messages are translatable (more info). To use this feature and translate the DPL messages into your favorite language, have a look at DynamicPageList2.i18n.php. All you have to do is to create in this file a $wgDPL2Messages['lang'] array where 'lang' is your language code, and use $wgDPL2Messages['en'] as a model. Replace values with appropriate translations.


Bug report

Before reporting bugs, view old ones on the discussion page. For more recent ones, make an advanced search on MediaZilla. Select Product: MediaWiki extensions, and Component: DynamicPageList2.

Report new bugs on MediaZilla. Select Product: MediaWiki extensions, and Component: DynamicPageList2.

Note: if you have installed DPL2 on a public site, you are invited to add it to the list of sites using DPL2. Thank you.

Feature request

View old requests and request features on the discussion page.

ToDo

See Talk:DynamicPageList2#General_ToDo_list.


Improvements and Changes

Release 0.9

Availability of DPL2 also as a parser function; change in behaviour regarding parameter expansion; please read the overview chapter on the general syntax for calling DPL2

New features:

  • mode=userformat
  • listseparators
  • titlematch, nottitlematch
  • notlinksto
  • includemaxlength

... and somne others

Release 0.8.1

Feature:

  • 'includepage=#heading' option (page transclusion of specific headings)

Release 0.8.0

Features:

  • 'includepage' option (page transclusion, labeled section transclusion)
  • 'secseparators' option to separate transcluded sections with custom HTML code

Security fix:

  • SQL injection
  • A few XSS vulnerabilities

Release 0.7.8

Features:

  • addpagecounter feature (adds # times page has been viewed)
  • 'ordermethod=counter' feature: orders pages by #times page has been viewed
  • Date output according to time zone offset in user's preferences
  • Improved generation of links.

Bugfixes:

  • 7773: Wrong user name with 'adduser=true'
  • 7847: Use of 'addfirstcategorydate=true' triggers SQL error.
  • 7772 Date not formatting (user time correction was ignored).
  • Incompatible encodings in mysql string concat when generating sortkeys (ordermethod=category,sortkey)

Older releases