Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ritzyed/ritzy

Collaborative web-based rich text editor
https://github.com/ritzyed/ritzy

Last synced: about 1 month ago
JSON representation

Collaborative web-based rich text editor

Awesome Lists containing this project

README 

        
= 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:



* 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.