Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Admin settings

From MoodleDocs
Revision as of 21:36, 9 November 2012 by Avindra Goolcharan (talk | contribs) (syntax highlighting)

Moodle's configuration is stored in a mixture of the config, config_plugins, and a few other tables. These settings are edited through the administration screens, which can be accessed by going to the .../admin/index.php URL on your moodle site, or using the Administration block that appears to administrators of the Moodle front page. This page explains how the code for displaying and editing of these settings works.

Where to find the code

This is explained further below, but in summary:

  • The library code is all in lib/adminlib.php.
  • The definition of the all the parts of the admin tree is in admin/settings/* some of which call out to plugins to see if they have settings they want to add.
  • The editing and saving of settings is managed by admin/settings.php, admin/upgradesettings.php, and admin/search.php.
  • The administration blocks that appear on the front page and on most of the admin screens is in blocks/admin_tree and blocks/admin_bookmarks.

In my experience most of this code is pretty easy to understand and work with, so here I will focus on giving an overview. For details, see the code.

The building blocks

All the settings are arranged into a tree structure. This tree structure is represented in memory as a tree of PHP objects.

At the root of the tree is an admin_root object.

That has children that are admin_categorys.

Admin categories contain other categories, admin_settingpages, and admin_externalpages.

Settings pages contain individual admin_settings.

admin_setting is a base class with lots of subclasses like admin_setting_configtext, admin_setting_configcheckbox, and so on. If you need to, you can create new subclasses.

External pages are for things that do not fit into the normal settings structure. For example the global assign roles page, or the page for managing activity modules.

How the tree is built

When Moodle needs the admin tree, it calls admin_get_root in lib/adminlib.php, which

  1. creates a global $ADMIN object which is an instance of admin_root.
  2. does require_once admin/settings/top.php, which adds the top level categories to $ADMIN.
  3. does require_once on all the other files in admin/settings to add more specific settings pages and the settings themselves. Some of these settings files additionally make calls out to various types of plugins. For example
    • admin/settings/plugins.php gives activity modules, blocks, question types, ... a chance to add admin settings.
  4. adds the admin reports to the tree.

As an optimisation, before building each bit of the tree, some capability checks are performed, and bits of the tree are skipped if the current user does not have permission to access them.

Exactly how different types of plugin should add their settings to the tree should be documented in the instructions for writing that sort of plugin.

Individual settings

Let us look at a simple example: mod/forum/settings.php. This is included by admin/settings/plugins.php, which has already created $settings, which is an admin_settingpage that we can add to. The file contains lots of lines that look a bit like:

$settings->add(new admin_setting_configcheckbox('forum_replytouser', get_string('replytouser', 'forum'),
                   get_string('replytouser_desc', 'forum'), 1));

What this means is that to our settings page, we are adding a checkbox setting. To understand this in more detail, we need to know what arguments the constructor for an admin_setting takes. The definition of the constructor is:

function admin_setting($name, $visiblename, $description, $defaultsetting) {

So, $name here is 'forum_replytouser'. This means that this setting is stored in the database in the row of the config table where name='forum_replytouser', and is accessible as $CFG->forum_replytouser.

$visiblename is get_string('replytouser', 'forum'), this is the label that is put in front of setting on the admin screen.

$description is get_string('replytouser_desc', 'forum'), this is a short bit of text displayed underneath the setting to explain it further.

$defaultsetting is the default value for this setting. This value is used when Moodle is installed. For simple settings like checkboxes and text fields, this is a simple value. For some more complicated settings, this is an array.

Let as now look at a more complicated example, from mod/quiz/settingstree.php:

$quizsettings->add(new admin_setting_text_with_advanced('quiz/timelimit',
        get_string('timelimit', 'quiz'), get_string('timelimit_desc', 'quiz'),
        array('value' => '0', 'fix' => false), PARAM_INT));

This shows two new things:

$name here is 'quiz/timelimit'. This is more complicated than a simple setting name. It means that this setting is stored in the config_plugins table, in the row where plugin='quiz' and name='timelimit'. It is not accessible through $CFG, to get it you can use get_config('quiz', 'timelimit').

And this example shows a $defaultsetting that is an array.

Normally, if you want a particular sort of setting, the easiest way is to look around the admin screens of your Moodle site, and find a setting like the one you want. Then go and copy the code and edit it. Therefore, we do not include a complete list of setting types here.

External pages

admin_externalpages represent screens of settings that do not fall into the standard pattern of admin_settings. The admin_externalpage object in the settings tree holds the URL of a PHP page that controls various settings.

In that PHP page, near the start you need to call the function admin_externalpage_setup($pagename), then, instead of the usual print_header and print_footer functions, you use admin_externalpage_print_header() and admin_externalpage_print_footer() functions. This ensures that your page appears with the administration blocks and appropriate navigation.

Note that if your external page relies on additional optional or required params, you may need to use the optional arguments to admin_externalpage_print_header to ensure that the Blocks editing on/off button works.

Note that there are some subclasses of admin_externalpage, for example admin_page_managemods. In a lot of cases, these subclasses only exist to override the search method so this page can be found by appropriate searches.

Once again, to understand this in more depth, your best approach is to look at how some of the external pages in Moodle work.

See also