1.. include:: ../../Includes.txt
2
3
4
5.. _versioning:
6
7Versioning
8^^^^^^^^^^
9
10TYPO3 CMS offers versioning of the database elements it manages. This
11versioning system allows you to work on future versions of content
12without affecting the live content. It is used by workflow systems to
13offer a process for such content, going from creation, editing to
14review and publishing.
15
16Versioning is available in the core API by default, but to gain access
17to management tools you must install the system extension "workspaces".
18
19
20.. _technical-details:
21
22Technical Details
23"""""""""""""""""
24
25Versioning must be enabled on a per-table basis in the
26:ref:`"ctrl" section of the TCA array <t3tca:ctrl>` for the given table.
27In addition a fixed set of fields has to exist for the management of versions.
28All of these technical details are specified in the
29:ref:`description of the "versioningWS" TCA property <t3tca:ctrl-reference-versioningws>`.
30All other versioning and workspace-related properties are also
31described there.
32
33Future and past versions of records in TYPO3 CMS remain in the same table
34as the live version. However, all "offline" versions have a pid
35value of "-1" to set them apart. Furthermore they have a database
36field called "t3ver\_oid" which points to their live ("online") counterpart.
37
38When a future/past version is swapped with the live version it is done
39by *swapping all field values except the uid and pid* fields (and of
40course versioning related fields are manipulated according to their
41function). It means that online content is always identified by the
42same id as before and therefore all references are kept intact.
43
44Versioning is easy for existing elements. However, moving, creating
45and deleting poses other problems. This is solved the following way:
46
47- Deleting elements is done by actually creating a new version of the
48  element *and* setting a flag in the new version (:code:`t3ver_state = 2`) that
49  indicates the live element must be deleted upon publishing the versions.
50
51- Creating elements is done by first creating a placeholder element
52  which is in fact live but carrying a flag (:code:`t3ver_state = 1`) that makes
53  it invisible online. Then a new version of this placeholder with the flag
54  (:code:`t3ver_state = -1`) is made which is what is modified until published.
55
56- Moving elements is done by first creating a placeholder element which
57  is in fact live but carrying a flag (:code:`t3ver_state = 3`) that makes it
58  invisible online. It also has a field, "t3ver\_move\_id", holding the
59  uid of the record to move (source record). In addition, a new version
60  of the source record is made with :code:`t3ver_state = 4` (move-to
61  pointer). This version is necessary in order for the versioning
62  system to have something to publish for the move operation. So in
63  summary, two records are created for a move operation in a workspace:
64  The placeholder (online, with :code:`t3ver_state = 3` and "t3ver\_move\_id" set) and a
65  new version (:code:`t3ver_state = 4`) of the online source record (the one being
66  moved).
67
68
69.. _unique-fields:
70
71Unique fields
72~~~~~~~~~~~~~
73
74- Unique fields like a page alias or user name are tricky in a
75  versioning scenario because the publication process must perform a
76  check if the field is unique in the "Live" situation. The implications
77  of implementing this means that we have chosen a solution where unique
78  fields are simply not swapped at all! It means that publication of a
79  new version of a page cannot and will not alter the alias of the live
80  version. The "Live" unique value will remain until changed in the live
81  version.
82
83- You can hide fields with the "unique" keyword when there are offline
84  versions. This is done with the display condition:
85
86.. code-block:: php
87
88	'displayCond' => 'VERSION:IS:false',
89
90
91.. _permissions:
92
93Permissions
94~~~~~~~~~~~
95
96This is an overview of how permissions are handled in relation to
97versioning:
98
99
100.. _display:
101
102Display
103*******
104
105- Read permissions are evaluated based on the live version of pages (as
106  the basic rule). The read permissions of the offline page version in a
107  workspace is not observed.
108
109- The ID of the live record is used so the live records display-
110  permissions get evaluated.
111
112
113.. _versioning-records:
114
115Versioning records
116******************
117
118- To create a new version the user must have read permission to the live
119  record he requests to version
120
121- A new version of a page will inherit the owner user, group and
122  permission settings from the live record
123
124
125.. _publishing-version:
126
127Publishing version
128******************
129
130- To publish, a user must have general publishing permission in the
131  workspace, for instance be the owner of it or have access to the Live
132  workspace.
133
134- In addition, the user must have read and edit access to the offline
135  version being published plus edit access to the *live version* that a
136  publishing action will substitute!
137
138- The permissions of a new version of a page follows the page when
139  published.
140
141
142.. _editing-records:
143
144Editing records
145***************
146
147- For all editing it is required that the stage of the versioned record
148  (or root point) allows editing.
149
150- Page records:
151
152  - Permission to edit is always evaluated based on the pages own
153    permission settings and not the live records.
154
155- Records from non-pages tables:
156
157  - Always based on the live parent page.
158
159
160.. _new-records:
161
162New records
163***********
164
165- When new records are created with a version and live place holder the
166  permissions depend on the live page under which the record is created.
167
168
169.. _moving-records:
170
171Moving records
172**************
173
174- Records can be moved as long as the source and destination root point
175  to a stage that allows it.
176
177- New records created with a placeholder element can be moved freely
178  around.
179
180- Generally, the stage of a moved record has to allow for editing plus
181  regular permissions for moving.
182
183
184.. _deleting-records:
185
186Deleting records
187****************
188
189- If a record supports versioning it will be marked for deletion if all
190  usual requirements are fulfilled at the time of the delete request:
191  delete access to record, no subpages if recursive deletion is not
192  enabled and no disallowed table records are found. As soon as the
193  record is marked for deletion any change to the record and subpages
194  that would otherwise prevent deletion for the user will not be
195  effective. The record *will* be deleted upon publication!
196
197- If you try to delete a Live record for which a version is found in the
198  workspace, that version is deleted instead.
199
200- Detaching versions from a workspace and raising stage of versions can
201  be done as long as the user has edit permission to the record.
202