Extension:Collection

MediaWiki extensions manual

Collection Release status: stable
Implementation	Special page, MyWiki
Description	Allows to organize personal selections of pages in a collection that can be edited, persisted and optionally retrieved as PDF, ODF or DocBook (XML)
Author(s)	PediaPress.com, Siebrand Mazeland, Marcin Cieślak
Latest version	1.7.0 (2014-04-18)
MediaWiki	1.17+
Database changes	No
License	GNU General Public License 2.0 or later
Download	Download snapshot (Git master) Git [?]: repo summary browse file tree commit history code review README
Example	wiki.openoffice.org
Parameters $wgCollectionStyleVersion $wgCollectionMWServeURL $wgCollectionMWServeCredentials $wgCollectionMWServeCert $wgCollectionHierarchyDelimiter $wgCollectionArticleNamespaces $wgCommunityCollectionNamespace $wgCollectionMaxArticles $wgCollectionLicenseName $wgCollectionLicenseURL $wgCollectionFormats $wgCollectionFormatToServeURL $wgCollectionContentTypeToFilename $wgCollectionPortletFormats $wgCollectionPortletForLoggedInUsersOnly $wgCollectionMaxSuggestions $wgCollectionSuggestCheapWeightThreshhold $wgCollectionSuggestThreshhold $wgCollectionPODPartners
Added rights collectionsaveasuserpage collectionsaveascommunitypage
Hooks used SkinTemplateBuildNavUrlsNav_urlsAfterPermalink OutputPageCheckLastModified ResourceLoaderGetConfigVars SiteNoticeAfter SkinBuildSidebar
Translate the Collection extension if it is available at translatewiki.net
Check usage and version matrix; code metrics
Issues:	Open tasks · Report a bug

The Collection extension allows a user to organize personal selections of pages in a collection. Collections can be

• edited and structured using chapters
• persisted, loaded and shared
• rendered as PDF (see Extension:PDF_Writer and Extension:Collection/OfflineContentGenerator TODO)
• exported as ODF Text Document (see Extension:OpenDocument_Export)
• exported as DocBook XML (see Extension:XML_Bridge)
• ordered as a printed book at http://pediapress.com/
• exported as ZIM file (see Extension:Collection/openZIM)
• exported as ePub file (ebook)

See the press release Wikis Go Printable for more information on this project.

Documentation & Support

The documentation for the collection can be found at http://mwlib.readthedocs.org/en/latest/collection.html

There is also a Google group for support and discussion of mwlib, mwlib.rl and the Collection extension.

mwlib developers have also been spotted on the pediapress IRC channel:

• Server: irc.freenode.net
• Channel: #pediapress

A detailed guide on how to prepare your wiki (templates, help pages, categories) if you setup the extension is available at meta.wikimedia.org.

Screencast

There is a screencast demoing the basic functionality available at youtube (in German) (2:45 minutes).

Creating cross-wiki article collections

It's best to use http://pediapress.com/collection/ for this purpose, see ticket 408.

Installation

• Download and place the file(s) in a directory called Collection in your extensions/ folder.
• Add the following code at the bottom of your LocalSettings.php:

require_once "$IP/extensions/Collection/Collection.php";

• Configure the extension as required
• Done! Navigate to "Special:Version" on your wiki to verify that the extension is successfully installed.

Please also read the included README for detailed configuration instructions of the extension.

This extension does not work if the parameter $wgScriptPath is empty, i. e.

$wgScriptPath = "";

Make sure that this parameter is either set to the default setting

$wgScriptPath = "/wiki";

or filled like this, e.g.

$wgScriptPath = "http://www.example.com"; #WITHOUT SLASH ON END

If that messes up your site, you may also patch "extensions/Collection/Collection.body.php": In function "renderCollection" change

'base_url' => 'http://www.example.com', #WITHOUT SLASH ON END

See this issue report for further information.

Configuration

See also readthedocs.org, Installation and Configuration of the Collection Extension and Customization via System Messages.

Generating PDFs, OpenDocument- & DocBook-Exports

It's easy to enable PDF (ODF, DocBook) support with this Extension. It is configured by default to use the server http://tools.pediapress.com/. Therefore (low traffic) sites that are accessible from the internet don't need to install their own PDF Server. Steps:

• Simply install and configure the Collection extension using the default value http://tools.pediapress.com/mw-serve/ for $wgCollectionMWServeURL (see README of the Collection extension for instructions) and make sure the MediaWiki API (api.php) is enabled on your MediaWiki installation.
• Some users report that installing PDFtk is necessary.

No installation of Python, ReportLab, mwlib etc. required! Note however, that in order to use this service, your wiki must be accessible from the internet and must be either accessible for non-logged-in users or login credentials must be configured (see README for instructions).

Have a look at the Solar system, example article from the English language Wikipedia, rendered as PDF using this technology.

Set up your own render server

If you either have a wiki which is not accessible from the outside or your site has high traffic, you need to install your own render server. The server is included with mwlib and can be used as a stand-alone HTTP server (which is the default protocol) or as FastCGI or SCGI server or as a CGI script.

Requirements and steps

Installing mwlib has a number of additional prerequisites. Please refer to the official installation documentation. Guides for your specific environment may also be useful, see below.

Other guides

• For documentation on how to do this on Ubuntu 12.04 look on Setup a render server on Ubuntu 12.04 LTS.
• For documentation on how to do this on OSX Mavericks look on Setup a render server on OSX. There are useful tips for localhost installations for other systems too.
• A comprehensive guide about Extension:Collection installation and configuration with instructions for installing on local machines - by edutechwiki (TECFA, University of Geneva).

Advanced and optional configuration

Most wikis will never need to know about what follows. Check the main PHP file to see all the global variables you can configure and their meaning. Some of them are useful to tweak the export in many cases.

Print on demand

Since version 1.6 (r113740) the extension offers the variable $wgCollectionPODPartners that is used to define available providers of the print-on-demand service.

By default it uses PediaPress service:

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

It is an array of elements, every of them will be listed as a possible print-on-demand provider. The parameters are:

name

short name of the provider

url

URL to point for more information if there is no information page

posturl

URL of the actual printing web service

infopagetitle

MediaWiki system message name (as visible in the MediaWiki: namespace) that contains page title of the page that will be used to shortly describe the provider. The default (for PediaPress) is MediaWiki:Coll-order_info_article, which defaults to Help:Books/PediaPress order information. If this page exists, it is used to display information about PediaPress book printing service.

It is also possible to disable print on demand altogether by setting:

$wgCollectionPODPartners = false;

Please see bug 33536 and commit entry for more information about this feature.

You can also configure which file formats are available:

$wgCollectionFormats = array(
    'rl' => 'PDF', # enabled by default
    'odf' => 'ODT',
    'docbook' => 'DocBook XML',
    'xhtml' => 'XHTML 1.0 Transitional',
    'epub' => 'e-book (EPUB)',
    'zim' => 'Kiwix (OpenZIM)',
);

See README.rst for more configuration options.

User rights for saving books

To allow users to save books in both their user space and the community space, add the following lines to your LocalSettings.php:

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

Add the links at another place

If you want to add the links at another place, e.g. in the menu "Personal Tools", you can do that by adding them into the according portlet. For example, in the Vector skin you can do that by adding to the file skins/Vector.php so that it looks like this:

	<h3><?php $this->msg( 'personaltools' ) ?></h3>
	<ul<?php $this->html( 'userlangattributes' ) ?>>
<?php
		$personalTools = $this->getPersonalTools();
 
		/* Links to create a PDF file/a book start */
		if ( class_exists('CollectionHooks') ) {
			$collectionURLs = CollectionHooks::getPortlet($this->getSkin());
 
			if ( $collectionURLs !== false ) {
				/* Put the links of the Collection extension below the last item. */
				$personalTools += $collectionURLs;
			}
		}
		/* Links to create a PDF file/a book end */
 
		foreach ( $personalTools as $key => $item ) {
			echo $this->makeListItem( $key, $item );
		}

You can still modify the order of the links in the portlet by modifying $personalTools directly before the foreach loop is executed.

The above implementation has the drawback, that the two newly inserted links do not show their tooltip. A solution for that is still outstanding and would be greatly appreciated.

Setting book prefix

To change the default prefix for book name edit the message MediaWiki:Coll-community book prefix

Performance

Performance of Collection is...

Cache

Recent versions store rendered "books" in a cache. Collections which have been previously exported by users should be available for download almost immediately, rather than after several minutes of rendering; the cached version can be updated by following a link offered in the download page.

Help improving the extension

If you want to help to make the extension better, you can:

• open a task for a bug or feature request,
  • please also test etherpad:BugTriage-Collection and etherpad:BugTriage-mwlib;
• fix and add translations using translatewiki.net.

Printed Books with PediaPress

Printed Wikipedia books as offered by PediaPress

PediaPress is a service that offers printed books based from wiki content. This service is seamlessly integrated in this extension (can be disabled).

Related

• Extension:PDF_Writer
• Extension:XML_Bridge
• Extension:OpenDocument_Export