Document Versions

Installation

To install the module, use the command line to run this command in an Apostrophe project's root directory:

npm install @apostrophecms-pro/document-versions

Usage

Configure the Document Versions module in the app.js file:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms-pro/document-versions': {}
  }
});

Open the Document Versions manager

The module doesn't need any additional configuration. The document versions will be created automatically after every document publishing operation - create or update. The dedicated management area can be accessed via the document context menu labeled "Document Versions" - it is presented together with the core menu actions "Edit", "Duplicate...", "Localize...", etc.

List and View Document Versions

Past versions of the document can be viewed by selecting them from the list at the far right side of the document versions dialog box. Every version shows its creation date and author and they are ordered by the reverse date of their creation. The most recent version is on top. When initially entering the document versions management area the most recent (first in the navigation on the right) version will be loaded and its content will be previewed in the center of the screen. The preview layout is the same as the well-known Editor dialog box. The field groups navigation is on the left and the corresponding content schema is in the middle. The only major difference is that the fields are read-only.

Version preview may be switched via the right-side navigation by clicking the desired date. When the desired document version has been identified, clicking on the restore button at the top-right of the dialog box will restore the Draft of the document currently being viewed. Keep in mind this operation won't publish your change, this has to be done manually.

Comparing Document Versions

Clicking on the "View Options" button at the top of the dialog box will open a menu with two options which are both turned off by default. The first option is "Compare versions". Activating this option by clicking the toggle will split the middle section of the dialog box.

The left side of this new view displays the document selected in the navigation. This is the document that will be restored when the "Restore" button is clicked. The right side of the new view will display the document version selected from the dropdown menu. Any fields that have had changes between the two document versions will be highlighted. The field groups navigation on the left side of the dialog box allows you to check each group in the schema for changes.

The other option available after clicking the "View Options" button is "Only show differences". Toggling this option will cause the split section to only display fields from the entire schema that have changed between the selected documents. This will also remove the left-side field groups navigation since any changed field, regardless of the group, will be shown. In this example, the content manager can easily see that one of the SEO fields has changed. Again, the document to be restored is chosen using the side navigation, while the document it is compared against is selected from a drop-down menu above the right side's document display area.

What documents are under version control?

• Document types may explicitly opt into document versions with versions: true. This option takes precedence over autopublish. See below.

What documents are not under version control?

• Every document type that is explicitly disabling versions (versions: false).
• Every document type that is explicitly enabling autopublish (autopublish: true) and not explicitly enabling versions.
• Every document type that is explicitly disabling localization (localized: false). For example, the core piece "Users" will not have any versions recorded because it has the localized option set to false.