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