= Ritzy Editor :toc: :sectanchors:
image:https://badges.gitter.im/Join%20Chat.svg[link="https://gitter.im/ritzyed/ritzy?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"] image:https://img.shields.io/badge/license-Apache-blue.svg[link="http://opensource.org/licenses/Apache-2.0"] image:https://img.shields.io/npm/v/ritzy.svg[link="https://www.npmjs.com/package/ritzy"] image:https://travis-ci.org/ritzyed/ritzy.svg[link="https://travis-ci.org/ritzyed/ritzy"]
[[about]] == About
=== Demo / Short Introduction (TL;DR)
Finally, a good, open source, cross-browser [1], rich text, real-time, embeddable, collaborative editor for the web! Here is a demo:
http://demo-ritzy.rhcloud.com/ (https://github.com/ritzyed/ritzy-demo[source])
[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:
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:
=== 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.