DPL:Manual - Source and Installation

From FollowTheScore
Jump to: navigation, search
Manual Source and Installation

Get code/file

Download the ZIP archive and extract the DynamicPageList subdirectory to a directory named yourwiki/extensions/DynamicPageList. You may ignore the other extensions but it is recommended to install at least Call and Inputbox as some DPL based applications like the DPL GUI use them.

Installation

  • You must invoke DPL from your LocalSettings.php with
    require_once("extensions/DynamicPageList/DynamicPageList.php");
Note: In former times the source file containing the entrance point was called DynamicPageList2.php: For downward compatibility reasons there is still a dummy file with that name.
  • In some special cases (when DPL queries refer to 'uncategorized pages') DPL needs a special database view in the MySQL database. You can run a script to cerate that view if you want to use DPL statements which refer to uncategorized pages. Many installations work well without that and you can postpone this step until you really need it. If DPL cannot execute a DPL statement without that view it will issue a corresponding warning.
    You must have admin rights in your database to execute the "create view" statement; if you defined a database table prefix at installation time of your wiki, you must use that prefix in the statement, otherwise delete "prefix_" before you issue the statement:
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

Note that you may get a misleading error message from the SQL interpreter (1084 syntax error) if you do not have sufficient privileges to create that view.

  • 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 DynamicPageList.php file itself.
  • After the "require_once()" call you can configure DPL according to your preferences. You can define the level of functionality, you can set certain default values and limits and you can make security restrictions (e.g. allowing DPL to run from 'protected' pages only. See the next chapters in this document.

The dpldemo website contains a lot of examples how DPL can be used. Some of these examples use certain other extensions. A few of those are also contained in the Download, mostly because they have been slightly improved to suit our needs. You may want to install these versions instead of the original version.


  • There is a special feature in DPL which needs another extension: If you use page inclusion and want to use images as link symbols for the original source you must install the LinkedImage extension. For details see there.

Using Postgres

If you are using Postgres you may be interested in reading DPL:Manual - DPL with PostgreSQL.

Installation issues regarding LabeledSectionTransclusion

An older version of DPL made use of another extension, called LabeledSectionTransclusion. Our thanks go to Steve Sanbeg, whose extension inspired DPL a lot and helped to make it stronger and more useful. Since version 0.9 of DPL the needed parts of that extension have been integrated into DPL (and further modified/enhanced). Therefore it is not necessary to install LabeledSectionTransclusion if you do not want to use it directly.

If you do install both extensions this should not cause trouble. There is only one situation known so far where there is some cross influencing:

  • in DPL it is possible to have multiple DPL statements on one page which return the same article (or transcluded parts of it) as part of their results. This typically happens when you want to show various chapters of the same transcluded article in the result of a DPL statement. But it could also happen if you wrote DPL statements with overlapping results.
  • LabeledSectionTransclusion will (by its design) only execute one transclusion. Any further references to the same article will only produce a link to the article and will not show any contents.
  • So, if you have a DPL statement on your page which lists contents of an article and you have a #lst statement on the same page which tries to transclude contents from that very article you will not see the contents but only a link to the page.

If you want to understand more about the relation between DPL and LabeledSectionTransclusion, here are some details:

  • include=mySectionMarker" works exactly like "#lst:myArticle|mySectionMarker" assuming that myArticle matches the selection criteria of the DPL statement
  • include=#myChapter" works exactly like "#lsth:myArticle|myChapter" assuming that myArticle matches the selection criteria of the DPL statement
  • there is no equivalent to "#lstx:" in DPL
  • the template based inclusion of DPL has no equivalent in LabeledSectionTransclusion
  • the possibility to truncate included text portions at some text length limit and put a reference to the source chapter into the output does not exist in LabeledSectionTransclusion
  • the internal mechanism of loop detection is different in the DPL version; this was needed because I had problems with several DPL statements on one page (only the first one showed a result)
So what does this mean?
  • from a technical point you can install both extensions
  • from a user´s point of view the section tagging (#lst) and the heading transclusion (#lsth) work identical.
  • it makes sense to have LabeledSectionTransclusion as a standalone tool if you want to transclude just one section of another article.

System requirements

  • MediaWiki 1.8.2 or above (because of internationalization and some other features)
  • if using MySQL:
    • MySQL 4.1 or above (because we use some optimisations that were not present in older versions)
    • MySQL 5.0.1 or above if you want to use the 'category' parameter on uncategorized pages (the creation of the DPL_clview requires the CREATE VIEW statement, see also MySQL 5.0 Reference Manual :: 19.2 CREATE VIEW Syntax).

Server-Wide Configuration: Extension options

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

Note that older versions of DPL (before 1.60) used global variables like $wgDPL2Xxx instead of ExtDynamicPageList::$xxx. So you must adapt your LocalSettings.php when changing to a newer version.

ExtDynamicPageList::$maxCategoryCount 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.

ExtDynamicPageList::$allowUnlimitedCategories Allows unlimited categories in the query. (ExtDynamicPageList2::$maxCategoryCount will be ignored)

ExtDynamicPageList::$minCategoryCount 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.

ExtDynamicPageList::$maxResultCount Maximum number of rows to retrieve from the wiki database to satisfy a DPL query. Default is 500. This is a tricky parameter when your wiki gets large. It does not always mean "maximum number of DPL results to display." You see, DPL initially makes a database query to get possible matches, then filters them afterward outside of SQL (for example, by regular expression in an includematch statement). If your wiki has more than 500 articles, this SQL query might return only some of the matches in the first 500 rows. As a result, your DPL query could be missing some results. As your wiki grows, you'll need to increase this variable or DPL results will become progressively incomplete.

ExtDynamicPageList::$allowUnlimitedResults Allow unlimited results to be shown. (ExtDynamicPageList::$maxResultCount will be ignored) Default is false.

ExtDynamicPageList::$categoryStyleListCutoff 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.

ExtDynamicPageList::$respectParserCache Default is false for <dpl> but 'true' for <DynamicPageList> You can change this according to your preferences. If set to 'true' DPL will no longer behave 'dynamically' because its output is taken from the ParserCache.

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

  • Change default parameter values: ExtDynamicPageList::$options['param']['default']='val'. Make sure val is a valid param value.
Example: ExtDynamicPageList::$options['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 ExtDynamicPageList::$options in DPLSetup.php), ExtDynamicPageList::$options['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).

$wgNonIncludableNamespaces This variable (which does not belong to DPL) is understood and respected by DPL. It will prevent contents from the namespaces listed here to appear in DPL output. See the concept of nonIncludableNamespaces.

ExtDynamicPageList::setFunctionalRichness($level) With a call of this function you can define how much functionality of DPL sahll be made available to the users; see DPL:Manual - Compatibility for details.

DPL Security

Novice users playing around with DPL may cause severe server load by writing DPL code which requires a lot of resources from the MediaWiki database (or which does extensive im memory string parsing of transcluded wiki text).

There is a configuration option which ensures that DPL code will only run from PROTECTED PAGES. Thus only those people who are permitted to protect wiki pages can write DPL queries.

To enable this option you have to add the following statement in your LocalSettings.php after the 'require_once for DPL':

ExtDynamicPageList::$options['RunFromProtectedPagesOnly'] = "some warning message";

A suitable warning message might look like:

'<small><i>Extension DPL (warning): current configuration allows execution of DPL code from protected pages only.</i></small>'


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 DynamicPageList.i18n.php. All you have to do is to create in this file a self::$messages['lang'] array where 'lang' is your language code, and use self::$messages['en'] as a model. Replace values with appropriate translations.

LocalSettings.php variables

Variable Parameter(s)
ExtDynamicPageList::$allowUnlimitedCategories Category
ExtDynamicPageList::$allowUnlimitedResults Count
ExtDynamicPageList::$categoryStyleListCutoff Category
ExtDynamicPageList::$maxCategoryCount Category
ExtDynamicPageList::$minCategoryCount Category
ExtDynamicPageList::$maxResultCount Count
ExtDynamicPageList::$respectParserCache dplcache
$wgNonIncludableNamespaces general MediaWiki concept