Initial revision
[Packages/TYPO3.CMS.git] / t3lib / class.t3lib_extobjbase.php
1 <?php
2 /***************************************************************
3 * Copyright notice
4 *
5 * (c) 1999-2003 Kasper Skårhøj (kasper@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 * Revised for TYPO3 3.6 July/2003 by Kasper Skårhøj
31 *
32 * @author Kasper Skårhøj <kasper@typo3.com>
33 * @package TYPO3
34 * @subpackage t3lib
35 */
36 /**
37 * [CLASS/FUNCTION INDEX of SCRIPT]
38 *
39 *
40 *
41 * 147: class t3lib_extobjbase
42 * 199: function init(&$pObj,$conf)
43 * 223: function handleExternalFunctionValue()
44 * 239: function incLocalLang()
45 * 252: function checkExtObj()
46 * 267: function extObjContent()
47 * 278: function modMenu()
48 *
49 * TOTAL FUNCTIONS: 6
50 * (This index is automatically created/updated by the extension "extdeveval")
51 *
52 */
53 /**
54 * EXAMPLE: One level.
55 *
56 * 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:
57 *
58 * t3lib_extMgm::insertModuleFunction(
59 * 'web_info',
60 * 'tx_cms_webinfo_page',
61 * t3lib_extMgm::extPath($_EXTKEY).'web_info/class.tx_cms_webinfo.php',
62 * 'LLL:EXT:cms/locallang_tca.php:mod_tx_cms_webinfo_page'
63 * );
64 *
65 *
66 *
67 * EXAMPLE: Two levels.
68 * 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.
69 * 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'.
70 * In the 'ext_tables.php' file of an extension ('wizard_crpages') which uses the framework provided by 'func_wizards' this looks like this:
71 *
72 * t3lib_extMgm::insertModuleFunction(
73 * 'web_func',
74 * 'tx_wizardcrpages_webfunc_2',
75 * t3lib_extMgm::extPath($_EXTKEY).'class.tx_wizardcrpages_webfunc_2.php',
76 * 'LLL:EXT:wizard_crpages/locallang.php:wiz_crMany',
77 * 'wiz'
78 * );
79 *
80 * But for this two-level thing to work it also requires that the parent module (the real backend module) supports it.
81 * 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):
82 *
83 * // Make instance:
84 * $SOBE = t3lib_div::makeInstance("SC_mod_web_func_index");
85 * $SOBE->init();
86 *
87 * // Include files?
88 * reset($SOBE->include_once);
89 * while(list(,$INC_FILE)=each($SOBE->include_once)) {include_once($INC_FILE);}
90 * $SOBE->checkExtObj(); // Checking for first level external objects
91 *
92 * // Repeat Include files! - if any files has been added by second-level extensions
93 * reset($SOBE->include_once);
94 * while(list(,$INC_FILE)=each($SOBE->include_once)) {include_once($INC_FILE);}
95 * $SOBE->checkSubExtObj(); // Checking second level external objects
96 *
97 * $SOBE->main();
98 * $SOBE->printContent();
99 *
100 * Notice that the first part is as usual: Include classes and call $SOBE->checkExtObj() to initialize any level-1 sub-modules
101 * But then again ->include_once is traversed IF the initialization of the level-1 modules might have added more files!!
102 * And after that $SOBE->checkSubExtObj() is called to initialize the second level.
103 * In this way even a third level could be supported - but most likely that is a too layered module to be practical.
104 *
105 * Anyways, the final interesting thing is to see what the framework "func_wizard" actually does:
106 *
107 * require_once(PATH_t3lib."class.t3lib_extobjbase.php");
108 * class tx_funcwizards_webfunc extends t3lib_extobjbase {
109 * var $localLangFile = "locallang.php";
110 * var $function_key = "wiz";
111 * function init(&$pObj,$conf) {
112 * // OK, handles ordinary init. This includes setting up the menu array with ->modMenu
113 * parent::init($pObj,$conf);
114 * // 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!!!
115 * $this->handleExternalFunctionValue();
116 * }
117 * ....
118 *
119 * Notice that the handleExternalFunctionValue of this class (t3lib_extobjbase) is called and that the ->function_key internal var is set!
120 *
121 * The two level-2 sub-module "wizard_crpages" and "wizard_sortpages" are totally normal "submodules".
122 */
123
124
125
126
127
128
129
130
131
132
133
134
135 /**
136 * Parent class for 'Extension Objects' in backend modules.
137 * 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...
138 * 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...)
139 * 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)
140 * 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.
141 * 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.
142 *
143 * @see t3lib_SCbase
144 * @author Kasper Skårhøj <kasper@typo3.com>
145 * @see tx_funcwizards_webfunc::init(), tx_funcwizards_webfunc, tx_wizardsortpages_webfunc_2
146 */
147 class t3lib_extobjbase {
148
149 /**
150 * Contains a reference to the parent object.
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 TCE_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
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::GPvar('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 if ($this->localLangFile && @is_file($this->thisPath.'/'.$this->localLangFile)) {
241 include($this->thisPath.'/'.$this->localLangFile);
242 $GLOBALS['LOCAL_LANG']=t3lib_div::array_merge_recursive_overrule($GLOBALS['LOCAL_LANG'],$LOCAL_LANG);
243 }
244 }
245
246 /**
247 * Same as t3lib_SCbase::checkExtObj()
248 *
249 * @return void
250 * @see t3lib_SCbase::checkExtObj()
251 */
252 function checkExtObj() {
253 if (is_array($this->extClassConf) && $this->extClassConf['name']) {
254 $this->extObj = t3lib_div::makeInstance($this->extClassConf['name']);
255 $this->extObj->init($this->pObj,$this->extClassConf);
256
257 // Re-write:
258 $this->pObj->MOD_SETTINGS = t3lib_BEfunc::getModuleData($this->pObj->MOD_MENU, t3lib_div::GPvar('SET'), $this->pObj->MCONF['name']);
259 }
260 }
261
262 /**
263 * Calls the main function inside ANOTHER sub-submodule which might exist.
264 *
265 * @return void
266 */
267 function extObjContent() {
268 if (is_object($this->extObj)) return $this->extObj->main();
269 }
270
271 /**
272 * Dummy function - but is used to set up additional menu items for this submodule.
273 * 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()
274 *
275 * @return array A MOD_MENU array which will be merged together with the one from the parent object
276 * @see init(), tx_cms_webinfo_page::modMenu()
277 */
278 function modMenu() {
279 return array();
280 }
281 }
282 ?>