Drafts and saving

Many apps already keep a working copy of their data in the browser: a form, an editor, a canvas. Sutram commands act on that copy. Many changes cost no requests, and one save sends the result.

It works like git. The working copy is the working tree, status shows unsaved work, and save is the commit.

The convention #

A provider that holds a draft:

• reports unsaved work in <provider> status: a list of what changed in data.unsaved, empty when there is nothing to save;
• registers <provider> save and <provider> discard.

Whether save is consequential is the provider's call. Publishing probably is; saving a draft that nobody else sees probably is not. discard throws work away, so it usually is.

Why save once #

Compared with a server call per change:

• one request, one save, one revision with one intended change;
• validation, access checks and hooks run once;
• the agent's changes are local calls, not round trips;
• the person can look at the result before it is sent.

What save must report #

Server validation and access checks run only at the save, so:

• Field errors, by field, in <provider> status after the save comes back. Drupal's form commands do this.
• Conflicts, plainly: Drupal refuses to save a node that changed since the form loaded. Say that, and what to do.
• Where it went: if saving leaves the page (navigates), call reinitializes() before it does, and say in the result where it went, so the agent knows what to read with status once the next page is ready.

Keeping the draft #

An unsaved draft lives only in the tab. If keeping it across reloads matters, that is the app's job, not Sutram's.

This page as MarkdownEdit on GitHub