For a deeper understanding of how the system is pieced together check out these articles:
Typester uses a combination of Containers, Modules, that interact via Mediators.
The architecture layout is:
- AppContainer (/containers/AppContainer.js)
- Mediator
- Modules:
- ContentEditable (/modules/ContentEditable.js)
- Selection (/modules/Selection.js)
- UIContainer (/containers/UIContainer.js) :: [singleton]
- Mediator ⇄ AppContainer.Mediator
- Modules:
- Flyout (/modules/Flyout.js)
- Toolbar (/modules/Toolbar.js)
- Mouse (/modules/Mouse.js)
- FormatterContainer (/containers/FormatterContainer.js) :: [singleton]
- Mediator ⇄ AppContainer.Mediator
- Modules:
- BaseFormatter (/modules/BaseFormatter.js)
- BlockFormatter (/modules/BlockFormatter.js)
- TextFormatter (/modules/TextFormatter.js)
- ListFormatter (/modules/ListFormatter.js)
- LinkFormatter (/modules/LinkFormatter.js)
- Paste (/modules/Paste.js)
- CanvasContainer (/containers/CanvasContainer.js) :: [singleton]
- Mediator ⇄ AppContainer.Mediator
- Modules:
- Selection (/modules/Selection.js)
- Canvas (/modules/Canvas.js)
Containers serve two purposes:
- Instantiate a mediator, with any provided
mediatorOpts, and, if a parent mediator is provided, link it. - Group and instantiate related modules passing the
mediatorinstance and a rootdomcollection
Example
import Selection from '../modules/Selection';
import Canvas from '../modules/Canvas';
const CanvasContainer = Container({
name: 'CanvasContainer',
modules: [
{ class: Selection },
{ class: Canvas }
],
/**
* @prop {object} mediatorOpts - Container specific mediator options. For the
* CanvasContainer the mediator is set to conceal, and not propagate, any messages
* from the selection module. This is to avoid cross contamination with the selection
* module used on the page.
*/
mediatorOpts: {
conceal: [
/selection:.*?/
]
},
handlers: {
events: {
'canvas:created' : 'handleCanvasCreated'
}
},
methods: {
init () {
},
handleCanvasCreated () {
const { mediator } = this;
const canvasWin = mediator.get('canvas:window');
const canvasDoc = mediator.get('canvas:document');
const canvasBody = mediator.get('canvas:body');
mediator.exec('selection:set:contextWindow', canvasWin);
mediator.exec('selection:set:contextDocument', canvasDoc);
mediator.exec('selection:set:el', canvasBody);
}
}
});Mediators serve as the primary way for Containers and Modules to interface with each other. This is done using call strings which are mapped to methods at the Container / Module level.
Call strings take the format of modulename:method:name.
There are 3 types of message handling:
- Commands - One-to-one message with no response.
- Requests - One-to-one message with a response.
- Events - One-to-many message with no response.
When declaring a Module or a Container adding a handlers object formatted as follows, will result in the mediator registering and mapping the call string to the named method.
handlers: {
commands: {
'methodname:do:something' : 'doSomething'
},
requests: {
'methodname:get:something' : 'getSomething'
},
events: {
'othermethodname:event:name' : 'reactToEvent'
}
},
methods: {
doSomething () { ... },
getSomething () { ...; return ...; },
reactToEvent () { ... }
}Note Modules declared via a Container will automatically receive the Container's mediator instance
Modules are the workhorses of this architecture. Any code that does anything of value should be placed here. The underlying structure of a module is:
import Module from '../core/Module';
const MyModule = Module({
// required
name: 'MyModule',
/**
* An enumerable collection of properties that will be accessable
* via this.prop
*/
props: {
foo: 'bar',
ping: 'pong',
maxCount: 0
},
/**
* Describe which DOM elements need to be found, and cached, from
* inside the root element.
*/
dom: {
'moduleElem' : '.module-elem' // Accessable with this.dom.moduleElem
},
/**
* The handlers available from this module that will be registered
* with the provided mediator
*/
handlers: {
commands: {
'mymodule:do:something' : 'doSomething'
},
requests: {
'mymodule:get:something' : 'getSomething'
},
events: {
'anothermodule:did:something' : 'reactToSomething'
},
/**
* These are bound directly to the DOM elements related to
* the module
*/
domEvents: {
'click' : 'rootClick', // Bound to dom.el[0],
'click @moduleElem' : 'moduleElemClick' // Bound to dom.moduleElem
}
},
/**
* This modules methods.
*/
methods: {
/**
* A hook that will be called when the module is ready for
* initialization
*/
setup () {...},
/**
* A hook that will be called once the module has been initialized
*/
init () {},
/**
* The rest is up to you to declare
*/
doSomething () { ... },
getSomething () { return 'something'; },
reactToSomething () { ... },
rootClick (evnt) { ... }, // evnt is the DOM event
moduleElemClick (evnt) { ... }
}
});
new MyModule({ el: document.querySelector('.my-module'), mediator: /* a mediator instance */});When working in the module methods you can access the module properties and methods
off of the this context of the method. The example module above's context
will be structured as follows:
{
props: {
foo: 'bar',
ping: 'pong',
maxCount: 0
},
dom: {
el: [<domnode>], // the el options provided when instantiating the module
moduleElem: [<domnode>]
},
mediator: mediator, // the mediator instance provided when instantiating the module
setup () {},
init () {},
doSomthing () {},
reactToSomething () {},
rootClick () {},
moduleElemClick () {}
}You are then able to destructure what you need from the context.
methods: {
doSomething () {
const { dom, props } = this;
dom.moduleElem.innerText = props.maxCount;
}
}Typester uses an <iframe> as a sandboxed DOM canvas inside which the
formatters can work on the content in isolation without poluting the
edit (undo/redo) history of the editor.
It also frees the formatters to use a combination of documentExec and direct DOM manipulation to get the desired results.
Once the formatting is complete the canvas body's innerHTML is copied and pasted into the editor, resulting in only a single edit history item being logged.
(core/BaseFormatter.js) - Common formatting logic
(core/BlockFormatter.js) - Formatting logic for block level element formatting (H1, H2, Blockquote, etc.)
(core/LinkFormatter.js) - Formattting logic for creating/updating/removing links
(core/ListFormatter.js) - Formatting logic for creating/updating/removing lists
(core/TextFormatter.js) - Formatting logic for inline/text formatting (bold, italic, etc.)
The formatters use a combination of:
- Pre-processing - Exporting the selection to the canvas and manipulating it in preparation for formatting
- Processing - Using a combination of documentExec commands and some DOM manipulation to get the desired formatting output, all done inside the canvas.
- Post-processing - Cleaning up and standardizing the processed output to iron out browser quirks.
- Commiting - Exporting the formatted content from the canvas and updating the content in the editor.
A typical formatting flow is as follows:
- Export to canvas
- Inject selection hooks before and after the editor's content
- Calculate the selection range coordinates, used by the canvas to clone the selection range.
- Clone all the nodes in the editor
- Export the cloned nodes to the canvas
- Set the selection range using the range coordinates calculated earlier
- Apply the formatting
- This can vary formatter to fomatter. See the formatter specific docs for more details
- Import the formatted content back from the canvas
- Cache the selection range, as it may be altered or lost during the next couple of steps
- Clean the formatted content inside the canvas
- If an additional importFilter has been provided, call it with the canvasBody element as the argument
- Re-apply the cached selection range
- Calculate the selection range coordinates inside the canvas
- Import the canvas HTML into the editor
- Set the selection range inside the editor using the coordinates calculated earlier
- Emit a complete event