Main Page: Difference between revisions

From DynamicPageList3 Manual
Content added Content deleted
imported>FrozenPlum
(Add link to the changelog)
(Create main page)
Line 1: Line 1:
__NOTOC__
{{DPL manual|section=|subsection=}}
Welcome to your new wiki! You may find the following link useful: [[mw:Help:Contents|Help:Contents]] on mediawiki.org.

'''DynamicPageList3''' (DPL3) is a powerful MediaWiki [[meta:extension|extension]] that generate lists of pages, page properties (metadata), and/or template parameter values, for display in other articles. DPL3 lists are automatically updated whenever the data it fetches changes and the cache is cleared or expires. The output can be formatted to create a range of displays from lists (the default format), to in-line paragraph text/content, tables, galleries, navigation, and many other possibilities.

As a basic example, DPL3 can be used to insert in a wiki page, an always-current list of all pages of a particular [[mw:Help:category|category]]. The data displayed may be selected and sorted based on factors like author, namespace, date, name pattern, usage of templates, or references to other articles, with a variety of custom formatting.


==Installation==
* '''For [[meta:Miraheze|Miraheze]] ([[mw:Project:WikiFarm|WikiFarm]]) users''', the DPL3 MediaWiki extension is already installed, it simply needs to be enabled by a user with the appropriate privileges in [[Meta:ManageWiki]].

* '''Other users''' should see the MediaWiki software [[mw:Extension:DynamicPageList3#Installation|DynamicPageList3 Extension installation]] page section for information on how to install the extension in MediaWiki.


== Configuration ==

DPL3 has a variety of configuration settings that can be used, as well as a number of defaults that are important to note. Settings should be defined before enabling the extension.

* '''For [[meta:Miraheze|Miraheze]] ([[mw:Project:WikiFarm|WikiFarm]]) users''', the DPL3 MediaWiki extension is already configured.

* '''Other users''' should see the MediaWiki software [[mw:Extension:DynamicPageList3#Configuration|DynamicPageList3 Extension configuration]] page section for a list of configuration options.


===Limiting results and resource consumption===

To prevent a DPL3 query from returning huge output (or consuming too many resources such as CPU or causing database load). The following configuration variables are noteworthy:

{| class="wikitable"
!Setting
!Default
!Description
|-
|<syntaxhighlight lang="php" inline>$wgDplSettings['maxQueryTime']</syntaxhighlight>
|10000
|Limits the time amount (in milliseconds) allowed for database queries.
|-
|<syntaxhighlight lang="php" inline>$wgDplSettings['maxCategoryCount']</syntaxhighlight>
|4
|Limits the number of categories allowed in queries ('''default''' is 4).
|-
|<syntaxhighlight lang="php" inline>$wgDplSettings['maxResultCount']</syntaxhighlight>
|500
|Limits the number of results returned in a query ('''default''' is 500).
|-
|<syntaxhighlight lang="php" inline>$wgDplSettings['runFromProtectedPagesOnly']</syntaxhighlight>
|<syntaxhighlight lang="php" inline>false</syntaxhighlight>
|Causes DPL3 to only run from protected pages (if set to ''true''), which can aid administrators having problems with malicious user activity resulting in computationally expensive queries.
|}

'''Note:''' For [[meta:Miraheze|Miraheze]] users, these settings are set by Miraheze.


=== Functional richness ===

DynamicPageList3 has different levels of functional richness, which can be configured as needed. Higher levels of functionality should be considered carefully and used sparingly.

'''Note:''' For [[meta:Miraheze|Miraheze]] users, these settings are set by Miraheze.

{| class="wikitable"
!Setting
!Value
!Description
|-
|<syntaxhighlight lang="php" inline>$wgDplSettings['functionalRichness']</syntaxhighlight>
|<syntaxhighlight lang="php" inline>0</syntaxhighlight>
|Provides functionality equivalent to Wikimedia's [[mw:Extension:DynamicPageList (Wikimedia)|DynamicPageList]] (also known as Intersection).
|-
|<syntaxhighlight lang="php" inline>$wgDplSettings['functionalRichness']</syntaxhighlight>
|<syntaxhighlight lang="php" inline>1</syntaxhighlight>
|Adds additional parameters for formatting.
|-
|<syntaxhighlight lang="php" inline>$wgDplSettings['functionalRichness']</syntaxhighlight>
|<syntaxhighlight lang="php" inline>2</syntaxhighlight>
|Adds features (performance equivalent) for [[mw:Manual:Pagelinks_table|pagelinks]] and templates.
|-
|<syntaxhighlight lang="php" inline>$wgDplSettings['functionalRichness']</syntaxhighlight>
|<syntaxhighlight lang="php" inline>3</syntaxhighlight>
|Allows more-expensive inclusion features, such as queries on revision level, and regular expression queries ('''default''').
|-
|<syntaxhighlight lang="php" inline>$wgDplSettings['functionalRichness']</syntaxhighlight>
|<syntaxhighlight lang="php" inline>4</syntaxhighlight>
|Permits potentially dangerous and exotic batch delete and update operations; not recommended for public websites. Also includes extra debugging parameters for development and testing.
|}

{{note|'''Important:''' Some levels of functional richness can cause high database or CPU load, and should be carefully considered.|warn}}

===Other===
{| class="wikitable"
!Setting
!Default
!Description
|-
| <syntaxhighlight lang="php" inline>$wgDplSettings['allowedNamespaces']</syntaxhighlight>
| <syntaxhighlight lang="php" inline>null</syntaxhighlight>
| All existing namespaces are used by default when DPL3 is initialized. An array of namespace constants can be provided to restrict DPL3 to only working in the specified namespaces.
|-
| <syntaxhighlight lang="php" inline>$wgDplSettings['allowUnlimitedCategories']</syntaxhighlight>
| <syntaxhighlight lang="php" inline>false</syntaxhighlight>
| Ignores 'maxCategoryCount' and allows unlimited categories, if set to <code>true</code>. Note that large numbers of categories in queries can cause servers to slow or crash.
|-
| <syntaxhighlight lang="php" inline>$wgDplSettings['allowUnlimitedResults']</syntaxhighlight>
| <syntaxhighlight lang="php" inline>false</syntaxhighlight>
| Ignores 'maxResultCount' and allows unlimited results, if set to <code>true</code>. Note that large sets of results may cause pages to slow or fail to load.
|-
| <syntaxhighlight lang="php" inline>$wgDplSettings['alwaysCacheResults']</syntaxhighlight>
| <syntaxhighlight lang="php" inline>false</syntaxhighlight>
| Ignores <code>'allowcachedresults'</code> and enables the parser cache, if set to <code>true</code>.
|-
| <syntaxhighlight lang="php" inline>$wgDplSettings['categoryStyleListCutoff']</syntaxhighlight>
| 6
| Maximum number of items permitted in a category list, additional are cut off.
|-
| <syntaxhighlight lang="php" inline>$wgDplSettings['handleSectionTag']</syntaxhighlight>
| <syntaxhighlight lang="php" inline>false</syntaxhighlight>
| Set this to have DPL3 handle <code>open</code> tags outside DPL parser tags.
|-
| <syntaxhighlight lang="php" inline>$wgDplSettings['minCategoryCount']</syntaxhighlight>
| 0
| Minimum number of categories permitted in DPL3 queries.
|-
| <syntaxhighlight lang="php" inline>$wgDplSettings['recursiveTagParse']</syntaxhighlight>
| <syntaxhighlight lang="php" inline>false</syntaxhighlight>
| Performs recursive parsing on <code>open</code> parser tags, converting tags and functions (for example, [[mw:Help:Magic words|magic words]] like <code><nowiki>{{PAGENAME}}</nowiki></code>). Though it may not work the same in all cases, this functions similarly to the <code><nowiki>{{#dpl}}</nowiki></code> DPL3 parser function (see [[#Other Modules|Other Modules]]).
|-
| <syntaxhighlight lang="php" inline>$wgDplSettings['queryCacheTime']</syntaxhighlight>
| 0
| Specifies the amount of time to cache a query for, the query cache then cannot be purged. Values between 30 and 600 are suggested.
|}

== Usage ==
The ''General use and invocation syntax'' page is essential to read, to understand the fundamentals of DPL3 use, it is not recommended to skip this section of the manual.
* [[General usage and invocation syntax|General usage and invocation syntax]]


== Primary DPL3 module ==
These sections contain documentation on DPL3's primary module. This is the DPL3 functionality used most often, and has a wide range of powerful coding options.
* [[Criteria for page selection|Criteria for page selection]]
* [[Controlling output format|Controlling output format]]
* [[Controlling output order|Controlling output order]]
* [[Controlling output volume|Controlling output volume]]
* [[Other parameters|Other parameters]]


== Other DPL3 modules ==
These sections detail some additional functions provided by the DPL3 extension.
* [[Dplchapter|<nowiki>{{#dplchapter: ... }}</nowiki>]]
* [[Dplvar|<nowiki>{{#dplvar: ... }}</nowiki>]]
* [[Dplreplace|<nowiki>{{#dplreplace: ... }}</nowiki>]]
* [[Dplnum|<nowiki>{{#dplnum: ... }}</nowiki>]]
* [[Dplmatrix|<nowiki>{{#dplmatrix: ... }}</nowiki>]]


== More information ==
* [[Compatibility|Compatibility with previous versions]]
* [[Bug reporting and feature requests|Bug reporting and feature requests]]
* [[Examples]] for a complete list of examples.
* For the legacy manual Table of Contents, see [[Parameter Quick Reference]].
* [https://github.com/Universal-Omega/DynamicPageList3/blob/master/CHANGELOG.md DPL3 Changelog on Github]

[[Category:Manual]]

Revision as of 23:13, 8 June 2023

Welcome to your new wiki! You may find the following link useful: Help:Contents on mediawiki.org.

Retrieved from "https://dpl3.wikitide.org/wiki/Main_Page?oldid=3"