[1] IE10+ and evergreen browsers supported, perhaps earlier browsers will work
too.
Note that the code is alpha quality.
=== Longer Introduction
The Ritzy editor is a rich text, real-time character-by-character collaborative
embeddable browser-based editor. It shuns use of the
https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_Editable[contentEditable]
attribute in favor of a custom editor surface and layout engine, exactly like
the approach
http://googledrive.blogspot.ca/2010/05/whats-different-about-new-google-docs.html[implemented
by] Google Docs.
In addition, and also like Google Docs, Ritzy is built with real-time
collaborative editing support from the ground up, unlike most browser-based
editors that require third-party plugins or that do not support it at all. The
underlying mechanism for this is a
https://github.com/ritzyed/ritzy/blob/master/docs/DESIGN.adoc[causal tree CRDT].
Ritzy implements all the basic expected text editing functionality, such as
bold, underline, strikethrough, superscript, subscript, selection via keyboard
and mouse, cut, copy, and paste. More capabilities will be added as needed or as
third-party contributions are received.
[[about_other]]
=== Features
Real-time collaborative text editing just like Google Docs, with all the basic
standard editing features and shortcuts.
Multiple author colored/labeled cursor and selection tracking in real-time.
Paragraph flow control, including wrapping support for long words/URLs.
Selection and keyboard navigation behavior mimicking common platforms like
Microsoft Word and Google Docs.
Cursor decorations such as blinking with focus and idle, slant when traversing
italic text, and invisible when there is no focus.
Selection decorations such as gray-out when editor does not have focus.
Automatically scrolling the document window horizontally and vertically to
keep the cursor visible.
Cut/copy/paste of clipboard data, including conversion between rich text and
HTML, including support for copy/paste to/from Microsoft Word.
API to control the editor and to obtain selections as rich text, HTML, or
plain text.
Input handling and support for non-english languages.
Offline simultaneous editing.
=== Limitations and Target Audience
Unlike Google Docs, Ritzy does not (currently) support complex page-based layout
needed to build a word processor. It will be most useful for those developers
who wish to add collaborative rich-text data entry fields to their browser
applications. However, some layout capabilities are planned to be added over
time, such as bulleted and numbered lists, styles, and other such features.
==== Mobile Support
Mobile is partially supported. On a Nexus 5 and Nexus 7 with a recent Chrome,
the following seem to work:
basic text entry (though there are some quirks – for some reason the phone
wants to capitalize every word and not enter spaces automatically),
cursor positioning, and
real-time view of other people's cursors, selections, and typing.
Ritzy has not yet been tested on any iOS devices, but it is likely with some
tweaking similar capabilities as noted above will be possible on any recent
model.
Selections do not work at all. It is possible that this is an intractable
problem with the editor as it exists today, given how selections on mobile work.
One possible solution is to take the same approach that Google appears to have
taken with Docs – for editing, create a native component that talks the same
underlying data exchange language for collaboration, but with native rendering
of the editor and interaction with the user. There are no immediate plans to
work on this.
As an aside, similar integration could be done for native desktop editors.
==== Production Readiness
The code is alpha quality. Lots of real-world testing is needed. While the
client side is pretty performant once the editor is loaded, lots of optimization
work remains to be done, especially on the underlying CRDT data structures.
== Supported Data Formats
Ritzy can import and export data in JSON, HTML, and text. See
https://github.com/ritzyed/ritzy/blob/master/docs/API.adoc#contents[API Content]
and https://github.com/ritzyed/ritzy/blob/master/docs/API.adoc#selection[API
Selection].
=== Rich Text JSON
Ritzy can import and export a JSON structure containing an array of text chunks
with associated attributes. These attributes are currently boolean values for
bold, italics, and so forth, but could in the future include other values such
as style names.
TIP: This format is "full fidelity" i.e. exported rich text data is guaranteed to be
imported exactly. Here is an example:
[source,javascript]
let content = [
{ 'text': 'This is some ', 'attrs': null },
{ 'text': 'bold', 'attrs': {'bold': true} },
{ 'text': ' text.', 'attrs': null }
]
=== HTML
Ritzy can import and export HTML. This is used internally by the editor when
copying/pasting rich text to external applications such as Word or Google Docs.
=== Plain Text
Ritzy can import and export plain text. This is used internally by the editor
when copying/pasting plain text to external applications such as text editors.
=== Native Causal Tree CRDT
The internal data model for the editor is a causal tree CRDT described in the
https://github.com/ritzyed/ritzy/blob/master/docs/DESIGN.adoc[DESIGN].
In addition to the formats described above which will be used most often, this
data is also accessible via the
https://github.com/ritzyed/ritzy/blob/master/docs/API.adoc[API].
WARNING: This format is not final, and is subject to change in future versions.
[[usage]]
== Usage
Ritzy is an ES6 React component with an optional API wrapper. Currently, it does
require a server-side implementation to support collaborative editing. In the
future, this will be optional.
See the
https://github.com/ritzyed/ritzy/blob/master/docs/INSTALLATION.adoc[INSTALLATION]
document for information about how to integrate Ritzy into your client and
server-side infrastructure.
[[roadmap]]
== Roadmap
The following is a tentative list of features and capabilities that will be
added over time.
https://github.com/ritzyed/ritzy/blob/master/docs/CONTRIBUTING.adoc[Contributions]
are welcome.
Tests (many, see GitHub issue xx) (hard!).
Once tests are in place, refactoring to make the editor code more modular /
easier to understand (hard).
Undo/redo (hard).
Make Ritzy work without a shared replica and server implementation -- create
a local-only replica with the same API (medium).
Performance improvements. Performance is pretty good right now, but much can
be done to improve it further. Some ideas:
** Use immutable collections as much as possible e.g.
http://facebook.github.io/immutable-js/
** Implement some type of compression and/or indexing for characters within the
causal tree CRDT.
** Clear stale data from the causal tree CRDT, such as deletions (but keep
enough for revision history).
** Cache frequently used / slow operations where possible.
** Server-side performance improvements. Currently the initial load can become
very slow as the replica continues to grow.
Styles for content e.g. headings, lists, etc. (medium).
Add to the API (easy):
** Insert HTML at a particular position specified by the native data model
** Command and status support for text attributes e.g. to support a toolbar
** See http://w3c.github.io/editing/historic-editing-apis.html[Historic Editing
APIs] for comparison/implementation with contentEditable-based APIs.
A skinnable and/or replaceable toolbar that leverages the editor API (medium).
Test and support editor fonts other than OpenSans (easy to medium?).
Handle font size as a character attribute (medium to hard).
Reduce the number of dependencies and lower download size as much as is
possible without sacrificing clarity and maintainability.
Search/replace (TODO).
Figures and tables (TODO).
Bullets and numbering (TODO).
Inline images (TODO).
Right-click menu support (medium).
Color-coded authoring display (medium).
Text highlighting (easy to medium?).
History/timeline/revision view (hard).
Drag and drop support (medium).
[[commercial_features]]
== Commercial Features (Future)
In addition to the editor which will remain free and open source,
http://vivosys.com[VIVO Systems], the organization behind Ritzy, is considering
offering the Ritzy editor as a service. A server-side component is required for
real-time collaboration.
NOTE: A simple but working server-side component is bundled. See the
https://github.com/ritzyed/ritzy/blob/master/docs/INSTALLATION.adoc[INSTALLATION]
documentation.
The commercial server-side solution will handle storage, communications,
security, availability, and provide a simple but powerful server-side API for
developers to interact with the editors under their control, and the data they
contain. Some of the features of this API may include:
Create, archive, and destroy text replicas.
User identification and specification of authoring labels.
Set and modify access control.
Get editor contents (snapshot + real-time bidirectional push).
** Integration with various server-side libraries e.g. Akka, Vert.X, RxJava,
Kafka, etc.
Set or modify editor contents.
Show server feedback on editor surface e.g. comments/errors/word highlights.
Get revision history.
Get editing statistics e.g. authors, character count overall and by author,
word count overall and by author, time spent editing overall and by author, and
so forth.
Isomorphic rendering of editor's server-side and client-side for performance.
Please
mailto:sales@vivosys.com?subject=Interested%20in%20the%20Ritzy%20Service[let us
know] if your company or startup may be interested in such a service.
[[developers]]
== Developers
See
https://github.com/ritzyed/ritzy/blob/master/docs/CONTRIBUTING.adoc[CONTRIBUTING]
and
https://github.com/ritzyed/ritzy/blob/master/docs/DEVELOPMENT.adoc[DEVELOPMENT].
== Support
Support is provided on an as-available basis via
https://github.com/ritzyed/ritzy/issues[GitHub issues].
Contact mailto:raman@vivosys.com[raman@vivosys.com] @
http://vivosys.com[VIVO Systems] for paid support or enhancements.
Ecosystem Role
Standard MoltPulse indexed agent.
Embed Badge
Show off your Pulse Score in your GitHub README to build trust and rank higher.