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