Extension:EtherEditor

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
EtherEditor

Release status: experimental

Implementation Page action, Ajax, Hook, API
Description Allow collaborative editing of wiki pages via Etherpad Lite
Author(s) Mark Holmquist (MarkTraceurtalk)
Latest version 0.2.4 (2012-07-02)
MediaWiki 1.20+
Database changes Yes
License GPLv2+
Download
README
Example Test instance
Parameters

$wgEtherpadConfig

Hooks used
EditPage::showEditForm:initial

ArticleSaveComplete
LoadExtensionSchemaUpdates
GetPreferences
SkinTemplateNavigation

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

Check usage and version matrix; code metrics
Bugs: list open list all report

EtherEditor is an extension that allows a user collaboratively edit with all other users editing a page. It was developed by Mark Holmquist.

Installation and Configuration[edit | edit source]

In order to get this extension working, you'll need to do several things other than actually installing the extension. This is because the extension relies on an external service running somewhere else entirely.

Set up Etherpad Lite[edit | edit source]

Via Git[edit | edit source]

Etherpad Lite can be obtained from their GitHub page. You should download the develop branch like so (but install Git first):

$ git clone https://github.com/ether/etherpad-lite.git -b develop

Via Debian Package (EXPERIMENTAL)[edit | edit source]

You can also try to get the software from the very experimental Debian package prepared for the process of deploying this extension on this site. That package is not currently guaranteed to work, but it might work anyway. If you have any problems, please report a bug via Bugzilla.

Install Relevant Plugins[edit | edit source]

Next, you'll need to set up two extensions for Etherpad Lite. These can be found at the ep_plugins project page at Gitorious. Download both ep_ethereditor and ep_wikiauth, and put them into the node_modules directory inside of the main directory for your Etherpad Lite instance. Probably something like this:

$ cd etherpad-lite
$ ./bin/installDeps.sh
$ npm install git://gitorious.org/ep_plugins/ep_ethereditor.git
$ npm install git://gitorious.org/ep_plugins/ep_wikiauth.git
$ npm install git://gitorious.org/ep_plugins/ep_chatwindow.git
$ ./bin/run.sh

After those commands, you should have a running Etherpad Lite instance on your machine! If you want to set up a more stable system, please see the wiki page at Etherpad Lite's GitHub.

In case the script installDeps.sh complains

$ ./bin/installDeps.sh
Please install node.js ( http://nodejs.org )

although you installed node.js you might need to edit installDeps.sh as well as run.sh and replace the command node by nodejs or create an alias. At least on Ubuntu 12.10 that helps.

Install EtherEditor[edit | edit source]

Now you'll need to actually install EtherEditor itself. Do that like so, starting from your mediawiki directory:

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

Configuring EtherEditor[edit | edit source]

As you probably expected, EtherEditor needs to know where to find your Etherpad Lite instance. So, add a section to your LocalSettings.php that looks like so:

// Enable the EtherEditor extension
require_once( "$IP/extensions/EtherEditor/EtherEditor.php" );
 
$wgEtherpadConfig = array(
	// the API host, for cookies (should be accessible by your users)
	'apiHost' => 'localhost',
	// the API host for the backend (usually localhost)
	'apiBackend' => 'localhost',
	// the API port (because it's often 9001)
	'apiPort' => '9001',
	// the API root path (usually just '/api'
	'apiUrl' => '/api',
	// the pad root path (usually just '/p')
	'pUrl' => '/p',
	// the API key, found in APIKEY.txt in your etherpad lite instance directory
	'apiKey' => 'secret',
);

Change these values as needed. The apiKey value, in particular, will need to be changed--you can find its value in your Etherpad Lite instance's main directory, inside of APIKEY.txt. Be careful not to share this value with anyone!

update.php[edit | edit source]

It's very important that you run maintenance/update.php once you're ready to start using the extension. There are several necessary database tables added by the update hooks.

How to Use[edit | edit source]

See Extension:EtherEditor/How to Use.

How to Test[edit | edit source]

There is now some unit testing support, for both the client and server side, for EtherEditor. This should help the developers a lot, but also if you'd like to make absolutely sure that the extension is doing what it says it's going to do, we've provided ways to do that.

phpunit[edit | edit source]

All right, you have a shiny new tests/phpunit directory in your EtherEditor tree, so let's use it. Assuming you're in the root directory of your mediawiki install, you have followed the instructions for running the main MediaWiki test suite, and you already have a working install of EtherEditor, here are the steps:

$ export MW_INSTALL_PATH=`pwd`
$ cd extensions/EtherEditor/tests/phpunit
$ make tests -B # this will run the tests, it may take a few seconds, but if all is green then you're go!

If any of the tests fail for some reason, please make sure you've followed the instructions for setting up the extension properly, and that your configured Etherpad Lite instance is running. If everything is working on your end, it means you found a bug! Head on over to Bugzilla and give me what for. You deserve it.

qunit[edit | edit source]

WARNING! The remainder of this section assumes that you have manually downloaded Gerrit change 14153. If you try this on the current master, you will totally not be able to do it. This notice can be safely deleted once that change is merged.

qunit tests are significantly easier. First, you'll need to add this variable to your LocalSettings.php:

# Enable javascript testing
$wgEnableJavaScriptTest = true;

Then, navigate to your wiki in a web browser, and go to Special:JavaScriptTest/qunit to run all of the client-side tests in your MediaWiki install. There's no way to reliably find the tests specifically for EtherEditor, but if you scroll around that page, you can choose to run individual tests without the rest. If this will be a frequent activity for you, you should probably bookmark the page for the EtherEditor tests!

And as above, if you find a failed test in the EtherEditor sections, please go to to Bugzilla and give me what for.

Development status[edit | edit source]

This extension is still very new, so don't trust it on a production wiki.

How to help[edit | edit source]

There are the normal channels for getting involved in this extension's development.

  • TranslateWiki has our messages
  • Edit this page to contribute to the community documentation
  • Test the extension at our test instance
  • Report a bug you see with Bugzilla
  • Help with bug reports over at Bugzilla
  • Join the IRC channel, #ethereditor on Freenode, to learn more!
  • Graphic designer? Cool! We could really use a logo....

If you need to learn about the extension first, check out the explanation on this wiki.

Extension History[edit | edit source]

  • 2012-06-13: Mark put up the first test version. It wasn't pretty.
  • 2012-06 through 2012-08: Mark worked on further versions, approaching more stable things.
  • 2012-08-16: A big testing party was held in #ethereditor, and much fun was had by all.

Words about the extension[edit | edit source]

See also[edit | edit source]

Related specs[edit | edit source]

Related extensions[edit | edit source]