Settings

Each Nextcloud applications 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 steps is to fill the new admin section with am 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.

Additionally since Nextcloud 23, groups can be granted authorization to access individual admin settings (see admin docs). 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.

<?php
namespace OCA\NotesTutorial\Settings;

use OCP\AppFramework\Http\TemplateResponse;
use OCP\IConfig;
use OCP\IL10N;
use OCP\Settings\IDelegatedSettings;

class NotesAdmin implements IDelegatedSettings {

    ...

    public function getName(): ?string {
        // This can also return an empty string in case there is only one setting
        // in the section.
        return $this->l->t('Notes Admin Settings');
    }

    public function getAuthorizedAppConfig(): array {
        return [
            // Allow list of regex that the user can modify with this setting.
            'notes' => ['/notes_.*/', '/my_notes_setting/'],
        ];
    }
}

Additionally, if your setting class needs to fetch data or send data to some admin-only controllers, you will need to mark the methods in the controller as accessible by the setting with annotations.

<?php
class NotesSettingsController extends Controller {
    /**
     * Save settings
     * @PasswordConfirmationRequired
     * @AuthorizedAdminSetting(settings=OCA\NotesTutorial\Settings\NotesAdmin)
     */
     public function saveSettings($mySetting) {
         ....
     }
     ...
}

If you have several classes that implement IDelegatedSettings for a function. You must add them in the key “settings” and they must seperate with semi-colons.

<?php
class NotesSettingsController extends Controller {
    /**
     * Save settings
     * @PasswordConfirmationRequired
     * @AuthorizedAdminSetting(settings=OCA\NotesTutorial\Settings\NotesAdmin;OCA\NotesTutorial\Settings\NotesSubAdmin)
     */
     public function saveSettings($mySetting) {
         ....
     }
     ...
}