Admin MDL-23244 Portfolio/repo admin pages use nested forms, which are illegal HTML...
[moodle.git] / lib / adminlib.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * Functions and classes used during installation, upgrades and for admin settings.
20  *
21  *  ADMIN SETTINGS TREE INTRODUCTION
22  *
23  *  This file performs the following tasks:
24  *   -it defines the necessary objects and interfaces to build the Moodle
25  *    admin hierarchy
26  *   -it defines the admin_externalpage_setup()
27  *
28  *  ADMIN_SETTING OBJECTS
29  *
30  *  Moodle settings are represented by objects that inherit from the admin_setting
31  *  class. These objects encapsulate how to read a setting, how to write a new value
32  *  to a setting, and how to appropriately display the HTML to modify the setting.
33  *
34  *  ADMIN_SETTINGPAGE OBJECTS
35  *
36  *  The admin_setting objects are then grouped into admin_settingpages. The latter
37  *  appear in the Moodle admin tree block. All interaction with admin_settingpage
38  *  objects is handled by the admin/settings.php file.
39  *
40  *  ADMIN_EXTERNALPAGE OBJECTS
41  *
42  *  There are some settings in Moodle that are too complex to (efficiently) handle
43  *  with admin_settingpages. (Consider, for example, user management and displaying
44  *  lists of users.) In this case, we use the admin_externalpage object. This object
45  *  places a link to an external PHP file in the admin tree block.
46  *
47  *  If you're using an admin_externalpage object for some settings, you can take
48  *  advantage of the admin_externalpage_* functions. For example, suppose you wanted
49  *  to add a foo.php file into admin. First off, you add the following line to
50  *  admin/settings/first.php (at the end of the file) or to some other file in
51  *  admin/settings:
52  * <code>
53  *     $ADMIN->add('userinterface', new admin_externalpage('foo', get_string('foo'),
54  *         $CFG->wwwdir . '/' . '$CFG->admin . '/foo.php', 'some_role_permission'));
55  * </code>
56  *
57  *  Next, in foo.php, your file structure would resemble the following:
58  * <code>
59  *         require(dirname(dirname(dirname(__FILE__))).'/config.php');
60  *         require_once($CFG->libdir.'/adminlib.php');
61  *         admin_externalpage_setup('foo');
62  *         // functionality like processing form submissions goes here
63  *         echo $OUTPUT->header();
64  *         // your HTML goes here
65  *         echo $OUTPUT->footer();
66  * </code>
67  *
68  *  The admin_externalpage_setup() function call ensures the user is logged in,
69  *  and makes sure that they have the proper role permission to access the page.
70  *  It also configures all $PAGE properties needed for navigation.
71  *
72  *  ADMIN_CATEGORY OBJECTS
73  *
74  *  Above and beyond all this, we have admin_category objects. These objects
75  *  appear as folders in the admin tree block. They contain admin_settingpage's,
76  *  admin_externalpage's, and other admin_category's.
77  *
78  *  OTHER NOTES
79  *
80  *  admin_settingpage's, admin_externalpage's, and admin_category's all inherit
81  *  from part_of_admin_tree (a pseudointerface). This interface insists that
82  *  a class has a check_access method for access permissions, a locate method
83  *  used to find a specific node in the admin tree and find parent path.
84  *
85  *  admin_category's inherit from parentable_part_of_admin_tree. This pseudo-
86  *  interface ensures that the class implements a recursive add function which
87  *  accepts a part_of_admin_tree object and searches for the proper place to
88  *  put it. parentable_part_of_admin_tree implies part_of_admin_tree.
89  *
90  *  Please note that the $this->name field of any part_of_admin_tree must be
91  *  UNIQUE throughout the ENTIRE admin tree.
92  *
93  *  The $this->name field of an admin_setting object (which is *not* part_of_
94  *  admin_tree) must be unique on the respective admin_settingpage where it is
95  *  used.
96  *
97  * Original author: Vincenzo K. Marcovecchio
98  * Maintainer:      Petr Skoda
99  *
100  * @package    core
101  * @subpackage admin
102  * @copyright  1999 onwards Martin Dougiamas  http://dougiamas.com
103  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
104  */
106 defined('MOODLE_INTERNAL') || die();
108 /// Add libraries
109 require_once($CFG->libdir.'/ddllib.php');
110 require_once($CFG->libdir.'/xmlize.php');
112 define('INSECURE_DATAROOT_WARNING', 1);
113 define('INSECURE_DATAROOT_ERROR', 2);
115 /**
116  * Automatically clean-up all plugin data and remove the plugin DB tables
117  *
118  * @param string $type The plugin type, eg. 'mod', 'qtype', 'workshopgrading' etc.
119  * @param string $name The plugin name, eg. 'forum', 'multichoice', 'accumulative' etc.
120  * @uses global $OUTPUT to produce notices and other messages
121  * @return void
122  */
123 function uninstall_plugin($type, $name) {
124     global $CFG, $DB, $OUTPUT;
126     // recursively uninstall all module subplugins first
127     if ($type === 'mod') {
128         if (file_exists("$CFG->dirroot/mod/$name/db/subplugins.php")) {
129             $subplugins = array();
130             include("$CFG->dirroot/mod/$name/db/subplugins.php");
131             foreach ($subplugins as $subplugintype=>$dir) {
132                 $instances = get_plugin_list($subplugintype);
133                 foreach ($instances as $subpluginname => $notusedpluginpath) {
134                     uninstall_plugin($subplugintype, $subpluginname);
135                 }
136             }
137         }
139     }
141     $component = $type . '_' . $name;  // eg. 'qtype_multichoice' or 'workshopgrading_accumulative' or 'mod_forum'
143     if ($type === 'mod') {
144         $pluginname = $name;  // eg. 'forum'
145         if (get_string_manager()->string_exists('modulename', $component)) {
146             $strpluginname = get_string('modulename', $component);
147         } else {
148             $strpluginname = $component;
149         }
151     } else {
152         $pluginname = $component;
153         if (get_string_manager()->string_exists('pluginname', $component)) {
154             $strpluginname = get_string('pluginname', $component);
155         } else {
156             $strpluginname = $component;
157         }
158     }
160     echo $OUTPUT->heading($pluginname);
162     $plugindirectory = get_plugin_directory($type, $name);
163     $uninstalllib = $plugindirectory . '/db/uninstall.php';
164     if (file_exists($uninstalllib)) {
165         require_once($uninstalllib);
166         $uninstallfunction = 'xmldb_' . $pluginname . '_uninstall';    // eg. 'xmldb_workshop_uninstall()'
167         if (function_exists($uninstallfunction)) {
168             if (!$uninstallfunction()) {
169                 echo $OUTPUT->notification('Encountered a problem running uninstall function for '. $pluginname);
170             }
171         }
172     }
174     if ($type === 'mod') {
175     // perform cleanup tasks specific for activity modules
177         if (!$module = $DB->get_record('modules', array('name' => $name))) {
178             print_error('moduledoesnotexist', 'error');
179         }
181         // delete all the relevant instances from all course sections
182         if ($coursemods = $DB->get_records('course_modules', array('module' => $module->id))) {
183             foreach ($coursemods as $coursemod) {
184                 if (!delete_mod_from_section($coursemod->id, $coursemod->section)) {
185                     echo $OUTPUT->notification("Could not delete the $strpluginname with id = $coursemod->id from section $coursemod->section");
186                 }
187             }
188         }
190         // clear course.modinfo for courses that used this module
191         $sql = "UPDATE {course}
192                    SET modinfo=''
193                  WHERE id IN (SELECT DISTINCT course
194                                 FROM {course_modules}
195                                WHERE module=?)";
196         $DB->execute($sql, array($module->id));
198         // delete all the course module records
199         $DB->delete_records('course_modules', array('module' => $module->id));
201         // delete module contexts
202         if ($coursemods) {
203             foreach ($coursemods as $coursemod) {
204                 if (!delete_context(CONTEXT_MODULE, $coursemod->id)) {
205                     echo $OUTPUT->notification("Could not delete the context for $strpluginname with id = $coursemod->id");
206                 }
207             }
208         }
210         // delete the module entry itself
211         $DB->delete_records('modules', array('name' => $module->name));
213         // cleanup the gradebook
214         require_once($CFG->libdir.'/gradelib.php');
215         grade_uninstalled_module($module->name);
217         // Perform any custom uninstall tasks
218         if (file_exists($CFG->dirroot . '/mod/' . $module->name . '/lib.php')) {
219             require_once($CFG->dirroot . '/mod/' . $module->name . '/lib.php');
220             $uninstallfunction = $module->name . '_uninstall';
221             if (function_exists($uninstallfunction)) {
222                 debugging("{$uninstallfunction}() has been deprecated. Use the plugin's db/uninstall.php instead", DEBUG_DEVELOPER);
223                 if (!$uninstallfunction()) {
224                     echo $OUTPUT->notification('Encountered a problem running uninstall function for '. $module->name.'!');
225                 }
226             }
227         }
229     } else if ($type === 'enrol') {
230         // NOTE: this is a bit brute force way - it will not trigger events and hooks properly
231         // nuke all role assignments
232         role_unassign_all(array('component'=>$component));
233         // purge participants
234         $DB->delete_records_select('user_enrolments', "enrolid IN (SELECT id FROM {enrol} WHERE enrol = ?)", array($name));
235         // purge enrol instances
236         $DB->delete_records('enrol', array('enrol'=>$name));
237         // tweak enrol settings
238         if (!empty($CFG->enrol_plugins_enabled)) {
239             $enabledenrols = explode(',', $CFG->enrol_plugins_enabled);
240             $enabledenrols = array_unique($enabledenrols);
241             $enabledenrols = array_flip($enabledenrols);
242             unset($enabledenrols[$name]);
243             $enabledenrols = array_flip($enabledenrols);
244             if (is_array($enabledenrols)) {
245                 set_config('enrol_plugins_enabled', implode(',', $enabledenrols));
246             }
247         }
248     }
250     // perform clean-up task common for all the plugin/subplugin types
252     // delete calendar events
253     $DB->delete_records('event', array('modulename' => $pluginname));
255     // delete all the logs
256     $DB->delete_records('log', array('module' => $pluginname));
258     // delete log_display information
259     $DB->delete_records('log_display', array('component' => $component));
261     // delete the module configuration records
262     unset_all_config_for_plugin($pluginname);
264     // delete the plugin tables
265     $xmldbfilepath = $plugindirectory . '/db/install.xml';
266     drop_plugin_tables($pluginname, $xmldbfilepath, false);
268     // delete the capabilities that were defined by this module
269     capabilities_cleanup($component);
271     // remove event handlers and dequeue pending events
272     events_uninstall($component);
274     echo $OUTPUT->notification(get_string('success'), 'notifysuccess');
277 /**
278  * Returns the version of installed component
279  *
280  * @param string $component component name
281  * @param string $source either 'disk' or 'installed' - where to get the version information from
282  * @return string|bool version number or false if the component is not found
283  */
284 function get_component_version($component, $source='installed') {
285     global $CFG, $DB;
287     list($type, $name) = normalize_component($component);
289     // moodle core or a core subsystem
290     if ($type === 'core') {
291         if ($source === 'installed') {
292             if (empty($CFG->version)) {
293                 return false;
294             } else {
295                 return $CFG->version;
296             }
297         } else {
298             if (!is_readable($CFG->dirroot.'/version.php')) {
299                 return false;
300             } else {
301                 $version = null; //initialize variable for IDEs
302                 include($CFG->dirroot.'/version.php');
303                 return $version;
304             }
305         }
306     }
308     // activity module
309     if ($type === 'mod') {
310         if ($source === 'installed') {
311             return $DB->get_field('modules', 'version', array('name'=>$name));
312         } else {
313             $mods = get_plugin_list('mod');
314             if (empty($mods[$name]) or !is_readable($mods[$name].'/version.php')) {
315                 return false;
316             } else {
317                 $module = new stdclass();
318                 include($mods[$name].'/version.php');
319                 return $module->version;
320             }
321         }
322     }
324     // block
325     if ($type === 'block') {
326         if ($source === 'installed') {
327             return $DB->get_field('block', 'version', array('name'=>$name));
328         } else {
329             $blocks = get_plugin_list('block');
330             if (empty($blocks[$name]) or !is_readable($blocks[$name].'/version.php')) {
331                 return false;
332             } else {
333                 $plugin = new stdclass();
334                 include($blocks[$name].'/version.php');
335                 return $plugin->version;
336             }
337         }
338     }
340     // all other plugin types
341     if ($source === 'installed') {
342         return get_config($type.'_'.$name, 'version');
343     } else {
344         $plugins = get_plugin_list($type);
345         if (empty($plugins[$name])) {
346             return false;
347         } else {
348             $plugin = new stdclass();
349             include($plugins[$name].'/version.php');
350             return $plugin->version;
351         }
352     }
355 /**
356  * Delete all plugin tables
357  *
358  * @param string $name Name of plugin, used as table prefix
359  * @param string $file Path to install.xml file
360  * @param bool $feedback defaults to true
361  * @return bool Always returns true
362  */
363 function drop_plugin_tables($name, $file, $feedback=true) {
364     global $CFG, $DB;
366     // first try normal delete
367     if (file_exists($file) and $DB->get_manager()->delete_tables_from_xmldb_file($file)) {
368         return true;
369     }
371     // then try to find all tables that start with name and are not in any xml file
372     $used_tables = get_used_table_names();
374     $tables = $DB->get_tables();
376     /// Iterate over, fixing id fields as necessary
377     foreach ($tables as $table) {
378         if (in_array($table, $used_tables)) {
379             continue;
380         }
382         if (strpos($table, $name) !== 0) {
383             continue;
384         }
386         // found orphan table --> delete it
387         if ($DB->get_manager()->table_exists($table)) {
388             $xmldb_table = new xmldb_table($table);
389             $DB->get_manager()->drop_table($xmldb_table);
390         }
391     }
393     return true;
396 /**
397  * Returns names of all known tables == tables that moodle knows about.
398  *
399  * @return array Array of lowercase table names
400  */
401 function get_used_table_names() {
402     $table_names = array();
403     $dbdirs = get_db_directories();
405     foreach ($dbdirs as $dbdir) {
406         $file = $dbdir.'/install.xml';
408         $xmldb_file = new xmldb_file($file);
410         if (!$xmldb_file->fileExists()) {
411             continue;
412         }
414         $loaded    = $xmldb_file->loadXMLStructure();
415         $structure = $xmldb_file->getStructure();
417         if ($loaded and $tables = $structure->getTables()) {
418             foreach($tables as $table) {
419                 $table_names[] = strtolower($table->name);
420             }
421         }
422     }
424     return $table_names;
427 /**
428  * Returns list of all directories where we expect install.xml files
429  * @return array Array of paths
430  */
431 function get_db_directories() {
432     global $CFG;
434     $dbdirs = array();
436     /// First, the main one (lib/db)
437     $dbdirs[] = $CFG->libdir.'/db';
439     /// Then, all the ones defined by get_plugin_types()
440     $plugintypes = get_plugin_types();
441     foreach ($plugintypes as $plugintype => $pluginbasedir) {
442         if ($plugins = get_plugin_list($plugintype)) {
443             foreach ($plugins as $plugin => $plugindir) {
444                 $dbdirs[] = $plugindir.'/db';
445             }
446         }
447     }
449     return $dbdirs;
452 /**
453  * Try to obtain or release the cron lock.
454  * @param string  $name  name of lock
455  * @param int  $until timestamp when this lock considered stale, null means remove lock unconditionally
456  * @param bool $ignorecurrent ignore current lock state, usually extend previous lock, defaults to false
457  * @return bool true if lock obtained
458  */
459 function set_cron_lock($name, $until, $ignorecurrent=false) {
460     global $DB;
461     if (empty($name)) {
462         debugging("Tried to get a cron lock for a null fieldname");
463         return false;
464     }
466     // remove lock by force == remove from config table
467     if (is_null($until)) {
468         set_config($name, null);
469         return true;
470     }
472     if (!$ignorecurrent) {
473     // read value from db - other processes might have changed it
474         $value = $DB->get_field('config', 'value', array('name'=>$name));
476         if ($value and $value > time()) {
477         //lock active
478             return false;
479         }
480     }
482     set_config($name, $until);
483     return true;
486 /**
487  * Test if and critical warnings are present
488  * @return bool
489  */
490 function admin_critical_warnings_present() {
491     global $SESSION;
493     if (!has_capability('moodle/site:config', get_context_instance(CONTEXT_SYSTEM))) {
494         return 0;
495     }
497     if (!isset($SESSION->admin_critical_warning)) {
498         $SESSION->admin_critical_warning = 0;
499         if (is_dataroot_insecure(true) === INSECURE_DATAROOT_ERROR) {
500             $SESSION->admin_critical_warning = 1;
501         }
502     }
504     return $SESSION->admin_critical_warning;
507 /**
508  * Detects if float supports at least 10 decimal digits
509  *
510  * Detects if float supports at least 10 decimal digits
511  * and also if float-->string conversion works as expected.
512  *
513  * @return bool true if problem found
514  */
515 function is_float_problem() {
516     $num1 = 2009010200.01;
517     $num2 = 2009010200.02;
519     return ((string)$num1 === (string)$num2 or $num1 === $num2 or $num2 <= (string)$num1);
522 /**
523  * Try to verify that dataroot is not accessible from web.
524  *
525  * Try to verify that dataroot is not accessible from web.
526  * It is not 100% correct but might help to reduce number of vulnerable sites.
527  * Protection from httpd.conf and .htaccess is not detected properly.
528  *
529  * @uses INSECURE_DATAROOT_WARNING
530  * @uses INSECURE_DATAROOT_ERROR
531  * @param bool $fetchtest try to test public access by fetching file, default false
532  * @return mixed empty means secure, INSECURE_DATAROOT_ERROR found a critical problem, INSECURE_DATAROOT_WARNING might be problematic
533  */
534 function is_dataroot_insecure($fetchtest=false) {
535     global $CFG;
537     $siteroot = str_replace('\\', '/', strrev($CFG->dirroot.'/')); // win32 backslash workaround
539     $rp = preg_replace('|https?://[^/]+|i', '', $CFG->wwwroot, 1);
540     $rp = strrev(trim($rp, '/'));
541     $rp = explode('/', $rp);
542     foreach($rp as $r) {
543         if (strpos($siteroot, '/'.$r.'/') === 0) {
544             $siteroot = substr($siteroot, strlen($r)+1); // moodle web in subdirectory
545         } else {
546             break; // probably alias root
547         }
548     }
550     $siteroot = strrev($siteroot);
551     $dataroot = str_replace('\\', '/', $CFG->dataroot.'/');
553     if (strpos($dataroot, $siteroot) !== 0) {
554         return false;
555     }
557     if (!$fetchtest) {
558         return INSECURE_DATAROOT_WARNING;
559     }
561     // now try all methods to fetch a test file using http protocol
563     $httpdocroot = str_replace('\\', '/', strrev($CFG->dirroot.'/'));
564     preg_match('|(https?://[^/]+)|i', $CFG->wwwroot, $matches);
565     $httpdocroot = $matches[1];
566     $datarooturl = $httpdocroot.'/'. substr($dataroot, strlen($siteroot));
567     make_upload_directory('diag');
568     $testfile = $CFG->dataroot.'/diag/public.txt';
569     if (!file_exists($testfile)) {
570         file_put_contents($testfile, 'test file, do not delete');
571     }
572     $teststr = trim(file_get_contents($testfile));
573     if (empty($teststr)) {
574     // hmm, strange
575         return INSECURE_DATAROOT_WARNING;
576     }
578     $testurl = $datarooturl.'/diag/public.txt';
579     if (extension_loaded('curl') and
580         !(stripos(ini_get('disable_functions'), 'curl_init') !== FALSE) and
581         !(stripos(ini_get('disable_functions'), 'curl_setop') !== FALSE) and
582         ($ch = @curl_init($testurl)) !== false) {
583         curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
584         curl_setopt($ch, CURLOPT_HEADER, false);
585         $data = curl_exec($ch);
586         if (!curl_errno($ch)) {
587             $data = trim($data);
588             if ($data === $teststr) {
589                 curl_close($ch);
590                 return INSECURE_DATAROOT_ERROR;
591             }
592         }
593         curl_close($ch);
594     }
596     if ($data = @file_get_contents($testurl)) {
597         $data = trim($data);
598         if ($data === $teststr) {
599             return INSECURE_DATAROOT_ERROR;
600         }
601     }
603     preg_match('|https?://([^/]+)|i', $testurl, $matches);
604     $sitename = $matches[1];
605     $error = 0;
606     if ($fp = @fsockopen($sitename, 80, $error)) {
607         preg_match('|https?://[^/]+(.*)|i', $testurl, $matches);
608         $localurl = $matches[1];
609         $out = "GET $localurl HTTP/1.1\r\n";
610         $out .= "Host: $sitename\r\n";
611         $out .= "Connection: Close\r\n\r\n";
612         fwrite($fp, $out);
613         $data = '';
614         $incoming = false;
615         while (!feof($fp)) {
616             if ($incoming) {
617                 $data .= fgets($fp, 1024);
618             } else if (@fgets($fp, 1024) === "\r\n") {
619                     $incoming = true;
620                 }
621         }
622         fclose($fp);
623         $data = trim($data);
624         if ($data === $teststr) {
625             return INSECURE_DATAROOT_ERROR;
626         }
627     }
629     return INSECURE_DATAROOT_WARNING;
632 /// CLASS DEFINITIONS /////////////////////////////////////////////////////////
634 /**
635  * Interface for anything appearing in the admin tree
636  *
637  * The interface that is implemented by anything that appears in the admin tree
638  * block. It forces inheriting classes to define a method for checking user permissions
639  * and methods for finding something in the admin tree.
640  *
641  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
642  */
643 interface part_of_admin_tree {
645 /**
646  * Finds a named part_of_admin_tree.
647  *
648  * Used to find a part_of_admin_tree. If a class only inherits part_of_admin_tree
649  * and not parentable_part_of_admin_tree, then this function should only check if
650  * $this->name matches $name. If it does, it should return a reference to $this,
651  * otherwise, it should return a reference to NULL.
652  *
653  * If a class inherits parentable_part_of_admin_tree, this method should be called
654  * recursively on all child objects (assuming, of course, the parent object's name
655  * doesn't match the search criterion).
656  *
657  * @param string $name The internal name of the part_of_admin_tree we're searching for.
658  * @return mixed An object reference or a NULL reference.
659  */
660     public function locate($name);
662     /**
663      * Removes named part_of_admin_tree.
664      *
665      * @param string $name The internal name of the part_of_admin_tree we want to remove.
666      * @return bool success.
667      */
668     public function prune($name);
670     /**
671      * Search using query
672      * @param string $query
673      * @return mixed array-object structure of found settings and pages
674      */
675     public function search($query);
677     /**
678      * Verifies current user's access to this part_of_admin_tree.
679      *
680      * Used to check if the current user has access to this part of the admin tree or
681      * not. If a class only inherits part_of_admin_tree and not parentable_part_of_admin_tree,
682      * then this method is usually just a call to has_capability() in the site context.
683      *
684      * If a class inherits parentable_part_of_admin_tree, this method should return the
685      * logical OR of the return of check_access() on all child objects.
686      *
687      * @return bool True if the user has access, false if she doesn't.
688      */
689     public function check_access();
691     /**
692      * Mostly useful for removing of some parts of the tree in admin tree block.
693      *
694      * @return True is hidden from normal list view
695      */
696     public function is_hidden();
698     /**
699      * Show we display Save button at the page bottom?
700      * @return bool
701      */
702     public function show_save();
705 /**
706  * Interface implemented by any part_of_admin_tree that has children.
707  *
708  * The interface implemented by any part_of_admin_tree that can be a parent
709  * to other part_of_admin_tree's. (For now, this only includes admin_category.) Apart
710  * from ensuring part_of_admin_tree compliancy, it also ensures inheriting methods
711  * include an add method for adding other part_of_admin_tree objects as children.
712  *
713  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
714  */
715 interface parentable_part_of_admin_tree extends part_of_admin_tree {
717 /**
718  * Adds a part_of_admin_tree object to the admin tree.
719  *
720  * Used to add a part_of_admin_tree object to this object or a child of this
721  * object. $something should only be added if $destinationname matches
722  * $this->name. If it doesn't, add should be called on child objects that are
723  * also parentable_part_of_admin_tree's.
724  *
725  * @param string $destinationname The internal name of the new parent for $something.
726  * @param part_of_admin_tree $something The object to be added.
727  * @return bool True on success, false on failure.
728  */
729     public function add($destinationname, $something);
733 /**
734  * The object used to represent folders (a.k.a. categories) in the admin tree block.
735  *
736  * Each admin_category object contains a number of part_of_admin_tree objects.
737  *
738  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
739  */
740 class admin_category implements parentable_part_of_admin_tree {
742 /** @var mixed An array of part_of_admin_tree objects that are this object's children */
743     public $children;
744     /** @var string An internal name for this category. Must be unique amongst ALL part_of_admin_tree objects */
745     public $name;
746     /** @var string The displayed name for this category. Usually obtained through get_string() */
747     public $visiblename;
748     /** @var bool Should this category be hidden in admin tree block? */
749     public $hidden;
750     /** @var mixed Either a string or an array or strings */
751     public $path;
752     /** @var mixed Either a string or an array or strings */
753     public $visiblepath;
755     /**
756      * Constructor for an empty admin category
757      *
758      * @param string $name The internal name for this category. Must be unique amongst ALL part_of_admin_tree objects
759      * @param string $visiblename The displayed named for this category. Usually obtained through get_string()
760      * @param bool $hidden hide category in admin tree block, defaults to false
761      */
762     public function __construct($name, $visiblename, $hidden=false) {
763         $this->children    = array();
764         $this->name        = $name;
765         $this->visiblename = $visiblename;
766         $this->hidden      = $hidden;
767     }
769     /**
770      * Returns a reference to the part_of_admin_tree object with internal name $name.
771      *
772      * @param string $name The internal name of the object we want.
773      * @param bool $findpath initialize path and visiblepath arrays
774      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
775      *                  defaults to false
776      */
777     public function locate($name, $findpath=false) {
778         if ($this->name == $name) {
779             if ($findpath) {
780                 $this->visiblepath[] = $this->visiblename;
781                 $this->path[]        = $this->name;
782             }
783             return $this;
784         }
786         $return = NULL;
787         foreach($this->children as $childid=>$unused) {
788             if ($return = $this->children[$childid]->locate($name, $findpath)) {
789                 break;
790             }
791         }
793         if (!is_null($return) and $findpath) {
794             $return->visiblepath[] = $this->visiblename;
795             $return->path[]        = $this->name;
796         }
798         return $return;
799     }
801     /**
802      * Search using query
803      *
804      * @param string query
805      * @return mixed array-object structure of found settings and pages
806      */
807     public function search($query) {
808         $result = array();
809         foreach ($this->children as $child) {
810             $subsearch = $child->search($query);
811             if (!is_array($subsearch)) {
812                 debugging('Incorrect search result from '.$child->name);
813                 continue;
814             }
815             $result = array_merge($result, $subsearch);
816         }
817         return $result;
818     }
820     /**
821      * Removes part_of_admin_tree object with internal name $name.
822      *
823      * @param string $name The internal name of the object we want to remove.
824      * @return bool success
825      */
826     public function prune($name) {
828         if ($this->name == $name) {
829             return false;  //can not remove itself
830         }
832         foreach($this->children as $precedence => $child) {
833             if ($child->name == $name) {
834             // found it!
835                 unset($this->children[$precedence]);
836                 return true;
837             }
838             if ($this->children[$precedence]->prune($name)) {
839                 return true;
840             }
841         }
842         return false;
843     }
845     /**
846      * Adds a part_of_admin_tree to a child or grandchild (or great-grandchild, and so forth) of this object.
847      *
848      * @param string $destinationame The internal name of the immediate parent that we want for $something.
849      * @param mixed $something A part_of_admin_tree or setting instance to be added.
850      * @return bool True if successfully added, false if $something can not be added.
851      */
852     public function add($parentname, $something) {
853         $parent = $this->locate($parentname);
854         if (is_null($parent)) {
855             debugging('parent does not exist!');
856             return false;
857         }
859         if ($something instanceof part_of_admin_tree) {
860             if (!($parent instanceof parentable_part_of_admin_tree)) {
861                 debugging('error - parts of tree can be inserted only into parentable parts');
862                 return false;
863             }
864             $parent->children[] = $something;
865             return true;
867         } else {
868             debugging('error - can not add this element');
869             return false;
870         }
872     }
874     /**
875      * Checks if the user has access to anything in this category.
876      *
877      * @return bool True if the user has access to at least one child in this category, false otherwise.
878      */
879     public function check_access() {
880         foreach ($this->children as $child) {
881             if ($child->check_access()) {
882                 return true;
883             }
884         }
885         return false;
886     }
888     /**
889      * Is this category hidden in admin tree block?
890      *
891      * @return bool True if hidden
892      */
893     public function is_hidden() {
894         return $this->hidden;
895     }
897     /**
898      * Show we display Save button at the page bottom?
899      * @return bool
900      */
901     public function show_save() {
902         foreach ($this->children as $child) {
903             if ($child->show_save()) {
904                 return true;
905             }
906         }
907         return false;
908     }
911 /**
912  * Root of admin settings tree, does not have any parent.
913  *
914  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
915  */
916 class admin_root extends admin_category {
917 /** @var array List of errors */
918     public $errors;
919     /** @var string search query */
920     public $search;
921     /** @var bool full tree flag - true means all settings required, false only pages required */
922     public $fulltree;
923     /** @var bool flag indicating loaded tree */
924     public $loaded;
925     /** @var mixed site custom defaults overriding defaults in settings files*/
926     public $custom_defaults;
928     /**
929      * @param bool $fulltree true means all settings required,
930      *                            false only pages required
931      */
932     public function __construct($fulltree) {
933         global $CFG;
935         parent::__construct('root', get_string('administration'), false);
936         $this->errors   = array();
937         $this->search   = '';
938         $this->fulltree = $fulltree;
939         $this->loaded   = false;
941         // load custom defaults if found
942         $this->custom_defaults = null;
943         $defaultsfile = "$CFG->dirroot/local/defaults.php";
944         if (is_readable($defaultsfile)) {
945             $defaults = array();
946             include($defaultsfile);
947             if (is_array($defaults) and count($defaults)) {
948                 $this->custom_defaults = $defaults;
949             }
950         }
951     }
953     /**
954      * Empties children array, and sets loaded to false
955      *
956      * @param bool $requirefulltree
957      */
958     public function purge_children($requirefulltree) {
959         $this->children = array();
960         $this->fulltree = ($requirefulltree || $this->fulltree);
961         $this->loaded   = false;
962     }
965 /**
966  * Links external PHP pages into the admin tree.
967  *
968  * See detailed usage example at the top of this document (adminlib.php)
969  *
970  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
971  */
972 class admin_externalpage implements part_of_admin_tree {
974 /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
975     public $name;
977     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
978     public $visiblename;
980     /** @var string The external URL that we should link to when someone requests this external page. */
981     public $url;
983     /** @var string The role capability/permission a user must have to access this external page. */
984     public $req_capability;
986     /** @var object The context in which capability/permission should be checked, default is site context. */
987     public $context;
989     /** @var bool hidden in admin tree block. */
990     public $hidden;
992     /** @var mixed either string or array of string */
993     public $path;
994     public $visiblepath;
996     /**
997      * Constructor for adding an external page into the admin tree.
998      *
999      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1000      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1001      * @param string $url The external URL that we should link to when someone requests this external page.
1002      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1003      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1004      * @param stdClass $context The context the page relates to. Not sure what happens
1005      *      if you specify something other than system or front page. Defaults to system.
1006      */
1007     public function __construct($name, $visiblename, $url, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1008         $this->name        = $name;
1009         $this->visiblename = $visiblename;
1010         $this->url         = $url;
1011         if (is_array($req_capability)) {
1012             $this->req_capability = $req_capability;
1013         } else {
1014             $this->req_capability = array($req_capability);
1015         }
1016         $this->hidden = $hidden;
1017         $this->context = $context;
1018     }
1020     /**
1021      * Returns a reference to the part_of_admin_tree object with internal name $name.
1022      *
1023      * @param string $name The internal name of the object we want.
1024      * @param bool $findpath defaults to false
1025      * @return mixed A reference to the object with internal name $name if found, otherwise a reference to NULL.
1026      */
1027     public function locate($name, $findpath=false) {
1028         if ($this->name == $name) {
1029             if ($findpath) {
1030                 $this->visiblepath = array($this->visiblename);
1031                 $this->path        = array($this->name);
1032             }
1033             return $this;
1034         } else {
1035             $return = NULL;
1036             return $return;
1037         }
1038     }
1040     /**
1041      * This function always returns false, required function by interface
1042      *
1043      * @param string $name
1044      * @return false
1045      */
1046     public function prune($name) {
1047         return false;
1048     }
1050     /**
1051      * Search using query
1052      *
1053      * @param string $query
1054      * @return mixed array-object structure of found settings and pages
1055      */
1056     public function search($query) {
1057         $textlib = textlib_get_instance();
1059         $found = false;
1060         if (strpos(strtolower($this->name), $query) !== false) {
1061             $found = true;
1062         } else if (strpos($textlib->strtolower($this->visiblename), $query) !== false) {
1063                 $found = true;
1064             }
1065         if ($found) {
1066             $result = new stdClass();
1067             $result->page     = $this;
1068             $result->settings = array();
1069             return array($this->name => $result);
1070         } else {
1071             return array();
1072         }
1073     }
1075     /**
1076      * Determines if the current user has access to this external page based on $this->req_capability.
1077      *
1078      * @return bool True if user has access, false otherwise.
1079      */
1080     public function check_access() {
1081         global $CFG;
1082         $context = empty($this->context) ? get_context_instance(CONTEXT_SYSTEM) : $this->context;
1083         foreach($this->req_capability as $cap) {
1084             if (has_capability($cap, $context)) {
1085                 return true;
1086             }
1087         }
1088         return false;
1089     }
1091     /**
1092      * Is this external page hidden in admin tree block?
1093      *
1094      * @return bool True if hidden
1095      */
1096     public function is_hidden() {
1097         return $this->hidden;
1098     }
1100     /**
1101      * Show we display Save button at the page bottom?
1102      * @return bool
1103      */
1104     public function show_save() {
1105         return false;
1106     }
1109 /**
1110  * Used to group a number of admin_setting objects into a page and add them to the admin tree.
1111  *
1112  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1113  */
1114 class admin_settingpage implements part_of_admin_tree {
1116 /** @var string An internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects */
1117     public $name;
1119     /** @var string The displayed name for this external page. Usually obtained through get_string(). */
1120     public $visiblename;
1122     /** @var mixed An array of admin_setting objects that are part of this setting page. */
1123     public $settings;
1125     /** @var string The role capability/permission a user must have to access this external page. */
1126     public $req_capability;
1128     /** @var object The context in which capability/permission should be checked, default is site context. */
1129     public $context;
1131     /** @var bool hidden in admin tree block. */
1132     public $hidden;
1134     /** @var mixed string of paths or array of strings of paths */
1135     public $path;
1136     public $visiblepath;
1138     /**
1139      * see admin_settingpage for details of this function
1140      *
1141      * @param string $name The internal name for this external page. Must be unique amongst ALL part_of_admin_tree objects.
1142      * @param string $visiblename The displayed name for this external page. Usually obtained through get_string().
1143      * @param mixed $req_capability The role capability/permission a user must have to access this external page. Defaults to 'moodle/site:config'.
1144      * @param boolean $hidden Is this external page hidden in admin tree block? Default false.
1145      * @param stdClass $context The context the page relates to. Not sure what happens
1146      *      if you specify something other than system or front page. Defaults to system.
1147      */
1148     public function __construct($name, $visiblename, $req_capability='moodle/site:config', $hidden=false, $context=NULL) {
1149         $this->settings    = new stdClass();
1150         $this->name        = $name;
1151         $this->visiblename = $visiblename;
1152         if (is_array($req_capability)) {
1153             $this->req_capability = $req_capability;
1154         } else {
1155             $this->req_capability = array($req_capability);
1156         }
1157         $this->hidden      = $hidden;
1158         $this->context     = $context;
1159     }
1161     /**
1162      * see admin_category
1163      *
1164      * @param string $name
1165      * @param bool $findpath
1166      * @return mixed Object (this) if name ==  this->name, else returns null
1167      */
1168     public function locate($name, $findpath=false) {
1169         if ($this->name == $name) {
1170             if ($findpath) {
1171                 $this->visiblepath = array($this->visiblename);
1172                 $this->path        = array($this->name);
1173             }
1174             return $this;
1175         } else {
1176             $return = NULL;
1177             return $return;
1178         }
1179     }
1181     /**
1182      * Search string in settings page.
1183      *
1184      * @param string $query
1185      * @return array
1186      */
1187     public function search($query) {
1188         $found = array();
1190         foreach ($this->settings as $setting) {
1191             if ($setting->is_related($query)) {
1192                 $found[] = $setting;
1193             }
1194         }
1196         if ($found) {
1197             $result = new stdClass();
1198             $result->page     = $this;
1199             $result->settings = $found;
1200             return array($this->name => $result);
1201         }
1203         $textlib = textlib_get_instance();
1205         $found = false;
1206         if (strpos(strtolower($this->name), $query) !== false) {
1207             $found = true;
1208         } else if (strpos($textlib->strtolower($this->visiblename), $query) !== false) {
1209                 $found = true;
1210             }
1211         if ($found) {
1212             $result = new stdClass();
1213             $result->page     = $this;
1214             $result->settings = array();
1215             return array($this->name => $result);
1216         } else {
1217             return array();
1218         }
1219     }
1221     /**
1222      * This function always returns false, required by interface
1223      *
1224      * @param string $name
1225      * @return bool Always false
1226      */
1227     public function prune($name) {
1228         return false;
1229     }
1231     /**
1232      * adds an admin_setting to this admin_settingpage
1233      *
1234      * not the same as add for admin_category. adds an admin_setting to this admin_settingpage. settings appear (on the settingpage) in the order in which they're added
1235      * n.b. each admin_setting in an admin_settingpage must have a unique internal name
1236      *
1237      * @param object $setting is the admin_setting object you want to add
1238      * @return bool true if successful, false if not
1239      */
1240     public function add($setting) {
1241         if (!($setting instanceof admin_setting)) {
1242             debugging('error - not a setting instance');
1243             return false;
1244         }
1246         $this->settings->{$setting->name} = $setting;
1247         return true;
1248     }
1250     /**
1251      * see admin_externalpage
1252      *
1253      * @return bool Returns true for yes false for no
1254      */
1255     public function check_access() {
1256         global $CFG;
1257         $context = empty($this->context) ? get_context_instance(CONTEXT_SYSTEM) : $this->context;
1258         foreach($this->req_capability as $cap) {
1259             if (has_capability($cap, $context)) {
1260                 return true;
1261             }
1262         }
1263         return false;
1264     }
1266     /**
1267      * outputs this page as html in a table (suitable for inclusion in an admin pagetype)
1268      * @return string Returns an XHTML string
1269      */
1270     public function output_html() {
1271         $adminroot = admin_get_root();
1272         $return = '<fieldset>'."\n".'<div class="clearer"><!-- --></div>'."\n";
1273         foreach($this->settings as $setting) {
1274             $fullname = $setting->get_full_name();
1275             if (array_key_exists($fullname, $adminroot->errors)) {
1276                 $data = $adminroot->errors[$fullname]->data;
1277             } else {
1278                 $data = $setting->get_setting();
1279                 // do not use defaults if settings not available - upgrade settings handles the defaults!
1280             }
1281             $return .= $setting->output_html($data);
1282         }
1283         $return .= '</fieldset>';
1284         return $return;
1285     }
1287     /**
1288      * Is this settings page hidden in admin tree block?
1289      *
1290      * @return bool True if hidden
1291      */
1292     public function is_hidden() {
1293         return $this->hidden;
1294     }
1296     /**
1297      * Show we display Save button at the page bottom?
1298      * @return bool
1299      */
1300     public function show_save() {
1301         foreach($this->settings as $setting) {
1302             if (empty($setting->nosave)) {
1303                 return true;
1304             }
1305         }
1306         return false;
1307     }
1311 /**
1312  * Admin settings class. Only exists on setting pages.
1313  * Read & write happens at this level; no authentication.
1314  *
1315  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1316  */
1317 abstract class admin_setting {
1318 /** @var string unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins. */
1319     public $name;
1320     /** @var string localised name */
1321     public $visiblename;
1322     /** @var string localised long description in Markdown format */
1323     public $description;
1324     /** @var mixed Can be string or array of string */
1325     public $defaultsetting;
1326     /** @var string */
1327     public $updatedcallback;
1328     /** @var mixed can be String or Null.  Null means main config table */
1329     public $plugin; // null means main config table
1330     /** @var bool true indicates this setting does not actually save anything, just information */
1331     public $nosave = false;
1333     /**
1334      * Constructor
1335      * @param string $name unique ascii name, either 'mysetting' for settings that in config,
1336      *                     or 'myplugin/mysetting' for ones in config_plugins.
1337      * @param string $visiblename localised name
1338      * @param string $description localised long description
1339      * @param mixed $defaultsetting string or array depending on implementation
1340      */
1341     public function __construct($name, $visiblename, $description, $defaultsetting) {
1342         $this->parse_setting_name($name);
1343         $this->visiblename    = $visiblename;
1344         $this->description    = $description;
1345         $this->defaultsetting = $defaultsetting;
1346     }
1348     /**
1349      * Set up $this->name and potentially $this->plugin
1350      *
1351      * Set up $this->name and possibly $this->plugin based on whether $name looks
1352      * like 'settingname' or 'plugin/settingname'. Also, do some sanity checking
1353      * on the names, that is, output a developer debug warning if the name
1354      * contains anything other than [a-zA-Z0-9_]+.
1355      *
1356      * @param string $name the setting name passed in to the constructor.
1357      */
1358     private function parse_setting_name($name) {
1359         $bits = explode('/', $name);
1360         if (count($bits) > 2) {
1361             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1362         }
1363         $this->name = array_pop($bits);
1364         if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->name)) {
1365             throw new moodle_exception('invalidadminsettingname', '', '', $name);
1366         }
1367         if (!empty($bits)) {
1368             $this->plugin = array_pop($bits);
1369             if ($this->plugin === 'moodle') {
1370                 $this->plugin = null;
1371             } else if (!preg_match('/^[a-zA-Z0-9_]+$/', $this->plugin)) {
1372                     throw new moodle_exception('invalidadminsettingname', '', '', $name);
1373                 }
1374         }
1375     }
1377     /**
1378      * Returns the fullname prefixed by the plugin
1379      * @return string
1380      */
1381     public function get_full_name() {
1382         return 's_'.$this->plugin.'_'.$this->name;
1383     }
1385     /**
1386      * Returns the ID string based on plugin and name
1387      * @return string
1388      */
1389     public function get_id() {
1390         return 'id_s_'.$this->plugin.'_'.$this->name;
1391     }
1393     /**
1394      * Returns the config if possible
1395      *
1396      * @return mixed returns config if successfull else null
1397      */
1398     public function config_read($name) {
1399         global $CFG;
1400         if (!empty($this->plugin)) {
1401             $value = get_config($this->plugin, $name);
1402             return $value === false ? NULL : $value;
1404         } else {
1405             if (isset($CFG->$name)) {
1406                 return $CFG->$name;
1407             } else {
1408                 return NULL;
1409             }
1410         }
1411     }
1413     /**
1414      * Used to set a config pair and log change
1415      *
1416      * @param string $name
1417      * @param mixed $value Gets converted to string if not null
1418      * @return bool Write setting to config table
1419      */
1420     public function config_write($name, $value) {
1421         global $DB, $USER, $CFG;
1423         if ($this->nosave) {
1424             return true;
1425         }
1427         // make sure it is a real change
1428         $oldvalue = get_config($this->plugin, $name);
1429         $oldvalue = ($oldvalue === false) ? null : $oldvalue; // normalise
1430         $value = is_null($value) ? null : (string)$value;
1432         if ($oldvalue === $value) {
1433             return true;
1434         }
1436         // store change
1437         set_config($name, $value, $this->plugin);
1439         // log change
1440         $log = new stdClass();
1441         $log->userid       = during_initial_install() ? 0 :$USER->id; // 0 as user id during install
1442         $log->timemodified = time();
1443         $log->plugin       = $this->plugin;
1444         $log->name         = $name;
1445         $log->value        = $value;
1446         $log->oldvalue     = $oldvalue;
1447         $DB->insert_record('config_log', $log);
1449         return true; // BC only
1450     }
1452     /**
1453      * Returns current value of this setting
1454      * @return mixed array or string depending on instance, NULL means not set yet
1455      */
1456     public abstract function get_setting();
1458     /**
1459      * Returns default setting if exists
1460      * @return mixed array or string depending on instance; NULL means no default, user must supply
1461      */
1462     public function get_defaultsetting() {
1463         $adminroot =  admin_get_root(false, false);
1464         if (!empty($adminroot->custom_defaults)) {
1465             $plugin = is_null($this->plugin) ? 'moodle' : $this->plugin;
1466             if (isset($adminroot->custom_defaults[$plugin])) {
1467                 if (array_key_exists($this->name, $adminroot->custom_defaults[$plugin])) { // null is valid value here ;-)
1468                     return $adminroot->custom_defaults[$plugin][$this->name];
1469                 }
1470             }
1471         }
1472         return $this->defaultsetting;
1473     }
1475     /**
1476      * Store new setting
1477      *
1478      * @param mixed $data string or array, must not be NULL
1479      * @return string empty string if ok, string error message otherwise
1480      */
1481     public abstract function write_setting($data);
1483     /**
1484      * Return part of form with setting
1485      * This function should always be overwritten
1486      *
1487      * @param mixed $data array or string depending on setting
1488      * @param string $query
1489      * @return string
1490      */
1491     public function output_html($data, $query='') {
1492     // should be overridden
1493         return;
1494     }
1496     /**
1497      * Function called if setting updated - cleanup, cache reset, etc.
1498      * @param string $functionname Sets the function name
1499      */
1500     public function set_updatedcallback($functionname) {
1501         $this->updatedcallback = $functionname;
1502     }
1504     /**
1505      * Is setting related to query text - used when searching
1506      * @param string $query
1507      * @return bool
1508      */
1509     public function is_related($query) {
1510         if (strpos(strtolower($this->name), $query) !== false) {
1511             return true;
1512         }
1513         $textlib = textlib_get_instance();
1514         if (strpos($textlib->strtolower($this->visiblename), $query) !== false) {
1515             return true;
1516         }
1517         if (strpos($textlib->strtolower($this->description), $query) !== false) {
1518             return true;
1519         }
1520         $current = $this->get_setting();
1521         if (!is_null($current)) {
1522             if (is_string($current)) {
1523                 if (strpos($textlib->strtolower($current), $query) !== false) {
1524                     return true;
1525                 }
1526             }
1527         }
1528         $default = $this->get_defaultsetting();
1529         if (!is_null($default)) {
1530             if (is_string($default)) {
1531                 if (strpos($textlib->strtolower($default), $query) !== false) {
1532                     return true;
1533                 }
1534             }
1535         }
1536         return false;
1537     }
1540 /**
1541  * No setting - just heading and text.
1542  *
1543  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1544  */
1545 class admin_setting_heading extends admin_setting {
1546 /**
1547  * not a setting, just text
1548  * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1549  * @param string $heading heading
1550  * @param string $information text in box
1551  */
1552     public function __construct($name, $heading, $information) {
1553         $this->nosave = true;
1554         parent::__construct($name, $heading, $information, '');
1555     }
1557     /**
1558      * Always returns true
1559      * @return bool Always returns true
1560      */
1561     public function get_setting() {
1562         return true;
1563     }
1565     /**
1566      * Always returns true
1567      * @return bool Always returns true
1568      */
1569     public function get_defaultsetting() {
1570         return true;
1571     }
1573     /**
1574      * Never write settings
1575      * @return string Always returns an empty string
1576      */
1577     public function write_setting($data) {
1578     // do not write any setting
1579         return '';
1580     }
1582     /**
1583      * Returns an HTML string
1584      * @return string Returns an HTML string
1585      */
1586     public function output_html($data, $query='') {
1587         global $OUTPUT;
1588         $return = '';
1589         if ($this->visiblename != '') {
1590             $return .= $OUTPUT->heading($this->visiblename, 3, 'main');
1591         }
1592         if ($this->description != '') {
1593             $return .= $OUTPUT->box(highlight($query, markdown_to_html($this->description)), 'generalbox formsettingheading');
1594         }
1595         return $return;
1596     }
1599 /**
1600  * The most flexibly setting, user is typing text
1601  *
1602  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1603  */
1604 class admin_setting_configtext extends admin_setting {
1606 /** @var mixed int means PARAM_XXX type, string is a allowed format in regex */
1607     public $paramtype;
1608     /** @var int default field size */
1609     public $size;
1611     /**
1612      * Config text constructor
1613      *
1614      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1615      * @param string $visiblename localised
1616      * @param string $description long localised info
1617      * @param string $defaultsetting
1618      * @param mixed $paramtype int means PARAM_XXX type, string is a allowed format in regex
1619      * @param int $size default field size
1620      */
1621     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $size=null) {
1622         $this->paramtype = $paramtype;
1623         if (!is_null($size)) {
1624             $this->size  = $size;
1625         } else {
1626             $this->size  = ($paramtype === PARAM_INT) ? 5 : 30;
1627         }
1628         parent::__construct($name, $visiblename, $description, $defaultsetting);
1629     }
1631     /**
1632      * Return the setting
1633      *
1634      * @return mixed returns config if successful else null
1635      */
1636     public function get_setting() {
1637         return $this->config_read($this->name);
1638     }
1640     public function write_setting($data) {
1641         if ($this->paramtype === PARAM_INT and $data === '') {
1642         // do not complain if '' used instead of 0
1643             $data = 0;
1644         }
1645         // $data is a string
1646         $validated = $this->validate($data);
1647         if ($validated !== true) {
1648             return $validated;
1649         }
1650         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
1651     }
1653     /**
1654      * Validate data before storage
1655      * @param string data
1656      * @return mixed true if ok string if error found
1657      */
1658     public function validate($data) {
1659         // allow paramtype to be a custom regex if it is the form of /pattern/
1660         if (preg_match('#^/.*/$#', $this->paramtype)) {
1661             if (preg_match($this->paramtype, $data)) {
1662                 return true;
1663             } else {
1664                 return get_string('validateerror', 'admin');
1665             }
1667         } else if ($this->paramtype === PARAM_RAW) {
1668             return true;
1670         } else {
1671             $cleaned = clean_param($data, $this->paramtype);
1672             if ("$data" === "$cleaned") { // implicit conversion to string is needed to do exact comparison
1673                 return true;
1674             } else {
1675                 return get_string('validateerror', 'admin');
1676             }
1677         }
1678     }
1680     /**
1681      * Return an XHTML string for the setting
1682      * @return string Returns an XHTML string
1683      */
1684     public function output_html($data, $query='') {
1685         $default = $this->get_defaultsetting();
1687         return format_admin_setting($this, $this->visiblename,
1688         '<div class="form-text defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" /></div>',
1689         $this->description, true, '', $default, $query);
1690     }
1693 /**
1694  * General text area without html editor.
1695  *
1696  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1697  */
1698 class admin_setting_configtextarea extends admin_setting_configtext {
1699     private $rows;
1700     private $cols;
1702     /**
1703      * @param string $name
1704      * @param string $visiblename
1705      * @param string $description
1706      * @param mixed $defaultsetting string or array
1707      * @param mixed $paramtype
1708      * @param string $cols The number of columns to make the editor
1709      * @param string $rows The number of rows to make the editor
1710      */
1711     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
1712         $this->rows = $rows;
1713         $this->cols = $cols;
1714         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
1715     }
1716     /**
1717      * Returns an XHTML string for the editor
1718      *
1719      * @param string $data
1720      * @param string $query
1721      * @return string XHTML string for the editor
1722      */
1723     public function output_html($data, $query='') {
1724         $default = $this->get_defaultsetting();
1726         $defaultinfo = $default;
1727         if (!is_null($default) and $default !== '') {
1728             $defaultinfo = "\n".$default;
1729         }
1731         return format_admin_setting($this, $this->visiblename,
1732         '<div class="form-textarea" ><textarea rows="'. $this->rows .'" cols="'. $this->cols .'" id="'. $this->get_id() .'" name="'. $this->get_full_name() .'">'. s($data) .'</textarea></div>',
1733         $this->description, true, '', $defaultinfo, $query);
1734     }
1737 /**
1738  * General text area with html editor.
1739  */
1740 class admin_setting_confightmleditor extends admin_setting_configtext {
1741     private $rows;
1742     private $cols;
1744     /**
1745      * @param string $name
1746      * @param string $visiblename
1747      * @param string $description
1748      * @param mixed $defaultsetting string or array
1749      * @param mixed $paramtype
1750      */
1751     public function __construct($name, $visiblename, $description, $defaultsetting, $paramtype=PARAM_RAW, $cols='60', $rows='8') {
1752         $this->rows = $rows;
1753         $this->cols = $cols;
1754         parent::__construct($name, $visiblename, $description, $defaultsetting, $paramtype);
1755         editors_head_setup();
1756     }
1757     /**
1758      * Returns an XHTML string for the editor
1759      *
1760      * @param string $data
1761      * @param string $query
1762      * @return string XHTML string for the editor
1763      */
1764     public function output_html($data, $query='') {
1765         $default = $this->get_defaultsetting();
1767         $defaultinfo = $default;
1768         if (!is_null($default) and $default !== '') {
1769             $defaultinfo = "\n".$default;
1770         }
1772         $editor = editors_get_preferred_editor(FORMAT_HTML);
1773         $editor->use_editor($this->get_id(), array('noclean'=>true));
1775         return format_admin_setting($this, $this->visiblename,
1776         '<div class="form-textarea"><textarea rows="'. $this->rows .'" cols="'. $this->cols .'" id="'. $this->get_id() .'" name="'. $this->get_full_name() .'">'. s($data) .'</textarea></div>',
1777         $this->description, true, '', $defaultinfo, $query);
1778     }
1781 /**
1782  * Password field, allows unmasking of password
1783  *
1784  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1785  */
1786 class admin_setting_configpasswordunmask extends admin_setting_configtext {
1787 /**
1788  * Constructor
1789  * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1790  * @param string $visiblename localised
1791  * @param string $description long localised info
1792  * @param string $defaultsetting default password
1793  */
1794     public function __construct($name, $visiblename, $description, $defaultsetting) {
1795         parent::__construct($name, $visiblename, $description, $defaultsetting, PARAM_RAW, 30);
1796     }
1798     /**
1799      * Returns XHTML for the field
1800      * Writes Javascript into the HTML below right before the last div
1801      *
1802      * @todo Make javascript available through newer methods if possible
1803      * @param string $data Value for the field
1804      * @param string $query Passed as final argument for format_admin_setting
1805      * @return string XHTML field
1806      */
1807     public function output_html($data, $query='') {
1808         $id = $this->get_id();
1809         $unmask = get_string('unmaskpassword', 'form');
1810         $unmaskjs = '<script type="text/javascript">
1811 //<![CDATA[
1812 var is_ie = (navigator.userAgent.toLowerCase().indexOf("msie") != -1);
1814 document.getElementById("'.$id.'").setAttribute("autocomplete", "off");
1816 var unmaskdiv = document.getElementById("'.$id.'unmaskdiv");
1818 var unmaskchb = document.createElement("input");
1819 unmaskchb.setAttribute("type", "checkbox");
1820 unmaskchb.setAttribute("id", "'.$id.'unmask");
1821 unmaskchb.onchange = function() {unmaskPassword("'.$id.'");};
1822 unmaskdiv.appendChild(unmaskchb);
1824 var unmasklbl = document.createElement("label");
1825 unmasklbl.innerHTML = "'.addslashes_js($unmask).'";
1826 if (is_ie) {
1827   unmasklbl.setAttribute("htmlFor", "'.$id.'unmask");
1828 } else {
1829   unmasklbl.setAttribute("for", "'.$id.'unmask");
1831 unmaskdiv.appendChild(unmasklbl);
1833 if (is_ie) {
1834   // ugly hack to work around the famous onchange IE bug
1835   unmaskchb.onclick = function() {this.blur();};
1836   unmaskdiv.onclick = function() {this.blur();};
1838 //]]>
1839 </script>';
1840         return format_admin_setting($this, $this->visiblename,
1841         '<div class="form-password"><input type="password" size="'.$this->size.'" id="'.$id.'" name="'.$this->get_full_name().'" value="'.s($data).'" /><div class="unmask" id="'.$id.'unmaskdiv"></div>'.$unmaskjs.'</div>',
1842         $this->description, true, '', NULL, $query);
1843     }
1846 /**
1847  * Path to directory
1848  *
1849  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1850  */
1851 class admin_setting_configfile extends admin_setting_configtext {
1852 /**
1853  * Constructor
1854  * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1855  * @param string $visiblename localised
1856  * @param string $description long localised info
1857  * @param string $defaultdirectory default directory location
1858  */
1859     public function __construct($name, $visiblename, $description, $defaultdirectory) {
1860         parent::__construct($name, $visiblename, $description, $defaultdirectory, PARAM_RAW, 50);
1861     }
1863     /**
1864      * Returns XHTML for the field
1865      *
1866      * Returns XHTML for the field and also checks whether the file
1867      * specified in $data exists using file_exists()
1868      *
1869      * @param string $data File name and path to use in value attr
1870      * @param string $query
1871      * @return string XHTML field
1872      */
1873     public function output_html($data, $query='') {
1874         $default = $this->get_defaultsetting();
1876         if ($data) {
1877             if (file_exists($data)) {
1878                 $executable = '<span class="pathok">&#x2714;</span>';
1879             } else {
1880                 $executable = '<span class="patherror">&#x2718;</span>';
1881             }
1882         } else {
1883             $executable = '';
1884         }
1886         return format_admin_setting($this, $this->visiblename,
1887         '<div class="form-file defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" />'.$executable.'</div>',
1888         $this->description, true, '', $default, $query);
1889     }
1892 /**
1893  * Path to executable file
1894  *
1895  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1896  */
1897 class admin_setting_configexecutable extends admin_setting_configfile {
1899 /**
1900  * Returns an XHTML field
1901  *
1902  * @param string $data This is the value for the field
1903  * @param string $query
1904  * @return string XHTML field
1905  */
1906     public function output_html($data, $query='') {
1907         $default = $this->get_defaultsetting();
1909         if ($data) {
1910             if (file_exists($data) and is_executable($data)) {
1911                 $executable = '<span class="pathok">&#x2714;</span>';
1912             } else {
1913                 $executable = '<span class="patherror">&#x2718;</span>';
1914             }
1915         } else {
1916             $executable = '';
1917         }
1919         return format_admin_setting($this, $this->visiblename,
1920         '<div class="form-file defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" />'.$executable.'</div>',
1921         $this->description, true, '', $default, $query);
1922     }
1925 /**
1926  * Path to directory
1927  *
1928  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1929  */
1930 class admin_setting_configdirectory extends admin_setting_configfile {
1932 /**
1933  * Returns an XHTML field
1934  *
1935  * @param string $data This is the value for the field
1936  * @param string $query
1937  * @return string XHTML
1938  */
1939     public function output_html($data, $query='') {
1940         $default = $this->get_defaultsetting();
1942         if ($data) {
1943             if (file_exists($data) and is_dir($data)) {
1944                 $executable = '<span class="pathok">&#x2714;</span>';
1945             } else {
1946                 $executable = '<span class="patherror">&#x2718;</span>';
1947             }
1948         } else {
1949             $executable = '';
1950         }
1952         return format_admin_setting($this, $this->visiblename,
1953         '<div class="form-file defaultsnext"><input type="text" size="'.$this->size.'" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($data).'" />'.$executable.'</div>',
1954         $this->description, true, '', $default, $query);
1955     }
1958 /**
1959  * Checkbox
1960  *
1961  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1962  */
1963 class admin_setting_configcheckbox extends admin_setting {
1964 /** @var string Value used when checked */
1965     public $yes;
1966     /** @var string Value used when not checked */
1967     public $no;
1969     /**
1970      * Constructor
1971      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
1972      * @param string $visiblename localised
1973      * @param string $description long localised info
1974      * @param string $defaultsetting
1975      * @param string $yes value used when checked
1976      * @param string $no value used when not checked
1977      */
1978     public function __construct($name, $visiblename, $description, $defaultsetting, $yes='1', $no='0') {
1979         parent::__construct($name, $visiblename, $description, $defaultsetting);
1980         $this->yes = (string)$yes;
1981         $this->no  = (string)$no;
1982     }
1984     /**
1985      * Retrieves the current setting using the objects name
1986      *
1987      * @return string
1988      */
1989     public function get_setting() {
1990         return $this->config_read($this->name);
1991     }
1993     /**
1994      * Sets the value for the setting
1995      *
1996      * Sets the value for the setting to either the yes or no values
1997      * of the object by comparing $data to yes
1998      *
1999      * @param mixed $data Gets converted to str for comparison against yes value
2000      * @return string empty string or error
2001      */
2002     public function write_setting($data) {
2003         if ((string)$data === $this->yes) { // convert to strings before comparison
2004             $data = $this->yes;
2005         } else {
2006             $data = $this->no;
2007         }
2008         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2009     }
2011     /**
2012      * Returns an XHTML checkbox field
2013      *
2014      * @param string $data If $data matches yes then checkbox is checked
2015      * @param string $query
2016      * @return string XHTML field
2017      */
2018     public function output_html($data, $query='') {
2019         $default = $this->get_defaultsetting();
2021         if (!is_null($default)) {
2022             if ((string)$default === $this->yes) {
2023                 $defaultinfo = get_string('checkboxyes', 'admin');
2024             } else {
2025                 $defaultinfo = get_string('checkboxno', 'admin');
2026             }
2027         } else {
2028             $defaultinfo = NULL;
2029         }
2031         if ((string)$data === $this->yes) { // convert to strings before comparison
2032             $checked = 'checked="checked"';
2033         } else {
2034             $checked = '';
2035         }
2037         return format_admin_setting($this, $this->visiblename,
2038         '<div class="form-checkbox defaultsnext" ><input type="hidden" name="'.$this->get_full_name().'" value="'.s($this->no).'" /> '
2039             .'<input type="checkbox" id="'.$this->get_id().'" name="'.$this->get_full_name().'" value="'.s($this->yes).'" '.$checked.' /></div>',
2040         $this->description, true, '', $defaultinfo, $query);
2041     }
2044 /**
2045  * Multiple checkboxes, each represents different value, stored in csv format
2046  *
2047  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2048  */
2049 class admin_setting_configmulticheckbox extends admin_setting {
2050 /** @var array Array of choices value=>label */
2051     public $choices;
2053     /**
2054      * Constructor: uses parent::__construct
2055      *
2056      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2057      * @param string $visiblename localised
2058      * @param string $description long localised info
2059      * @param array $defaultsetting array of selected
2060      * @param array $choices array of $value=>$label for each checkbox
2061      */
2062     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2063         $this->choices = $choices;
2064         parent::__construct($name, $visiblename, $description, $defaultsetting);
2065     }
2067     /**
2068      * This public function may be used in ancestors for lazy loading of choices
2069      *
2070      * @todo Check if this function is still required content commented out only returns true
2071      * @return bool true if loaded, false if error
2072      */
2073     public function load_choices() {
2074         /*
2075         if (is_array($this->choices)) {
2076             return true;
2077         }
2078         .... load choices here
2079         */
2080         return true;
2081     }
2083     /**
2084      * Is setting related to query text - used when searching
2085      *
2086      * @param string $query
2087      * @return bool true on related, false on not or failure
2088      */
2089     public function is_related($query) {
2090         if (!$this->load_choices() or empty($this->choices)) {
2091             return false;
2092         }
2093         if (parent::is_related($query)) {
2094             return true;
2095         }
2097         $textlib = textlib_get_instance();
2098         foreach ($this->choices as $desc) {
2099             if (strpos($textlib->strtolower($desc), $query) !== false) {
2100                 return true;
2101             }
2102         }
2103         return false;
2104     }
2106     /**
2107      * Returns the current setting if it is set
2108      *
2109      * @return mixed null if null, else an array
2110      */
2111     public function get_setting() {
2112         $result = $this->config_read($this->name);
2114         if (is_null($result)) {
2115             return NULL;
2116         }
2117         if ($result === '') {
2118             return array();
2119         }
2120         $enabled = explode(',', $result);
2121         $setting = array();
2122         foreach ($enabled as $option) {
2123             $setting[$option] = 1;
2124         }
2125         return $setting;
2126     }
2128     /**
2129      * Saves the setting(s) provided in $data
2130      *
2131      * @param array $data An array of data, if not array returns empty str
2132      * @return mixed empty string on useless data or bool true=success, false=failed
2133      */
2134     public function write_setting($data) {
2135         if (!is_array($data)) {
2136             return ''; // ignore it
2137         }
2138         if (!$this->load_choices() or empty($this->choices)) {
2139             return '';
2140         }
2141         unset($data['xxxxx']);
2142         $result = array();
2143         foreach ($data as $key => $value) {
2144             if ($value and array_key_exists($key, $this->choices)) {
2145                 $result[] = $key;
2146             }
2147         }
2148         return $this->config_write($this->name, implode(',', $result)) ? '' : get_string('errorsetting', 'admin');
2149     }
2151     /**
2152      * Returns XHTML field(s) as required by choices
2153      *
2154      * Relies on data being an array should data ever be another valid vartype with
2155      * acceptable value this may cause a warning/error
2156      * if (!is_array($data)) would fix the problem
2157      *
2158      * @todo Add vartype handling to ensure $data is an array
2159      *
2160      * @param array $data An array of checked values
2161      * @param string $query
2162      * @return string XHTML field
2163      */
2164     public function output_html($data, $query='') {
2165         if (!$this->load_choices() or empty($this->choices)) {
2166             return '';
2167         }
2168         $default = $this->get_defaultsetting();
2169         if (is_null($default)) {
2170             $default = array();
2171         }
2172         if (is_null($data)) {
2173             $data = array();
2174         }
2175         $options = array();
2176         $defaults = array();
2177         foreach ($this->choices as $key=>$description) {
2178             if (!empty($data[$key])) {
2179                 $checked = 'checked="checked"';
2180             } else {
2181                 $checked = '';
2182             }
2183             if (!empty($default[$key])) {
2184                 $defaults[] = $description;
2185             }
2187             $options[] = '<input type="checkbox" id="'.$this->get_id().'_'.$key.'" name="'.$this->get_full_name().'['.$key.']" value="1" '.$checked.' />'
2188                 .'<label for="'.$this->get_id().'_'.$key.'">'.highlightfast($query, $description).'</label>';
2189         }
2191         if (is_null($default)) {
2192             $defaultinfo = NULL;
2193         } else if (!empty($defaults)) {
2194                 $defaultinfo = implode(', ', $defaults);
2195             } else {
2196                 $defaultinfo = get_string('none');
2197             }
2199         $return = '<div class="form-multicheckbox">';
2200         $return .= '<input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
2201         if ($options) {
2202             $return .= '<ul>';
2203             foreach ($options as $option) {
2204                 $return .= '<li>'.$option.'</li>';
2205             }
2206             $return .= '</ul>';
2207         }
2208         $return .= '</div>';
2210         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
2212     }
2215 /**
2216  * Multiple checkboxes 2, value stored as string 00101011
2217  *
2218  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2219  */
2220 class admin_setting_configmulticheckbox2 extends admin_setting_configmulticheckbox {
2222 /**
2223  * Returns the setting if set
2224  *
2225  * @return mixed null if not set, else an array of set settings
2226  */
2227     public function get_setting() {
2228         $result = $this->config_read($this->name);
2229         if (is_null($result)) {
2230             return NULL;
2231         }
2232         if (!$this->load_choices()) {
2233             return NULL;
2234         }
2235         $result = str_pad($result, count($this->choices), '0');
2236         $result = preg_split('//', $result, -1, PREG_SPLIT_NO_EMPTY);
2237         $setting = array();
2238         foreach ($this->choices as $key=>$unused) {
2239             $value = array_shift($result);
2240             if ($value) {
2241                 $setting[$key] = 1;
2242             }
2243         }
2244         return $setting;
2245     }
2247     /**
2248      * Save setting(s) provided in $data param
2249      *
2250      * @param array $data An array of settings to save
2251      * @return mixed empty string for bad data or bool true=>success, false=>error
2252      */
2253     public function write_setting($data) {
2254         if (!is_array($data)) {
2255             return ''; // ignore it
2256         }
2257         if (!$this->load_choices() or empty($this->choices)) {
2258             return '';
2259         }
2260         $result = '';
2261         foreach ($this->choices as $key=>$unused) {
2262             if (!empty($data[$key])) {
2263                 $result .= '1';
2264             } else {
2265                 $result .= '0';
2266             }
2267         }
2268         return $this->config_write($this->name, $result) ? '' : get_string('errorsetting', 'admin');
2269     }
2272 /**
2273  * Select one value from list
2274  *
2275  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2276  */
2277 class admin_setting_configselect extends admin_setting {
2278 /** @var array Array of choices value=>label */
2279     public $choices;
2281     /**
2282      * Constructor
2283      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2284      * @param string $visiblename localised
2285      * @param string $description long localised info
2286      * @param string|int $defaultsetting
2287      * @param array $choices array of $value=>$label for each selection
2288      */
2289     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2290         $this->choices = $choices;
2291         parent::__construct($name, $visiblename, $description, $defaultsetting);
2292     }
2294     /**
2295      * This function may be used in ancestors for lazy loading of choices
2296      *
2297      * Override this method if loading of choices is expensive, such
2298      * as when it requires multiple db requests.
2299      *
2300      * @return bool true if loaded, false if error
2301      */
2302     public function load_choices() {
2303         /*
2304         if (is_array($this->choices)) {
2305             return true;
2306         }
2307         .... load choices here
2308         */
2309         return true;
2310     }
2312     /**
2313      * Check if this is $query is related to a choice
2314      *
2315      * @param string $query
2316      * @return bool true if related, false if not
2317      */
2318     public function is_related($query) {
2319         if (parent::is_related($query)) {
2320             return true;
2321         }
2322         if (!$this->load_choices()) {
2323             return false;
2324         }
2325         $textlib = textlib_get_instance();
2326         foreach ($this->choices as $key=>$value) {
2327             if (strpos($textlib->strtolower($key), $query) !== false) {
2328                 return true;
2329             }
2330             if (strpos($textlib->strtolower($value), $query) !== false) {
2331                 return true;
2332             }
2333         }
2334         return false;
2335     }
2337     /**
2338      * Return the setting
2339      *
2340      * @return mixed returns config if successful else null
2341      */
2342     public function get_setting() {
2343         return $this->config_read($this->name);
2344     }
2346     /**
2347      * Save a setting
2348      *
2349      * @param string $data
2350      * @return string empty of error string
2351      */
2352     public function write_setting($data) {
2353         if (!$this->load_choices() or empty($this->choices)) {
2354             return '';
2355         }
2356         if (!array_key_exists($data, $this->choices)) {
2357             return ''; // ignore it
2358         }
2360         return ($this->config_write($this->name, $data) ? '' : get_string('errorsetting', 'admin'));
2361     }
2363     /**
2364      * Returns XHTML select field
2365      *
2366      * Ensure the options are loaded, and generate the XHTML for the select
2367      * element and any warning message. Separating this out from output_html
2368      * makes it easier to subclass this class.
2369      *
2370      * @param string $data the option to show as selected.
2371      * @param string $current the currently selected option in the database, null if none.
2372      * @param string $default the default selected option.
2373      * @return array the HTML for the select element, and a warning message.
2374      */
2375     public function output_select_html($data, $current, $default, $extraname = '') {
2376         if (!$this->load_choices() or empty($this->choices)) {
2377             return array('', '');
2378         }
2380         $warning = '';
2381         if (is_null($current)) {
2382         // first run
2383         } else if (empty($current) and (array_key_exists('', $this->choices) or array_key_exists(0, $this->choices))) {
2384             // no warning
2385             } else if (!array_key_exists($current, $this->choices)) {
2386                     $warning = get_string('warningcurrentsetting', 'admin', s($current));
2387                     if (!is_null($default) and $data == $current) {
2388                         $data = $default; // use default instead of first value when showing the form
2389                     }
2390                 }
2392         $selecthtml = '<select id="'.$this->get_id().'" name="'.$this->get_full_name().$extraname.'">';
2393         foreach ($this->choices as $key => $value) {
2394         // the string cast is needed because key may be integer - 0 is equal to most strings!
2395             $selecthtml .= '<option value="'.$key.'"'.((string)$key==$data ? ' selected="selected"' : '').'>'.$value.'</option>';
2396         }
2397         $selecthtml .= '</select>';
2398         return array($selecthtml, $warning);
2399     }
2401     /**
2402      * Returns XHTML select field and wrapping div(s)
2403      *
2404      * @see output_select_html()
2405      *
2406      * @param string $data the option to show as selected
2407      * @param string $query
2408      * @return string XHTML field and wrapping div
2409      */
2410     public function output_html($data, $query='') {
2411         $default = $this->get_defaultsetting();
2412         $current = $this->get_setting();
2414         list($selecthtml, $warning) = $this->output_select_html($data, $current, $default);
2415         if (!$selecthtml) {
2416             return '';
2417         }
2419         if (!is_null($default) and array_key_exists($default, $this->choices)) {
2420             $defaultinfo = $this->choices[$default];
2421         } else {
2422             $defaultinfo = NULL;
2423         }
2425         $return = '<div class="form-select defaultsnext">' . $selecthtml . '</div>';
2427         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, $warning, $defaultinfo, $query);
2428     }
2431 /**
2432  * Select multiple items from list
2433  *
2434  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2435  */
2436 class admin_setting_configmultiselect extends admin_setting_configselect {
2437 /**
2438  * Constructor
2439  * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2440  * @param string $visiblename localised
2441  * @param string $description long localised info
2442  * @param array $defaultsetting array of selected items
2443  * @param array $choices array of $value=>$label for each list item
2444  */
2445     public function __construct($name, $visiblename, $description, $defaultsetting, $choices) {
2446         parent::__construct($name, $visiblename, $description, $defaultsetting, $choices);
2447     }
2449     /**
2450      * Returns the select setting(s)
2451      *
2452      * @return mixed null or array. Null if no settings else array of setting(s)
2453      */
2454     public function get_setting() {
2455         $result = $this->config_read($this->name);
2456         if (is_null($result)) {
2457             return NULL;
2458         }
2459         if ($result === '') {
2460             return array();
2461         }
2462         return explode(',', $result);
2463     }
2465     /**
2466      * Saves setting(s) provided through $data
2467      *
2468      * Potential bug in the works should anyone call with this function
2469      * using a vartype that is not an array
2470      *
2471      * @todo Add vartype handling to ensure $data is an array
2472      * @param array $data
2473      */
2474     public function write_setting($data) {
2475         if (!is_array($data)) {
2476             return ''; //ignore it
2477         }
2478         if (!$this->load_choices() or empty($this->choices)) {
2479             return '';
2480         }
2482         unset($data['xxxxx']);
2484         $save = array();
2485         foreach ($data as $value) {
2486             if (!array_key_exists($value, $this->choices)) {
2487                 continue; // ignore it
2488             }
2489             $save[] = $value;
2490         }
2492         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
2493     }
2495     /**
2496      * Is setting related to query text - used when searching
2497      *
2498      * @param string $query
2499      * @return bool true if related, false if not
2500      */
2501     public function is_related($query) {
2502         if (!$this->load_choices() or empty($this->choices)) {
2503             return false;
2504         }
2505         if (parent::is_related($query)) {
2506             return true;
2507         }
2509         $textlib = textlib_get_instance();
2510         foreach ($this->choices as $desc) {
2511             if (strpos($textlib->strtolower($desc), $query) !== false) {
2512                 return true;
2513             }
2514         }
2515         return false;
2516     }
2518     /**
2519      * Returns XHTML multi-select field
2520      *
2521      * @todo Add vartype handling to ensure $data is an array
2522      * @param array $data Array of values to select by default
2523      * @param string $query
2524      * @return string XHTML multi-select field
2525      */
2526     public function output_html($data, $query='') {
2527         if (!$this->load_choices() or empty($this->choices)) {
2528             return '';
2529         }
2530         $choices = $this->choices;
2531         $default = $this->get_defaultsetting();
2532         if (is_null($default)) {
2533             $default = array();
2534         }
2535         if (is_null($data)) {
2536             $data = array();
2537         }
2539         $defaults = array();
2540         $size = min(10, count($this->choices));
2541         $return = '<div class="form-select"><input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
2542         $return .= '<select id="'.$this->get_id().'" name="'.$this->get_full_name().'[]" size="'.$size.'" multiple="multiple">';
2543         foreach ($this->choices as $key => $description) {
2544             if (in_array($key, $data)) {
2545                 $selected = 'selected="selected"';
2546             } else {
2547                 $selected = '';
2548             }
2549             if (in_array($key, $default)) {
2550                 $defaults[] = $description;
2551             }
2553             $return .= '<option value="'.s($key).'" '.$selected.'>'.$description.'</option>';
2554         }
2556         if (is_null($default)) {
2557             $defaultinfo = NULL;
2558         } if (!empty($defaults)) {
2559             $defaultinfo = implode(', ', $defaults);
2560         } else {
2561             $defaultinfo = get_string('none');
2562         }
2564         $return .= '</select></div>';
2565         return format_admin_setting($this, $this->visiblename, $return, $this->description, true, '', $defaultinfo, $query);
2566     }
2569 /**
2570  * Time selector
2571  *
2572  * This is a liiitle bit messy. we're using two selects, but we're returning
2573  * them as an array named after $name (so we only use $name2 internally for the setting)
2574  *
2575  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2576  */
2577 class admin_setting_configtime extends admin_setting {
2578 /** @var string Used for setting second select (minutes) */
2579     public $name2;
2581     /**
2582      * Constructor
2583      * @param string $hoursname setting for hours
2584      * @param string $minutesname setting for hours
2585      * @param string $visiblename localised
2586      * @param string $description long localised info
2587      * @param array $defaultsetting array representing default time 'h'=>hours, 'm'=>minutes
2588      */
2589     public function __construct($hoursname, $minutesname, $visiblename, $description, $defaultsetting) {
2590         $this->name2 = $minutesname;
2591         parent::__construct($hoursname, $visiblename, $description, $defaultsetting);
2592     }
2594     /**
2595      * Get the selected time
2596      *
2597      * @return mixed An array containing 'h'=>xx, 'm'=>xx, or null if not set
2598      */
2599     public function get_setting() {
2600         $result1 = $this->config_read($this->name);
2601         $result2 = $this->config_read($this->name2);
2602         if (is_null($result1) or is_null($result2)) {
2603             return NULL;
2604         }
2606         return array('h' => $result1, 'm' => $result2);
2607     }
2609     /**
2610      * Store the time (hours and minutes)
2611      *
2612      * @param array $data Must be form 'h'=>xx, 'm'=>xx
2613      * @return bool true if success, false if not
2614      */
2615     public function write_setting($data) {
2616         if (!is_array($data)) {
2617             return '';
2618         }
2620         $result = $this->config_write($this->name, (int)$data['h']) && $this->config_write($this->name2, (int)$data['m']);
2621         return ($result ? '' : get_string('errorsetting', 'admin'));
2622     }
2624     /**
2625      * Returns XHTML time select fields
2626      *
2627      * @param array $data Must be form 'h'=>xx, 'm'=>xx
2628      * @param string $query
2629      * @return string XHTML time select fields and wrapping div(s)
2630      */
2631     public function output_html($data, $query='') {
2632         $default = $this->get_defaultsetting();
2634         if (is_array($default)) {
2635             $defaultinfo = $default['h'].':'.$default['m'];
2636         } else {
2637             $defaultinfo = NULL;
2638         }
2640         $return = '<div class="form-time defaultsnext">'.
2641             '<select id="'.$this->get_id().'h" name="'.$this->get_full_name().'[h]">';
2642         for ($i = 0; $i < 24; $i++) {
2643             $return .= '<option value="'.$i.'"'.($i == $data['h'] ? ' selected="selected"' : '').'>'.$i.'</option>';
2644         }
2645         $return .= '</select>:<select id="'.$this->get_id().'m" name="'.$this->get_full_name().'[m]">';
2646         for ($i = 0; $i < 60; $i += 5) {
2647             $return .= '<option value="'.$i.'"'.($i == $data['m'] ? ' selected="selected"' : '').'>'.$i.'</option>';
2648         }
2649         $return .= '</select></div>';
2650         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', $defaultinfo, $query);
2651     }
2655 /**
2656  * Used to validate a textarea used for ip addresses
2657  *
2658  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2659  */
2660 class admin_setting_configiplist extends admin_setting_configtextarea {
2662 /**
2663  * Validate the contents of the textarea as IP addresses
2664  *
2665  * Used to validate a new line separated list of IP addresses collected from
2666  * a textarea control
2667  *
2668  * @param string $data A list of IP Addresses separated by new lines
2669  * @return mixed bool true for success or string:error on failure
2670  */
2671     public function validate($data) {
2672         if(!empty($data)) {
2673             $ips = explode("\n", $data);
2674         } else {
2675             return true;
2676         }
2677         $result = true;
2678         foreach($ips as $ip) {
2679             $ip = trim($ip);
2680             if(preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}$#', $ip, $match) ||
2681                 preg_match('#^(\d{1,3})(\.\d{1,3}){0,3}(\/\d{1,2})$#', $ip, $match) ||
2682                 preg_match('#^(\d{1,3})(\.\d{1,3}){3}(-\d{1,3})$#', $ip, $match)) {
2683                 $result = true;
2684             } else {
2685                 $result = false;
2686                 break;
2687             }
2688         }
2689         if($result) {
2690             return true;
2691         } else {
2692             return get_string('validateerror', 'admin');
2693         }
2694     }
2697 /**
2698  * An admin setting for selecting one or more users who have a capability
2699  * in the system context
2700  *
2701  * An admin setting for selecting one or more users, who have a particular capability
2702  * in the system context. Warning, make sure the list will never be too long. There is
2703  * no paging or searching of this list.
2704  *
2705  * To correctly get a list of users from this config setting, you need to call the
2706  * get_users_from_config($CFG->mysetting, $capability); function in moodlelib.php.
2707  *
2708  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2709  */
2710 class admin_setting_users_with_capability extends admin_setting_configmultiselect {
2711     /** @var string The capabilities name */
2712     protected $capability;
2713     /** @var int include admin users too */
2714     protected $includeadmins;
2716     /**
2717      * Constructor.
2718      *
2719      * @param string $name unique ascii name, either 'mysetting' for settings that in config, or 'myplugin/mysetting' for ones in config_plugins.
2720      * @param string $visiblename localised name
2721      * @param string $description localised long description
2722      * @param array $defaultsetting array of usernames
2723      * @param string $capability string capability name.
2724      * @param bool $includeadmins include administrators
2725      */
2726     function __construct($name, $visiblename, $description, $defaultsetting, $capability, $includeadmins = true) {
2727         $this->capability    = $capability;
2728         $this->includeadmins = $includeadmins;
2729         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
2730     }
2732     /**
2733      * Load all of the uses who have the capability into choice array
2734      *
2735      * @return bool Always returns true
2736      */
2737     function load_choices() {
2738         if (is_array($this->choices)) {
2739             return true;
2740         }
2741         $users = get_users_by_capability(get_context_instance(CONTEXT_SYSTEM),
2742             $this->capability, 'u.id,u.username,u.firstname,u.lastname', 'u.lastname,u.firstname');
2743         $this->choices = array(
2744             '$@NONE@$' => get_string('nobody'),
2745             '$@ALL@$' => get_string('everyonewhocan', 'admin', get_capability_string($this->capability)),
2746         );
2747         if ($this->includeadmins) {
2748             $admins = get_admins();
2749             foreach ($admins as $user) {
2750                 $this->choices[$user->id] = fullname($user);
2751             }
2752         }
2753         if (is_array($users)) {
2754             foreach ($users as $user) {
2755                 $this->choices[$user->id] = fullname($user);
2756             }
2757         }
2758         return true;
2759     }
2761     /**
2762      * Returns the default setting for class
2763      *
2764      * @return mixed Array, or string. Empty string if no default
2765      */
2766     public function get_defaultsetting() {
2767         $this->load_choices();
2768         $defaultsetting = parent::get_defaultsetting();
2769         if (empty($defaultsetting)) {
2770             return array('$@NONE@$');
2771         } else if (array_key_exists($defaultsetting, $this->choices)) {
2772                 return $defaultsetting;
2773             } else {
2774                 return '';
2775             }
2776     }
2778     /**
2779      * Returns the current setting
2780      *
2781      * @return mixed array or string
2782      */
2783     public function get_setting() {
2784         $result = parent::get_setting();
2785         if ($result === null) {
2786             // this is necessary for settings upgrade
2787             return null;
2788         }
2789         if (empty($result)) {
2790             $result = array('$@NONE@$');
2791         }
2792         return $result;
2793     }
2795     /**
2796      * Save the chosen setting provided as $data
2797      *
2798      * @param array $data
2799      * @return mixed string or array
2800      */
2801     public function write_setting($data) {
2802     // If all is selected, remove any explicit options.
2803         if (in_array('$@ALL@$', $data)) {
2804             $data = array('$@ALL@$');
2805         }
2806         // None never needs to be written to the DB.
2807         if (in_array('$@NONE@$', $data)) {
2808             unset($data[array_search('$@NONE@$', $data)]);
2809         }
2810         return parent::write_setting($data);
2811     }
2814 /**
2815  * Special checkbox for calendar - resets SESSION vars.
2816  *
2817  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2818  */
2819 class admin_setting_special_adminseesall extends admin_setting_configcheckbox {
2820 /**
2821  * Calls the parent::__construct with default values
2822  *
2823  * name =>  calendar_adminseesall
2824  * visiblename => get_string('adminseesall', 'admin')
2825  * description => get_string('helpadminseesall', 'admin')
2826  * defaultsetting => 0
2827  */
2828     public function __construct() {
2829         parent::__construct('calendar_adminseesall', get_string('adminseesall', 'admin'),
2830             get_string('helpadminseesall', 'admin'), '0');
2831     }
2833     /**
2834      * Stores the setting passed in $data
2835      *
2836      * @param mixed gets converted to string for comparison
2837      * @return string empty string or error message
2838      */
2839     public function write_setting($data) {
2840         global $SESSION;
2841         unset($SESSION->cal_courses_shown);
2842         return parent::write_setting($data);
2843     }
2846 /**
2847  * Special select for settings that are altered in setup.php and can not be altered on the fly
2848  *
2849  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2850  */
2851 class admin_setting_special_selectsetup extends admin_setting_configselect {
2852 /**
2853  * Reads the setting directly from the database
2854  *
2855  * @return mixed
2856  */
2857     public function get_setting() {
2858     // read directly from db!
2859         return get_config(NULL, $this->name);
2860     }
2862     /**
2863      * Save the setting passed in $data
2864      *
2865      * @param string $data The setting to save
2866      * @return string empty or error message
2867      */
2868     public function write_setting($data) {
2869         global $CFG;
2870         // do not change active CFG setting!
2871         $current = $CFG->{$this->name};
2872         $result = parent::write_setting($data);
2873         $CFG->{$this->name} = $current;
2874         return $result;
2875     }
2878 /**
2879  * Special select for frontpage - stores data in course table
2880  *
2881  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2882  */
2883 class admin_setting_sitesetselect extends admin_setting_configselect {
2884 /**
2885  * Returns the site name for the selected site
2886  *
2887  * @see get_site()
2888  * @return string The site name of the selected site
2889  */
2890     public function get_setting() {
2891         $site = get_site();
2892         return $site->{$this->name};
2893     }
2894     /**
2895      * Updates the database and save the setting
2896      *
2897      * @param string data
2898      * @return string empty or error message
2899      */
2900     public function write_setting($data) {
2901         global $DB, $SITE;
2902         if (!in_array($data, array_keys($this->choices))) {
2903             return get_string('errorsetting', 'admin');
2904         }
2905         $record = new stdClass();
2906         $record->id           = SITEID;
2907         $temp                 = $this->name;
2908         $record->$temp        = $data;
2909         $record->timemodified = time();
2910         // update $SITE
2911         $SITE->{$this->name} = $data;
2912         return ($DB->update_record('course', $record) ? '' : get_string('errorsetting', 'admin'));
2913     }
2916 /**
2917  * Select for blog's bloglevel setting: if set to 0, will set blog_menu
2918  * block to hidden.
2919  *
2920  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2921  */
2922 class admin_setting_bloglevel extends admin_setting_configselect {
2923     /**
2924      * Updates the database and save the setting
2925      *
2926      * @param string data
2927      * @return string empty or error message
2928      */
2929     public function write_setting($data) {
2930         global $DB;
2931         if ($data['bloglevel'] == 0) {
2932             $DB->set_field('block', 'visible', 0, array('name' => 'blog_menu'));
2933         } else {
2934             $DB->set_field('block', 'visible', 1, array('name' => 'blog_menu'));
2935         }
2936         return parent::write_setting($data);
2937     }
2940 /**
2941  * Special select - lists on the frontpage - hacky
2942  *
2943  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2944  */
2945 class admin_setting_courselist_frontpage extends admin_setting {
2946 /** @var array Array of choices value=>label */
2947     public $choices;
2949     /**
2950      * Construct override, requires one param
2951      *
2952      * @param bool $loggedin Is the user logged in
2953      */
2954     public function __construct($loggedin) {
2955         global $CFG;
2956         require_once($CFG->dirroot.'/course/lib.php');
2957         $name        = 'frontpage'.($loggedin ? 'loggedin' : '');
2958         $visiblename = get_string('frontpage'.($loggedin ? 'loggedin' : ''),'admin');
2959         $description = get_string('configfrontpage'.($loggedin ? 'loggedin' : ''),'admin');
2960         $defaults    = array(FRONTPAGECOURSELIST);
2961         parent::__construct($name, $visiblename, $description, $defaults);
2962     }
2964     /**
2965      * Loads the choices available
2966      *
2967      * @return bool always returns true
2968      */
2969     public function load_choices() {
2970         global $DB;
2971         if (is_array($this->choices)) {
2972             return true;
2973         }
2974         $this->choices = array(FRONTPAGENEWS          => get_string('frontpagenews'),
2975             FRONTPAGECOURSELIST    => get_string('frontpagecourselist'),
2976             FRONTPAGECATEGORYNAMES => get_string('frontpagecategorynames'),
2977             FRONTPAGECATEGORYCOMBO => get_string('frontpagecategorycombo'),
2978             'none'                 => get_string('none'));
2979         if ($this->name == 'frontpage' and $DB->count_records('course') > FRONTPAGECOURSELIMIT) {
2980             unset($this->choices[FRONTPAGECOURSELIST]);
2981         }
2982         return true;
2983     }
2984     /**
2985      * Returns the selected settings
2986      *
2987      * @param mixed array or setting or null
2988      */
2989     public function get_setting() {
2990         $result = $this->config_read($this->name);
2991         if (is_null($result)) {
2992             return NULL;
2993         }
2994         if ($result === '') {
2995             return array();
2996         }
2997         return explode(',', $result);
2998     }
3000     /**
3001      * Save the selected options
3002      *
3003      * @param array $data
3004      * @return mixed empty string (data is not an array) or bool true=success false=failure
3005      */
3006     public function write_setting($data) {
3007         if (!is_array($data)) {
3008             return '';
3009         }
3010         $this->load_choices();
3011         $save = array();
3012         foreach($data as $datum) {
3013             if ($datum == 'none' or !array_key_exists($datum, $this->choices)) {
3014                 continue;
3015             }
3016             $save[$datum] = $datum; // no duplicates
3017         }
3018         return ($this->config_write($this->name, implode(',', $save)) ? '' : get_string('errorsetting', 'admin'));
3019     }
3021     /**
3022      * Return XHTML select field and wrapping div
3023      *
3024      * @todo Add vartype handling to make sure $data is an array
3025      * @param array $data Array of elements to select by default
3026      * @return string XHTML select field and wrapping div
3027      */
3028     public function output_html($data, $query='') {
3029         $this->load_choices();
3030         $currentsetting = array();
3031         foreach ($data as $key) {
3032             if ($key != 'none' and array_key_exists($key, $this->choices)) {
3033                 $currentsetting[] = $key; // already selected first
3034             }
3035         }
3037         $return = '<div class="form-group">';
3038         for ($i = 0; $i < count($this->choices) - 1; $i++) {
3039             if (!array_key_exists($i, $currentsetting)) {
3040                 $currentsetting[$i] = 'none'; //none
3041             }
3042             $return .='<select class="form-select" id="'.$this->get_id().$i.'" name="'.$this->get_full_name().'[]">';
3043             foreach ($this->choices as $key => $value) {
3044                 $return .= '<option value="'.$key.'"'.("$key" == $currentsetting[$i] ? ' selected="selected"' : '').'>'.$value.'</option>';
3045             }
3046             $return .= '</select>';
3047             if ($i !== count($this->choices) - 2) {
3048                 $return .= '<br />';
3049             }
3050         }
3051         $return .= '</div>';
3053         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', NULL, $query);
3054     }
3057 /**
3058  * Special checkbox for frontpage - stores data in course table
3059  *
3060  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3061  */
3062 class admin_setting_sitesetcheckbox extends admin_setting_configcheckbox {
3063 /**
3064  * Returns the current sites name
3065  *
3066  * @return string
3067  */
3068     public function get_setting() {
3069         $site = get_site();
3070         return $site->{$this->name};
3071     }
3073     /**
3074      * Save the selected setting
3075      *
3076      * @param string $data The selected site
3077      * @return string empty string or error message
3078      */
3079     public function write_setting($data) {
3080         global $DB, $SITE;
3081         $record = new stdClass();
3082         $record->id            = SITEID;
3083         $record->{$this->name} = ($data == '1' ? 1 : 0);
3084         $record->timemodified  = time();
3085         // update $SITE
3086         $SITE->{$this->name} = $data;
3087         return ($DB->update_record('course', $record) ? '' : get_string('errorsetting', 'admin'));
3088     }
3091 /**
3092  * Special text for frontpage - stores data in course table.
3093  * Empty string means not set here. Manual setting is required.
3094  *
3095  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3096  */
3097 class admin_setting_sitesettext extends admin_setting_configtext {
3098 /**
3099  * Return the current setting
3100  *
3101  * @return mixed string or null
3102  */
3103     public function get_setting() {
3104         $site = get_site();
3105         return $site->{$this->name} != '' ? $site->{$this->name} : NULL;
3106     }
3108     /**
3109      * Validate the selected data
3110      *
3111      * @param string $data The selected value to validate
3112      * @return mixed true or message string
3113      */
3114     public function validate($data) {
3115         $cleaned = clean_param($data, PARAM_MULTILANG);
3116         if ($cleaned === '') {
3117             return get_string('required');
3118         }
3119         if ("$data" == "$cleaned") { // implicit conversion to string is needed to do exact comparison
3120             return true;
3121         } else {
3122             return get_string('validateerror', 'admin');
3123         }
3124     }
3126     /**
3127      * Save the selected setting
3128      *
3129      * @param string $data The selected value
3130      * @return string empty or error message
3131      */
3132     public function write_setting($data) {
3133         global $DB, $SITE;
3134         $data = trim($data);
3135         $validated = $this->validate($data);
3136         if ($validated !== true) {
3137             return $validated;
3138         }
3140         $record = new stdClass();
3141         $record->id            = SITEID;
3142         $record->{$this->name} = $data;
3143         $record->timemodified  = time();
3144         // update $SITE
3145         $SITE->{$this->name} = $data;
3146         return ($DB->update_record('course', $record) ? '' : get_string('dbupdatefailed', 'error'));
3147     }
3150 /**
3151  * Special text editor for site description.
3152  *
3153  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3154  */
3155 class admin_setting_special_frontpagedesc extends admin_setting {
3156 /**
3157  * Calls parent::__construct with specific arguments
3158  */
3159     public function __construct() {
3160         parent::__construct('summary', get_string('frontpagedescription'), get_string('frontpagedescriptionhelp'), NULL);
3161         editors_head_setup();
3162     }
3164     /**
3165      * Return the current setting
3166      * @return string The current setting
3167      */
3168     public function get_setting() {
3169         $site = get_site();
3170         return $site->{$this->name};
3171     }
3173     /**
3174      * Save the new setting
3175      *
3176      * @param string $data The new value to save
3177      * @return string empty or error message
3178      */
3179     public function write_setting($data) {
3180         global $DB, $SITE;
3181         $record = new stdClass();
3182         $record->id            = SITEID;
3183         $record->{$this->name} = $data;
3184         $record->timemodified  = time();
3185         $SITE->{$this->name} = $data;
3186         return ($DB->update_record('course', $record) ? '' : get_string('errorsetting', 'admin'));
3187     }
3189     /**
3190      * Returns XHTML for the field plus wrapping div
3191      *
3192      * @param string $data The current value
3193      * @param string $query
3194      * @return string The XHTML output
3195      */
3196     public function output_html($data, $query='') {
3197         global $CFG;
3199         $CFG->adminusehtmleditor = can_use_html_editor();
3200         $return = '<div class="form-htmlarea">'.print_textarea($CFG->adminusehtmleditor, 15, 60, 0, 0, $this->get_full_name(), $data, 0, true, 'summary') .'</div>';
3202         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', NULL, $query);
3203     }
3206 /**
3207  * Administration interface for emoticon_manager settings.
3208  *
3209  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3210  */
3211 class admin_setting_emoticons extends admin_setting {
3213 /**
3214  * Calls parent::__construct with specific args
3215  */
3216     public function __construct() {
3217         global $CFG;
3219         $manager = get_emoticon_manager();
3220         $defaults = $this->prepare_form_data($manager->default_emoticons());
3221         parent::__construct('emoticons', get_string('emoticons', 'admin'), get_string('emoticons_desc', 'admin'), $defaults);
3222     }
3224     /**
3225      * Return the current setting(s)
3226      *
3227      * @return array Current settings array
3228      */
3229     public function get_setting() {
3230         global $CFG;
3232         $manager = get_emoticon_manager();
3234         $config = $this->config_read($this->name);
3235         if (is_null($config)) {
3236             return null;
3237         }
3239         $config = $manager->decode_stored_config($config);
3240         if (is_null($config)) {
3241             return null;
3242         }
3244         return $this->prepare_form_data($config);
3245     }
3247     /**
3248      * Save selected settings
3249      *
3250      * @param array $data Array of settings to save
3251      * @return bool
3252      */
3253     public function write_setting($data) {
3255         $manager = get_emoticon_manager();
3256         $emoticons = $this->process_form_data($data);
3258         if ($emoticons === false) {
3259             return false;
3260         }
3262         if ($this->config_write($this->name, $manager->encode_stored_config($emoticons))) {
3263             return ''; // success
3264         } else {
3265             return get_string('errorsetting', 'admin') . $this->visiblename . html_writer::empty_tag('br');
3266         }
3267     }
3269     /**
3270      * Return XHTML field(s) for options
3271      *
3272      * @param array $data Array of options to set in HTML
3273      * @return string XHTML string for the fields and wrapping div(s)
3274      */
3275     public function output_html($data, $query='') {
3276         global $OUTPUT;
3278         $out  = html_writer::start_tag('table', array('border' => 1, 'class' => 'generaltable'));
3279         $out .= html_writer::start_tag('thead');
3280         $out .= html_writer::start_tag('tr');
3281         $out .= html_writer::tag('th', get_string('emoticontext', 'admin'));
3282         $out .= html_writer::tag('th', get_string('emoticonimagename', 'admin'));
3283         $out .= html_writer::tag('th', get_string('emoticoncomponent', 'admin'));
3284         $out .= html_writer::tag('th', get_string('emoticonalt', 'admin'), array('colspan' => 2));
3285         $out .= html_writer::tag('th', '');
3286         $out .= html_writer::end_tag('tr');
3287         $out .= html_writer::end_tag('thead');
3288         $out .= html_writer::start_tag('tbody');
3289         $i = 0;
3290         foreach($data as $field => $value) {
3291             switch ($i) {
3292             case 0:
3293                 $out .= html_writer::start_tag('tr');
3294                 $current_text = $value;
3295                 $current_filename = '';
3296                 $current_imagecomponent = '';
3297                 $current_altidentifier = '';
3298                 $current_altcomponent = '';
3299             case 1:
3300                 $current_filename = $value;
3301             case 2:
3302                 $current_imagecomponent = $value;
3303             case 3:
3304                 $current_altidentifier = $value;
3305             case 4:
3306                 $current_altcomponent = $value;
3307             }
3309             $out .= html_writer::tag('td',
3310                 html_writer::empty_tag('input',
3311                     array(
3312                         'type'  => 'text',
3313                         'class' => 'form-text',
3314                         'name'  => $this->get_full_name().'['.$field.']',
3315                         'value' => $value,
3316                     )
3317                 ), array('class' => 'c'.$i)
3318             );
3320             if ($i == 4) {
3321                 if (get_string_manager()->string_exists($current_altidentifier, $current_altcomponent)) {
3322                     $alt = get_string($current_altidentifier, $current_altcomponent);
3323                 } else {
3324                     $alt = $current_text;
3325                 }
3326                 if ($current_filename) {
3327                     $out .= html_writer::tag('td', $OUTPUT->render(new pix_emoticon($current_filename, $alt, $current_imagecomponent)));
3328                 } else {
3329                     $out .= html_writer::tag('td', '');
3330                 }
3331                 $out .= html_writer::end_tag('tr');
3332                 $i = 0;
3333             } else {
3334                 $i++;
3335             }
3337         }
3338         $out .= html_writer::end_tag('tbody');
3339         $out .= html_writer::end_tag('table');
3340         $out  = html_writer::tag('div', $out, array('class' => 'form-group'));
3341         $out .= html_writer::tag('div', html_writer::link(new moodle_url('/admin/resetemoticons.php'), get_string('emoticonsreset', 'admin')));
3343         return format_admin_setting($this, $this->visiblename, $out, $this->description, false, '', NULL, $query);
3344     }
3346     /**
3347      * Converts the array of emoticon objects provided by {@see emoticon_manager} into admin settings form data
3348      *
3349      * @see self::process_form_data()
3350      * @param array $emoticons array of emoticon objects as returned by {@see emoticon_manager}
3351      * @return array of form fields and their values
3352      */
3353     protected function prepare_form_data(array $emoticons) {
3355         $form = array();
3356         $i = 0;
3357         foreach ($emoticons as $emoticon) {
3358             $form['text'.$i]            = $emoticon->text;
3359             $form['imagename'.$i]       = $emoticon->imagename;
3360             $form['imagecomponent'.$i]  = $emoticon->imagecomponent;
3361             $form['altidentifier'.$i]   = $emoticon->altidentifier;
3362             $form['altcomponent'.$i]    = $emoticon->altcomponent;
3363             $i++;
3364         }
3365         // add one more blank field set for new object
3366         $form['text'.$i]            = '';
3367         $form['imagename'.$i]       = '';
3368         $form['imagecomponent'.$i]  = '';
3369         $form['altidentifier'.$i]   = '';
3370         $form['altcomponent'.$i]    = '';
3372         return $form;
3373     }
3375     /**
3376      * Converts the data from admin settings form into an array of emoticon objects
3377      *
3378      * @see self::prepare_form_data()
3379      * @param array $data array of admin form fields and values
3380      * @return false|array of emoticon objects
3381      */
3382     protected function process_form_data(array $form) {
3384         $count = count($form); // number of form field values
3386         if ($count % 5) {
3387             // we must get five fields per emoticon object
3388             return false;
3389         }
3391         $emoticons = array();
3392         for ($i = 0; $i < $count / 5; $i++) {
3393             $emoticon                   = new stdClass();
3394             $emoticon->text             = clean_param(trim($form['text'.$i]), PARAM_NOTAGS);
3395             $emoticon->imagename        = clean_param(trim($form['imagename'.$i]), PARAM_PATH);
3396             $emoticon->imagecomponent   = clean_param(trim($form['imagecomponent'.$i]), PARAM_SAFEDIR);
3397             $emoticon->altidentifier    = clean_param(trim($form['altidentifier'.$i]), PARAM_STRINGID);
3398             $emoticon->altcomponent     = clean_param(trim($form['altcomponent'.$i]), PARAM_SAFEDIR);
3400             if (strpos($emoticon->text, ':/') !== false or strpos($emoticon->text, '//') !== false) {
3401                 // prevent from breaking http://url.addresses by accident
3402                 $emoticon->text = '';
3403             }
3405             if (strlen($emoticon->text) < 2) {
3406                 // do not allow single character emoticons
3407                 $emoticon->text = '';
3408             }
3410             if (preg_match('/^[a-zA-Z]+[a-zA-Z0-9]*$/', $emoticon->text)) {
3411                 // emoticon text must contain some non-alphanumeric character to prevent
3412                 // breaking HTML tags
3413                 $emoticon->text = '';
3414             }
3416             if ($emoticon->text !== '' and $emoticon->imagename !== '' and $emoticon->imagecomponent !== '') {
3417                 $emoticons[] = $emoticon;
3418             }
3419         }
3420         return $emoticons;
3421     }
3424 /**
3425  * Special setting for limiting of the list of available languages.
3426  *
3427  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3428  */
3429 class admin_setting_langlist extends admin_setting_configtext {
3430 /**
3431  * Calls parent::__construct with specific arguments
3432  */
3433     public function __construct() {
3434         parent::__construct('langlist', get_string('langlist', 'admin'), get_string('configlanglist', 'admin'), '', PARAM_NOTAGS);
3435     }
3437     /**
3438      * Save the new setting
3439      *
3440      * @param string $data The new setting
3441      * @return bool
3442      */
3443     public function write_setting($data) {
3444         $return = parent::write_setting($data);
3445         get_string_manager()->reset_caches();
3446         return $return;
3447     }
3450 /**
3451  * Selection of one of the recognised countries using the list
3452  * returned by {@link get_list_of_countries()}.
3453  *
3454  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3455  */
3456 class admin_settings_country_select extends admin_setting_configselect {
3457     protected $includeall;
3458     public function __construct($name, $visiblename, $description, $defaultsetting, $includeall=false) {
3459         $this->includeall = $includeall;
3460         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
3461     }
3463     /**
3464      * Lazy-load the available choices for the select box
3465      */
3466     public function load_choices() {
3467         global $CFG;
3468         if (is_array($this->choices)) {
3469             return true;
3470         }
3471         $this->choices = array_merge(
3472                 array('0' => get_string('choosedots')),
3473                 get_string_manager()->get_list_of_countries($this->includeall));
3474         return true;
3475     }
3478 /**
3479  * Course category selection
3480  *
3481  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3482  */
3483 class admin_settings_coursecat_select extends admin_setting_configselect {
3484 /**
3485  * Calls parent::__construct with specific arguments
3486  */
3487     public function __construct($name, $visiblename, $description, $defaultsetting) {
3488         parent::__construct($name, $visiblename, $description, $defaultsetting, NULL);
3489     }
3491     /**
3492      * Load the available choices for the select box
3493      *
3494      * @return bool
3495      */
3496     public function load_choices() {
3497         global $CFG;
3498         require_once($CFG->dirroot.'/course/lib.php');
3499         if (is_array($this->choices)) {
3500             return true;
3501         }
3502         $this->choices = make_categories_options();
3503         return true;
3504     }
3507 /**
3508  * Special control for selecting days to backup
3509  *
3510  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3511  */
3512 class admin_setting_special_backupdays extends admin_setting_configmulticheckbox2 {
3513 /**
3514  * Calls parent::__construct with specific arguments
3515  */
3516     public function __construct() {
3517         parent::__construct('backup_sche_weekdays', get_string('schedule'), get_string('backupschedulehelp'), array(), NULL);
3518         $this->plugin = 'backup';
3519     }
3520     /**
3521      * Load the available choices for the select box
3522      *
3523      * @return bool Always returns true
3524      */
3525     public function load_choices() {
3526         if (is_array($this->choices)) {
3527             return true;
3528         }
3529         $this->choices = array();
3530         $days = array('sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday');
3531         foreach ($days as $day) {
3532             $this->choices[$day] = get_string($day, 'calendar');
3533         }
3534         return true;
3535     }
3538 /**
3539  * Special debug setting
3540  *
3541  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3542  */
3543 class admin_setting_special_debug extends admin_setting_configselect {
3544 /**
3545  * Calls parent::__construct with specific arguments
3546  */
3547     public function __construct() {
3548         parent::__construct('debug', get_string('debug', 'admin'), get_string('configdebug', 'admin'), DEBUG_NONE, NULL);
3549     }
3551     /**
3552      * Load the available choices for the select box
3553      *
3554      * @return bool
3555      */
3556     public function load_choices() {
3557         if (is_array($this->choices)) {
3558             return true;
3559         }
3560         $this->choices = array(DEBUG_NONE      => get_string('debugnone', 'admin'),
3561             DEBUG_MINIMAL   => get_string('debugminimal', 'admin'),
3562             DEBUG_NORMAL    => get_string('debugnormal', 'admin'),
3563             DEBUG_ALL       => get_string('debugall', 'admin'),
3564             DEBUG_DEVELOPER => get_string('debugdeveloper', 'admin'));
3565         return true;
3566     }
3569 /**
3570  * Special admin control
3571  *
3572  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3573  */
3574 class admin_setting_special_calendar_weekend extends admin_setting {
3575 /**
3576  * Calls parent::__construct with specific arguments
3577  */
3578     public function __construct() {
3579         $name = 'calendar_weekend';
3580         $visiblename = get_string('calendar_weekend', 'admin');
3581         $description = get_string('helpweekenddays', 'admin');
3582         $default = array ('0', '6'); // Saturdays and Sundays
3583         parent::__construct($name, $visiblename, $description, $default);
3584     }
3585     /**
3586      * Gets the current settings as an array
3587      *
3588      * @return mixed Null if none, else array of settings
3589      */
3590     public function get_setting() {
3591         $result = $this->config_read($this->name);
3592         if (is_null($result)) {
3593             return NULL;
3594         }
3595         if ($result === '') {
3596             return array();
3597         }
3598         $settings = array();
3599         for ($i=0; $i<7; $i++) {
3600             if ($result & (1 << $i)) {
3601                 $settings[] = $i;
3602             }
3603         }
3604         return $settings;
3605     }
3607     /**
3608      * Save the new settings
3609      *
3610      * @param array $data Array of new settings
3611      * @return bool
3612      */
3613     public function write_setting($data) {
3614         if (!is_array($data)) {
3615             return '';
3616         }
3617         unset($data['xxxxx']);
3618         $result = 0;
3619         foreach($data as $index) {
3620             $result |= 1 << $index;
3621         }
3622         return ($this->config_write($this->name, $result) ? '' : get_string('errorsetting', 'admin'));
3623     }
3625     /**
3626      * Return XHTML to display the control
3627      *
3628      * @param array $data array of selected days
3629      * @param string $query
3630      * @return string XHTML for display (field + wrapping div(s)
3631      */
3632     public function output_html($data, $query='') {
3633     // The order matters very much because of the implied numeric keys
3634         $days = array('sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday');
3635         $return = '<table><thead><tr>';
3636         $return .= '<input type="hidden" name="'.$this->get_full_name().'[xxxxx]" value="1" />'; // something must be submitted even if nothing selected
3637         foreach($days as $index => $day) {
3638             $return .= '<td><label for="'.$this->get_id().$index.'">'.get_string($day, 'calendar').'</label></td>';
3639         }
3640         $return .= '</tr></thead><tbody><tr>';
3641         foreach($days as $index => $day) {
3642             $return .= '<td><input type="checkbox" class="form-checkbox" id="'.$this->get_id().$index.'" name="'.$this->get_full_name().'[]" value="'.$index.'" '.(in_array("$index", $data) ? 'checked="checked"' : '').' /></td>';
3643         }
3644         $return .= '</tr></tbody></table>';
3646         return format_admin_setting($this, $this->visiblename, $return, $this->description, false, '', NULL, $query);
3648     }
3652 /**
3653  * Admin setting that allows a user to pick appropriate roles for something.
3654  *
3655  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
3656  */
3657 class admin_setting_pickroles extends admin_setting_configmulticheckbox {
3658 /** @var array Array of capabilities which identify roles */
3659     private $types;
3661     /**
3662      * @param string $name Name of config variable
3663      * @param string $visiblename Display name
3664      * @param string $description Description
3665      * @param array $types Array of archetypes which identify
3666      *              roles that will be enabled by default.
3667      */
3668     public function __construct($name, $visiblename, $description, $types) {
3669         parent::__construct($name, $visiblename, $description, NULL, NULL);
3670         $this->types = $types;
3671     }
3673     /**
3674      * Load roles as choices
3675      *
3676      * @return bool true=>success, false=>error
3677      */
3678     public function load_choices() {
3679         global $CFG, $DB;
3680         if (during_initial_install()) {
3681             return false;
3682         }
3683         if (is_array($this->choices)) {
3684             return true;
3685         }
3686         if ($roles = get_all_roles()) {
3687             $this->choices = array();
3688             foreach($roles as $role) {