[BUGFIX] Remove early return in PageTreeDataProvider
[Packages/TYPO3.CMS.git] / t3lib / class.t3lib_spritemanager.php
index 669b7fd..35a16aa 100644 (file)
 <?php
 /***************************************************************
-*  Copyright notice
-*
-*  (c) 2010 Steffen Ritter <info@steffen-ritter.net>
-*  All rights reserved
-*
-*  This script is part of the TYPO3 project. The TYPO3 project is
-*  free software; you can redistribute it and/or modify
-*  it under the terms of the GNU General Public License as published by
-*  the Free Software Foundation; either version 2 of the License, or
-*  (at your option) any later version.
-*
-*  The GNU General Public License can be found at
-*  http://www.gnu.org/copyleft/gpl.html.
-*  A copy is found in the textfile GPL.txt and important notices to the license
-*  from the author is found in LICENSE.txt distributed with these scripts.
-*
-*
-*  This script is distributed in the hope that it will be useful,
-*  but WITHOUT ANY WARRANTY; without even the implied warranty of
-*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-*  GNU General Public License for more details.
-*
-*  This copyright notice MUST APPEAR in all copies of the script!
-***************************************************************/
+ *  Copyright notice
+ *
+ *  (c) 2010-2011 Steffen Ritter <info@steffen-ritter.net>
+ *  All rights reserved
+ *
+ *  This script is part of the TYPO3 project. The TYPO3 project is
+ *  free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  The GNU General Public License can be found at
+ *  http://www.gnu.org/copyleft/gpl.html.
+ *  A copy is found in the textfile GPL.txt and important notices to the license
+ *  from the author is found in LICENSE.txt distributed with these scripts.
+ *
+ *
+ *  This script is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  This copyright notice MUST APPEAR in all copies of the script!
+ ***************************************************************/
 
 
 /**
- * TYPO3 Sprite Manager, it is initiated from BE and FE if BE-User ist active
- * Its task will be to build css-definitions for registered Icons of Extensions,
- * TCA-Tables and so on, so that they will be usuable through sprite-icon-api.
- * An special configurable handler-class will process the "real" task so that
- * the user may differ between details of generation and their caching.
+ * TYPO3 sprite manager, used in BE and in FE if a BE user is logged in.
+ *
+ * This class builds CSS definitions of registered icons, writes TCA definitions
+ * and registers sprite icons in a cache file.
  *
- * @author     Steffen Ritter <info@steffen-ritter.net>
+ * A configurable handler class does the business task.
+ *
+ * @author Steffen Ritter <info@steffen-ritter.net>
  * @package TYPO3
  * @subpackage t3lib
  */
 class t3lib_SpriteManager {
        /**
-        * @var string
+        * @var string Directory for cached sprite informations
         */
        public static $tempPath = 'typo3temp/sprites/';
 
        /**
-        *@var t3lib_spritemanager_SpriteIconGenerator
+        * @var t3lib_spritemanager_SpriteIconGenerator Handler class instance
         */
        protected $handler = NULL;
 
        /**
-        * @var array
+        * @var array Register of valid icons
         */
        protected $iconNames = array();
 
        /**
-        * @var string the file name the current cache file
+        * @var string Name of current cache file
         */
        protected $tempFileName = '';
 
        /**
-        * class constructor checks if cache has to be rebuild and initiates the rebuild
-        * instantiates the handler class
+        * Check if the icon cache has to be rebuild, instantiate and call the handler class if so.
         *
-        * @param boolean $regenerate   with set to false, cache won't be regenerated if needed (useful for feediting)
+        * @param boolean Suppress regeneration if FALSE (useful for feediting)
         * @return void
         */
-       function __construct($regenerate = TRUE) {
-                       // we check for existance of our targetDirectory
+       function __construct($allowRegeneration = TRUE) {
+                       // Create temp directory if missing
                if (!is_dir(PATH_site . self::$tempPath)) {
                        t3lib_div::mkdir(PATH_site . self::$tempPath);
                }
-                       // create a fileName, the hash includes all icons and css-styles registered and the extlist
+
+                       // Create cache filename, the hash includes all icons, registered CSS styles registered and the extension list
                $this->tempFileName = PATH_site . self::$tempPath .
-                                                       md5(serialize($GLOBALS['TBE_STYLES']['spritemanager']) .
-                                                       md5(serialize($GLOBALS['TBE_STYLES']['spriteIconApi']['coreSpriteImageNames'])) . 
-                                                       $GLOBALS['TYPO3_CONF_VARS']['EXT']['extList']) . '.inc';
-                       // if no cache-file for the current config ist present, regenerate it
-               if(!@file_exists($this->tempFileName)) {
-                               // regenerate if allowed
-                       if($regenerate) {
+                                                         md5(serialize($GLOBALS['TBE_STYLES']['spritemanager']) .
+                                                                 md5(serialize($GLOBALS['TBE_STYLES']['spriteIconApi']['coreSpriteImageNames'])) .
+                                                                 $GLOBALS['TYPO3_CONF_VARS']['EXT']['extList']) . '.inc';
+
+                       // Regenerate cache file if not already existing
+               if (!@file_exists($this->tempFileName)) {
+                       if ($allowRegeneration) {
                                $handlerClass = (
-                                       $GLOBALS['TYPO3_CONF_VARS']['BE']['spriteIconGenerator_handler'] ?
-                                       $GLOBALS['TYPO3_CONF_VARS']['BE']['spriteIconGenerator_handler'] :
-                                       't3lib_spritemanager_SimpleHandler'
+                               $GLOBALS['TYPO3_CONF_VARS']['BE']['spriteIconGenerator_handler'] ?
+                                               $GLOBALS['TYPO3_CONF_VARS']['BE']['spriteIconGenerator_handler'] :
+                                               't3lib_spritemanager_SimpleHandler'
                                );
                                $this->handler = t3lib_div::makeInstance($handlerClass);
-                                       // check if the handler could be loaded and implements the needed interface
+
+                                       // Throw exception if handler class does not implement required interface
                                if (!$this->handler || !($this->handler instanceof t3lib_spritemanager_SpriteIconGenerator)) {
-                                       throw new Exception(
-                                               "class in TYPO3_CONF_VARS[BE][spriteIconGenerator_handler] does not exist,
-                                               or does not implement t3lib_spritemanager_SpriteIconGenerator"
+                                       throw new RuntimeException(
+                                               'Class in $TYPO3_CONF_VARS[BE][spriteIconGenerator_handler] (' .
+                                               $GLOBALS['TYPO3_CONF_VARS']['BE']['spriteIconGenerator_handler'] .
+                                               ') does not exist or does not implement t3lib_spritemanager_SpriteIconGenerator.',
+                                               1294586333
                                        );
                                }
-                                       // all went good? to go for rebuild
+
                                $this->rebuildCache();
                        } else {
-                                       // use old file if present
-                               list($this->tempFileName) = t3lib_div::getFilesInDir(PATH_site . self::$tempPath, 'inc', 1);
+                                       // Set tempFileName to existing file if regeneration is not allowed
+                               list($this->tempFileName) = t3lib_div::getFilesInDir(PATH_site . self::$tempPath, 'inc', TRUE);
                        }
                }
        }
 
        /**
-        * this method calls the main methods from the handler classes
-        * merges the results with the data from the skin, and cache it
+        * Call handler class, merge results with skin data and cache it.
         *
         * @return void
         */
        protected function rebuildCache() {
-                       // ask the handlerClass to kindly rebuild our data
+                       // Generate CSS and TCA files, build icon set register
                $this->handler->generate();
 
-                       // get all Icons registered from skins, merge with core-Icon-List
-               $availableSkinIcons = (array)$GLOBALS['TBE_STYLES']['spriteIconApi']['coreSpriteImageNames'];
+                       // Get all icons registered from skins, merge with core icon list
+               $availableSkinIcons = (array) $GLOBALS['TBE_STYLES']['spriteIconApi']['coreSpriteImageNames'];
                foreach ($GLOBALS['TBE_STYLES']['skins'] as $skinName => $skinData) {
-                       $availableSkinIcons = array_merge($availableSkinIcons, (array)$skinData['availableSpriteIcons']);
+                       $availableSkinIcons = array_merge($availableSkinIcons, (array) $skinData['availableSpriteIcons']);
                }
 
-                       // merge icon names whith them provided by the skin,
-                       // registered from "complete sprites" and the ones detected
-                       // by the handlerclass
+                       // Merge icon names provided by the skin, with
+                       // registered "complete sprites" and the handler class
                $this->iconNames = array_merge(
                        $availableSkinIcons,
                        (array) $GLOBALS['TBE_STYLES']['spritemanager']['spriteIconsAvailable'],
                        $this->handler->getAvailableIconNames()
                );
 
-                       // serialize found icons, and cache them to file
+                       // Create serialized cache data
                $cacheString = addslashes(serialize($this->iconNames));
                $fileContent = '<?php $GLOBALS[\'TBE_STYLES\'][\'spriteIconApi\'][\'iconsAvailable\'] = unserialize(stripslashes(\'' . $cacheString . '\')); ?>';
 
-                       // delete old cache files
-               $oldFiles = t3lib_div::getFilesInDir(PATH_site . self::$tempPath, 'inc', 1);
+                       // Clean up cache directory
+               $oldFiles = t3lib_div::getFilesInDir(PATH_site . self::$tempPath, 'inc', TRUE);
                foreach ($oldFiles as $file) {
                        @unlink($file);
                }
-                       // and write the new one
+
+                       // Write new cache file
                t3lib_div::writeFile($this->tempFileName, $fileContent);
        }
 
-
        /**
-        * includes the generated cacheFile, if present
+        * Include cache file if exists
         *
         * @return void
         */
@@ -152,32 +154,36 @@ class t3lib_SpriteManager {
        }
 
        /**
-        * if an extension has an pregenerated sprite, it might register it here.
-        * Giving the "available" iconNames and the styleSheetFile where the sprite icons are defined (make shure the css  filename contains the extname to be unique).
-        * the iconnames and the stylesheet must follow the conventions as follows:
-        * IconName: extensions-$extKey-$iconName.
-        * Class for loading the sprite: t3-icon-extensions-$extKey
-        * Class for single icons: t3-icon-$extKey-$iconName
-        * NOTE: do not use this for skins, stylesheets of skins will be included automatically.
-        * Available icons of skins should be located manually (extTables) to $GLOBALS[TBE_STYLES][skins][skinName][availableIcons]
+        * API for extensions to register own sprites.
+        *
+        * Get an array of icon names and the styleSheetFile with defined sprite icons.
+        * The stylesheet filename should contain the extension name to be unique.
+        *
+        * Naming conventions:
+        * - IconName: extensions-$extKey-$iconName
+        * - CSS class for loading the sprite: t3-icon-extensions-$extKey
+        * - CSS class for single icons: t3-icon-$extKey-$iconName
         *
-        * @param array icons   the names of the introduced icons
-        * @parram string $styleSheetFile       the name of the styleshet file relative to PATH_site
+        * @param array Icon names
+        * @param string Stylesheet filename relative to PATH_typo3. Skins do not need to supply the $styleSheetFile, if the CSS file is within the registered stylesheet folders
+        * @return void
         */
-       public static function addIconSprite(array $icons, $styleSheetFile) {
+       public static function addIconSprite(array $icons, $styleSheetFile = '') {
                $GLOBALS['TBE_STYLES']['spritemanager']['spriteIconsAvailable'] = array_merge(
-                       $GLOBALS['TBE_STYLES']['spritemanager']['spriteIconsAvailable'],
+                       (array) $GLOBALS['TBE_STYLES']['spritemanager']['spriteIconsAvailable'],
                        $icons
                );
-
-               $GLOBALS['TBE_STYLES']['spritemanager']['cssFiles'][] = $styleSheetFile;
+               if ($styleSheetFile !== '') {
+                       $GLOBALS['TBE_STYLES']['spritemanager']['cssFiles'][] = $styleSheetFile;
+               }
        }
 
        /**
-        * will allow Ext-Developers to register their icons to get included in sprites,
-        * they may use them afterwards with t3lib_iconWorks::getSpriteIcon('extensions-$extKey-iconName');
-        * @param array $icons  array which contains the adding icons array ( $iconname => $iconFile) $iconFile relative to PATH_typo3
-        * @param string        $extKey string of the extension which adds the icons
+        * API for extensions to register new sprite images which can be used with
+        * t3lib_iconWorks::getSpriteIcon('extensions-$extKey-iconName');
+        *
+        * @param array Icons to be registered, $iconname => $iconFile, $iconFile must be relative to PATH_site
+        * @param string Extension key
         * @return void
         */
        public static function addSingleIcons(array $icons, $extKey = '') {
@@ -187,18 +193,23 @@ class t3lib_SpriteManager {
        }
 
        /**
-        * static function to add a type-with icon to an already existent table which makes use of "typeicon_classes"
-        * feature or to provide icon for "modules" in pages table
-        * @param string        $table  the table the type has been added
-        * @param string        $type   the type - must equal the value of the column in the table
-        * @param string        $iconFile       relative to PATH_typo3
+        * API to register new type icons for tables which use "typeicon_classes"
+        * Can be used to provide icons for "modules" in pages table
+        *
+        * @param string Table name to which the type icon should be added
+        * @param string Type column name of the table
+        * @param string Icon filename, relative to PATH_typo3
+        * @return void
         */
        public static function addTcaTypeIcon($table, $type, $iconFile) {
                $GLOBALS['TBE_STYLES']['spritemanager']['singleIcons']['tcarecords-' . $table . '-' . $type] = $iconFile;
-               if(isset($GLOBALS['TCA'][$table]['typeicon_classes'])) {
-                       $GLOBALS['TCA'][$table]['typeicon_classes'][$type] = 'tcarecords-' . $table . '-' . $type;
-               } 
+               if (is_array($GLOBALS['TCA'][$table]['ctrl']['typeicon_classes'])) {
+                       $GLOBALS['TCA'][$table]['ctrl']['typeicon_classes'][$type] = 'tcarecords-' . $table . '-' . $type;
+               }
        }
 }
 
-?>
+if (defined('TYPO3_MODE') && isset($GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['XCLASS']['t3lib/class.t3lib_spritemanager.php'])) {
+       include_once($GLOBALS['TYPO3_CONF_VARS'][TYPO3_MODE]['XCLASS']['t3lib/class.t3lib_spritemanager.php']);
+}
+?>
\ No newline at end of file