TYPO3 offers versioning of the database elements it manages. This versioning system allows you to work on future versions of content without affecting the live content. It is used by workflow systems to offer a process for such content, going from creation, editing to review and publishing (where the draft version is swapped with the live version).
Versioning is available in the core API by default, but to gain access to management tools you must install an extension, eg. the system extension “versioning”.
The versioning system offers three types of versioning fitting various scenarios:
Element: A single database record from any table with versioning enabled is copied and configured as a future version of the original element. Color code is light green.
Page: A single page record is versioned and other content on the page (tables with “versioning_followPages” set in [ctrl]) is copied along. Color code is light blue.
Branch: A single page record is versioned and subpages to a specified depth including content is copied along. Color code is light red.
Here are some explanation why three types are necessary to gain the most flexibility:
“Element” versions are the most basic form and also the simplest. Whenever possible I would prefer this type because of the simplicity. However “Element” versions cannot take their environment into account. So moving an “Element” version to another page or even within the same page is impossible (or so complex to implement that we didn't even try).
Unfortunately, changing the order of for example content elements on a page is a very common way to re-organize page content. Therefore the versioning type “Page” means that some page content is copied along with the page version and thereby freely re-arrangeable. Furthermore, the process of versioning is necessary only one time for the page and not for each element on it that is changed. The downside to this method is that more content than necessary is copied and when the page versions are swapped, the new content elements on the page will have different UIDs than the former (breaking all links with anchors or “Insert Record”/TemplaVoila references to content elements on the former page ). The “Page” versioning type is most useful for columns-based websites, while TemplaVoila based sites can benefit more from the element-based versioning, especially in the context of workspaces where versioning is transparently done.
Finally, the “Branch” versioning type is used if you want to rework a whole branch of the page tree of a site. This gives you flexibility in terms of adding, deleting, moving and copying elements around that is unmatched by any of the other types. But on the other hand you suffer the same problems of “Page” versioning where you might break links and other id-references since all content below the versioned page “root point” will be separate copies of original content without any references back to their originals. You will loose not only anchor-point references but also links to page IDs! As it is right now I consider this type most useful for building new sections of a website or major rearrangements of sections where these consequences are acceptable. Yet, it remains to be seen what actual usage people will make of it.
Versioning must be enabled on a per-table basis in the [ctrl] section of the $TCA array entry for a table. In addition a fixed set of fields has to exist for the management of versions. All of these technical details are specified in the document “TYPO3 Core API” where you will also find other in-depth information.
Future and past versions of records in TYPO3 remain in the same table as the live version. However, all “offline” versions will have a pid value of “-1” which identifies them as “offline”. Further they have a field, “t3ver_oid” which points to their live (“online”) version.
When a future/past version is swapped with the live version it is done by swapping all field values except the uid and pid fields (and of course versioning related fields are manipulated according to their function). It means that online content is always identified by the same id as before and therefore all references are kept intact (except content inside “Page” and “Branch” versioning, see above).
Versioning is easy for existing elements. However, creating and deleting poses other problems. This is solved the following way:
Deleting elements is done by actually creating a new version of the element and setting a flag in the new version (t3ver_state=2) that indicates the live element must be deleted upon swapping the versions. Thus deletion is “scheduled” to happen when the versions are swapped.
Creating elements is done by first creating a placeholder element which is in fact live but carrying a flag (t3ver_state=1) that makes it invisible online. Then a new version of this placeholder is made which is what is modified until published.
Unique fields like a page alias or user name are tricky in a versioning scenario because the publication process must perform a check if the field is unique in the “Live” situation. The implications of implementing this means that we have chosen a solution where unique fields are simply not swapped at all! It means that publication of a new version of a page cannot and will not alter the alias of the live version. The “Live” unique value will remain until changed in the live version.
You can hide fields with the “unique” keyword when they are offline versions. This is done with the display condition:
'displayCond' => 'VERSION:IS:false',
When a new version of an element is created, its publishing counter (t3ver_count) is set to zero. This means its life cycle state is interpreted as “Draft”; the element is in the pipeline to be published. When the element is published the life cycle state is “Live” and when it is swapped out again the publishing counter will be incremented and the life cycle is interpreted as “Archive”. Yet, the element can be continously published and unpublished and for each time the publishing counter will be incremented, telling how many times an element has been online.
This is an overview of how permissions are handled in relation to versioning:
Display
Read permissions are evaluated based on the live version of pages (as the basic rule). The read permissions of the offline page version in a workspace is not observed. (Reason: When for example the page tree is generated TYPO3 selects all live records and then looks for versioned overlays).
Read permissions for new page versions of “branch” type is observed in eg. Web > List module. This is due to the fact that the real ID of a “branch” type page is what the backend uses in the Web>List module while for “page” and “Element” type versions the ID of the live record is used in which case the live records display-permissions is what gets evaluated.
Versionizing records
To create a new version the user must have read permission to the live record he requests to version
A new version of a page will inherit the owner user, group and permission settings from the live record
To create a "Page" or "Branch" version of a page requires read permission to all subpages. All records that should be copied along with "Page" and "Branch" versions will be so regardless of the users table-modify permissions.
Publishing version
To publish, a user must have general publishing permission in the workspace, for instance be the owner of it or have access to the Live workspace.
In addition, the user must have read and edit access to the offline version being published plus edit access to the live version that a publishing action will substitute!
The permissions of a new version of a page follows the page when published.
Editing records
For all editing it is required that the stage of the versioned record (or root point) allows editing.
Page records:
Permission to edit is always evaluated based on the pages own permission settings and not the live records.
Records from non-pages tables:
"Element" versions: Always based on the live parent page.
Live records inside a "Branch" or "Page" versioning type immediately under the root point depends on permissions of the root point offline version.
New records
When new records are created with a version and live place holder the permissions depend on the live page under which the record is created.
Moving records
Records that are related to "Page" and "Branch" versions of a page can be moved internally or to other "Page" or "Branch" versions as long as the source and destination root points has a stage that allows it.
New records created with a place holder element can be moved freely around except into other "Page" and "Branch" versions.
Generally, the stage of a moved record has to allow for editing plus regular permissions for moving are observed.
Deleting records
If the record is inside a "Page" or "Branch" type version of a page, then it can be readily deleted if other permissions allow, including stage of the root point.
If a record is outside a versioned branch and supports versioning it will be marked for deletion if all usual requirements are fulfilled at the time of the delete request: Delete access to record, that no subpages are found if not recursive deletion is enabled and no disallowed table records are found. As soon as the record is marked for deletion any change to the record and subpages that would otherwise prevent deletion for the user will not be effective: The record will be deleted upon publication!
If you try to delete a Live record for which a version is found in the workspace, that version is deleted instead.
Detaching versions from a workspace and raising stage of versions can be done as long as the user has edit permission to the record.
One problem with raw versioning is that it easily requires a lot of administration and awareness from users. For instance, an author has to consciously create a new version of a page or content element before he must edit it. Maybe he forgets. So either he makes a change live or - if TYPO3 is configured for it - he will be denied access to editing but frustrated over an error message. Further, keeping track of versions across the system might be difficult since changes are often made at various places and should be published together.
Some of these problems are fixed when elements are always processed with a workflow that keeps track of them. But a workflow process might be too rigid for scenarios where a group of editors are concerned with the site content broadly and not the narrow scope of an element centred workflow.
Furthermore, the preview of future content is hard to implement unless you require people to request a preview of each individual new version - but most often they like to see the combined impact of all future versions!
The concept of workspaces is the answer. Workspaces puts versioning into action in a very usable and transparent way offering all the flexibility from live editing but without sacrificing the important control of content publishing and review.
A workspace is a state in the backend of TYPO3. Basically there are three types of workspaces:
LIVE workspace: This is exactly the state TYPO3 has always been in. Any change you make will be instantly live. Nothing has changed, it just got a name.
Draft workspace: When a user selects the draft workspace new rules apply to anything he does in the backend:
Draft: Any change he tries to make will not affect the live website. It's a safe playground.
Transparent versioning: He can edit pages and elements because a new version is made automatically and attached to the workspace. No training needed, no administrative overhead!
Previewing: Visiting the frontend website will display it as it will appear when all versions in the workspace is eventually published (switch enable/disable this feature).
Overview of changes: The workspace manager module gives a clear overview of all changes that has been made inside the workspace across the site. This gives unparalleled control before publishing the content live.
Constraints: Only tables that support versioning can be edited. All management of files in fileadmin/ is disabled because they may affect the live website and thus would break the principle of “safe playground”.
Custom workspaces:
Inherits all properties of the default “Draft workspace” but can be configured additionally with owners, members and reviewers plus database- and file mounts plus other settings. A custom workspace is a great way to do team-based maintenance of (a section of) the website including a basic implementation of workflow states with editor-reviewer-publisher.
Some of the constraints of the default draft workspace can be eased up a bit by configuration; For instance records that does not support versioning can be allowed to be edited and file mounts can be defined inside of which files can be managed.
A draft workspace is a container for draft versions of content. Each versionable element can have zero or 1 version in a workspace (versions are attached to workspaces with a relation in the field “t3ver_wsid”). The fact that there can be only one new version of any element in a draft workspace makes in unambiguous which version to edit, preview and publish.
Analogy: The concept of workspaces can be compared with how CVS works for programmers; You check out the current source to your local computer (= entering a draft workspace), then you can change any script you like on your local computer (= transparent editing in the workspace), run tests of the changed code scripts (= previewing the workspace in the frontend) , compare the changes you made with the source in CVS (= using the Workspace Manager modules overview to review the complete amount of changes made) and eventually you commit the changes to CVS (= publishing the content of the workspace).
There are two ways to publish an element in a workspace; publish or swap. In both cases the draft content is published live. But when swapping it means the current live element is attached to the workspace when taken offline. This is contrary to the publish mode which pushes the live item out of any workspace and “into the archive”.
The swapping mode is useful if you have a temporary campaign, say a christmas special frontpage and website section. You create the christmas edition in a custom workspace and two weeks before christmas you swap in the christmas edition. All normal pages and elements that were unpublished are now in the workspace, waiting for christmas to pass by and eventually the old frontpage etc. will be swapped back in. The christmas edition is now back in the workspace and ready for next year.
I would like to more clearly describe the various workspace types, their differences and applications:
Topic | Live workspace | Draft workspace (default) | Custom workspaces |
|---|---|---|---|
Access | Users and groups must be specifically allowed access to the Live workspace. (Checkboxes in user/group record) (For upgrades from pre-4.0 versions this is done by default). | Users and groups must be specifically allowed access to the Draft workspace. (Checkboxes in user/group record) | Granted through the workspace configuration which includes: - A list of editors (users and/or groups) - A list of reviewers (users and/or groups) - Owner users (initial creator) |
Editing | Live content | Draft versions of live content | Draft versions of live content Option: To allow editing of tables without versioning available. |
DB mounts | From user profile | From user profile | Specific DB mounts can be specified in which case they will overrule DB mounts from user profiles. Specific DB mounts are required to be within the DB mounts from the user profile (for security reasons) If no DB mounts specified for workspace, user profile mounts are used (default) |
File mounts | From user profile | None available. All file manipulation access is banned! (Otherwise violation of “draft principle”) | By default, none is available due to same principle as for Draft workspace. Optionally, file mounts can be specified for convenience reasons. |
Scheduled publishing | N/A | N/A | If CLI-script is configured in cronjob you can specify publishing date/time down to the minute. You can also specify an unpublish time which requires the use of swapping as publishing type. |
Reviewing | Only through a separate workflow system. | Content can be raised from “Editing” stage through “Review” to “Publish”. However, the state does not impose any limitations on editing and publication of workspace contents. | Members can raise content from “Editing” stage to “Review”. Members can only edit content when its in “Editing stage” (or “Rejected”) Reviewers can raise the content from “Editing” stage to “Review” stage to “Publish” - or they can reject content back to editing. Reviewers can only edit content in these modes. Owners can operate all states of course. Owners are the only ones to edit content when in “Publish” mode. Thus “Publish” mode provides protection for content awaiting publication. The “Rejected” flag is reset automatically when editing occurs on a rejected element. Options available for automatic email notification between the roles. |
Publishing (For all: Requires edit access to live element) | No limitations. Content can be edited live and even content from other workspaces can be published through the versioning API regardless of stage. | All users with access to Live workspace is able to publish. | Workspace owners can publish (even without access to Live workspace). Reviewers/Members cannot publish unless they have access to online workspace as well (this default behaviour can be disabled). Option: Restrict publishing to elements in "Publish" stage only. |
Settings | N/A | N/A | Users with permission to create a custom workspace can do so. Workspace owners can add other owners, reviewers and editors and change all workspace properties. |
Auto versioning | N/A | Yes | Yes, but can be disabled so a conscious versioning actions is required. |
Swapping | N/A | Yes | Yes, but can be disabled. |
Versioning types | All | All | All, but you can disable any of the types “Element”, “Page” and “Branch”. |
Other notes | Custom workspaces has a freeze flag that will shut down any update/edit/copy/move/delete etc. command in the workspace until it is unset again. | ||
Module access | All backend modules can specify $MCONF['workspaces'] = “[online,offline,custom]” to limit access based current workspace of user. See description elsewhere in this document. | ||
Usage | Administrative purposes. First creation of site. | Everyday maintenance for trusted editors. | Specific projects on a site branch. Simple review-cycles. Informal team-work on site maintenance. |
Generally, “admin” users have access to all functionality as usual.
Since workspaces implies transparent support all over the backend and frontend it means that extensions must be programmed with this in mind. Although the ideal is complete transparency in backend and perfect previews in the frontend this is almost impossible to obtain. But a high level of consistency can be obtained by using API functions in TYPO3. These functions and the challenges they are invented to answer are discussed in “TYPO3 Core API”.
This section shortly covers the workspace related features in the backend with a visual tour-de-force.
Most significantly workspaces have a selector box in the lower right corner of the backend. The shortcut frame is permanently visible for users unless disabled by Page TSconfig:
In this selector box the backend user chooses between the workspaces available to him. The whole backend reloads each time he changes workspace. This is necessary because the backend might be differently composed depending on the workspace the user is in.
The workspace is reflected in the top of the page tree:
By default the "Live" workspace is not, but this is easily configured with User TSconfig: "options.pageTree.onlineWorkspaceInfo = 1"
When you are in a draft workspace you will find a "New version" button in various modules, including Web > Page:
Clicking this button will create a new "Page" type version of the page. In the page tree "Page" type versions are highlighted with a blue background color. This means the page header is versioned and content elements on the page is copied along. (See previously for a description of this versioning type). This type of versioning offers the flexibility to rearrange content elements between the columns of a page.
The module Web > Versioning allows you to monitor the versioning of elements on a specific page:
This view shows you the live version (sometimes called "Online") and the draft version (sometimes called "Offline") in a comparison view which helps you to understand what has changed in the draft version. You can also raise the stage of the content for review, you can publish, preview etc.
Instead of explicitly creating a "Page" type version of the page you can also go ahead and just edit the elements on the page. Transparently an edited element will be versioned and highlighted with green background to reflect the new state. In the page tree a page containing versioned elements will be highlighted with light yellow:
In case you also version the page header it will become green in the page tree (here I changed the page title to "Sed non tellus"):
Using the Web > Versioning module you will see the workspace content for the page. Obviously the page and one content element is found in draft versions in the workspace:
Comparing this view with the previous example where the page was versioned as a "Page" version you will now see that only changed elements appear, not every content element from the page. This type is called "Element" versioning and offers no flexibility in terms of rearranging element but benefits from maintaining all ids and being more straight forward to work with.
If you wish to compare changes in the content between the live and draft version you simply enable "Show difference view" and the display is updated to this:
This gives a reviewer a clear idea of the changes that has been performed. The red text is what was removed, the green text is what was added. A click on the button "Send all to Review" will raise the "Editing" stage to "Review" stage. "Publish page" / "Swap page" will perform publishing of all listed elements in the view (unless restrictions apply which is the case if the individual publish/swap buttons for each element is missing).
Finally, you can also create a "Branch" type version of the page. This will copy not only the page and its content elements but the whole subtree under the page. In order to do so, click the icon of a page, select "Versioning" and in the "Versioning" view you can create a new "Branch" version:
The page tree is now updated to look like this. The darker red page is the root point of the "Branch" version while the lighter red pages is the individual page tree belonging to that version. This type of versioning offers the flexibility to rearrange pages in a branch.
The Web > Versioning module displays the "Branch" version like this:
When you deal with "Branch" versions you will find a special token, #VEP# in the visual page path in backend modules. This token indicates where the branch point is in the path:
The Workspace Manager is available by clicking the workspace-icon next to the workspace selector in the lower right corner of the backend. Or you can access it as the module User > Workspace:
The Workspace Manager is the extended version of "Web > Versioning" where you will get an overview of the full workspace content. All versions in the workspace are shown here, can be previewed, managed and published due to your permissions:
Previewing content in the workspace is easy. Generally, you can enable "Frontend Preview" from the checkbox next to the workspace selector in the lower right corner of the backend interface. This will reflect the workspace changes when browsing the frontend website as long as you are logged in as a backend user.
Alternatively, you use the Web > View module:
Click the page with versioned content in the page tree...
... and you will be able to preview the draft content:
When you see a preview of a workspace in the frontend you will always be notified by the red box in the bottom of the page:
You can also click the magnifying-glass found many places in the backend. When you do that in a workspace you will get a special dual-view of the Live and Draft content combined with access to the Web > Versioning module for easy approval or publication:
By default you can use the "Draft workspace" for ad-hoc jobs that doesn't require strict control over review processes etc. In case you need teams of people with various roles such as author, reviewer and publisher you can create a custom workspace. By doing so you can customize roles, permissions and other features to suit your needs:
The custom Workspace is adequately described in the content sensitive help so no more details will be given here.
The workspace technology offers a simple scheme for staging content through review to publication. In the Workspace Manager or Web > Versioning module you can "raise content " to the next level and attach a comment while doing so:
The stage is raised to "Review" and will be reflected in the interface:
Likewise you can take the next step to "Publish" at which point the the workspace owner (of custom workspaces) can uncritically publish assuming the review process has caught any problems - or the workspace owner can act as a final level of review:
In case the reviewer or owner finds reasons to reject the content they can do so with an explanation going to the editor:
At any time a mouse-over on the Stage control will display the log of events:
Notice: The stage feature is only subject to access restrictions inside custom workspaces. In Live and the default Draft workspace the feature is available as a state any user can set and final publishing does not require the "Publish" stage to be reached for any content.
Publishing content from a workspace can either be done with individual elements, pages including elements or the whole workspace at once. Publishing the full workspace is available from the top of the Workspace Manager:
For each element in the list you can access control buttons for publish, swap, release from workspace, edit element, view change history and preview.
Next to the control buttons you see the Lifecycle of content. In the screenshot one of the elements is different from the others: It turns out that this element has actually been published three times. This is possible if the "Swap workspace" buttons are used; They will simply swap the live version with the draft version so that the Live version is taken back into the workspace in exchange. Doing this a few times forth and back will increase the lifecycle counter beyond the otherwise most common state which is "Archive" (published one time).
The other elements shown are all in "Draft" state meaning they have not been published live - yet.
In the Workspace Manager you can also enable display of sub-elements for "Page" and "Branch" versioning types:
This will provide you with a threaded display of the versioned content:
Another feature is to enable difference view in the Workspace Manager. By doing so you will see every element compared to its live counterpart (if available) and it will be clear to you what changes has been made:
The system log will also reflect operations in the workspace. The "User" column is tagged with the workspace in which the action took place:
Setting up access to workspaces: For the Live and default Draft workspace you will have to configure this in the Backend User and Group records by checkboxes:
In the Tools > User Admin module this is also reflected in the comparison view:
For custom workspaces users are assigned membership directly in the configuration record of the workspace:
Tip: Although the default settings for upgraded websites will be that all users and groups have access to the Live workspace the intention of the workspace technology is that in most typical cases the average backend user only works in a draft workspace and therefore cannot change live content before a supervisor with access to the Live workspace will enter the backend and publish the workspace content.
Creating new content: The workspace technology is aimed at being so tough that even a complete website can be built from scratch without changing any live content. Here the Draft Workspace is used to build a complete page structure and dummy content. In the workspace everything looks like if it was live, even when previewed in the frontend with Web > View.
Changing to the Live workspace reveals a set of placeholder records. These are necessary to reserve the future position for the new content in the workspace. However, those placeholders are ignored in the live workspace frontend and will therefore not affect any live content.
The Web > List module shows the same reflection. In the screenshot below you can see how pages, content elements, localized versions of content elements, page language overlays and even TypoScript Templates are created as versions in the workspace:
In the Live workspace this is reflected like this by the "invisible" placeholders:
By publication of the workspace these placeholders are substituted with the new versions from the workspace.
Managing custom workspaces: [This section still misses introduction to the yet missing workspace administration interface in the Workspace Manager.]
