Difference between revisions of "DPL:Manual - Source and Installation"

From FollowTheScore
Jump to: navigation, search
(<tt>LocalSettings.php</tt> variables)
(Server-Wide Configuration: Extension options)
Line 84: Line 84:
 
'''$wgNonIncludableNamespaces'''
 
'''$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''.
 
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''.
 +
 +
 +
== 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 <tt>LocalSettings.php</tt> after the  <tt>'require_once for DPL2'</tt>:
 +
 +
ExtDynamicPageList2::$options['RunFromProtectedPagesOnly'] = "some warning message";
 +
 +
A suitable warning message might look like:
 +
<pre><nowiki>'<small><i>Extension DPL (warning): current configuration allows execution of DPL code from protected pages only.</i></small>'</nowiki></pre>
  
 
== Internationalization ==
 
== Internationalization ==

Revision as of 09:20, 1 May 2009

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

  1. You must invoke DPL from your LocalSettings.php with
    require_once("extensions/DynamicPageList/DynamicPageList2.php");
  2. 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.
  3. In some special cases (when DPL queries refer to uncategorized pages) DPL needs a special database view in the MySQL database. You should run the database statement which creates 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 DynamicPageList2.php file itself.

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:

  • includepage=mySectionMarker" works exactly like "#lst:myArticle|mySectionMarker" assuming that myArticle matches the selection criteria of the DPL statement
  • includepage=#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 (which I personally find quite useful) 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 DynamicPageList2.php) or in DynamicPageList2.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 ExtDynamicPageList2::$xxx. So you must adapt your LocalSettings.php when changing to a newer version.

ExtDynamicPageList2::$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.

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

ExtDynamicPageList2::$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.

ExtDynamicPageList2::$maxResultCount Maximum number of results to allow. Default is 500.

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

ExtDynamicPageList2::$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.

ExtDynamicPageList2::$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 DynamicPageList2.php (beginning). Use it at your own risk. Anyway, below are some usage examples:

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


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 DPL2':

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

LocalSettings.php variables

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