Settings
Creating an admin section
Each Nextcloud application can provide both personal and admin settings. For this you will need to create a section implementing IIconSection. This section will be used in the setting sidebar to create a new entry.
In our case we will create an admin section class in <myapp>/lib/Sections/NotesAdmin.php:
<?php
namespace OCA\NotesTutorial\Sections;
use OCP\IL10N;
use OCP\IURLGenerator;
use OCP\Settings\IIconSection;
class NotesAdmin implements IIconSection {
private IL10N $l;
private IURLGenerator $urlGenerator;
public function __construct(IL10N $l, IURLGenerator $urlGenerator) {
$this->l = $l;
$this->urlGenerator = $urlGenerator;
}
public function getIcon(): string {
return $this->urlGenerator->imagePath('core', 'actions/settings-dark.svg');
}
public function getID(): string {
return 'notes';
}
public function getName(): string {
return $this->l->t('Notes tutorial');
}
public function getPriority(): int {
return 98;
}
}
The next step is to fill the new admin section with an admin setting. For that,
we create a new class in <myapp>/lib/Settings/NotesAdmin.php.
<?php
namespace OCA\NotesTutorial\Settings;
use OCP\AppFramework\Http\TemplateResponse;
use OCP\IConfig;
use OCP\IL10N;
use OCP\Settings\ISettings;
class NotesAdmin implements ISettings {
private IL10N $l;
private IConfig $config;
public function __construct(IConfig $config, IL10N $l) {
$this->config = $config;
$this->l = $l;
}
/**
* @return TemplateResponse
*/
public function getForm() {
$parameters = [
'mySetting' => $this->config->getSystemValue('my_notes_setting', true),
];
return new TemplateResponse('settings', 'settings/admin', $parameters, '');
}
public function getSection() {
return 'notes'; // Name of the previously created section.
}
/**
* @return int whether the form should be rather on the top or bottom of
* the admin section. The forms are arranged in ascending order of the
* priority values. It is required to return a value between 0 and 100.
*
* E.g.: 70
*/
public function getPriority() {
return 10;
}
}
The last missing part is to register both classes inside <myapp>/appinfo/info.xml.
<settings>
<admin>OCA\NotesTutorial\Settings\NotesAdmin</admin>
<admin-section>OCA\NotesTutorial\Sections\NotesAdmin</admin-section>
</settings>
Note
To register personal sections and settings class use <personal-section> and <personal> instead.
Delegated administration
Added in version 23.
Nextcloud has built-in functionality which permits administrators to delegate authority
to others without granting them full administration privileges (and without making them a
member of the admin group).
Specific groups can be granted authorization to access individual admin settings. This is a
feature that needs to be enabled for each admin setting class. To do so, the setting class
needs to implement IDelegatedSettings instead of ISettings and implement two additional
methods.
Using the application ID
The app name can be referenced through Application::APP_ID. This avoids duplicating
the app ID as a string:
use OCA\NotesTutorial\AppInfo\Application;
public function getAuthorizedAppConfig(): array {
return [
// Multiple keys: authorize several exact keys in this app.
Application::APP_ID => [
'my_notes_setting',
'another_notes_setting',
],
];
}
Escaping dynamic regular expressions
When a regular expression is built from a variable or a constant, escape the inserted
value with preg_quote():
$prefix = preg_quote('notes_', '/');
return [
Application::APP_ID => [
"/^{$prefix}[a-z0-9_]+$/",
],
];
Using configuration constants
For stable, declared configuration keys, prefer dedicated constants or constants from an
app’s ConfigLexicon class. This keeps the delegated authorization list synchronized
with the app’s configuration definitions.
For example, <myapp>/lib/ConfigLexicon.php might contain:
<?php
namespace OCA\NotesTutorial;
class ConfigLexicon {
// For PHP versions before 8.3, omit the "string" type.
public const string MY_SETTING = 'my_notes_setting';
public const string ANOTHER_SETTING = 'another_notes_setting';
}
Which can then reference:
use OCA\NotesTutorial\AppInfo\Application;
use OCA\NotesTutorial\ConfigLexicon;
public function getAuthorizedAppConfig(): array {
return [
// Constants: Preferred for stable, declared configuration keys.
Application::APP_ID => [
ConfigLexicon::MY_SETTING,
ConfigLexicon::ANOTHER_SETTING,
],
];
}