search

WikiToLearn / mediawiki-extensions-Collection

MediaWiki Collection extension fork for WikiToLearn
GNU General Public License v2.0
0 stars 1 forks source link

readme

==================================== Collection Extension for MediaWiki

About the Collection Extension

The Collection extension for MediaWiki_ allows users to collect articles and generate downloadable version in different formats (PDF, OpenDocument Text etc.) for article collections and single articles.

The extension has been developed for and tested with MediaWiki_ version 1.25wmf19 and later, due to the use of the OOjs UI widget library.

The extension is being developed under the GNU General Public License by PediaPress GmbH in close collaboration with Wikimedia Foundation and the Commonwealth of Learning_.

Copyright (C) 2008-2015, PediaPress GmbH, Siebrand Mazeland, Marcin Cieślak, the Wikimedia Foundation, and other contributors

Prerequisites

If you use a render server the MediaWiki API_ must be enabled (i.e. just don't override the default value of true for $wgEnableApi in your LocalSettings.php).

Install PHP with cURL support

Currently Collection extension needs PHP with cURL support, see http://php.net/curl

Installation and Configuration of the Collection Extension

If you intend to use the public render server, you're now ready to go.

Install and Setup a Render Server

Rendering and ZIP file generation is done by a server, which can run separately from the MediaWiki installation and can be shared by different MediaWikis.

If you have a low-traffic MediaWiki you can use the public render server running at http://tools.pediapress.com/mw-serve/. In this case, just keep the configuration variable $wgCollectionMWServeURL (see below) at its default value.

Your MediaWiki must be accessible from the render server, i.e. if your MediaWiki is behind a firewall you cannot use the public render server.

If you can't use the public render server, you have two choices:

1) To install an OCG_ server, follow the instructions at https://www.mediawiki.org/wiki/Offline_content_generator

2) To install a mwlib_ server, you'll have to :ref:install mwlib <mwlib-install> and :ref:run your own render server <mwlib-renderserver>. See http://mwlib.readthedocs.org/ for more information.

Finally you'll have to set $wgCollectionMWServeURL in your LocalSetting.php:

$wgCollectionMWServeURL (string)

Set this to the URL of either an mwlib or an OCG render server (see above).

The default is http://tools.pediapress.com/mw-serve/, the public mwlib_ render server hosted by PediaPress.

If you must use a proxy in order to reach the render server, you can prefix the URL with the proxy URL and separate them with |, for example:

   http://my.proxy.host:8888|https://tools.pediapress.com/mw-serve/

If you need to use a | character in the URL of your render server, use a blank proxy: |http://my.render.server/path-with-|/.

Password protected wikis

Password protected wikis require some more information. You'll have to set the $wgCollectionMWServeCredentials variable.

$wgCollectionMWServeCredentials (string)

Set this to a string of the form "USERNAME:PASSWORD" (or "USERNAME:PASSWORD:DOMAIN" if you're using LDAP), if the MediaWiki requires to be logged in to view articles. The render server will then login with these credentials using MediaWiki API before doing other requests.

SECURITY NOTICE: If the MediaWiki and the render server communicate over an insecure channel (for example on an unencrypted channel over the internet), please DO NOT USE THIS SETTING, as the credentials will be exposed to eavesdropping!

Advanced Settings

The following variables can be set in LocalSetting.php. Most people do not have to change them:

$wgCollectionMWServeCert (string) Filename of a SSL certificate in PEM format for the mw-serve render server. This needs to be used for self-signed certificates, otherwise cURL will throw an error. The default is null, i.e. no certificate.

$wgCollectionFormats An array mapping names of writers on the server to the name of the produced format. The default value is::

   array(
   'rl' => 'PDF',
   )

i.e. only PDF enabled. If you want to add OpenDocument Text in addition to PDF you can set $wgCollectionFormats to something like this::

   $wgCollectionFormats = array(
   'rl' => 'PDF',
   'odf' => 'ODT',
   );

On the public mwlib_ render server tools.pediapress.com, currently the following writers are available:

$wgCollectionFormatToServeURL (array) An array matching writer names with the server which should be used for them. For example, if you wanted to configure an OCG_ server for PDF only, you might have::

   $wgCollectionFormatToServeURL = array(
   'rdf2latex' => 'http://my-ocg-server.com:8000',
   );

You can specify proxies in the same way as for $wgCollectionMWServeURL.

$wgCollectionCommandToServeURL (array) An array matching server commands with the server which should be used for them. For example, to use the public pediapress POD server, you might have::

   $wgCollectionCommandToServeURL = array(
   'zip_post' => 'http://tools.pediapress.com/mw-serve/',
   );

Again, proxies can be prefixed to the URL, separated by |, in the same way as for $wgCollectionMWServeURL.

$wgCollectionContentTypeToFilename (array) An array matching content types to filenames for downloaded documents. The default is::

  $wgCollectionContentTypeToFilename = array(
      'application/pdf' => 'collection.pdf',
      'application/vnd.oasis.opendocument.text' => 'collection.odt',
      'text/plain' => 'collection.txt',
  );

$wgCollectionPortletFormats (array) An array containing formats (keys in $wgCollectionFormats) that shall be displayed as "Download as XYZ" links in the "Print/export" portlet. The default value is::

   array( 'rl' );

i.e. there's one link "Download as PDF".

$wgCollectionHierarchyDelimiter (string or null) FEATURE REMOVED 2015-03. Use $wgNamespacesWithSubpages instead. The only accepted delimiter is now the standard slash, "/".

$wgCollectionArticleNamespaces (array) List of namespace numbers for pages which can be added to a collection. Category pages (NS_CATEGORY) are always an exception (all articles in a category are added, not the category page itself). Default is::

array(
  NS_MAIN,
  NS_TALK,
  NS_USER,
  NS_USER_TALK,
  NS_PROJECT,
  NS_PROJECT_TALK,
  NS_MEDIAWIKI,
  NS_MEDIAWIKI_TALK,
  100,
  101,
  102,
  103,
  104,
  105,
  106,
  107,
  108,
  109,
  110,
  111,
);

$wgCommunityCollectionNamespace (integer) Namespace for "community collections", i.e. the namespace where non-personal article collection pages are saved.

 Note: This configuration setting is only used if the system message
 Coll-community_book_prefix has not been set (see below).

Default is NS_PROJECT.

$wgCollectionMaxArticles (integer) Maximum number of articles allowed in a collection.

Default is 500.

$wgCollectionLicenseName (string or null) License name for articles in this MediaWiki. If set to null the localized version of the word "License" is used.

Default is null.

$wgCollectionLicenseURL (string or null) HTTP URL of an article containing the full license text in wikitext format for articles in this MediaWiki. E.g.

::

   $wgCollectionLicenseURL = 'http://en.wikipedia.org/w/index.php?title=Wikipedia:Text_of_the_GNU_Free_Documentation_License&action=raw';

for the GFDL. If set to null, the standard MediaWiki variables $wgRightsPage, $wgRightsUrl and $wgRightsText are used for license information.

If your MediaWiki contains articles with different licenses, make sure that each article contains the name of the license and set $wgCollectionLicenseURL to an article that contains all needed licenses.

$wgCollectionPODPartners (array or false) Array of parameters needed to define print on demand providers:

::

    $wgCollectionPODPartners = array(
            'pediapress' => array(
                    'name' => 'PediaPress',
                    'url' => 'http://pediapress.com/',
                    'posturl' => 'http://pediapress.com/api/collections/',
                    'infopagetitle' => 'coll-order_info_article',
            ),
    );

(This is the default.)

name, url and posturl are mandatory parameters to display information on the list of available providers.

If infopagetitle is present, it will be interpreted as the MediaWiki message that contains the name of the short information on particular provider. For example, it can be coll-order_info_mypress and if the message contains Help:Books/MyPress order information, a contents of this page will be used. The message itself can be localized for different languages.

Setting $wgCollectionPODPartners to false disables ordering interface altogether.

$wgEnableWriteAPI

If you want to let users save their collections as wiki pages, make sure $wgEnableWriteAPI is set to true, i.e. put this line in your LocalSettings.php::

$wgEnableWriteAPI = true;

(This is the default.)

There are two MediaWiki rights that are checked, before users are allowed to save collections: To be able to save collection pages under the User namespace, users must have the right 'collectionsaveasuserpage'; to be able to save collection pages under the community namespace (see $wgCommunityCollectionNamespace), users must have the right 'collectionsaveascommunitypage'. For example, if all logged-in users shall be allowed to save collection pages under the User namespace, but only autoconfirmed users, shall be allowed to save collection pages under the community namespace, add this to your LocalSettings.php::

$wgGroupPermissions['user']['collectionsaveasuserpage'] = true;
$wgGroupPermissions['autoconfirmed']['collectionsaveascommunitypage'] = true;

You may also want to configure some of the following:

Customization via System Messages

There are several system messages, which can be adjusted for a MediaWiki installation. They can be changed by editing the wiki page [[MediaWiki:SYSTEMMESSAGENAME]], where SYSTEMMESSAGENAME is the name of the system message.

.. _mwlib: http://mwlib.readthedocs.org/ .. _MediaWiki: http://www.mediawiki.org/ .. _OCG: https://www.mediawiki.org/wiki/Offline_content_generator .. PediaPress GmbH: http://pediapress.com/ .. Wikimedia Foundation: http://wikimediafoundation.org/ .. Commonwealth of Learning: http://www.col.org/ .. MediaWiki API: http://www.mediawiki.org/wiki/API .. _Meta-Wiki: http://meta.wikimedia.org/wiki/Book_tool/Help/Books