 Release status: stable | |
|---|---|
| Implementation | Data extraction |
| Description | Provides dynamic page lists with configurable and extensible features tomodules and to other extensions |
| Author(s) | RV1971 (RV1971talk) |
| Latest version | 1.1.0 (2018-03-24) |
| MediaWiki | 1.30+ |
| PHP | 7.0+ |
| Database changes | No |
| License | GNU General Public License 3.0 or later |
| Download | Release Notes |
| |
| Translate the DynamicPageListEngine extension if it is available at translatewiki.net | |
TheDynamicPageListEngine extension is a backend providing dynamic page lists, which can be used onphp level for other extensions, or onLua level with theScribunto extension.The page selection and sorting criteria are compatible withDynamicPageList (Wikimedia).
Given that there are alreadyDynamicPageList (Wikimedia) andDynamicPageList (third-party), which are not completely compatible, you might be wondering why yet another such extension. In short:
DynamicPageListEngine folder to yourextensions/ directory.cdextensions/gitclonehttps://gerrit.wikimedia.org/r/mediawiki/extensions/DynamicPageListEnginewfLoadExtension('DynamicPageListEngine');
Done – Navigate toSpecial:Version on your wiki to verify that the extension is successfully installed.Even though this extension has been tested on MediaWiki 1.30 only, it is likely to work on slightly earlier versions as well.
To upgrade, simplyinstall the most recent version.
With version 1.0.0, almost all configuration parameters and messages names have been changed. If you have customized any of them, you need to adapt your configuration.
Since version 1.0.0, pages using DynamicPageListEngine are assigned to atracking category.If you already have such pages, you can fix the categories either by performing anull edit on each page or by executing the scriptmaintenance/refreshLinks.php.Note that the latter may take a considerable amount of time.
There is a number of parameters that can be customized inLocalSettings.php.The default configuration aims at maximum compatibility withDynamicPageList (Wikimedia) and is likely to satisfy your needs if you use this extension for the first time.
true) or not (false). SeeUsage for details. You shouldalways enable at leastDpleFeatureCount, otherwise there is no limit to the number of fetched records, andDpleFeatureCheck, otherwise there is no limit on the complexity of the query. If you want to use Lua, you also needDpleFeatureResults. Each of these may be replaced with a derived class or a class with similar semantics.:: The default list of features may be viewed in the extension'sextension.json.$wgDpleCondCostMap.Unless you arevery concerned about performance issues, you may simply enable all features in$wgDpleFeatures by copying it from the fileDynamicPageListEngine.php any uncommenting everything.In that case, to limit performance impact, you might decide to set$wgDpleMaxCost to a low value which however permits to use each feature, for instance 3.
Since the extension defines a lot of messages which are constantly evolving with further development, they are not documented here. Please refer toi18n/qqq.json.
For use on php level, please refer to the integrated doxygen documentation. For use on Lua level, seeLua library.
The accepted parameters and other aspects of the behaviour are implemented as features corresponding to php classes. With the variable$wgDynamicPageListEngineFeatures inLocalSettings.php you can configure which features you want to enable.The bundled features are described in the following sections, where the titles correspond to the class names without the prefix "DynamicPageListEngineFeature".
Unless otherwise stated, using arrays as parameter values return the intersection of the individual result sets.If the parameters contradict each other (e.g. the same namespace is nominated innamespace and innot namespace), the results are undefined.
Select by namespace.Recognizes the parametersnamespace andnotnamespace which may be a namespace name or namespace index or an array thereof.Any invalid value, including the empty string, is interpreted as the main namespace, for compatibility withDynamicPageList (Wikimedia).
Ifnamespace is an array, the result set consists (obviously) in the pages inany of the namespaces, i.e. the result set is the union of the individual result sets, unlike other parameters (includingnotnamespace) where the result set is the intersection.
Select by category.Recognizes the parameterscategory andnotcategory.Each of them may be a string or an array.Ifcategory is an array, the result set consists in the pages contained inall listed categories.Ifnotcategory is an array, the result set consists in the pages contained innone of the listed categories.
Include or exclude redirects. Recognizes the parameterredirects, which may be one ofexclude|include|only|resolve.
Default isexclude, for compatibility withDynamicPageList (Wikimedia).This implies that enabling this feature in$wgDynamicPageListEngineFeatures will change the result set of a dynamic page list even for parameter sets which do not contain theredirects parameter, if the result set would contain redirects.
The valueresolve selects only redirects just likeonly, but in addition the target for each redirect is retrieved.This means that the result object for each page has a propertytarget which is an associative array of properties of the redirect target.
Select by title prefix, suffix or fragment.Recognizes the parameterstitleprefix, nottitleprefix, titlesuffix, nottitlesuffix, titlecontains andnottitlecontains, each of which may be a title substring or an array thereof.As usual, spaces and underscores in titles are equivalent.
Iftitleprefix, titlesuffix, titlecontains is an array, the result set consists (obviously) in the pages satisfyingany of the conditions, i.e. the result is the union of the individual result sets, unlike other parameters (includingnottitleprefix) where the result set is the intersection.
This class implements a[not]title{prefix suffix contains} condition for substrings, but not a general[not]titlematch for LIKE patterns, because escaping of the% and_ characters depends on the database backend and hence it could not be ensured that a condition containing these metacharacters supplies the same result on all database backends.
Include or exclude subpages.Recognizes the parametersubpages, which may be one ofexclude|include|only.Default isexclude, for consistency with theRedirects feature.
This implies that enabling this feature in$wgDynamicPageListEngineFeatures will change the result set of a dynamic page list even for parameter sets which do not contain thesubpages parameter, if the result set would contain subpages.
Subpage selection works with a simple LIKE '%/%' expression, regardless of whether the namespace of a page has subpages enabled.To distinguish whether subpages are enabled, a CASE expression or something similar would need to be evaluated for each single row, and it would be difficult to implement this in an efficientand portable way.
Select pages linking to the specified pages.Recognizes the parameterslinksto andnotlinksto.Each of them may be a string or an array.The result set differs from the result of "What links here" because it does not contain redirects, for compatibility withDynamicPageList (third-party).
Select paged linked from specified pages.Recognizes the parameterslinksfrom andnotlinksfrom.Each of them may be a string or an array.The names are chosen for compatibility withDynamicPageList (third-party).
Select pages redirecting to the specified pages.Recognizes the parametersredirectsto andnotredirectsto.Each of them may be a string or an array.
Select pages using the specified pages as templates.Recognizes the parametersuses andnotuses.Each of them may be a string or an array.The results are the same as withDynamicPageList (third-party).
Select pages used as templates by the specified pages.Recognizes the parametersusedby andnotusedby.Each of them may be a string or an array.The results are the same as withDynamicPageList (third-party).
Select pages that contain the specified images.Recognizes the parametersimageused andnotimageused.Each of them may be a string or an array.The names are chosen for compatibility withDynamicPageList (third-party).
Select images that are contained in the specified pages. Recognizes the parametersimagecontainer andnotimagecontainer. Each of them may be a string or an array. The names are chosen for compatibility withDynamicPageList (third-party).
Select categories which contain the specified pages. Recognizes the parameterscontains andnotcontains. Each of them may be a string or an array.
Select pages by extra information in category tags. You can addextra information in a category sort key, in constructs like[[Category:...|user:{{PAGENAME}}|head of team]]. For MediaWiki, the whole stringuser:{{PAGENAME}}|head of team is the sort key. The extension considers the part after the second pipe character (head of team in the example) as extra information.
The feature recognizes the parametersextra andnotextra.extra selects exact matches of the extra information appended to the sort key for the first category specified with thecategory parameter.notextra selects the complement of this. If no categories are selected, these parameters are silently ignored.
Ifextra is an array, the result set consists (obviously) in the pages satisfyingany of the conditions, i.e. the result is the union of the individual record sets, unlike other parameters (includingnotextra) where the result set is the intersection.
Select categories byextra information in category tags.
The feature recognizes the parametersextrax andnotextrax.extrax selects categories with exact matches for the extra information appended to the sort key for the first page specified with thecontains parameter.notextrax selects the complement of this. If nocontains parameter was used, these parameters are silently ignored.
Ifextrax is an array, the result set consists (obviously) in the pages satisfyingany of the conditions, i.e. the result is the union of the individual record sets, unlike other parameters (includingnotextrax) where the result is the intersection.
Selection by modifying user. Recognizes the parameterscreatedby, notcreatedby, modifiedby, notmodifiedby, lastmodifiedby andnotlastmodifiedby, each of which may be a title substring or an array thereof.
Ifcreatedby, modifiedby, lastmodifiedby is an array, the result set consists in the pages satisfyingany of the conditions, i.e. the result is the union of the individual record sets, unlike other parameters (includingnotcreatedby) where the result is the intersection.
Use of[not]modifiedby is likely to create much more database load than the other parameters because the record sets to join may be very large.This is reflected in$wgDynamicPageListEngineCondCostMap, but you might need to adjust this value.You can effectively disable these parameters by setting their cost higher than the value of$wgDynamicPageListEngineMaxCost.
Limit the number of records to fetch from the database.Recognizes the parametercount which gives the limit.Invalid values (including 0) are interpreted as 1, for compatibility withDynamicPageList (Wikimedia).In any case, the number is limited to$wgDynamicPageListEngineMaxResultCount.
Sort the result records.Recognizes the parametersorder (defaultdescending) andordermethod (defaultcategoryadd).Some values are replaced by fallback values if no category was indicated.Defaults and fallback values are chosen for compatibility withDynamicPageList (Wikimedia).
In addition to theordermethod values recognized byDynamicPageList (Wikimedia), the valuetitle is accepted as well.It sorts by title without namespace prefix.
Check whether the whole specification is acceptable in terms of database load.
Convert query results to other representations.SeeLua library for details.
All functions explained below take a single argument which is an associative array of parameters. The recognized parameters are explained inUsage.
mw.ext.dpl.getFullpagenames{ parameters }
Select and sort pages according to the parameters and return an array of full page names.
mw.ext.dpl.getPagenames{ parameters }
Select and sort pages according to the parameters and return an array of page names without namespace. This is useful if you know the namespace in advance because you have specified it in the arguments.
mw.ext.dpl.getPages{ parameters }
Select and sort pages according to the parameters and return an array of associative arrays, each of which represents a page. The latter contain the following items which have the same meaning as the corresponding properties ofmw.title objects:namespace, nsText, text, prefixedText, baseText, subpageText, canTalk, isContentPage, isSubpage, isTalkPage, isRedirect. In addition, the following items are provided:
category parameter, if any.contains parameter, if any, to the selected category.contains parameter, if any, provided thatDynamicPageListEngineFeatureExtrax is enabled.These are the release notes for version 1.1. SeeExtension:DynamicPageListEngine/History for older releases.
& characters are now handled correctly.Please report software bugs and feature requests on thetalk page.