Extension:EtherEditor/How it works

From MediaWiki.org
Jump to: navigation, search

This is a summary of the moving parts of EtherEditor. I'll write this from a big-picture standpoint, but ask questions (e.g. in our IRC channel, #ethereditor) if you have any.

What we do when the edit page gets loaded[edit]

In order to use the editor, we need some extra information on the client side. We load that up in our EditPage::showEditForm:initial hook, which is defined in EtherEditorHooks.php.

$output->addJsConfigVars( array(
  'wgEtherEditorDbId' => $epPad->getId(),
  'wgEtherEditorOtherPads' => $epPad->getOtherPads(),
  'wgEtherEditorApiHost' => $apiHost,
  'wgEtherEditorApiPort' => $apiPort,
  'wgEtherEditorPadUrl' => $wgEtherpadConfig['pUrl'],
  'wgEtherEditorPadName' => $epPad->getEpId(),
  'wgEtherEditorSessionId' => $sessionId ) );

How the collaboration mode gets set up[edit]

When the user actually clicks on the collaborate checkbox, a few different javascript methods get called. enableEther, which enables the functionality of the extension and sets up some callbacks; initializePad, which actually loads the pad interface, and a bunch of different other setup methods.

Basically what happens is, we embed an iframe element into the page tha contains the actual pad interface, hide the normal textarea, and set up a few sneaky methods for sending signals back and forth.

How we come up with a pad URL[edit]

Pad URLs have to be built on the server side because of the information involved. Here's an example:

 http://etherpad.wmflabs.org/pad/p/g.s8oes9dhwrvt0zif$original

The important parts are the URL to the base of the pad directory and the group ID. We get the first from the configuration of the wiki (it's part of the stuff you configure before you can use the extension), but the group ID is brought over from the Etherpad Lite instance. Groups are the only way we can implement any authentication, so we use them for everything. They also help us by solving the problem of special characters, since hashing the page name gets rid of anything Etherpad Lite might deem inappropriate for pad URLs. We can just pass in the literal string "original" as the pad name and be done with it.

Read more about Etherpad Lite groups and other data types

How we implemented the normal wikitext format buttons[edit]

The first few iterations of EtherEditor used a modified set of the Etherpad Lite formatting buttons. Now, we use the native MediaWiki ones (though we highly suggest the WikiEditor extension) through a little-known hack that lets a JavaScript program submit POST requests to iframes. Essentially, we POST signals to Etherpad Lite (and specifically, a required plugin that we wrote) that say "hey, the user wants this text bolded", and the Etherpad Lite plugin will add the proper wikitext. However, it's not as simple as that. We also need to know whether the pad has been loaded. For this purpose, we have a signal that we send from the plugin, back to the parent DOM. That signal doesn't take very long to load, but if we tried to set things up on the pad without the plugin being loaded, bad things might happen.

How the text from the pad gets submitted to MediaWiki[edit]

In order to get the text from the pad into the wiki page, we take a bit of a long path:

  1. Call the MediaWiki API, to an EtherEditor method, that will fetch the text
  2. The API module calls an Etherpad Lite API method that fetches the text
  3. The EtherEditor API module returns the text to the frontend code
  4. We stick the text into the textarea where it started

After that, the user could have hit any of the three "save-like" buttons at the bottom of the page, and we can still handle it.

TODO: It might be possible to use the same method as we use for the formatting buttons (see above) to transfer the text into the textarea.

Others?[edit]

If you have other things you want explained, make a suggestion on IRC or on the talk page here.