Extension:EtherpadLite

From MediaWiki.org
Jump to: navigation, search
shortcut: EPL
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.png
EtherpadLite

Release status:Extension status stable

ImplementationTemplate:Extension#type Tag, User interface
DescriptionTemplate:Extension#description The extension adds a tag <eplite> to the MediaWiki parser and provides a method to embed Etherpad Lite pads on MediaWiki pages. The Etherpad Lite server is not part of the extension.
Author(s)Template:Extension#username Thomas Gries (Wikinauttalk)
Latest versionTemplate:Extension#version 1.13 (2012-03-19)
MediaWikiTemplate:Extension#mediawiki 1.19+
PHPTemplate:Extension#php 5.3+
Database changesTemplate:Extension#needs-updatephp No
LicenseTemplate:Extension#license GPL; MIT
Download
TagsTemplate:Extension#tags
<eplite>
Hooks usedTemplate:Extension#hook
ParserFirstCallInitManual:Hooks/ParserFirstCallInit

Translate the EtherpadLite extension if it is available at translatewiki.net

Check usage and version matrix.

IssuesPhabricator

Open tasks · Report a bug

The EtherpadLite extension adds a tag <eplite> to the MediaWiki parser and provides a method to embed Etherpad Lite pads on MediaWiki pages. The Etherpad Lite server is not part of the extension.

The Wikiuser username is automatically preset as Etherpad editor and chat username (pictured). In the current version, the Etherpad username can be overwritten and forged by pad users.[1]

Warning Warning: This extension may have security issues if $wgEtherpadLiteUrlWhitelist isn't set to a list of allowed Etherpad Lite servers.

Usage[edit]

Some differently flavoured examples are shown. See screenshot and source code for complete list of parameters. You can determine pad servers, pad names (id), width, height of the window (iframe) on the MediaWiki page and many more parameters. Basically, you only have to indicate a pad name.

<eplite id="mytestpad" />
<eplite id="MyPseudoSecretPadHash-7ujHvhq06g" height="200px" width="600px" />
<eplite src="https://www.example.com/p/" id="mytestpad" />
<eplite id="mytestpad" show-controls="false" show-linenumbers="false" show-chat="false" monospaced-fonts="false" />

20120211 Extension EtherpadLite screenshot with three pads on MediaWiki page.png

Installation[edit]

The extension can be retrieved directly from Git [?]:

  • Browse code
  • Some extensions have tags for stable releases.
  • Each branch is associated with a past MediaWiki release. There is also a "master" branch containing the latest alpha version (might require an alpha version of MediaWiki).

Extract the snapshot and place it in the extensions/EtherpadLite/ directory of your MediaWiki installation.

If you are familiar with git and have shell access to your server, you can also obtain the extension as follows:

cd extensions/
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/EtherpadLite.git


  • Download and place the file(s) in a directory called EtherpadLite in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    require_once "$IP/extensions/EtherpadLite/EtherpadLite.php";
    
  • YesY Done - Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Warning Warning: This extension may have security issues if $wgEtherpadLiteUrlWhitelist isn't set to a list of allowed Etherpad Lite servers.

Prerequisites[edit]

You need at least one Etherpad Lite host server on which the pad lives. Assign the base-URL to $wgEtherpadLiteDefaultPadUrl as shown above. For test purposes only —not for production— you can use the project's test server http://beta.etherpad.org/p/ at your own risk.

For setting up your own Etherpad Lite server (based on node.js) see Etherpad Lite homepage https://github.com/ether/etherpad-lite.

The extension is based on:

The present MediaWiki extension does not require jQuery, it adds an <iframe>.

Pads which use resources from external domains will presumably not work fine in all browsers due to modern security concepts relating cross site scripting attacks.

Configuration settings[edit]

parameter default needed comment
$wgEtherpadLiteDefaultPadUrl http://beta.etherpad.org/p/
see comment
needed The default pad server base-URL which is used if no specific pad server base-URL is assigned in <eplite> tag. The src= attribute can be used to assign a pad server base-URL and is needed if you want to use more than one pad server.
  • The installation default value is the URL of the Etherpad Lite developers' test pad as shown. You cannot rely on its availabilty and service continuity. So for production wikis, you need to set an other pad server base-URL such as https://only-or-most-used-pad-server.org/p/ as default to your wiki editors.
$wgEtherpadLiteUrlWhitelist array()
see comment
needed For a maximum level of security, you should limit the usage to a distinct whitelist of base-URLs of Etherpad Lite servers
  • like array("https://only-or-most-used-pad-server.org/p/", "https://another-reliable-pad-server.org/p/");
  • Set it to array($wgEtherpadLiteDefaultPadUrl) if you expressly want to allow your default pad server base-Url (see above) only, which makes sense. As it's an array, you can combine it like array($wgEtherpadLiteDefaultPadUrl, "https://another-reliable-pad-server.org/p/")
  • Wildcards for subdomains are regrettably not usable. Each team has its own base-URL needed to be allowed.
  • Set it to array("*") if you expressly want to allow all URLs. Do not allow all URLs in public Internet wikis — it is not clever!
  • An empty array (array(), the installation default) or non-existent array means: no whitelist is defined, no pads are allowed.
$wgEtherpadLiteDefaultWidth "300px" Your editors' default pad width; CSS units can be used
$wgEtherpadLiteDefaultHeight "200px" Your editors' default pad height; CSS units can be used

Deinstallation[edit]

  1. remove the require_once( "$IP/extensions/EtherpadLite/EtherpadLite.php" ); from your $IP/LocalSettings.php
  2. delete $IP/extensions/EtherpadLite subdirectory

Known bugs[edit]

See also[edit]

References[edit]

  1. filed as T38319 "E:EtherpadLite - Implement correct user authentication and user name setting using the EtherpadLite API".