Skip to content

Commit

Permalink
[docs] check: add new admin setting docs
Browse files Browse the repository at this point in the history
New features as part of MDL-67898
  • Loading branch information
matthewhilton committed Sep 29, 2023
1 parent df2a305 commit 56198f7
Showing 1 changed file with 57 additions and 0 deletions.
57 changes: 57 additions & 0 deletions docs/apis/subsystems/check/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,63 @@ https://github.com/moodle/moodle/blob/master/lib/classes/check/access/riskxss_re

Some checks are by their nature asynchronous. For instance having moodle send an email to itself and then having it processed by the inbound mail handler to make it's properly configured (see [MDL-48800](https://tracker.moodle.org/browse/MDL-48800)). In cases like these please make sure the age or staleness of the check is shown in the summary, and you should also consider turning the result status into a warning if the result is too old. If appropriate make the threshold a configurable admin setting.

## Showing checks in admin settings

Even though checks will appear in the corresponding report pages, it may be useful to have these show up in admin settings close to where they may be actioned. For example, showing a LDAP connection check on the same page as the LDAP connection settings.

Use the `admin_setting_check` class to easily add these.

```php title="mod/myplugin/settings.php"
$settings->add(new admin_setting_check('myplugin/usefulcheck', new \mod\myplugin\check\usefulcheck()));

// Or with multiple instances of checks
$settings->add(new admin_setting_check('myplugin/usefulcheck1', new \mod\myplugin\check\usefulcheck(1)));
$settings->add(new admin_setting_check('myplugin/usefulcheck2', new \mod\myplugin\check\usefulcheck(2)));
```

The results of the check are fetched asynchronously using Ajax, so the page loading time is impacted as little as possible.

### Utilising as a plugin configuration check

Internally, the `admin_setting_check` class calls a webservice that will load the admin tree to find the check object it is linked to. Therefore it is possible to include checks here that are not included in your plugin's lib.php callback, or pass flags to your checks to change how they behave.

For example, a check might look like the following:

```php title="mod/myplugin/classes/connectioncheck.php"
class connectioncheck extends check {

private $isprecheck;

public function __construct($isprecheck = false) {
$this->isprecheck = $isprecheck;
}

public function get_result(): result {
$enabled = get_config(...);

if ($enabled || $this->isprecheck) {
return new foobar_result();
}

return na_result();
}
}
```

The lib.php callback will pass `$isprecheck = false`, so it reports N/A if the plugin is disabled in the status reports.
```php title="mod/myplugin/lib.php"
function mod_myplugin_status_checks() {
return [new connection_check(false)];
}
```

But when viewed in the admin settings, `$isprecheck = true` is passed so the check runs regardless of the plugin being enabled.
```php title="mod/myplugin/settings.php"
$settings->add(new admin_setting_check('myplugin/usefulcheck', new \mod\myplugin\check\connectioncheck(true)));
```

Users can use this to confirm they have plugin settings (such as connection details or API tokens) correct before enabling the plugin.

## See also

- [Performance overview](https://docs.moodle.org/en/Performance_overview) user docs

0 comments on commit 56198f7

Please sign in to comment.