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