Editing together
How several people edit one page at once (Live editing for editors). Part of Architecture.
Several people can edit one page at the same time, and every change shows for the others as it is made. Nothing is saved by this: a revision is made only when someone saves.
Who is here:
- every few seconds (
poll_intervalinframe_editor.settings, 5 by default, between 2 and 60; set it on the components page) the editor posts the id of the selected item to…/presenceand gets back the other editors and the latest revision of the page (id, author, state, time); - each editor is a round avatar in the top bar, and the item another editor has selected has an outline in their colour with their name. The colour comes from the user id, so everyone sees the same one;
- an editor is forgotten 30 seconds after the last poll (Drupal's expirable key value store,
frame_editor.presence). Polling stops while the browser tab is hidden.
What they change:
- the layout of a page and language is a Yjs document in each browser (the
yjspackage, bundled with the editor). Items are maps by id, lists (the page and every slot) are lists of ids, text props are text, so two people typing in the same field are merged character by character. A change in Puck becomes the smallest change of the document, and a change of the document becomessetDatain Puck, which is no step of Puck's history; - the site is only a relay. It never reads the updates: it keeps them in order in Drupal's key value store (collection
frame_editor.live, entriesnid:language:number) and gives the editors what is new. Each entry has the update (base64), the user, the time and a plain summary of the change (items, props, component) that the editor adds. Updates over 1 MB, or that are not base64, are refused; - the editor posts its changes at most every 300 ms, and polls
…/live?since=Nevery second while someone else is on the page, else everypoll_intervalseconds. It stops while the tab is hidden; - an item changed by someone else is outlined for a moment in their colour, with their name;
- a log that has more than 200 entries is shortened: an editor posts a snapshot of the whole document and the entries it has are deleted. A page without entries starts from its latest revision. The live state of a page that nobody changed for 30 days is deleted (on the next read, and on cron);
- Undo and Redo, in the top bar, take back only your own changes; the changes of others stay. Their shortcuts (Ctrl or Cmd with Z, and with Shift or Y) do the same. Puck's own buttons are hidden on pages;
- a save by any other way than the editor (the page form, an import, a script) changes the layout behind the live state. The base marker goes up, the entries are deleted, and the open editors start again from the saved page, with a notice. The editor's own save does not: it says
live: truein the request to the save endpoint. A request to that endpoint without it (a script, an editor that does not edit live) is a save in another way; - templates and saved blocks have no live document: they keep a private unsaved draft per user.
Saving and the History:
- the Save, Publish and Draft buttons save the shared layout. First the editor posts what waits and asks the site once more, so what the others did in the last seconds is in the saved page. Then it saves as before. After the save it posts one more entry, with an update that changes nothing and a note: the revision, its state in words (a moderation state, else Published or Draft) and a fingerprint of the layout it saved;
- an editor who reads such an entry shows "Name saved Published" and adds it to the History. If the layout they hold at that point has the same fingerprint, it is the saved page for them too, and they have nothing unsaved. If not (they changed something after), the page stays unsaved for them;
- unsaved means: the layout in the shared document differs from the layout of the latest saved revision. This is the same for everyone on the page. The changes of others therefore also show "Unsaved changes" until someone saves, and nobody has it after a save;
- the History of a page is the activity since the editor was opened, kept in memory (
liveHistory.js, at most 50 lines). A line is a change of yours, a change of another editor (with their name and colour; what one editor does in a row, within 10 seconds, is one line), or a save. Typing in one field is one line. Undo and Redo add a line for the change they make but are not counted on the History button. The button counts the changes since the last save, while the layout differs from the saved page; - a click on a line restores the layout as it was after that line, as a new change of yours. Going back in time inside a shared document would undo the work of others, so the earlier lines stay, and Undo takes the restore back. A reload starts the History again with one line ("Opened"); the layout itself is shared and comes back;
- under the lines, Saved versions (
SavedVersions.jsx) lists the revisions of the page in this language (RevisionController,/frame-editor/node/N/revisions, 20 at a time,?before=for older ones) with their layouts; the editor compares each with the one before (versions.js,describe()ofhistory.js). The row of the revision that is on the page (a restored one, else the newest) hasaria-current="true"and a background; a restored one that is not saved is explained by one notice above the list, cleared byframe-editor:saved; the revision that is live is labelled Active; The revision log message typed in the Page settings goes with the save of the layout (message), so the revision that holds the layout has it; typing it alone does not make the Page settings a change of their own; - the first item dropped by two editors into the same empty slot: the list of a slot is made together with the item that has it, so both inserts go into one list and both items stay. When another editor deletes the item you have selected, or moves it, your selection follows it or is cleared.