Keep the history of a column

An article is edited many times. Sometimes a good paragraph is removed by mistake, or somebody asks what the headline said last Tuesday. A versioned column keeps every save of its value, and a versions region shows that history on the record’s page.

Mark the columns to keep

Add versioned to each column whose history you want to keep.

table posts "Posts" {
  title text required versioned "Title"
  body  markdown required versioned "Body" { max_kb: 256 }
}

Each save that changes one of these columns now adds a version. A version holds the values of all the versioned columns, the time of the save, and who saved it. Saves by one person within 10 minutes are one version, so a burst of typo fixes does not push older versions out.

Each record keeps its 20 newest versions. To keep a different amount, add versions keep to the table:

versions keep 20 within 1y

The limits are in The versions statement.

Show the history on the record’s page

Add a versions region to the page that edits the record. Give it the roles that may see the history.

page newsroom_post "{:post.title}" {
  route: /newsroom/posts/{id}
  access: admin, editor

  data post of posts

  form of posts {
    fields: title, body
  }

  versions of posts "History" {
    access: admin, editor
  }
}

The page now lists the saves, newest first. Each line shows when the save happened, who made it, which columns changed, and the record’s status at the time. The name is the person’s profile name, and never an e-mail address.

A history names the people who worked on a record. Give the region an access: of its own. Without one, the region follows the page’s rule, and a visitor without a sign-in does not see it.

Compare two saves

Select Compare on a line. The page shows what changed since the save before it: each text line that was removed and each line that was added, marked with a sign and a word as well as a colour. A date, a number, or a choice shows its value before and after.

The comparison is an ordinary address, so it works without JavaScript and can be shared with a colleague who may see the history.

Restore an old save

Select Restore on a line. The page’s form opens with that save’s title and body in it. The other fields keep their current values.

Check the form and press Save. The save runs every rule the form has, and adds a new version. The old versions stay as they were, so a restore can itself be undone.

If somebody else saved the record after you opened the restore form, the first Save is refused and tells you so. Check the values and press Save again to restore anyway.

Restore is offered only to a person whose form on this page may edit the record. An author who may see the history but not edit the record gets no Restore link.

Understand what the history does not keep

• Deleting a record deletes its history.
• A picture is not versioned, and an old version does not keep a picture in a Markdown text alive. Restoring a text whose picture was deleted is refused, and the message names the picture.
• A sensitive column cannot be versioned yet.

To remove part of a history, for example after a request to erase a name, the operator edits the organization’s file. The application cannot declare it.