t3lib/class.t3lib_extobjbase.php

   1 <?php
   2 /***************************************************************
   3 *  Copyright notice
   4 *
   5 *  (c) 1999-2008 Kasper Skaarhoj (kasperYYYY@typo3.com)
   6 *  All rights reserved
   7 *
   8 *  This script is part of the TYPO3 project. The TYPO3 project is
   9 *  free software; you can redistribute it and/or modify
  10 *  it under the terms of the GNU General Public License as published by
  11 *  the Free Software Foundation; either version 2 of the License, or
  12 *  (at your option) any later version.
  13 *
  14 *  The GNU General Public License can be found at
  15 *  http://www.gnu.org/copyleft/gpl.html.
  16 *  A copy is found in the textfile GPL.txt and important notices to the license
  17 *  from the author is found in LICENSE.txt distributed with these scripts.
  18 *
  19 *
  20 *  This script is distributed in the hope that it will be useful,
  21 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  22 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23 *  GNU General Public License for more details.
  24 *
  25 *  This copyright notice MUST APPEAR in all copies of the script!
  26 ***************************************************************/
  27 /**
  28  * Contains the base class for 'Extension Objects' in backend modules.
  29  *
  30  * $Id$
  31  * Revised for TYPO3 3.6 July/2003 by Kasper Skaarhoj
  32  *
  33  * @author      Kasper Skaarhoj <kasperYYYY@typo3.com>
  34  */
  35 /**
  36  * [CLASS/FUNCTION INDEX of SCRIPT]
  37  *
  38  *
  39  *
  40  *  145: class t3lib_extobjbase
  41  *  197:     function init(&$pObj,$conf)
  42  *  221:     function handleExternalFunctionValue()
  43  *  237:     function incLocalLang()
  44  *  253:     function checkExtObj()
  45  *  268:     function extObjContent()
  46  *  279:     function modMenu()
  47  *
  48  * TOTAL FUNCTIONS: 6
  49  * (This index is automatically created/updated by the extension "extdeveval")
  50  *
  51  */
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63 /**
  64  * EXAMPLE: One level.
  65  *
  66  * This can be seen in the extension 'cms' where the info module have a function added. In 'ext_tables.php' this is done by this function call:
  67  *
  68  *      t3lib_extMgm::insertModuleFunction(
  69  *              'web_info',
  70  *              'tx_cms_webinfo_page',
  71  *              t3lib_extMgm::extPath($_EXTKEY).'web_info/class.tx_cms_webinfo.php',
  72  *              'LLL:EXT:cms/locallang_tca.php:mod_tx_cms_webinfo_page'
  73  *      );
  74  *
  75  *
  76  *
  77  * EXAMPLE: Two levels.
  78  * This is the advanced example. You can see it with the extension 'func_wizards' which is the first layer but then providing another layer for extensions to connect by.
  79  * The key used in TBE_MODULES_EXT is normally 'function' (for the 'function menu') but the 'func_wizards' extension uses an alternative key for its configuration: 'wiz'.
  80  * In the 'ext_tables.php' file of an extension ('wizard_crpages') which uses the framework provided by 'func_wizards' this looks like this:
  81  *
  82  *      t3lib_extMgm::insertModuleFunction(
  83  *              'web_func',
  84  *              'tx_wizardcrpages_webfunc_2',
  85  *              t3lib_extMgm::extPath($_EXTKEY).'class.tx_wizardcrpages_webfunc_2.php',
  86  *              'LLL:EXT:wizard_crpages/locallang.php:wiz_crMany',
  87  *              'wiz'
  88  *      );
  89  *
  90  * But for this two-level thing to work it also requires that the parent module (the real backend module) supports it.
  91  * This is the case for the modules web_func and web_info since they have two times inclusion sections in their index.php scripts. For example (from web_func):
  92  *
  93  *      // Make instance:
  94  *      $SOBE = t3lib_div::makeInstance("SC_mod_web_func_index");
  95  *      $SOBE->init();
  96  *
  97  *      // Include files?
  98  *      foreach($SOBE->include_once as $INC_FILE)       include_once($INC_FILE);
  99  *      $SOBE->checkExtObj();   // Checking for first level external objects
 100  *
 101  *      // Repeat Include files! - if any files has been added by second-level extensions
 102  *      foreach($SOBE->include_once as $INC_FILE)       include_once($INC_FILE);
 103  *      $SOBE->checkSubExtObj();        // Checking second level external objects
 104  *
 105  *      $SOBE->main();
 106  *      $SOBE->printContent();
 107  *
 108  * Notice that the first part is as usual: Include classes and call $SOBE->checkExtObj() to initialize any level-1 sub-modules
 109  * But then again ->include_once is traversed IF the initialization of the level-1 modules might have added more files!!
 110  * And after that $SOBE->checkSubExtObj() is called to initialize the second level.
 111  * In this way even a third level could be supported - but most likely that is a too layered model to be practical.
 112  *
 113  * Anyways, the final interesting thing is to see what the framework "func_wizard" actually does:
 114  *
 115  *      require_once(PATH_t3lib."class.t3lib_extobjbase.php");
 116  *      class tx_funcwizards_webfunc extends t3lib_extobjbase {
 117  *              var $localLangFile = "locallang.php";
 118  *              var $function_key = "wiz";
 119  *              function init(&$pObj,$conf)     {
 120  *                              // OK, handles ordinary init. This includes setting up the menu array with ->modMenu
 121  *                      parent::init($pObj,$conf);
 122  *                              // Making sure that any further external classes are added to the include_once array. Notice that inclusion happens twice in the main script because of this!!!
 123  *                      $this->handleExternalFunctionValue();
 124  *              }
 125  *      ....
 126  *
 127  * Notice that the handleExternalFunctionValue of this class (t3lib_extobjbase) is called and that the ->function_key internal var is set!
 128  *
 129  * The two level-2 sub-module "wizard_crpages" and "wizard_sortpages" are totally normal "submodules".
 130  */
 131
 132 /**
 133  * Parent class for 'Extension Objects' in backend modules.
 134  * Used for 'submodules' to other modules. Also called 'Function menu modules' in t3lib_extMgm. And now its even called 'Extension Objects'. Or 'Module functions'. Wish we had just one name. Or a name at all...(?) Thank God its not so advanced when it works...
 135  * In other words this class is used for backend modules which is not true backend modules appearing in the menu but rather adds themselves as a new entry in the function menu which typically exists for a backend module (like Web>Functions, Web>Info or Tools etc...)
 136  * The magic that binds this together is stored in the global variable $TBE_MODULES_EXT where extensions wanting to connect a module based on this class to an existing backend module store configuration which consists of the classname, script-path and a label (title/name)
 137  * For more information about this, please see the large example comment for the class t3lib_SCbase. This will show the principle of a 'level-1' connection.
 138  * The more advanced example - having two layers as it is done by the 'func_wizards' extension with the 'web_info' module - can be seen in the comment above.
 139  *
 140  * @author      Kasper Skaarhoj <kasperYYYY@typo3.com>
 141  * @package TYPO3
 142  * @subpackage t3lib
 143  * @see t3lib_SCbase,tx_funcwizards_webfunc::init(), tx_funcwizards_webfunc, tx_wizardsortpages_webfunc_2
 144  */
 145 class t3lib_extobjbase {
 146
 147         /**
 148          * Contains a reference to the parent (calling) object (which is probably an instance of an extension class to t3lib_SCbase)
 149          *
 150          * @var t3lib_SCbase
 151          * @see init()
 152          */
 153         var $pObj;      // parent SC object
 154
 155         /**
 156          * Set to the directory name of this class file.
 157          * @see init()
 158          */
 159         var $thisPath = '';
 160
 161         /**
 162          * Can be hardcoded to the name of a locallang.php file (from the same directory as the class file) to use/load
 163          * @see incLocalLang()
 164          */
 165         var $localLangFile = 'locallang.php';
 166
 167         /**
 168          * Contains module configuration parts from TBE_MODULES_EXT if found
 169          *
 170          * @see handleExternalFunctionValue()
 171          */
 172         var $extClassConf;
 173
 174         /**
 175          * If this value is set it points to a key in the TBE_MODULES_EXT array (not on the top level..) where another classname/filepath/title can be defined for sub-subfunctions.
 176          * This is a little hard to explain, so see it in action; it used in the extension 'func_wizards' in order to provide yet a layer of interfacing with the backend module.
 177          * The extension 'func_wizards' has this description: 'Adds the 'Wizards' item to the function menu in Web>Func. This is just a framework for wizard extensions.' - so as you can see it is designed to allow further connectivity - 'level 2'
 178          *
 179          * @see handleExternalFunctionValue(), tx_funcwizards_webfunc
 180          */
 181         var $function_key = '';
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191         /**
 192          * Initialize the object
 193          *
 194          * @param       object          A reference to the parent (calling) object (which is probably an instance of an extension class to t3lib_SCbase)
 195          * @param       array           The configuration set for this module - from global array TBE_MODULES_EXT
 196          * @return      void
 197          * @see t3lib_SCbase::checkExtObj()
 198          */
 199         function init(&$pObj,$conf)     {
 200                 global $LANG;
 201
 202                 $this->pObj = &$pObj;
 203
 204                         // Path of this script:
 205                 $this->thisPath = dirname($conf['path']);
 206                 if (!@is_dir($this->thisPath))  {
 207                         die('Error: '.$this->thisPath.' was not a directory as expected...');
 208                 }
 209
 210                         // Local lang:
 211                 $this->incLocalLang();
 212
 213                         // Setting MOD_MENU items as we need them for logging:
 214                 $this->pObj->MOD_MENU = array_merge($this->pObj->MOD_MENU,$this->modMenu());            // Candidate for t3lib_div::array_merge() if integer-keys will some day make trouble...
 215         }
 216
 217         /**
 218          * If $this->function_key is set (which means there are two levels of object connectivity) then $this->extClassConf is loaded with the TBE_MODULES_EXT configuration for that sub-sub-module
 219          *
 220          * @return      void
 221          * @see $function_key, tx_funcwizards_webfunc::init()
 222          */
 223         function handleExternalFunctionValue()  {
 224                         // Must clean first to make sure the correct key is set...
 225                 $this->pObj->MOD_SETTINGS = t3lib_BEfunc::getModuleData($this->pObj->MOD_MENU, t3lib_div::_GP('SET'), $this->pObj->MCONF['name']);
 226                 if ($this->function_key)        {
 227                         $this->extClassConf = $this->pObj->getExternalItemConfig($this->pObj->MCONF['name'],$this->function_key,$this->pObj->MOD_SETTINGS[$this->function_key]);
 228                         if (is_array($this->extClassConf) && $this->extClassConf['path'])       {
 229                                 $this->pObj->include_once[] = $this->extClassConf['path'];
 230                         }
 231                 }
 232         }
 233
 234         /**
 235          * Including any locallang file configured and merging its content over the current global LOCAL_LANG array (which is EXPECTED to exist!!!)
 236          *
 237          * @return      void
 238          */
 239         function incLocalLang() {
 240                 global $LANG;
 241                 #if ($this->localLangFile && @is_file($this->thisPath.'/'.$this->localLangFile))        {
 242                 #       include($this->thisPath.'/'.$this->localLangFile);
 243                 if ($this->localLangFile && (@is_file($this->thisPath.'/'.$this->localLangFile) || @is_file($this->thisPath.'/'.substr($this->localLangFile,0,-4).'.xml')))     {
 244                         $LOCAL_LANG = $LANG->includeLLFile($this->thisPath.'/'.$this->localLangFile, FALSE);
 245                         if (is_array($LOCAL_LANG)) {
 246                                 $GLOBALS['LOCAL_LANG'] = t3lib_div::array_merge_recursive_overrule((array)$GLOBALS['LOCAL_LANG'], $LOCAL_LANG);
 247                         }
 248                 }
 249         }
 250
 251         /**
 252          * Same as t3lib_SCbase::checkExtObj()
 253          *
 254          * @return      void
 255          * @see t3lib_SCbase::checkExtObj()
 256          */
 257         function checkExtObj()  {
 258                 if (is_array($this->extClassConf) && $this->extClassConf['name'])       {
 259                         $this->extObj = t3lib_div::makeInstance($this->extClassConf['name']);
 260                         $this->extObj->init($this->pObj,$this->extClassConf);
 261
 262                                 // Re-write:
 263                         $this->pObj->MOD_SETTINGS = t3lib_BEfunc::getModuleData($this->pObj->MOD_MENU, t3lib_div::_GP('SET'), $this->pObj->MCONF['name']);
 264                 }
 265         }
 266
 267         /**
 268          * Calls the main function inside ANOTHER sub-submodule which might exist.
 269          *
 270          * @return      void
 271          */
 272         function extObjContent()        {
 273                 if (is_object($this->extObj))   return $this->extObj->main();
 274         }
 275
 276         /**
 277          * Dummy function - but is used to set up additional menu items for this submodule.
 278          * For an example see the extension 'cms' where the 'web_info' submodule is defined in cms/web_info/class.tx_cms_webinfo.php, tx_cms_webinfo_page::modMenu()
 279          *
 280          * @return      array           A MOD_MENU array which will be merged together with the one from the parent object
 281          * @see init(), tx_cms_webinfo_page::modMenu()
 282          */
 283         function modMenu()      {
 284                 return array();
 285         }
 286 }
 287 ?>