View source for Extension:DynamicPageList (third-party)/pl

<languages/>
{{Note|1=<span lang="en" dir="ltr" class="mw-content-ltr">This is a third-party extension, not to be confused with the {{ll|Extension:DynamicPageList (Wikimedia)|DynamicPageList}} used on Wikimedia sites or {{ll|Extension:DynamicPageList3}}.</span>
|2=reminder
}}
{{archival requested|T353927}}
{{Incompatible|version=1.35|alternative={{ll|Extension:DynamicPageList3}}}}
{{Extension
|name      = DynamicPageList (third party)
|status    = unmaintained
|type1     = tag
|type2     = parser function
|author    = * [[w:User:IlyaHaykinson|IlyaHaykinson]],
* [[w:de:Benutzer:Unendlich~dewiki|Unendlich~dewiki]],
* [[meta:User:Dangerman|Dangerville]],
* '''[[User:Algorithmix|Algorithmix]]''',
* [[User:Theaitetos|Theaitetos]]
|image     =
|version   = Continuous updates
|update    = 
|mediawiki = '''<big>1.32.x - 1.34.x only</big>'''
|download  = {{WikimediaDownload|DynamicPageList|phab=EDPL}}
|needs-updatephp = No
|readme    = 
|changelog =
|description = <span lang="en" dir="ltr" class="mw-content-ltr">Allows to '''create lists''' of other articles based on their ''category, namespace, title, references'' or ''template usage'' and '''include contents''' or arguments of template calls of those articles into your page.</span>
|parameters= <span lang="en" dir="ltr" class="mw-content-ltr">see description</span>
|license   = GPL-2.0-or-later
|rights    = 
|phabricator = dynamicpagelist_third-party
|example   = [https://followthescore.org/dpldemo/index.php/Extension_DPL various sample reports]
}}
<span lang="en" dir="ltr" class="mw-content-ltr">The '''DynamicPageList (third-party)''' extension is a reporting tool for MediaWiki, listing category members and intersections with various formats and details.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For full documentation, see the [https://followthescore.org/dpldemo/index.php?title=Extension_DPL full original manual] or [https://web.archive.org/web/20161105221036/http://semeb.com/dpldemo/DPL:Manual manual] (German Manual [http://www.wiki-aventurica.de/wiki/Hilfe:Dynamic_Page_List Hilfe:DynamicPageList]).</span>

<span lang="en" dir="ltr" class="mw-content-ltr">In its most basic form, DPL displays a list of pages in one or more categories.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Selections may also be based on factors such as author, namespace, date, name pattern, usage of templates or references to other articles.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Output takes a variety of forms, some of which incorporate elements of selected articles.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">This extension is invoked with the parser function <code>{{#dpl: .... }}</code> or parser tag {{tag|DPL|open}}.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">A [[Special:MyLanguage/Extension:DynamicPageList (Wikimedia)|Wikimedia]]-compatible implementation of certain features can be invoked with {{tag|DynamicPageList|open}}.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">DPL can result in computationally-expensive database queries.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For best performance, use the optional parameters [https://followthescore.org/dpldemo/index.php?title=DPL:Manual_-_DPL_parameters:_Other_parameters#allowcachedresults allowcachedresults] and/or [https://followthescore.org/dpldemo/index.php?title=DPL:Manual_-_DPL_parameters:_Other_parameters#dplcache dplcache] where possible.</span>

<span id="Installation"></span>
== Instalacja ==
{{Note|1=LocalSettings.php must '''not''' include [[Extension:Intersection|Wikimedia's version of DPL]] (Intersection).}}

{{ExtensionInstall
|DynamicPageList
|repo-name=DynamicPageList
|custom-steps=* <span lang="en" dir="ltr" class="mw-content-ltr">[[#Configuration|Configure as required]] if necessary</span>
}}

{{note|1=<span lang="en" dir="ltr" class="mw-content-ltr">During the installation process a template is automatically created.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If you are getting error messages about how user in the "users" group does not have permissions, it probably has something to do with the installer "user" does not have permission to create a template.</span> <span lang="en" dir="ltr" class="mw-content-ltr">In order to install the extension, you may need to temporarily open up page creation permissions and then turn them off after the extension is installed.</span>}}

<span id="Configuration"></span>
== Konfiguracja ==
<span lang="en" dir="ltr" class="mw-content-ltr">DPL configuration settings and their default values, '''[https://followthescore.org/dpldemo/index.php?title=DPL:Manual_-_Source_and_Installation#Server-Wide_Configuration:_Extension_options from the manual]''':</span><!--We may as well try to keep these in alphabetical order-->

{|class = "wikitable"
! Ustawienia
! Domyślnie
! Opis
|-
|<code>ExtDynamicPageList::$allowedNamespaces</code> || <code>null</code>
| <span lang="en" dir="ltr" class="mw-content-ltr">To be initialized at first use of DPL, array of all namespaces except Media and Special, because we cannot use the DB for these to generate dynamic page lists.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Cannot be customized.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Use {{phpi|ExtDynamicPageList::$options['namespace']}} or {{phpi|ExtDynamicPageList::$options['notnamespace']}} for customization.</span>
|-
|<code>ExtDynamicPageList::$allowUnlimitedCategories</code> || <code>true</code> || <span lang="en" dir="ltr" class="mw-content-ltr">Allow unlimited categories in the Query</span>
|-
|<code>ExtDynamicPageList::$allowUnlimitedResults</code> || <code>false</code> || <span lang="en" dir="ltr" class="mw-content-ltr">Allow unlimited results to be shown</span>
|-
|<code>ExtDynamicPageList::$behavingLikeIntersection</code> || <code>false</code> || <span lang="en" dir="ltr" class="mw-content-ltr">Changes certain default values to comply with Extension:Intersection</span>
|-
|<code>ExtDynamicPageList::$categoryStyleListCutoff</code> || 6
| <span lang="en" dir="ltr" class="mw-content-ltr">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 {{phpi|CategoryPage::formatList()}})</span>
|-
|<code>ExtDynamicPageList::$fixedCategories</code> || <code>empty array</code> || An array which holds categories to which the page containing the DPL query shall be assigned although reset_all|categories has been used
|-
|<code>ExtDynamicPageList::$functionalRichness</code> || 0
| <span lang="en" dir="ltr" class="mw-content-ltr">The amount of functionality of DPL that is accesible for the user; to be set by DynamicPageList.php and DynamicPageListMigration.php see the fixcategory command</span>
|-
|<code>ExtDynamicPageList::$maxCategoryCount</code> || 4 || <span lang="en" dir="ltr" class="mw-content-ltr">Maximum number of categories allowed in the Query</span> 
|-
|<code>ExtDynamicPageList::$maxResultCount</code> || 500 || <span lang="en" dir="ltr" class="mw-content-ltr">Maximum number of results to allow</span>
|-
|<code>ExtDynamicPageList::$minCategoryCount</code> || 0 || <span lang="en" dir="ltr" class="mw-content-ltr">Minimum number of categories needed in the Query</span>
|-
|<code>ExtDynamicPageList::$options</code> || ''no options'' || <span lang="en" dir="ltr" class="mw-content-ltr">If you add a line like the following to your LocalSettings.php, DPL will only run from protected pages: <code>ExtDynamicPageList::$options['RunFromProtectedPagesOnly'] = "<small><i>Extension DPL (warning): current configuration allows execution from protected pages only.</i></small>";</code>.</span> There is a whole bunch of other options too; see [https://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/DynamicPageList/DPLSetup.php?view=markup DPLSetup.php].
|-
|<code>ExtDynamicPageList::$respectParserCache</code> || <code>false</code> for &lt;dpl&gt; but <code>true</code> for &lt;DynamicPageList&gt;. || If set to 'true' DPL will no longer behave dynamically because its output is taken from the ParserCache. In other words, false = make page dynamic ; true = execute only when parser cache is refreshed
|-
|}

<span lang="en" dir="ltr" class="mw-content-ltr">These are all public static variables.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">The global variable {{manual|$wgNonincludableNamespaces}} is also respected by DPL.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It will prevent the contents of the listed namespaces from appearing in DPL's output.</span>

{{note|1=<code>$maxResultCount</code> is a LIMIT ''on the SQL query itself''. Some DPL query parameters like <code>includematch</code> are applied ''after'' the SQL query, however, so results here may easily be misleading.}}

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Functional richness ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">DynamicPageList has many features; some are expensive, or dangerous in the wrong hands.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is important to choose an appropriate level of functionality for your wiki.</span>

* <code>ExtDynamicPageList::setFunctionalRichness(0)</code> - <span lang="en" dir="ltr" class="mw-content-ltr">equivalent to Wikimedia's DPL</span>
* <code>ExtDynamicPageList::setFunctionalRichness(1)</code> - <span lang="en" dir="ltr" class="mw-content-ltr">adds additional formatting parameters</span>
* <code>ExtDynamicPageList::setFunctionalRichness(2)</code> - <span lang="en" dir="ltr" class="mw-content-ltr">adds performance equivalent features for templates and pagelinks</span>
* <code>ExtDynamicPageList::setFunctionalRichness(3)</code> - allows more-expensive page inclusion features and regular expression queries; expect to use the [https://followthescore.org/dpldemo/index.php?title=DPL:Manual_-_DPL_parameters:_Other_parameters#dplcache dplcache] parameter
* <code>ExtDynamicPageList::setFunctionalRichness(4)</code> - <span lang="en" dir="ltr" class="mw-content-ltr">permits exotic and potentially dangerous batch update and delete operations; not recommended for public websites</span>

{{Note|1=The Functional Richness grouping described above is a built-in suggestion; it can easily be adapted to your own preferences within "DPLSetup.php".}}

<span id="Usage"></span>
== Użycie ==

<div lang="en" dir="ltr" class="mw-content-ltr">
===Extended DPL functionality===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
DPL is invoked by using the parser function <code>{{#dpl: .... }}</code>, or the parser extension tag {{tag|DPL}}.
</div>

:''<span lang="en" dir="ltr" class="mw-content-ltr">See:</span> [https://followthescore.org/dpldemo/index.php?title=DPL:Manual_-_General_Usage_and_Invocation_Syntax Manual - General Usage and Invocation Syntax] and [https://followthescore.org/dpldemo/index.php?title=DPL:Manual_-_DPL_parameters:_Criteria_for_page_selection Manual - '''DPL parameters''']''

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Backwards-compatible functionality ===
</div>
Functionality compatible with Wikimedia's DPL extension can be invoked with <syntaxhighlight lang=html inline><DynamicPageList> .... </DynamicPageList></syntaxhighlight>.
:''See: {{ll|Extension:DynamicPageList (Wikimedia)#Use|Extension:DynamicPageList (Wikimedia)#Use}}''

<div lang="en" dir="ltr" class="mw-content-ltr">
==Overview==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Assume you have written some articles about ''countries''.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Typically these articles will have three things in common:</span>

* They will belong to a common category
* They will have a similar chapter structure, i.e. they will contain paragraphs named 'Religion' or 'History'
* They will use a template which is used to present highly structured short data items ('Capital', 'Inhabitants', ..) in a nice way (e.g. as a wikitable)

<div lang="en" dir="ltr" class="mw-content-ltr">
===DPL generates reports on articles===
</div>
Let us assume that there is an article on Islam.
You want to give some information about the spreading of this religion over various countries.
But you do not want to create redundancy by repeating information that was already given in the articles on the countries.

In our scenario the natural approach with DPL would be to generate a list of 'countries' (=category) where Islam plays a role (i.e. restrict your selection to articles of category 'Country' which contain a link to 'Islam').
Typically you would want to include part of the text chapter on 'Religion' from each of the relevant countries.
You might also want to give the number of inhabitants for each country.
The output should be shown as an alphabetically ordered table.
It would be nice if the user could easily sort the table by inhabitants or some other criteria.

With DPL you can ..

* generate a list of all those articles (or a random sample)
* show metadata of the articles (popularity, date of last update, ..)
* show one or more chapters of the articles ('transclude' content)
* show parameter values which are passed to the common template
* order articles appropriately
* present the result in a sortable table (e.g.)
* use multi column output

<div lang="en" dir="ltr" class="mw-content-ltr">
===Which steps are necessary?===
</div>
'''Find the articles you want to list:'''

* select by a logical combination (AND,OR,NOT) of categories
* specify a range for the number of categories the article must be assigned to
* select by a logical combination (AND,OR,NOT) of namespaces
* define a pattern which must match the article's name
* name a page to which the article must or must not link
* name a template which the article must or must not use
* name a text pattern which must occur within external links from a page
* exclude or include redirections
* restrict your search to stable pages or quality pages ("flagged revisions")
* use other criteria for selection like author, date of last change etc.
* define regular expressions to match the contents of pages you want to include

'''Order the result list of articles according to'''

* name
* date of last change
* popularity
* user who changed them last
* size
* restrict the output to the first n articles or to a random sample
* use descending or ascending sequence

'''Define attributes you want to see'''

* article name
* article namespace
* article size
* date of last change
* date of last access
* user who changed them last

'''Define contents you want to show'''

* whole article
* contents of certain chapters (identified by headings)
* text portions (defined by special marker tags in the article)
* values of template calls
* substitute the original template by a different one and show the output of that template

'''Define the output format'''

* specify headline and footer for your report
* use ordered list, unordered list
* use tables, sorted tables (using javascript)
* format table fields individually by applying templates to their content
* use category style listing
* create "tag clouds" by varying output text size depending on popularity of pages 
* multi column output
* truncate title or contents to a certain maximum length
* add a link to the article or to one or more of its chapters

<div lang="en" dir="ltr" class="mw-content-ltr">
===DPL generates reports on categories===
</div>
Apart from producing a list of pages which match certain criteria, DPL can also create a list of categories a selected set of pages belongs to.
This can be useful to get an idea of the semantic scope of a group of pages (which can be defined by some arbitrary criteria).
One of the more useful applications would be question like: "To which categories do the pages belong which contain a reference to the current page?"

<div lang="en" dir="ltr" class="mw-content-ltr">
===DPL can be used for bulk editing===
</div>
Sometimes you want to perform a similar editing task on many articles (like adding a template at the beginning of the text).
DPL has a feature which allows you to update other articles based on regular expressions.
This feature is experimental and can be disabled in the DPL config file.

<div lang="en" dir="ltr" class="mw-content-ltr">
===DPL interacts with other extensions===
</div>
There is a special mechanism which allows you to call your own extension inside the result loop of  a DPL query.
This opens doors for assembling new 'applications' without having to program on php level.
For example you can create menu trees for [[Extension:Treeview]], you can generate nice bar graphs or pie charts using DPL together with ''Ploticus'', you can call 'gallery' or whatever you want...


<div lang="en" dir="ltr" class="mw-content-ltr">
===DPL is a platform for building other applications===
</div>
The power of DPL makes it possible to create applications on wiki template level which would normally require PHP programming.
One example of this is a light-weight "semantic wiki" approach.
See the [https://followthescore.org/dpldemo DPL demo page] for details.

<div lang="en" dir="ltr" class="mw-content-ltr">
===DPL and performance===
</div>
With a few lines of DPL code it is possible to create huge output and CPU load (think of a DPL query which tries to include the contents of all articles in your mediawiki ;-)).
Normally this is not a problem because users who write DPL queries have some level of expertise.
If you are afraid, however, you can restrict the execution of DPL queries to ''protected articles''.

Apart from that the general performance of DPL on medium-size wikis is quite acceptable (see the performance tests on the dpldemo website).
Use of [https://followthescore.org/dpldemo/index.php?title=DPL:Manual_-_DPL_parameters:_Other_parameters#allowcachedresults allowcachedresults] and/or [https://followthescore.org/dpldemo/index.php?title=DPL:Manual_-_DPL_parameters:_Other_parameters#dplcache dplcache] where possible can improve performance.

<span id="See_also"></span>
==Zobacz też==

<div lang="en" dir="ltr" class="mw-content-ltr">
===Further reading===
</div>
DPL can do much more than we can explain here.
The complete [https://followthescore.org/dpldemo/index.php?title=Extension_DPL full original manual] or  [https://web.archive.org/web/20161105221036/http://semeb.com/dpldemo/DPL:Manual manual] (German Manual [http://www.wiki-aventurica.de/wiki/Hilfe:Dynamic_Page_List Hilfe:DynamicPageList]) describes more.

<div lang="en" dir="ltr" class="mw-content-ltr">
===Related extensions===
</div>
* {{ll|Manual:Managing data in MediaWiki}} – An overview and comparison.
* {{ll|Extension:Semantic MediaWiki}} turns links and data in wiki pages into queryable information
* {{ll|Extension:NukeDPL}} deletes pages based on DynamicPageList; also useful for testing different DPL settings without actually deleting the pages

[[Category:Category extensions{{#translation:}}]]
[[Category:List extensions{{#translation:}}]]
[[Category:Namespace extensions{{#translation:}}]]
[[Category:Special page extensions{{#translation:}}]]
[[Category:Table extensions{{#translation:}}]]
[[Category:Page content extensions{{#translation:}}]]
[[Category:Tag cloud extensions{{#translation:}}]] <!-- has tag cloud display option -->
[[Category:Category intersection extensions{{#translation:}}]]