From 0c74a2ec50606ba607a56b36ed174aa04afcf6a7 Mon Sep 17 00:00:00 2001
From: Arthur Schiwon <blizzz@arthur-schiwon.de>
Date: Wed, 17 Aug 2016 16:23:17 +0200
Subject: [PATCH] add Settings doc

---
 developer_manual/app/index.rst    |   1 +
 developer_manual/app/info.rst     |  20 +++
 developer_manual/app/settings.rst | 277 ++++++++++++++++++++++++++++++
 3 files changed, 298 insertions(+)
 create mode 100644 developer_manual/app/settings.rst

diff --git a/developer_manual/app/index.rst b/developer_manual/app/index.rst
index b7cad020c..500ecb77b 100644
--- a/developer_manual/app/index.rst
+++ b/developer_manual/app/index.rst
@@ -32,6 +32,7 @@
    two-factor-provider
    hooks
    backgroundjobs
+   settings
    logging
    testing
    publishing
diff --git a/developer_manual/app/info.rst b/developer_manual/app/info.rst
index 3769c4f3f..eebb1aefa 100644
--- a/developer_manual/app/info.rst
+++ b/developer_manual/app/info.rst
@@ -51,6 +51,11 @@ The :file:`appinfo/info.xml` contains metadata about the app:
           <os>Linux</os>
           <owncloud min-version="6.0.4" max-version="8"/>
       </dependencies>
+      
+      <settings>
+          <admin-section>OCA\YourAppsNamespace\Settings\AdminSection</admin-section>
+          <admin>OCA\YourAppsNamespace\Settings\AdminSettings</admin>
+      </setting>
 
       <!-- deprecated, just for reference -->
       <requiremin>5</requiremin>
@@ -187,7 +192,22 @@ owncloud
           * ownCloud 9.1 matches Nextcloud 10
           * ownCloud 9.2 matches Nextcloud 11
 
+settings
+--------
 
+When your app has admin settings, this is the place to register the corresponding classes.
+
+admin-section
+=============
+
+In case the app needs to register a new section on the admin settings page, it needs to implement the \OCP\Settings\ISection interface. The implementing class needs to be specified here.
+
+admin
+=====
+
+In case the app has its own admin related settings, it needs to implement the \OCP\Settings\ISettings interface. The implementing class needs to be specified here.
+          
+          
 Deprecated
 ----------
 
diff --git a/developer_manual/app/settings.rst b/developer_manual/app/settings.rst
new file mode 100644
index 000000000..96a06ed42
--- /dev/null
+++ b/developer_manual/app/settings.rst
@@ -0,0 +1,277 @@
+========
+Settings
+========
+
+.. sectionauthor:: Arthur Schiwon <blizzz@arthur-schiwon.de>
+
+An app can register both admin settings as well as personal settings.
+
+Admin
+-----
+
+For Nextcloud 10 the admin settings page got reworked. It is not a long list
+anymore, but divided into sections, where related settings forms are grouped.
+For example, in the **Sharing** section are only settings (built-in and of apps)
+relate to sharing.
+
+Settings Form
+=============
+
+For the settings form, three things are necessary
+
+1. A class implementing ``\OCP\Settings\ISettings``
+2. A template
+3. The implementing class specified in the apps`s info.xml
+
+Below is an example for an implementor of the ISettings interface. It is based
+on the survey_client solution.
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\YourAppNamespace\Settings;
+
+    use OCA\YourAppNamespace\Collector;
+    use OCP\AppFramework\Http\TemplateResponse;
+    use OCP\BackgroundJob\IJobList;
+    use OCP\IConfig;
+    use OCP\IDateTimeFormatter;
+    use OCP\IL10N;
+    use OCP\Settings\ISettings;
+
+    class AdminSettings implements ISettings {
+
+            /** @var Collector */
+            private $collector;
+
+            /** @var IConfig */
+            private $config;
+
+            /** @var IL10N */
+            private $l;
+
+            /** @var IDateTimeFormatter */
+            private $dateTimeFormatter;
+
+            /** @var IJobList */
+            private $jobList;
+
+            /**
+             * Admin constructor.
+             *
+             * @param Collector $collector
+             * @param IConfig $config
+             * @param IL10N $l
+             * @param IDateTimeFormatter $dateTimeFormatter
+             * @param IJobList $jobList
+             */
+            public function __construct(Collector $collector,
+                                                                    IConfig $config,
+                                                                    IL10N $l,
+                                                                    IDateTimeFormatter $dateTimeFormatter,
+                                                                    IJobList $jobList
+            ) {
+                    $this->collector = $collector;
+                    $this->config = $config;
+                    $this->l = $l;
+                    $this->dateTimeFormatter = $dateTimeFormatter;
+                    $this->jobList = $jobList;
+            }
+
+            /**
+             * @return TemplateResponse
+             */
+            public function getForm() {
+
+                    $lastSentReportTime = (int) $this->config->getAppValue('survey_client', 'last_sent', 0);
+                    if ($lastSentReportTime === 0) {
+                            $lastSentReportDate = $this->l->t('Never');
+                    } else {
+                            $lastSentReportDate = $this->dateTimeFormatter->formatDate($lastSentReportTime);
+                    }
+
+                    $lastReport = $this->config->getAppValue('survey_client', 'last_report', '');
+                    if ($lastReport !== '') {
+                            $lastReport = json_encode(json_decode($lastReport, true), JSON_PRETTY_PRINT);
+                    }
+
+                    $parameters = [
+                            'is_enabled' => $this->jobList->has('OCA\Survey_Client\BackgroundJobs\MonthlyReport', null),
+                            'last_sent' => $lastSentReportDate,
+                            'last_report' => $lastReport,
+                            'categories' => $this->collector->getCategories()
+                    ];
+
+                    return new TemplateResponse('yourappid', 'admin', $parameters);
+            }
+
+            /**
+             * @return string the section ID, e.g. 'sharing'
+             */
+            public function getSection() {
+                    return 'survey_client';
+            }
+
+            /**
+             * @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.
+             */
+            public function getPriority() {
+                    return 50;
+            }
+
+    }
+
+The parameters of the constructor will be resolved and an instance created
+automatically on demand, so that the developer does not need to take care of it.
+
+``getSection`` is supposed to return the section ID of the desired admin section.
+Currently, built-in values are ``server``, ``sharing``, ``encryption``,
+``logging``, ``additional`` and ``tips-tricks``. Apps can register sections
+of their own (see below), and also register into sections of other apps.
+
+``getPriority`` is used to order forms within a section. The lower the value,
+the more on top it will appear, and vice versa. The result depends on the
+priorities of other settings.
+
+Nextcloud will look for the templates in a template folder located in your apps
+root directory. It should always end on .php, in this case ``templates/admin.php``
+would be the final relative path.
+
+.. code-block:: php
+
+    <?php
+    /** @var $l \OCP\IL10N */
+    /** @var $_ array */
+
+    script('myappid', 'admin');         // adds a Javascript file
+    style('survey_client', 'admin');    // adds a CSS file
+    ?>
+
+    <div id="survey_client" class="section">
+            <h2><?php p($l->t('Your app')); ?></h2>
+
+            <p>
+                    <?php p($l->t('Only administrators are allowed to click the red button')); ?>
+            </p>
+
+            <button><?php p($l->t('Click red button')); ?></button>
+
+            <p>
+                    <input id="your_app_magic" name="your_app_magic"
+                               type="checkbox" class="checkbox" value="1" <?php if ($_['is_enabled']): ?> checked="checked"<?php endif; ?> />
+                    <label for="your_app_magic"><?php p($l->t('Do some magic')); ?></label>
+            </p>
+
+            <h3><?php p($l->t('Things to define')); ?></h3>
+            <?php
+            foreach ($_['categories'] as $category => $data) {
+                    ?>
+                    <p>
+                            <input id="your_app_<?php p($category); ?>" name="your_app_<?php p($category); ?>"
+                                       type="checkbox" class="checkbox your_app_category" value="1" <?php if ($data['enabled']): ?> checked="checked"<?php endif; ?> />
+                            <label for="your_app_<?php p($category); ?>"><?php print_unescaped($data['displayName']); ?></label>
+                    </p>
+                    <?php
+            }
+            ?>
+
+            <?php if (!empty($_['last_report'])): ?>
+
+            <h3><?php p($l->t('Last report')); ?></h3>
+
+            <p><textarea title="<?php p($l->t('Last report')); ?>" class="last_report" readonly="readonly"><?php p($_['last_report']);?></textarea></p>
+
+            <em class="last_sent"><?php p($l->t('Sent on: %s', [$_['last_sent']])); ?></em>
+
+            <?php endif; ?>
+
+    </div>
+
+Then, the implementing class should be added to the info.xml. Settings will be
+registered upon install and update. When settings are added to an existing,
+installed and enabled app, it should be made sure that the version is
+increased so Nextcloud can register the class. It is only possible to register
+one ISettings implementor.
+
+For a more complex example using embedded templates have a look at the
+implementation of the **user_ldap** app.
+
+
+Section
+=======
+
+It is also possible, that an app registers its own section. This should be done
+only, if there is not fitting corresponding section and the apps settings form
+takes a lot of screen estate. Otherwise, register to "additional".
+
+Basically, it works the same way as with the settings form. There are only two
+differences. First, the interface that must be implemented is ``\OCP\Settings\ISection``.
+
+Second, a template is not necessary.
+
+An example implementation of the ISection interface:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\YourAppNamespace\Settings;
+
+    use OCP\IL10N;
+    use OCP\Settings\ISection;
+
+    class AdminSection implements ISection {
+
+            /** @var IL10N */
+            private $l;
+
+            public function __construct(IL10N $l) {
+                    $this->l = $l;
+            }
+
+            /**
+             * returns the ID of the section. It is supposed to be a lower case string
+             *
+             * @returns string
+             */
+            public function getID() {
+                    return 'yourappid'; //or a generic id if feasible
+            }
+
+            /**
+             * returns the translated name as it should be displayed, e.g. 'LDAP / AD
+             * integration'. Use the L10N service to translate it.
+             *
+             * @return string
+             */
+            public function getName() {
+                    return $this->l->t('Translatable Section Name');
+            }
+
+            /**
+             * @return int whether the form should be rather on the top or bottom of
+             * the settings navigation. The sections are arranged in ascending order of
+             * the priority values. It is required to return a value between 0 and 99.
+             */
+            public function getPriority() {
+                    return 80;
+            }
+
+    }
+
+Also the section must be registered in the apps`s info.xml.
+
+Personal
+--------
+
+Registering personal settings follows and old style yet. Within the app
+intialisation (e.g. in appinfo/app.php) a method must be called:
+
+.. code-block:: php
+
+    <?php
+    \OCP\App::registerPersonal('yourappid', 'personal');
+
+Upon opening the personal page, Nextcloud will look for ``personal.php`` script,
+execute it and print the output.