Settings

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 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 a 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 attribute.

Note

The attribute is only available in Nextcloud 27 or later. In older versions, the @AuthorizedAdminSetting(settings=OCA\NotesTutorial\Settings\NotesAdmin) annotation can be used.

<?php
use OCP\AppFramework\Http\Attribute\AuthorizedAdminSetting;
class NotesSettingsController extends Controller {
    /**
     * Save settings
     */
    #[PasswordConfirmationRequired]
    #[AuthorizedAdminSetting(settings: 'OCA\NotesTutorial\Settings\NotesAdmin')]
    public function saveSettings($mySetting) {
        ....
    }
    ...
}

If you have several IDelegatedSettings classes that are needed for a function, simply add the annotation multiple times. them in the key “settings” and they must separate with semi-colons.

Note

If you use the deprecated annotation specify the classes separated by semicolons:

@AuthorizedAdminSetting(settings=OCA\NotesTutorial\Settings\NotesAdmin;OCA\NotesTutorial\Settings\NotesSubAdmin)

<?php
use OCP\AppFramework\Http\Attribute\AuthorizedAdminSetting;
class NotesSettingsController extends Controller {
    /**
     * Save settings
     */
    #[PasswordConfirmationRequired]
    #[AuthorizedAdminSetting(settings: 'OCA\NotesTutorial\Settings\NotesAdmin')]
    #[AuthorizedAdminSetting(settings: 'OCA\NotesTutorial\Settings\NotesSubAdmin')]
     public function saveSettings($mySetting) {
         ....
     }
     ...
}