[TASK] Clean up phpDoc comments in t3lib classes
[Packages/TYPO3.CMS.git] / t3lib / class.t3lib_modsettings.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 *
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 * Manage storing and restoring of $GLOBALS['SOBE']->MOD_SETTINGS settings.
29 * Provides a presets box for BE modules.
30 *
31 * inspired by t3lib_fullsearch
32 *
33 * @author René Fritz <r.fritz@colorcube.de>
34 */
35
36 /**
37 * usage inside of scbase class
38 *
39 * ....
40 *
41 * $this->MOD_MENU = array(
42 * 'function' => array(
43 * 'xxx ...
44 * ),
45 * 'tx_dam_select_storedSettings' => '',
46 *
47 * ....
48 *
49 * function main() {
50 * // reStore settings
51 * $store = t3lib_div::makeInstance('t3lib_modSettings');
52 * $store->init('tx_dam_select');
53 * $store->setStoreList('tx_dam_select');
54 * $store->processStoreControl();
55 *
56 * // show control panel
57 * $this->content.= $this->doc->section('Settings',$store->getStoreControl(),0,1);
58 *
59 * Format of saved settings
60 *
61 * $GLOBALS['SOBE']->MOD_SETTINGS[$this->prefix.'_storedSettings'] = serialize(
62 * array (
63 * 'any id' => array (
64 * 'title' => 'title for saved settings',
65 * 'desc' => 'descritpion text, not mandatory',
66 * 'data' => array(), // data from MOD_SETTINGS
67 * 'user' => NULL, // can be used for extra data used by the application to identify this entry
68 * 'tstamp' => 12345, // $GLOBALS['EXEC_TIME']
69 * ),
70 * 'another id' => ...
71 *
72 * ) );
73 *
74 */
75
76 /**
77 * Manage storing and restoring of $GLOBALS['SOBE']->MOD_SETTINGS settings.
78 * Provides a presets box for BE modules.
79 *
80 * @author René Fritz <r.fritz@colorcube.de>
81 * @package TYPO3
82 * @subpackage t3lib
83 */
84 class t3lib_modSettings {
85
86 /**
87 * If type is set 'ses' then the module data will be stored into the session and will be lost with logout.
88 * Type 'perm' will store the data permanently.
89 */
90 var $type = 'perm';
91
92 /**
93 * prefix of MOD_SETTING array keys that should be stored
94 */
95 var $prefix = '';
96
97 /**
98 * Names of keys of the MOD_SETTING array which should be stored
99 */
100 var $storeList = array();
101
102 /**
103 * The stored settings array
104 */
105 var $storedSettings = array();
106
107 /**
108 * Message from the last storage command
109 */
110 var $msg = '';
111
112 /**
113 * Name of the form. Needed for JS
114 */
115 var $formName = 'storeControl';
116
117 // Write messages into the devlog?
118 var $writeDevLog = 0;
119
120 /********************************
121 *
122 * Init / setup
123 *
124 ********************************/
125
126 /**
127 * Initializes the object
128 *
129 * @param string $prefix Prefix of MOD_SETTING array keys that should be stored
130 * @param array $storeList Additional names of keys of the MOD_SETTING array which should be stored (array or comma list)
131 * @return void
132 */
133 function init($prefix = '', $storeList = '') {
134 $this->prefix = $prefix;
135 $this->setStoreList($storeList);
136 $this->type = 'perm';
137
138 // Enable dev logging if set
139 if ($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_modSettings.php']['writeDevLog']) {
140 $this->writeDevLog = TRUE;
141 }
142 if (TYPO3_DLOG) {
143 $this->writeDevLog = TRUE;
144 }
145 }
146
147 /**
148 * Set session type to 'ses' which will store the settings data not permanently.
149 *
150 * @param string $type Default is 'ses'
151 * @return void
152 */
153 function setSessionType($type = 'ses') {
154 $this->type = $type;
155 }
156
157 /********************************
158 *
159 * Store list - which values should be stored
160 *
161 ********************************/
162
163 /**
164 * Set MOD_SETTINGS keys which should be stored
165 *
166 * @param mixed $storeList Array or string (,) - set additional names of keys of the MOD_SETTING array which should be stored
167 * @return void
168 */
169 function setStoreList($storeList) {
170 $this->storeList = is_array($storeList) ? $storeList : t3lib_div::trimExplode(',', $storeList, 1);
171
172 if ($this->writeDevLog) {
173 t3lib_div::devLog('Store list:' . implode(',', $this->storeList), 't3lib_modSettings', 0);
174 }
175 }
176
177 /**
178 * Add MOD_SETTINGS keys to the current list
179 *
180 * @param mixed Array or string (,) - add names of keys of the MOD_SETTING array which should be stored
181 * @return void
182 */
183 function addToStoreList($storeList) {
184 $storeList = is_array($storeList) ? $storeList : t3lib_div::trimExplode(',', $storeList, 1);
185 $this->storeList = array_merge($this->storeList, $storeList);
186
187 if ($this->writeDevLog) {
188 t3lib_div::devLog('Store list:' . implode(',', $this->storeList), 't3lib_modSettings', 0);
189 }
190 }
191
192 /**
193 * Add names of keys of the MOD_SETTING array by a prefix
194 *
195 * @param string $prefix Prefix of MOD_SETTING array keys that should be stored
196 * @return void
197 */
198 function addToStoreListFromPrefix($prefix = '') {
199 $prefix = $prefix ? $prefix : $this->prefix;
200
201 foreach ($GLOBALS['SOBE']->MOD_SETTINGS as $key => $value) {
202 if (preg_match('/^' . $prefix . '/', $key)) {
203 $this->storeList[$key] = $key;
204 }
205 }
206
207 unset($this->storeList[$this->prefix . '_storedSettings']);
208
209 if ($this->writeDevLog) {
210 t3lib_div::devLog('Store list:' . implode(',', $this->storeList), 't3lib_modSettings', 0);
211 }
212 }
213
214 /********************************
215 *
216 * Process storage array
217 *
218 ********************************/
219
220 /**
221 * Get the stored settings from MOD_SETTINGS and set them in $this->storedSettings
222 *
223 * @return void
224 */
225 function initStorage() {
226 $storedSettings = unserialize($GLOBALS['SOBE']->MOD_SETTINGS[$this->prefix . '_storedSettings']);
227 $this->storedSettings = $this->cleanupStorageArray($storedSettings);
228 }
229
230 /**
231 * Remove corrupted data entries from the stored settings array
232 *
233 * @param array $storedSettings The stored settings
234 * @return array Cleaned up stored settings
235 */
236 function cleanupStorageArray($storedSettings) {
237
238 $storedSettings = is_array($storedSettings) ? $storedSettings : array();
239
240 // Clean up the array
241 foreach ($storedSettings as $id => $sdArr) {
242 if (!is_array($sdArr)) {
243 unset($storedSettings[$id]);
244 }
245 if (!is_array($sdArr['data'])) {
246 unset($storedSettings[$id]);
247 }
248 if (!trim($sdArr['title'])) {
249 $storedSettings[$id]['title'] = '[no title]';
250 }
251 }
252
253 return $storedSettings;
254 }
255
256 /**
257 * Creates an entry for the stored settings array
258 * Collects data from MOD_SETTINGS selected by the storeList
259 *
260 * @param array $data Should work with data from _GP('storeControl'). This is ['title']: Title for the entry. ['desc']: A description text. Currently not used by this class
261 * @return array Entry for the stored settings array
262 */
263 function compileEntry($data) {
264 $storageData = array();
265 foreach ($this->storeList as $MS_key) {
266 $storageData[$MS_key] = $GLOBALS['SOBE']->MOD_SETTINGS[$MS_key];
267 }
268 $storageArr = array(
269 'title' => $data['title'],
270 'desc' => (string) $data['desc'],
271 'data' => $storageData,
272 'user' => NULL,
273 'tstamp' => $GLOBALS['EXEC_TIME'],
274 );
275 $storageArr = $this->processEntry($storageArr);
276
277 return $storageArr;
278 }
279
280 /**
281 * Copies the stored data from entry $index to $writeArray which can be used to set MOD_SETTINGS
282 *
283 * @param mixed $storeIndex The entry key
284 * @param array $writeArray Preset data array. Will be overwritten by copied values.
285 * @return array Data array
286 */
287 function getStoredData($storeIndex, $writeArray = array()) {
288 if ($this->storedSettings[$storeIndex]) {
289 foreach ($this->storeList as $k) {
290 $writeArray[$k] = $this->storedSettings[$storeIndex]['data'][$k];
291 }
292 }
293 return $writeArray;
294 }
295
296 /**
297 * Processing of the storage command LOAD, SAVE, REMOVE
298 *
299 * @param string $mconfName Name of the module to store the settings for. Default: $GLOBALS['SOBE']->MCONF['name'] (current module)
300 * @return string Storage message. Also set in $this->msg
301 */
302 function processStoreControl($mconfName = '') {
303
304 $this->initStorage();
305
306 $storeControl = t3lib_div::_GP('storeControl');
307 $storeIndex = $storeControl['STORE'];
308
309 $msg = '';
310 $saveSettings = FALSE;
311 $writeArray = array();
312
313 if (is_array($storeControl)) {
314 if ($this->writeDevLog) {
315 t3lib_div::devLog('Store command: ' . t3lib_div::arrayToLogString($storeControl), 't3lib_modSettings', 0);
316 }
317
318 // Processing LOAD
319 if ($storeControl['LOAD'] AND $storeIndex) {
320 $writeArray = $this->getStoredData($storeIndex, $writeArray);
321 $saveSettings = TRUE;
322 $msg = "'" . $this->storedSettings[$storeIndex]['title'] . "' preset loaded!";
323
324 // Processing SAVE
325 } elseif ($storeControl['SAVE']) {
326 if (trim($storeControl['title'])) {
327
328 // Get the data to store
329 $newEntry = $this->compileEntry($storeControl);
330
331 // Create an index for the storage array
332 if (!$storeIndex) {
333 $storeIndex = t3lib_div::shortMD5($newEntry['title']);
334 }
335
336 // Add data to the storage array
337 $this->storedSettings[$storeIndex] = $newEntry;
338
339 $saveSettings = TRUE;
340 $msg = "'" . $newEntry['title'] . "' preset saved!";
341
342 } else {
343 $msg = 'Please enter a name for the preset!';
344 }
345
346 // Processing REMOVE
347 } elseif ($storeControl['REMOVE'] AND $storeIndex) {
348 // Removing entry
349 $msg = "'" . $this->storedSettings[$storeIndex]['title'] . "' preset entry removed!";
350 unset($this->storedSettings[$storeIndex]);
351
352 $saveSettings = TRUE;
353 }
354
355 $this->msg = $msg;
356
357 if ($saveSettings) {
358 $this->writeStoredSetting($writeArray, $mconfName);
359 }
360 }
361 return $this->msg;
362 }
363
364 /**
365 * Write the current storage array and update MOD_SETTINGS
366 *
367 * @param array $writeArray Array of settings which should be overwrite current MOD_SETTINGS
368 * @param string $mconfName Name of the module to store the settings for. Default: $GLOBALS['SOBE']->MCONF['name'] (current module)
369 * @return void
370 */
371 function writeStoredSetting($writeArray = array(), $mconfName = '') {
372 // for debugging: just removes all module data from user settings
373 // $GLOBALS['BE_USER']->pushModuleData($GLOBALS['SOBE']->MCONF['name'],array());
374
375 // Making sure, index 0 is not set
376 unset($this->storedSettings[0]);!
377 $this->storedSettings = $this->cleanupStorageArray($this->storedSettings);
378 $writeArray[$this->prefix . '_storedSettings'] = serialize($this->storedSettings);
379
380 $GLOBALS['SOBE']->MOD_SETTINGS = t3lib_BEfunc::getModuleData($GLOBALS['SOBE']->MOD_MENU, $writeArray, ($mconfName ? $mconfName : $GLOBALS['SOBE']->MCONF['name']), $this->type);
381
382 if ($this->writeDevLog) {
383 t3lib_div::devLog('Settings stored:' . $this->msg, 't3lib_modSettings', 0);
384 }
385 }
386
387 /********************************
388 *
389 * GUI
390 *
391 ********************************/
392
393 /**
394 * Returns the storage control box
395 *
396 * @param string $showElements List of elemetns which should be shown: load,remove,save
397 * @param boolean $useOwnForm If set the box is wrapped with own form tag
398 * @return string HTML code
399 */
400 function getStoreControl($showElements = 'load,remove,save', $useOwnForm = TRUE) {
401 $showElements = t3lib_div::trimExplode(',', $showElements, 1);
402
403 $this->initStorage();
404
405 // Preset selector
406 $opt = array();
407 $opt[] = '<option value="0"> </option>';
408 foreach ($this->storedSettings as $id => $v) {
409 $opt[] = '<option value="' . $id . '">' . htmlspecialchars($v['title']) . '</option>';
410 }
411 $storedEntries = count($opt) > 1;
412
413 $codeTD = array();
414
415 // LOAD, REMOVE, but also show selector so you can overwrite an entry with SAVE
416 if ($storedEntries AND (count($showElements))) {
417
418 // Selector box
419 $onChange = 'document.forms[\'' . $this->formName . '\'][\'storeControl[title]\'].value= this.options[this.selectedIndex].value!=0 ? this.options[this.selectedIndex].text : \'\';';
420 $code = '
421 <select name="storeControl[STORE]" onChange="' . htmlspecialchars($onChange) . '">
422 ' . implode('
423 ', $opt) . '
424 </select>';
425
426 // Load button
427 if (in_array('load', $showElements)) {
428 $code .= '
429 <input type="submit" name="storeControl[LOAD]" value="Load" /> ';
430 }
431
432 // Remove button
433 if (in_array('remove', $showElements)) {
434 $code .= '
435 <input type="submit" name="storeControl[REMOVE]" value="Remove" /> ';
436 }
437 $codeTD[] = '<td width="1%">Preset:</td>';
438 $codeTD[] = '<td nowrap="nowrap">' . $code . '&nbsp;&nbsp;</td>';
439 }
440
441 // SAVE
442 if (in_array('save', $showElements)) {
443 $onClick = (!$storedEntries) ? '' : 'if (document.forms[\'' . $this->formName . '\'][\'storeControl[STORE]\'].options[document.forms[\'' . $this->formName . '\'][\'storeControl[STORE]\'].selectedIndex].value<0) return confirm(\'Are you sure you want to overwrite the existing entry?\');';
444 $code = '<input name="storeControl[title]" value="" type="text" max="80" width="25"> ';
445 $code .= '<input type="submit" name="storeControl[SAVE]" value="Save" onClick="' . htmlspecialchars($onClick) . '" />';
446 $codeTD[] = '<td nowrap="nowrap">' . $code . '</td>';
447 }
448
449 $codeTD = implode('
450 ', $codeTD);
451
452 if (trim($code)) {
453 $code = '
454 <!--
455 Store control
456 -->
457 <table border="0" cellpadding="3" cellspacing="0" width="100%">
458 <tr class="bgColor4">
459 ' . $codeTD . '
460 </tr>
461 </table>
462 ';
463 }
464
465 if ($this->msg) {
466 $code .= '
467 <div><strong>' . htmlspecialchars($this->msg) . '</strong></div>';
468 }
469 // TODO need to add parameters
470 if ($useOwnForm AND trim($code)) {
471 $code = '
472 <form action="' . t3lib_div::getIndpEnv('SCRIPT_NAME') . '" method="post" name="' . $this->formName . '" enctype="' . $GLOBALS['TYPO3_CONF_VARS']['SYS']['form_enctype'] . '">' . $code . '</form>';
473 }
474
475 return $code;
476 }
477
478 /********************************
479 *
480 * Misc
481 *
482 ********************************/
483
484 /**
485 * Processing entry for the stored settings array
486 * Can be overwritten by extended class
487 *
488 * @param array $storageData Entry for the stored settings array
489 * @return array Entry for the stored settings array
490 */
491 function processEntry($storageArr) {
492 return $storageArr;
493 }
494 }
495
496 ?>