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