Managing Versions with eZ Publish

This article is the seventh in a series focusing on concepts and features discussed in the newly released book eZ Publish Content Management Basics. This article provides an introduction to the version management system of eZ Publish, focusing on the content life cycle and the Version history interface.

The target audience includes all content editors responsible for content management through either the Website Interface or the Administration Interface of an eZ Publish website. Readers can review the access requirements for the Administration Interface and Website Interface from the previous articles in this series.

Recall from the first article in this series that a content type is called a content class (or "class" for short), while a specific piece of content is called a content object (or "object" for short). A content class can be thought of as a structural blueprint for a particular type of content. The properties of that content are referred to as attributes. A content object consists of one or more versions. It is this additional layer that makes it possible to have different versions of the same content. Versions are also known as the second dimension of content objects.

Version-related information

The system stores various information related to each version, including a version number, timestamps for when it was created and last modified, the user who created the version and the version status. In addition, for multilingual sites, the system keeps track of the translations within each version.

The life cycle of a content object consists of several statuses (also called "states"), as shown in the illustration below. The main statuses are Draft, Published and Archived. The version with the Published status is the one that is displayed to site visitors. A draft contains content that has been saved but not yet published. Archived versions represent old content that you can revert to if needed.

Life cycle of a content object

We now present a brief overview of what you can and cannot do to a version, depending on its status. This is not exhaustive and does not cover all exceptions, but it gives a good overview of the most common actions and is intended to clarify as well as identify common user errors. As a rule of thumb, a version can only be edited if it is a draft and it can only be edited by the same user who initially created it.

When a new object is created, eZ Publish creates a new draft version. Because the object has not been published yet, its status is set to "Draft" and the current version of the object is unknown. Storing the draft will not change the status of the object. The contents of the draft are simply stored in version 1. The draft version becomes available on the My drafts page and is listed as "Status: Draft" when the version is previewed.

When the draft version is published, both the version and the object status are set to "Published". In addition, the object's current version is set to "1", which indicates the published version of the object. When published, the contents of the object can be viewed by others. Note that up until this point, the contents of the object were not visible on the public site.

You can use the Version history interface to view and manage the versions that belong to an object. In addition to providing an overview of an object's versions, the Version history interface enables you to remove, copy and edit existing versions. As the screenshot below shows, the interface shows the different version numbers, the edited language for each version, information about the version structure, and (for multilingual sites) a dropdown list containing the available translations for each version. The interface has the same overall look and functionality regardless of whether it is accessed from the Website Interface or the Administration Interface:

Version history interface / version overview page

To view version-related information without bringing up the Version history interface, you have to log in to the Administration Interface and either enable the Details window in the main area when viewing the content you want to explore, or open the Object Edit Interface.

Accessing the Version history interface

To bring up the Version history interface in the Website Interface, navigate to the content you want to examine, then click the Manage versions button on the Website Toolbar.

From the Administration Interface, the Version history interface can be accessed by clicking the Manage versions button located inside the Object information window of the Object Edit Interface or by selecting "Advanced - Manage versions" from the context-sensitive pop-up menu.

Comparing versions

The content diff feature is a tool that provides a visual comparison of the differences between versions.

You can access the content diff feature by selecting desired versions from the dropdown lists and clicking the Compare versions button at the bottom right of the top window of the Version history interface.

With the eZ Publish versioning system, you can revert an object from the current version to a previous version. Only a limited number of versions of each content object are stored in the database, to prevent the database from getting too large. By default, this is set to 10, but can be altered by your site administrator.

Do not confuse reverting to a previous version with recovering deleted content from trash. When deleting content, all versions of that content are removed and will vanish from the public siteaccess. In that case, you would need to restore the entire object, instead of a particular version.

To revert to a prior version of an object, make sure you are logged in with your Editor (or Administrator) user account and follow the steps below.

1. Locate the content in question and bring up the Version history interface as previously described.
2. Click the Copy button next to the version to which you want to revert. The selected version will most likely have an Archived status.
3. Click the Edit button next to the newly created version (having the higher version number) to enter edit mode.
4. Click the Send for publishing button at the bottom of the page. You can optionally edit this version before publishing it.

You can resume working on a draft at a later time. However, only the user who created the draft can resume working on it, unlike the situation with published versions, where any content editor can edit them.

Managing drafts from the Website Interface

To view a list of your saved drafts and retrieve one for editing through the Website Interface, access your User profile page (My profile link in the top right when you are logged in) and click on the My drafts link.

This will display a list of drafts belonging to you. Click on the corresponding Edit button on the right to resume editing. You can also click on the name of a draft to bring up a preview, then click the Edit button. Deleting drafts is done by selecting one or more drafts, marking the corresponding checkbox, then clicking the Remove button below the draft. To remove all drafts, click the Empty Draft button.

Managing drafts from the Administration Interface

To bring up a stored draft and continue editing it from the Administration Interface, click on the My account tab, then select My drafts from the left menu. Editing, previewing and deleting drafts is done as described above for the Website Interface, provided that you have accessed your draft list.

Editing conflicts

The built-in version control mechanism alerts you when you trigger an editing conflict. This usually happens when two people are attempting to work on the same content object. Whatever the case, editing conflicts always involve unpublished drafts. Note that content editors do not have to be logged in to the system at the same time for editing conflicts to occur; editing conflicts are triggered whenever you try to edit an object where there is at least one unpublished draft that is newer than the published version.

The simplest way to solve an editing conflict is to decide whether you want to edit the published version or one of the drafts. Note, however, that this might only postpone the editing conflict until the other content editor resumes her work and re-triggers the same editing conflict. Therefore, we recommend that you examine the different scenarios described here.

Editing conflict scenarios

Sometimes when editing an object, you might accidentally close the browser or simply click the Store and exit button (with the intent of resuming the edit process later). The object will then have an unpublished draft. The next time you try to edit the published version of the object, the system will warn you about this. You can select one of the drafts and edit it. This is the most common scenario because there is usually only one unpublished draft. If there are several unpublished drafts, you might want to remove them to avoid further conflicts. Alternatively, create a new draft by clicking the New draft button, or go back by clicking the Cancel button.

A second scenario is that somebody else may be editing the same object that you wish to edit. The other person is either editing the object at the same time or has left an unpublished draft. When you try to edit the same object, the system will display a warning indicating that there is a conflict. The system is simply telling you that you should be careful, because somebody else is working on the same object. There might be several drafts in the list. Unlike in the previous scenario, you cannot edit this draft because it belongs to a different user. You can create a new draft by clicking the New draft button, or go back by clicking the Cancel button.

In the final scenario, somebody else may be editing the same object that you wish to edit (as in the previous scenario), but there are also drafts that you have left on the system. This is the worst-case scenario and you should definitely contact the other user(s) before doing anything else. You might also want to take the opportunity to sort through all of your other drafts.

Good editing practices

Each content editor can help to reduce the number and frequency of editing conflicts by adopting some easy and basic editing routines. You should always exit edit mode by clicking the Send for publishing, Discard draft or Store and exit button. Clicking your web browser's Back button is a very common mistake that is responsible for many stale drafts.

When you wish to edit an existing content object, remember that there might be unpublished draft(s) of this content. You can select one of the drafts and edit it either from the My drafts page, the Version history interface, or from the list that displays when you trigger an editing conflict.

We encourage all content editors to regularly check the draft list. Remove any drafts that you do not intend to work on and that have become deprecated. In other words, clean up this list on a regular basis and aim to have it contain only your work-in-progress drafts.

Every time you click either the Create or Edit button, eZ Publish automatically creates a new version of the content. The version mechanism follows a "copy-and-edit" approach rather than an "overwrite / replace" approach. The system stores information related to each version, including a version number, timestamps for when it was created and last modified, the user who created the version and the version status.

The life cycle of a content object consists of several statuses. The main statuses are Draft, Published and Archived. As a rule of thumb, a version can only be edited if it is a draft and it can only be edited by the same user who initially created it.

The Version history interface makes it possible to view and manage the versions that belong to an object, enabling you to remove, copy, edit and compare existing versions.

eZ Publish alerts you when you trigger an editing conflict. This usually happens when two people are attempting to work on the same content object, and the easiest solution is to decide whether you want to edit the published version or one of the drafts, then select the desired version and click the Edit button.

Resources

• eZ Publish Content Management Basics
• eZ documentation site
• An Introduction to eZ Publish Concepts - first article from this series
• Creating Content Quickly and Easily with the eZ Publish Website Interface - second article from this series
• Formatting Text with the eZ Publish Online Editor - third article from this series
• Layout of the eZ Publish Administration Interface - fourth article from this series
• Advanced Content Editing with the eZ Publish Administration Interface - fifth article from this series
• Cross Publishing Content in eZ Publish - sixth article from this series