Extension:DynamicPageListEngine
DynamicPageListEngine État de la version : stable |
|
---|---|
Implémentation | Extraction de données |
Description | Provides dynamic page lists with configurable and extensible features to modules and to other extensions |
Auteur(s) | RV1971 (RV1971discussion) |
Dernière version | 1.1.0 (2018-03-24) |
MediaWiki | 1.30+ |
PHP | 7.0+ |
Modifie la base de données |
Non |
Licence | Licence publique générale GNU v3.0 ou supérieur |
Téléchargement | Release Notes |
|
|
Téléchargements trimestriels | 16 (Ranked 117th) |
Traduire l’extension DynamicPageListEngine sur translatewiki.net si elle y est disponible | |
The DynamicPageListEngine extension is a backend providing dynamic page lists, which can be used on php level for other extensions, or on Lua level with the Scribunto extension. The page selection and sorting criteria are compatible with DynamicPageList (Wikimedia).
Given that there are already DynamicPageList (Wikimedia) and DynamicPageList (third-party), which are not completely compatible, you might be wondering why yet another such extension. In short:
- I needed dynamic page lists on Lua level, and none of the two existing extensions provided that.
- Adding such a feature on top of DynamicPageList (Wikimedia) was not feasible due to its monolithic implementation.
- Adding such a feature on top of DynamicPageList (third-party) might have been possible, but then it would have been partially incompatible with the Wikimedia extension. More importantly, as the the DPL manual states, "DPL at the moment is rather monolithic" as well.
- Hence the only solution was to create a new extension from scratch.
- The extremely high number of features in the third-party extension suggests the need for a configurable, modular and extensible backend.
Installation
- Téléchargez et placez le(s) fichier(s) dans un répertoire appelé
DynamicPageListEngine
dans votre dossierextensions/
.
Les développeurs et les contributeurs au code doivent à la place installer l'extension à partir de Git en utilisant:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/DynamicPageListEngine - Ajoutez le code suivant à la fin de votre fichier LocalSettings.php :
wfLoadExtension( 'DynamicPageListEngine' );
- Fait – Accédez à Special:Version sur votre wiki pour vérifier que l'extension a bien été installée.
Even though this extension has been tested on MediaWiki 1.30 only, it is likely to work on slightly earlier versions as well.
Mise à jour
To upgrade, simply install the most recent version.
Upgrading from 0.3 or earlier
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 a tracking category.
If you already have such pages, you can fix the categories either by performing a null edit on each page or by executing the script maintenance/refreshLinks.php
.
Note that the latter may take a considerable amount of time.
Configuration
LocalSettings.php
There is a number of parameters that can be customized in LocalSettings.php . The default configuration aims at maximum compatibility with DynamicPageList (Wikimedia) and is likely to satisfy your needs if you use this extension for the first time.
- $wgDpleMaxCost
- Maxiumum cost of a dynamic page list in terms of database load. The default value NULL means that it is automatically set to the corresponding value for DynamicPageList (Wikimedia).
- $wgDpleMaxResultCount
- Maxiumum number of records to fetch for one list. The default value NULL means that it is automatically set to the corresponding value for DynamicPageList (Wikimedia).
- $wgDpleFeatures
- Features to enable. An associative array between feature name/class and a boolean to indicate enabled (true) or not (false). See Usage for details. You should always enable at least
DpleFeatureCount
, 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's extension.json.
- $wgDpleCondCostMap
- Cost of selection conditions in terms of database load. A unit of 1 should correspond to an efficient table join. You can tune this map to reflect the real cost on your particular installation and/or prevent users from excessive use of certain features.
- $wgDpleOrderCostMap
- Cost of order methods in terms of database load, in units which should be vaguely comparable to those of
$wgDpleCondCostMap
.
Unless you are very concerned about performance issues, you may simply enable all features in $wgDpleFeatures
by copying it from the file DynamicPageListEngine.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.
Messages
Since the extension defines a lot of messages which are constantly evolving with further development, they are not documented here. Please refer to i18n/qqq.json
.
Utilisation
For use on php level, please refer to the integrated doxygen documentation. For use on Lua level, see Lua library.
The accepted parameters and other aspects of the behaviour are implemented as features corresponding to php classes. With the variable $wgDynamicPageListEngineFeatures
in LocalSettings.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 in namespace
and in not namespace
), the results are undefined.
Namespace
Select by namespace. Recognizes the parameters namespace
and notnamespace
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 with DynamicPageList (Wikimedia).
If namespace
is an array, the result set consists (obviously) in the pages in any of the namespaces, i.e. the result set is the union of the individual result sets, unlike other parameters (including notnamespace
) where the result set is the intersection.
Category
Select by category. Recognizes the parameters category
and notcategory
. Each of them may be a string or an array. If category
is an array, the result set consists in the pages contained in all listed categories. If notcategory
is an array, the result set consists in the pages contained in none of the listed categories.
Redirects
Include or exclude redirects. Recognizes the parameter redirects
,
which may be one of exclude|include|only|resolve
.
Default is exclude
, for compatibility with DynamicPageList (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 the redirects
parameter, if the result set would contain redirects.
The value resolve
selects only redirects just like only
, but in addition the target for each redirect is retrieved. This means that the result objuect for each page has a property target
which is an associative array of properties of the redirect target.
Titlematch
Select by title prefix, suffix or fragment. Recognizes the parameters titleprefix, nottitleprefix, titlesuffix, nottitlesuffix, titlecontains
and nottitlecontains
, each of which may be a title substring or an array thereof. As usual, spaces and underscores in titles are equivalent.
If titleprefix, titlesuffix, titlecontains
is an array, the result set consists (obviously) in the pages satisfying any of the conditions, i.e. the result is the union of the individual result sets, unlike other parameters (including nottitleprefix
) 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.
Subpages
Include or exclude subpages. Recognizes the parameter subpages
, which may be one of exclude|include|only
. Default is exclude
, for consistency with the Redirects 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 the subpages
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 efficient and portable way.
Linksto
Select pages linking to the specified pages. Recognizes the parameters linksto
and notlinksto
. 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 with DynamicPageList (third-party).
Linksfrom
Select paged linked from specified pages. Recognizes the parameters linksfrom
and notlinksfrom
. Each of them may be a string or an array. The names are chosen for compatibility with DynamicPageList (third-party).
Redirectsto
Select pages redirecting to the specified pages. Recognizes the parameters redirectsto
and notredirectsto
. Each of them may be a string or an array.
Uses
Select pages using the specified pages as templates. Recognizes the parameters uses
and notuses
. Each of them may be a string or an array. The results are the same as with DynamicPageList (third-party).
Usedby
Select pages used as templates by the specified pages. Recognizes the parameters usedby
and notusedby
. Each of them may be a string or an array. The results are the same as with DynamicPageList (third-party).
Imageused
Select pages that contain the specified images. Recognizes the parameters imageused
and notimageused
. Each of them may be a string or an array. The names are chosen for compatibility with DynamicPageList (third-party).
Imagecontainer
Select images that are contained in the specified pages. Recognizes the parameters imagecontainer
and notimagecontainer
. Each of them may be a string or an array. The names are chosen for compatibility with DynamicPageList (third-party).
Contains
Select categories which contain the specified pages. Recognizes the parameters contains
and notcontains
. Each of them may be a string or an array.
Extra
Select pages by extra information in category tags. You can add extra information in a category sort key, in constructs like [[Category:...|user:{{PAGENAME}}|head of team]]
. For MediaWiki, the whole string user:{{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 parameters extra
and notextra
. extra
selects exact matches of the extra information appended to the sort key for the first category specified with the category
parameter. notextra
selects the complement of this. If no categories are selected, these parameters are silently ignored.
If extra
is an array, the result set consists (obviously) in the pages satisfying any of the conditions, i.e. the result is the union of the individual record sets, unlike other parameters (including notextra
) where the result set is the intersection.
Extrax
Select categories by extra information in category tags.
The feature recognizes the parameters extrax
and notextrax
. extrax
selects categories with exact matches for the extra information appended to the sort key for the first page specified with the contains
parameter. notextrax
selects the complement of this. If no contains
parameter was used, these parameters are silently ignored.
If extrax
is an array, the result set consists (obviously) in the pages satisfying any of the conditions, i.e. the result is the union of the individual record sets, unlike other parameters (including notextrax
) where the result is the intersection.
User
Selection by modifying user. Recognizes the parameters createdby, notcreatedby, modifiedby, notmodifiedby, lastmodifiedby
and notlastmodifiedby
, each of which may be a title substring or an array thereof.
If createdby, modifiedby, lastmodifiedby
is an array, the result set consists in the pages satisfying any of the conditions, i.e. the result is the union of the individual record sets, unlike other parameters (including notcreatedby
) 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
.
Count
Limit the number of records to fetch from the database. Recognizes the parameter count
which gives the limit. Invalid values (including 0) are interpreted as 1, for compatibility with DynamicPageList (Wikimedia). In any case, the number is limited to $wgDynamicPageListEngineMaxResultCount
.
Order
Sort the result records. Recognizes the parameters order
(default descending
) and ordermethod
(default categoryadd
). Some values are replaced by fallback values if no category was indicated. Defaults and fallback values are chosen for compatibility with DynamicPageList (Wikimedia).
In addition to the ordermethod
values recognized by DynamicPageList (Wikimedia), the value title
is accepted as well. It sorts by title without namespace prefix.
Check
Check whether the whole specification is acceptable in terms of database load.
Results
Convert query results to other representations. See Lua library for details.
Lua library
All functions explained below take a single argument which is an associative array of parameters. The recognized parameters are explained in Usage.
mw.ext.dpl.getFullpagenames
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
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
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 of mw.title objects: namespace, nsText, text, prefixedText, baseText, subpageText, canTalk, isContentPage, isSubpage, isTalkPage, isRedirect
. In addition, the following items are provided:
- length
- Uncompressed length in bytes of the page's current source text.
- categoryadd
- Timestamp of addition to the first category specified with the
category
parameter, if any. - categoryaddx
- Timestamp of addition of the first page specified with the
contains
parameter, if any, to the selected category. - counter
- Page view counter, unless counters are disabled.
- sortkey
- Sort key in the first category, if any, provided that DynamicPageListEngineFeatureExtra is enabled.
- extra
- Extra information given with sort key, if any, provided that DynamicPageListEngineFeatureExtra is enabled.
- sortkeyx
- Sort key in the category of the first page specified with the
contains
parameter, if any, provided that DynamicPageListEngineFeatureExtrax is enabled. - extra
- Extra information given with the sortkeyx sort key, if any, provided that DynamicPageListEngineFeatureExtrax is enabled.
Release notes
These are the release notes for version 1.1. See Extension:DynamicPageListEngine/History for older releases.
New features
- Added the withoutsuffix item to the result records of Extension:DynamicPageListEngine#mw.ext.dpl.getPages.
- Added the resolve option to the Extension:DynamicPageListEngine#Redirects module.
- Added the Extension:DynamicPageListEngine#Redirectsto module.
Bugfixes
- Page titles containing
&
characters are now handled correctly.
Bug reports and feature requests
Please report software bugs and feature requests on the talk page.