Extension:EtherEditor/How it works
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
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
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
Pad URLs have to be built on the server side because of the information involved. Here's an example:
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.
How the text from the pad gets submitted to MediaWiki
In order to get the text from the pad into the wiki page, we take a bit of a long path:
- Call the MediaWiki API, to an EtherEditor method, that will fetch the text
- The API module calls an Etherpad Lite API method that fetches the text
- The EtherEditor API module returns the text to the frontend code
- 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.
If you have other things you want explained, make a suggestion on IRC or on the talk page here.