From b83a86ef184523c5de96734c5151207762e69365 Mon Sep 17 00:00:00 2001
From: Carl Schwan <carl@carlschwan.eu>
Date: Mon, 11 Oct 2021 11:50:09 +0200
Subject: [PATCH] Add setting section in the app developement tutorial

Fix #7158

Signed-off-by: Carl Schwan <carl@carlschwan.eu>
---
 developer_manual/app_development/tutorial.rst |   2 +
 developer_manual/basics/index.rst             |   1 +
 developer_manual/basics/setting.rst           | 178 ++++++++++++++++++
 3 files changed, 181 insertions(+)
 create mode 100644 developer_manual/basics/setting.rst

diff --git a/developer_manual/app_development/tutorial.rst b/developer_manual/app_development/tutorial.rst
index c87f5f864..29afd385e 100644
--- a/developer_manual/app_development/tutorial.rst
+++ b/developer_manual/app_development/tutorial.rst
@@ -934,6 +934,8 @@ To run the integration tests change into the **notestutorial** directory and run
 
     phpunit -c phpunit.integration.xml
 
+
+
 Adding a RESTful API (optional)
 -------------------------------
 
diff --git a/developer_manual/basics/index.rst b/developer_manual/basics/index.rst
index ad99a2ac3..c96c3588d 100644
--- a/developer_manual/basics/index.rst
+++ b/developer_manual/basics/index.rst
@@ -14,5 +14,6 @@ Basic concepts
    front-end/index
    backgroundjobs
    logging
+   setting
    storage/index
    testing
diff --git a/developer_manual/basics/setting.rst b/developer_manual/basics/setting.rst
new file mode 100644
index 000000000..7533ffd81
--- /dev/null
+++ b/developer_manual/basics/setting.rst
@@ -0,0 +1,178 @@
+========
+Settings
+========
+
+.. sectionauthor:: Carl Schwan <carl@carlschwan.eu>
+
+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**:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\NotesTutorial\Sections;
+
+    use OCP\IL10N;
+    use OCP\IURLGenerator;
+    use OCP\Settings\IIconSection;
+
+    class NotesAdmin extends IIconSection {
+
+        /** @var IL10N */
+        private $l;
+ 
+        /** @var IURLGenerator */
+        private $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**.
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\NotesTutorial\Settings;
+
+    use OCP\AppFramework\Http\TemplateResponse;
+    use OCP\IConfig;
+    use OCP\IL10N;
+    use OCP\Settings\ISettings;
+
+    class NotesAdmin extends ISettings {
+
+        /** @var IL10N */
+        private $l;
+ 
+        /** @var IURLGenerator */
+        private $urlGenerator;
+
+        /** @var IConfig */
+        private $config;
+
+        /** @var IL10N $l*/
+        private $l;
+
+        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**.
+
+.. code-block:: 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 <https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/admin_delegation_configuration>`_).
+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.
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\NotesTutorial\Settings;
+
+    use OCP\AppFramework\Http\TemplateResponse;
+    use OCP\IConfig;
+    use OCP\IL10N;
+    use OCP\Settings\IDelegatedSettings;
+
+    class NotesAdmin extends 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.
+
+.. code-block:: php
+
+    <?php
+    class NotesSettingsController extends Controller {
+        /**
+         * Save settings
+         * @PasswordConfirmationRequired
+         * @AuthorizedAdminSetting(settings=OCA\NotesTutorial\Settings\NotesAdmin)
+         */
+         public function saveSettings($mySetting) {
+             ....
+         }
+         ...
+    }
+