Eplica Transpozor

Content transposing plugin manager for Eplica's Inline WYSIWYG Editor.

The Eplica Transpozor manages the lifecycle of specially written Eplica Inline Editor plugins that know how to search for specific HTML content, replace it with purpose-built structured editing interface, and then transform back to static HTML format when the user hits "Save" in the editor.

Usage.

The transpozor depends on the EPLICA global object being defined, and containing the inlineEditor object. (Both those conditions are automatically met when Eplica Webmasters are logged in.)

So an ideal place to import the transpozor would be in a website's editorStylingRules.js file:

import transpozor from 'eplica-transpozor';

Then use the .addPlugin() method to register any transpozor plugins you have written.

import { myPlugin, myPlugin2, myPlugin3 } from './_js/myplugins';

transpozor
    .addPlugin( myPlugin );
transpozor
    .addPlugin( myPlugin2 )
    .addPlugin( myPlugin3 );

(Note the optional chaining API.)

Custom Events

The transpozor automatically looks for the EPLICA.inlineEditor and does the neccessary event bindings when .addPlugin is called for the first time, so no further configuration is required. (FWIW, the transpozor object also exposes itself as EPLICA.inlineEditor.transpozor.)

Finally, you can use the .on() method to bind custom event-handlers to the start and end of the transposing life-cycle.

transpozor
    .on('start', function (e) {
        // e.editElm (The current inline-editor element)
        // e.transposeElms (Array of HTML elements about to be transposed)
      })
    .on('end', function (e) {
        // e.editElm (The current inline-editor element)
        // e.transposeElms (Array of HTML elements that were just transposed)
      });

The start event triggers as the Inline Editor is starting (during the EditorOpen phase), just before the transpozor searches each inline-editor element for transposable content.

The end event triggers for each inline-editor element during the Save phase, as soon as the transposing editing UIs have been converted back to its final HTML form.

Injecting New Transpose Widgets

A user may want to insert a new/empty transpozor widget into an active Editing zone.

This is most commonly done via the Inline Editor's toolbar as a "HTML Snippet" ("Greinaklippur") similar to this:

<img src="https://eplica-cdn.is/f/e2-w.png"
    data-transpozor-insert="myPluginId"
    onload="EPLICA.inlineEditor.transpozor.rescan()" />

...but it can also be done programatically, like so:

var widgetMarker = document.createElement('div');
widgetMarker.setAttribute('data-transpozor-insert', 'myPluginId');
editElm.appendChild( widgetMarker );
transpozor.rescan();

Advanced Usage

If you want to manually control when the transpozor registers with the inline-editor (i.e. not wait until .addPlugin() is first called), you must call the .registerWithEditor() method. (BTW You can optionally feed it a custom editor instance).

transpozor.registerWithEditor();

editor.addEvent('EditorOpen', someOpenHandler);
editor.addEvent('Save', someSaveHandler);

transpozor
    .on('start', eventHandler)
    .addPlugin( myPlugin );

This allows control over when the transpozor's start and end events trigger in relation to normal Inline-Editor life-cycle event handlers.

You can also optionally feed .registerWithEditor a custom editor instance – if you don't want it to use the default EPLICA.inlineEditor global.

transpozor
    .registerWithEditor( EplicaEditorRef );

Please note, that repeat calls to .registerWithEditor() are simply ignored.