Merged workspace support branch into trunk
authorfrancois <francois@735d13b6-9817-0410-8766-e36946ffe9aa>
Tue, 25 Jan 2011 08:30:15 +0000 (08:30 +0000)
committerfrancois <francois@735d13b6-9817-0410-8766-e36946ffe9aa>
Tue, 25 Jan 2011 08:30:15 +0000 (08:30 +0000)
Updated documentation with new API and more developer information
references #9543

git-svn-id: https://svn.typo3.org/TYPO3v4/Extensions/overlays/trunk@42558 735d13b6-9817-0410-8766-e36946ffe9aa

1  2 
ChangeLog
class.tx_overlays.php
doc/manual.sxw

diff --cc ChangeLog
+++ b/ChangeLog
@@@ -1,3 -1,3 +1,7 @@@
++2011-01-25 Francois Suter (Cobweb)  <typo3@cobweb.ch>
++
++      * Added support for versioning/workspaces
++
  2010-08-31 Francois Suter (Cobweb)  <typo3@cobweb.ch>
  
        * First public release (version 1.0.0)
@@@ -93,13 -115,22 +115,19 @@@ final class tx_overlays 
                }
  
                        // Execute the query itself
-               $res = $GLOBALS['TYPO3_DB']->exec_SELECTquery($selectFields, $fromTable, $where, $groupBy, $orderBy, $limit);
-                       // Assemble a raw recordset
-               $records = array();
-               while (($row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res))) {
-                       $records[] = $row;
 -//t3lib_div::debug($GLOBALS['TYPO3_DB']->SELECTquery($selectFields, $fromTable, $where, $groupBy, $orderBy, $limit));
+               $records = $GLOBALS['TYPO3_DB']->exec_SELECTgetRows($selectFields, $fromTable, $where, $groupBy, $orderBy, $limit);
 -//t3lib_div::debug($records, 'before versioning');
+                       // Perform version overlays, if needed
+               if ($doVersioning) {
+                       $numRecords = count($records);
+                       for ($i = 0; $i < $numRecords; $i++) {
+                               $GLOBALS['TSFE']->sys_page->versionOL($fromTable, $records[$i]);
+                                       // The versioned record may actually be FALSE if it is meant to be deleted
+                                       // in the workspace. To be really clean, unset it.
+                               if ($records[$i] === FALSE) {
+                                       unset($records[$i]);
+                               }
+                       }
                }
-               $GLOBALS['TYPO3_DB']->sql_free_result($res);
 -//t3lib_div::debug($records, 'after versioning');
  
                        // If we have both a uid and a pid field, we can proceed with overlaying the records
                if ($doOverlays) {
        public static function getEnableFieldsCondition($table, $showHidden = FALSE, $ignoreArray = array()) {
                $enableCondition = '';
                        // First check if table has a TCA ctrl section, otherwise t3lib_page::enableFields() will die() (stupid thing!)
 -                      // NOTE: since TYPO3 4.5, an execption is thrown, so this method could eventually be adapted
++                      // NOTE: since TYPO3 4.5, an exception is thrown, so this method could eventually be adapted
                if (isset($GLOBALS['TCA'][$table]['ctrl'])) {
                        $showHidden = $showHidden ? $showHidden : ($table == 'pages' ? $GLOBALS['TSFE']->showHiddenPage : $GLOBALS['TSFE']->showHiddenRecords);
                        $enableCondition = $GLOBALS['TSFE']->sys_page->enableFields($table, $showHidden , $ignoreArray);
        }
  
        /**
++       * This method used to assemble the proper condition with regards to versioning/workspaces
++       * However it is now deprecated and getVersioningCondition should be used instead
++       * 
++       * @param <type> $table
++       * @return <type> 
++       * @deprecated Use self::getVersioningCondition() instead. Kept for backwards-compatibility but may be removed in the future.
++       */
++      public static function getWorkspaceCondition($table) {
++              t3lib_div::logDeprecatedFunction();
++              return self::getVersioningCondition($table);
++      }
++
++      /**
         * This method assembles the proper condition with regards to versioning/workspaces
         *
-        * NOTE: this is not complete yet! It just makes sure that only live records
-        * are shown in the FE, but workspace preview does not work yet.
+        * Explanations on parameter $getOverlaysDirectly:
+        * -----------------------------------------------
+        * The base condition assembled by this method will get the placeholders for new or modified records.
+        * This is normally the right way to do things, since those records are overlaid with their workspace version afterwards.
+        * However if you want this condition as part of a more complicated query implying JOINs,
+        * selecting placeholders will not work as the relationships are normally built with the version overlays
+        * and not the placeholders. In this case it is desirable to select the overlays directly,
+        * which can be achieved by setting $getOverlaysDirectly to TRUE
         *
-        * @param       string          $table: name of the table to build the condition for
-        * @return      string
 -       * NOTE 1: this should be considered as experimental for now as it hasn't been tested in all possible scenarios
 -       * NOTE 2: if this all sounds like gibberish, try reading more about workspaces in "Core API"
++       * NOTE: if this all sounds like gibberish, try reading more about workspaces in "Core API"
+        * (there's also quite some stuff in "Inside TYPO3", but part of it is badly outdated)
+        *
+        * @param       string          $table: (true) name of the table to build the condition for
+        * @param       string          $alias: alias to use for the table instead of its true name
+        * @param       boolean         $getOverlaysDirectly: flag to choose original/placeholder records or overlays (see explanations above)
+        * @return      string          SQL to add to the WHERE clause (without "AND")
         */
-       public static function getWorkspaceCondition($table) {
+       public static function getVersioningCondition($table, $alias = '', $getOverlaysDirectly = FALSE) {
                $workspaceCondition = '';
+               if (empty($alias)) {
+                       $alias = $table;
+               }
                        // If the table has some TCA definition, check workspace handling
                if (isset($GLOBALS['TCA'][$table]['ctrl']) && !empty($GLOBALS['TCA'][$table]['ctrl']['versioningWS'])) {
-                               // If not performing a workspace preview, make sure to grab only live records
-                       if (!$GLOBALS['TSFE']->sys_page->versioningPreview) {
-                               $workspaceCondition .= $table . '.t3ver_oid = 0 AND ' . $table . '.t3ver_state <= 0';
+                               // Base condition to get only live records
+                               // (they get overlaid afterwards in case of preview)
+                       $workspaceCondition .= '(' . $alias . '.t3ver_state <= 0 AND ' . $alias . '.t3ver_oid = 0)';
+                               // Additional conditions when previewing a workspace
+                       if ($GLOBALS['TSFE']->sys_page->versioningPreview) {
+                               $workspace = intval($GLOBALS['BE_USER']->workspace);
+                                       // Condition for records that are unmodified but whose parent was modified
+                                       // (when a parent record is modified, copies of its children are made that refer to the modified parent)
+                               $workspaceCondition .= ' OR (' . $alias . '.t3ver_state = 0 AND ' . $alias . '.t3ver_wsid = ' . $workspace . ')';
+                                       // Choose the version state of records to select based on the $getOverlaysDirectly flag
+                                       // (see explanations in the phpDoc comment above)
+                               $modificationPlaceholderState = 1;
+                               $movePlaceholderState = 3;
+                               if ($getOverlaysDirectly) {
+                                       $modificationPlaceholderState = -1;
+                                       $movePlaceholderState = 4;
+                               }
+                                       // Select new records (which exist only in the workspace)
+                                       // This is achieved by selecting the placeholders, which will be overlaid
+                                       // with the actual content later when calling t3lib_page::versionOL()
+                               $workspaceCondition .= ' OR (' . $alias . '.t3ver_state = ' . $modificationPlaceholderState . ' AND ' . $alias . '.t3ver_wsid = ' . $workspace . ')';
+                                       // Move-to placeholder
+                               $workspaceCondition .= ' OR (' . $alias . '.t3ver_state = ' . $movePlaceholderState . ' AND ' . $alias . '.t3ver_wsid = ' . $workspace . ')';
                        }
                }
                return $workspaceCondition;
         * @param       string          $table: name of the table for which to fetch the records
         * @param       array           $uids: array of all uid's of the original records for which to fetch the translation
         * @param       integer         $currentLanguage: uid of the system language to translate to
+        * @param       boolean         $doVersioning: true if versioning overlay must be performed
         * @return      array           All overlay records arranged per original uid and per pid, so that they can be checked (this is related to workspaces)
         */
-       public static function getOverlayRecords($table, $uids, $currentLanguage) {
 -      public static function getOverlayRecords($table, $uids, $currentLanguage, $doVersioning) {
++      public static function getOverlayRecords($table, $uids, $currentLanguage, $doVersioning = FALSE) {
                if (is_array($uids) && count($uids) > 0) {
                        if (isset($GLOBALS['TCA'][$table]['ctrl']['transForeignTable'])) {
-                               return self::getForeignOverlayRecords($GLOBALS['TCA'][$table]['ctrl']['transForeignTable'], $uids, $currentLanguage);
+                               return self::getForeignOverlayRecords($GLOBALS['TCA'][$table]['ctrl']['transForeignTable'], $uids, $currentLanguage, $doVersioning);
                        } else {
-                               return self::getLocalOverlayRecords($table, $uids, $currentLanguage);
+                               return self::getLocalOverlayRecords($table, $uids, $currentLanguage, $doVersioning);
                        }
                } else {
                        return array();
         * @param       string          $table: name of the table for which to fetch the records
         * @param       array           $uids: array of all uid's of the original records for which to fetch the translation
         * @param       integer         $currentLanguage: uid of the system language to translate to
+        * @param       boolean         $doVersioning: true if versioning overlay must be performed
         * @return      array           All overlay records arranged per original uid and per pid, so that they can be checked (this is related to workspaces)
         */
-       public static function getLocalOverlayRecords($table, $uids, $currentLanguage) {
 -      public static function getLocalOverlayRecords($table, $uids, $currentLanguage, $doVersioning) {
++      public static function getLocalOverlayRecords($table, $uids, $currentLanguage, $doVersioning = FALSE) {
                $overlays = array();
                if (is_array($uids) && count($uids) > 0) {
                        $tableCtrl = $GLOBALS['TCA'][$table]['ctrl'];
         * @param       string          $table: name of the table for which to fetch the records
         * @param       array           $uids: array of all uid's of the original records for which to fetch the translation
         * @param       integer         $currentLanguage: uid of the system language to translate to
+        * @param       boolean         $doVersioning: true if versioning overlay must be performed
         * @return      array           All overlay records arranged per original uid and per pid, so that they can be checked (this is related to workspaces)
         */
-       public static function getForeignOverlayRecords($table, $uids, $currentLanguage) {
 -      public static function getForeignOverlayRecords($table, $uids, $currentLanguage, $doVersioning) {
++      public static function getForeignOverlayRecords($table, $uids, $currentLanguage, $doVersioning = FALSE) {
                $overlays = array();
                if (is_array($uids) && count($uids) > 0) {
                        $tableCtrl = $GLOBALS['TCA'][$table]['ctrl'];
diff --cc doc/manual.sxw
index 3a25087,3a25087..81c775e
Binary files differ