Repository files navigation

A collaborative editing module for theQuill text editor used by theReedsy team.

npm install quill-cursors --save

quill-cursors is a Quill module that exposes a number of methods to help display other users' cursors forcollaborative editing.

First,set up a Quill editor.

Next, loadquill-cursors through any of the options presented byUMD.

Load script in HTML:

<scriptsrc="quill-cursors.js"></script>

UsingES6-styleimport:

importQuillCursorsfrom'quill-cursors';

Using CommonJS-stylerequire:

constQuillCursors=require('quill-cursors');

Then, register thequill-cursors module:

Quill.register('modules/cursors',QuillCursors);constquill=newQuill('#editor',{modules:{cursors:true,}});

Finally, use the exposedquill-cursors methods to update the cursors (see below). For an example setup, see theexample code, which can be run with:

npm start

Thequill-cursors module has the following optional configuration:

• templatestring: override the default HTML template used for a cursor
• containerClassstring (default:ql-cursors): the CSS class to add to the cursors container
• hideDelayMsnumber (default:3000): number of milliseconds to show the username flag before hiding it
• hideSpeedMsnumber (default:400): the duration of the flag hiding animation in milliseconds
• selectionChangeSourcestring |null (default:api): the event source to use when emittingselection-change
• transformOnTextChangeboolean (default:false): attempt to locally infer cursor positions whenever the editorcontents change, without receiving an update from the other client. This can be useful for smoother performance onhigh-latency connections.
• boundsContainerHTMLElement (default: Quill's bounds container): the element container used to determine flag positioning
• positionFlag(flag: HTMLElement, caretRectangle: ClientRect, container: ClientRect) => void (default: flip horizontally): an optional function for positioning the caret flag according to its position relative to the bounds container. By default, the flag will flip horizontally when it reaches the right-hand edge of the bounds

Provide these options when setting up the Quill editor:

consteditor=newQuill('#editor',{modules:{cursors:{template:'<div>...</div>',hideDelayMs:5000,hideSpeedMs:0,selectionChangeSource:null,transformOnTextChange:true,},},});

For the custom template to work correctly with the module, it should closely follow the classes in theoriginal template.

By default, QuillJS willsuppressselection-change events when typingto avoid noise.

However, you will probably want to update thequill-cursors selection on bothselection-change andtext-change.In order to aid this,quill-cursors will automatically emit aselection-change event ontext-change.

You can differentiate between user input and thequill-cursors module by checking thesource argument for theselection-change event. By default,quill-cursors will havesource = 'api', but if you need to differentiatebetween calls fromquill-cursors and other events, then you can change thissource using theselectionChangeSourceoption.

If emitting an event is undesirable (eg you wantselection-change to act like the Quill default), then theselectionChangeSource can be set tonull, and an event will not be emitted. Note that in this case, you will need toseparately handle thetext-change event and update the cursor position.

The module instance can be retrieved through Quill'sgetModule:

constcursors=editor.getModule('cursors');

createCursor(id:string,name:string,color:string):Cursor;

Creates aCursor instance with the givenid. If a cursor with thisid already exists, a new one is not created.

• idstring: the unique ID for the cursor
• namestring: the name to display on the cursor
• colorstring: theCSS color to use for the cursor

Returns aCursor object:

{  id:string;  name:string;  color:string;  range:Range;// See https://quilljs.com/docs/api/#selection-change}

moveCursor(id:string,range:QuillRange):void;

Sets the selection range of the cursor with the givenid.

• idstring: the ID of the cursor to move
• rangeRange: the selection range

removeCursor(id:string):void;

Removes the cursor with the givenid from the DOM.

• idstring: the ID of the cursor to remove

update():void;

Redraws all of the cursors in the DOM.

clearCursors():void;

Removes all the cursors from the DOM.

toggleFlag(id:string,shouldShow?: boolean):void;

Toggles display of the flag for the cursor with the givenid.

• idstring: the ID of the cursor whose flag should be toggled
• shouldShowboolean (optional): if set totrue, will display the flag. If set tofalse, will hide it. If omitted, the flag's display state will be toggled.

cursors():Cursor[];

Returns an array of all theCursor objects in the DOM in no particular order.

This code is available under theMIT license.