t3lib/class.t3lib_scbase.php

   1 <?php
   2 /***************************************************************
   3 *  Copyright notice
   4 *
   5 *  (c) 1999-2005 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 parent class for 'ScriptClasses' 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  *  133: class t3lib_SCbase
  41  *  249:     function init()
  42  *  269:     function menuConfig()
  43  *  292:     function mergeExternalItems($modName,$menuKey,$menuArr)
  44  *  317:     function handleExternalFunctionValue($MM_key='function', $MS_value=NULL)
  45  *  335:     function getExternalItemConfig($modName,$menuKey,$value='')
  46  *  349:     function checkExtObj()
  47  *  363:     function checkSubExtObj()
  48  *  375:     function extObjHeader()
  49  *  384:     function extObjContent()
  50  *
  51  * TOTAL FUNCTIONS: 9
  52  * (This index is automatically created/updated by the extension "extdeveval")
  53  *
  54  */
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70 /**
  71  * EXAMPLE PROTOTYPE
  72  *
  73  * As for examples there are lots of them if you search for classes which extends 't3lib_SCbase'.
  74  * However you can see a prototype example of how a module might use this class in an index.php file typically hosting a backend module.
  75  * NOTICE: This example only outlines the basic structure of how this class is used. You should consult the documentation and other real-world examples for some actual things to do when building modules.
  76  *
  77  *                // TYPICAL 'HEADER' OF A BACKEND MODULE:
  78  *              unset($MCONF);
  79  *              require ('conf.php');
  80  *              require ($BACK_PATH.'init.php');
  81  *              require ($BACK_PATH.'template.php');
  82  *              $LANG->includeLLFile('EXT:prototype/locallang.php');
  83  *              require_once(PATH_t3lib.'class.t3lib_scbase.php');              // NOTICE THE INCLUSION OF t3lib_SCbase
  84  *              $BE_USER->modAccess($MCONF,1);
  85  *
  86  *                      // SC_mod_prototype EXTENDS THE CLASS t3lib_SCbase with a main() and printContent() function:
  87  *              class SC_mod_prototype extends t3lib_SCbase {
  88  *                              // MAIN FUNCTION - HERE YOU CREATE THE MODULE CONTENT IN $this->content
  89  *                      function main() {
  90  *                                      // TYPICALLY THE INTERNAL VAR, $this->doc is instantiated like this:
  91  *                              $this->doc = t3lib_div::makeInstance('mediumDoc');
  92  *                                      // TYPICALLY THE INTERNAL VAR, $this->backPath is set like this:
  93  *                              $this->backPath = $this->doc->backPath = $GLOBALS['BACK_PATH'];
  94  *                                      // ... AND OF COURSE A LOT OF OTHER THINGS GOES ON - LIKE PUTTING CONTENT INTO $this->content
  95  *                              $this->content='';
  96  *                      }
  97  *                              // PRINT CONTENT - DONE AS THE LAST THING
  98  *                      function printContent() {
  99  *                              echo $this->content;
 100  *                      }
 101  *              }
 102  *
 103  *                      // CHECKING IF THERE ARE AN EXTENSION CLASS CONFIGURED FOR THIS CLASS:
 104  *              if (defined('TYPO3_MODE') && $TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['ext/prototype/index.php']) {
 105  *                      include_once($TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['ext/prototype/index.php']);
 106  *              }
 107  *
 108  *                // MAKE INSTANCE OF THE SCRIPT CLASS AND CALL init()
 109  *              $SOBE = t3lib_div::makeInstance('SC_mod_prototype');
 110  *              $SOBE->init();
 111  *
 112  *                // AFTER INIT THE INTERNAL ARRAY ->include_once MAY HOLD FILENAMES TO INCLUDE
 113  *              foreach($SOBE->include_once as $INC_FILE)       include_once($INC_FILE);
 114  *
 115  *                // THEN WE WILL CHECK IF THERE IS A 'SUBMODULE' REGISTERED TO BE INITIALIZED AS WELL:
 116  *              $SOBE->checkExtObj();
 117  *
 118  *                // THEN WE CALL THE main() METHOD AND THIS SHOULD SPARK THE CREATION OF THE MODULE OUTPUT.
 119  *              $SOBE->main();
 120  *                // FINALLY THE printContent() FUNCTION WILL OUTPUT THE ACCUMULATED CONTENT
 121  *              $SOBE->printContent();
 122  */
 123
 124 /**
 125  * Parent class for 'ScriptClasses' in backend modules.
 126  * See example comment above.
 127  *
 128  * @author      Kasper Skaarhoj <kasperYYYY@typo3.com>
 129  * @package TYPO3
 130  * @subpackage t3lib
 131  * @see t3lib_extobjbase
 132  */
 133 class t3lib_SCbase {
 134
 135         /**
 136          * Loaded with the global array $MCONF which holds some module configuration from the conf.php file of backend modules.
 137          * @see init()
 138          */
 139         var $MCONF = array();
 140
 141         /**
 142          * The integer value of the GET/POST var, 'id'. Used for submodules to the 'Web' module (page id)
 143          * @see init()
 144          */
 145         var $id;
 146
 147         /**
 148          * The value of GET/POST var, 'CMD'
 149          * @see init()
 150          */
 151         var $CMD;
 152
 153         /**
 154          * A WHERE clause for selection records from the pages table based on read-permissions of the current backend user.
 155          * @see init()
 156          */
 157         var $perms_clause;
 158
 159
 160
 161         /**
 162          * The module menu items array. Each key represents a key for which values can range between the items in the array of that key.
 163          * @see init()
 164          */
 165         var $MOD_MENU = Array (
 166                         'function' => array()
 167                 );
 168
 169         /**
 170          * Current settings for the keys of the MOD_MENU array
 171          * @see $MOD_MENU
 172          */
 173         var $MOD_SETTINGS = array();
 174
 175         /**
 176          * Module TSconfig based on PAGE TSconfig / USER TSconfig
 177          * @see menuConfig()
 178          */
 179         var $modTSconfig;
 180
 181         /**
 182          * If type is 'ses' then the data is stored as session-lasting data. This means that it'll be wiped out the next time the user logs in.
 183          * Can be set from extension classes of this class before the init() function is called.
 184          *
 185          * @see menuConfig(), t3lib_BEfunc::getModuleData()
 186          */
 187         var $modMenu_type = '';
 188
 189         /**
 190          * dontValidateList can be used to list variables that should not be checked if their value is found in the MOD_MENU array. Used for dynamically generated menus.
 191          * Can be set from extension classes of this class before the init() function is called.
 192          *
 193          * @see menuConfig(), t3lib_BEfunc::getModuleData()
 194          */
 195         var $modMenu_dontValidateList = '';
 196
 197         /**
 198          * List of default values from $MOD_MENU to set in the output array (only if the values from MOD_MENU are not arrays)
 199          * Can be set from extension classes of this class before the init() function is called.
 200          *
 201          * @see menuConfig(), t3lib_BEfunc::getModuleData()
 202          */
 203         var $modMenu_setDefaultList = '';
 204
 205         /**
 206          * Contains module configuration parts from TBE_MODULES_EXT if found
 207          *
 208          * @see handleExternalFunctionValue()
 209          */
 210         var $extClassConf;
 211
 212         /**
 213          * Contains absolute paths to class files to include from the global scope. This is done in the module index.php files after calling the init() function
 214          *
 215          * @see handleExternalFunctionValue()
 216          */
 217         var $include_once = array();
 218
 219         /**
 220          * Generally used for accumulating the output content of backend modules
 221          */
 222         var $content = '';
 223
 224         /**
 225          * Generally used to hold an instance of the 'template' class from typo3/template.php
 226          *
 227          * @var template
 228          */
 229         var $doc;
 230
 231         /**
 232          * May contain an instance of a 'Function menu module' which connects to this backend module.
 233          *
 234          * @see checkExtObj()
 235          */
 236         var $extObj;
 237
 238
 239
 240
 241
 242
 243
 244
 245         /**
 246          * Initializes the backend module by setting internal variables, initializing the menu.
 247          *
 248          * @return      void
 249          * @see menuConfig()
 250          */
 251         function init() {
 252                         // name might be set from outside
 253                 if (!$this->MCONF['name']) {
 254                         $this->MCONF = $GLOBALS['MCONF'];
 255                 }
 256                 $this->id = intval(t3lib_div::_GP('id'));
 257                 $this->CMD = t3lib_div::_GP('CMD');
 258                 $this->perms_clause = $GLOBALS['BE_USER']->getPagePermsClause(1);
 259                 $this->menuConfig();
 260                 $this->handleExternalFunctionValue();
 261         }
 262
 263         /**
 264          * Initializes the internal MOD_MENU array setting and unsetting items based on various conditions. It also merges in external menu items from the global array TBE_MODULES_EXT (see mergeExternalItems())
 265          * Then MOD_SETTINGS array is cleaned up (see t3lib_BEfunc::getModuleData()) so it contains only valid values. It's also updated with any SET[] values submitted.
 266          * Also loads the modTSconfig internal variable.
 267          *
 268          * @return      void
 269          * @see init(), $MOD_MENU, $MOD_SETTINGS, t3lib_BEfunc::getModuleData(), mergeExternalItems()
 270          */
 271         function menuConfig()   {
 272                         // page/be_user TSconfig settings and blinding of menu-items
 273                 $this->modTSconfig = t3lib_BEfunc::getModTSconfig($this->id,'mod.'.$this->MCONF['name']);
 274                 $this->MOD_MENU['function'] = $this->mergeExternalItems($this->MCONF['name'],'function',$this->MOD_MENU['function']);
 275                 $this->MOD_MENU['function'] = t3lib_BEfunc::unsetMenuItems($this->modTSconfig['properties'],$this->MOD_MENU['function'],'menu.function');
 276
 277                 #debug($this->MOD_MENU['function'],$this->MCONF['name']);
 278                 #debug($this->modTSconfig['properties']);
 279
 280                 $this->MOD_SETTINGS = t3lib_BEfunc::getModuleData($this->MOD_MENU, t3lib_div::_GP('SET'), $this->MCONF['name'], $this->modMenu_type, $this->modMenu_dontValidateList, $this->modMenu_setDefaultList);
 281         }
 282
 283         /**
 284          * Merges menu items from global array $TBE_MODULES_EXT
 285          *
 286          * @param       string          Module name for which to find value
 287          * @param       string          Menu key, eg. 'function' for the function menu.
 288          * @param       array           The part of a MOD_MENU array to work on.
 289          * @return      array           Modified array part.
 290          * @access private
 291          * @see t3lib_extMgm::insertModuleFunction(), menuConfig()
 292          */
 293         function mergeExternalItems($modName,$menuKey,$menuArr) {
 294                 $mergeArray = $GLOBALS['TBE_MODULES_EXT'][$modName]['MOD_MENU'][$menuKey];
 295                 if (is_array($mergeArray))      {
 296                         reset($mergeArray);
 297                         while(list($k,$v)=each($mergeArray))    {
 298                                 if ((string)$v['ws']==='' ||
 299                                         ($GLOBALS['BE_USER']->workspace===0 && t3lib_div::inList($v['ws'],'online')) ||
 300                                         ($GLOBALS['BE_USER']->workspace===-1 && t3lib_div::inList($v['ws'],'offline')) ||
 301                                         ($GLOBALS['BE_USER']->workspace>0 && t3lib_div::inList($v['ws'],'custom')))     {
 302                                                 $menuArr[$k]=$GLOBALS['LANG']->sL($v['title']);
 303                                 }
 304                         }
 305                 }
 306                 return $menuArr;
 307         }
 308
 309         /**
 310          * Loads $this->extClassConf with the configuration for the CURRENT function of the menu.
 311          * If for this array the key 'path' is set then that is expected to be an absolute path to a file which should be included - so it is set in the internal array $this->include_once
 312          *
 313          * @param       string          The key to MOD_MENU for which to fetch configuration. 'function' is default since it is first and foremost used to get information per "extension object" (I think that is what its called)
 314          * @param       string          The value-key to fetch from the config array. If NULL (default) MOD_SETTINGS[$MM_key] will be used. This is usefull if you want to force another function than the one defined in MOD_SETTINGS[function]. Call this in init() function of your Script Class: handleExternalFunctionValue('function', $forcedSubModKey)
 315          * @return      void
 316          * @see getExternalItemConfig(), $include_once, init()
 317          */
 318         function handleExternalFunctionValue($MM_key='function', $MS_value=NULL)        {
 319                 $MS_value = is_null($MS_value) ? $this->MOD_SETTINGS[$MM_key] : $MS_value;
 320                 $this->extClassConf = $this->getExternalItemConfig($this->MCONF['name'],$MM_key,$MS_value);
 321                 if (is_array($this->extClassConf) && $this->extClassConf['path'])       {
 322                         $this->include_once[]=$this->extClassConf['path'];
 323                 }
 324         }
 325
 326         /**
 327          * Returns configuration values from the global variable $TBE_MODULES_EXT for the module given.
 328          * For example if the module is named "web_info" and the "function" key ($menuKey) of MOD_SETTINGS is "stat" ($value) then you will have the values of $TBE_MODULES_EXT['webinfo']['MOD_MENU']['function']['stat'] returned.
 329          *
 330          * @param       string          Module name
 331          * @param       string          Menu key, eg. "function" for the function menu. See $this->MOD_MENU
 332          * @param       string          Optionally the value-key to fetch from the array that would otherwise have been returned if this value was not set. Look source...
 333          * @return      mixed           The value from the TBE_MODULES_EXT array.
 334          * @see handleExternalFunctionValue()
 335          */
 336         function getExternalItemConfig($modName,$menuKey,$value='')     {
 337                 return strcmp($value,'')?$GLOBALS['TBE_MODULES_EXT'][$modName]['MOD_MENU'][$menuKey][$value]:$GLOBALS['TBE_MODULES_EXT'][$modName]['MOD_MENU'][$menuKey];
 338         }
 339
 340         /**
 341          * Creates an instance of the class found in $this->extClassConf['name'] in $this->extObj if any (this should hold three keys, "name", "path" and "title" if a "Function menu module" tries to connect...)
 342          * This value in extClassConf might be set by an extension (in a ext_tables/ext_localconf file) which thus "connects" to a module.
 343          * The array $this->extClassConf is set in handleExternalFunctionValue() based on the value of MOD_SETTINGS[function]
 344          * (Should be) called from global scope right after inclusion of files from the ->include_once array.
 345          * If an instance is created it is initiated with $this passed as value and $this->extClassConf as second argument. Further the $this->MOD_SETTING is cleaned up again after calling the init function.
 346          *
 347          * @return      void
 348          * @see handleExternalFunctionValue(), t3lib_extMgm::insertModuleFunction(), $extObj
 349          */
 350         function checkExtObj()  {
 351                 if (is_array($this->extClassConf) && $this->extClassConf['name'])       {
 352                         $this->extObj = t3lib_div::makeInstance($this->extClassConf['name']);
 353                         $this->extObj->init($this,$this->extClassConf);
 354                                 // Re-write:
 355                         $this->MOD_SETTINGS = t3lib_BEfunc::getModuleData($this->MOD_MENU, t3lib_div::_GP('SET'), $this->MCONF['name'], $this->modMenu_type, $this->modMenu_dontValidateList, $this->modMenu_setDefaultList);
 356                 }
 357         }
 358
 359         /**
 360          * Calls the checkExtObj function in sub module if present.
 361          *
 362          * @return      void
 363          */
 364         function checkSubExtObj()       {
 365                 if (is_object($this->extObj))   $this->extObj->checkExtObj();
 366         }
 367
 368         /**
 369          * Calls the 'header' function inside the "Function menu module" if present.
 370          * A header function might be needed to add JavaScript or other stuff in the head. This can't be done in the main function because the head is already written.
 371          * example call in the header function:
 372          * $this->pObj->doc->JScode = $this->pObj->doc->wrapScriptTags(' ...
 373          *
 374          * @return      void
 375          */
 376         function extObjHeader() {
 377                 if (is_callable(array($this->extObj,'head')))   $this->extObj->head();
 378         }
 379
 380         /**
 381          * Calls the 'main' function inside the "Function menu module" if present
 382          *
 383          * @return      void
 384          */
 385         function extObjContent()        {
 386                 $this->extObj->pObj = &$this;
 387                 if (is_callable(array($this->extObj, 'main')))  $this->content.=$this->extObj->main();
 388         }
 389 }
 390 ?>