Settings

An app can register both admin settings as well as personal settings. Settings are divided into sections to group similar settings together. For example, in the Sharing section are only settings (built-in and of apps) related to sharing.

Settings form

For the settings to show up, three things are necessary:

  1. A class implementing \OCP\Settings\ISettings
  2. A template
  3. The implementing class specified in the app’s info.xml

Below is an example for an implementor of the ISettings interface. It is based on the survey_client solution.

  1. <?php
  2. namespace OCA\YourAppNamespace\Settings;
  4. use OCA\YourAppNamespace\Collector;
  5. use OCP\AppFramework\Http\TemplateResponse;
  6. use OCP\BackgroundJob\IJobList;
  7. use OCP\IConfig;
  8. use OCP\IDateTimeFormatter;
  9. use OCP\IL10N;
  10. use OCP\Settings\ISettings;
  12. class AdminSettings implements ISettings {
  14.         /** @var Collector */
  15.         private $collector;
  17.         /** @var IConfig */
  18.         private $config;
  20.         /** @var IL10N */
  21.         private $l;
  23.         /** @var IDateTimeFormatter */
  24.         private $dateTimeFormatter;
  26.         /** @var IJobList */
  27.         private $jobList;
  29.         /**
  30.          * Admin constructor.
  31.          *
  32.          * @param Collector $collector
  33.          * @param IConfig $config
  34.          * @param IL10N $l
  35.          * @param IDateTimeFormatter $dateTimeFormatter
  36.          * @param IJobList $jobList
  37.          */
  38.         public function __construct(Collector $collector,
  39.                                                                 IConfig $config,
  40.                                                                 IL10N $l,
  41.                                                                 IDateTimeFormatter $dateTimeFormatter,
  42.                                                                 IJobList $jobList
  43.         ) {
  44.                 $this->collector = $collector;
  45.                 $this->config = $config;
  46.                 $this->l = $l;
  47.                 $this->dateTimeFormatter = $dateTimeFormatter;
  48.                 $this->jobList = $jobList;
  49.         }
  51.         /**
  52.          * @return TemplateResponse
  53.          */
  54.         public function getForm() {
  56.                 $lastSentReportTime = (int) $this->config->getAppValue('survey_client', 'last_sent', 0);
  57.                 if ($lastSentReportTime === 0) {
  58.                         $lastSentReportDate = $this->l->t('Never');
  59.                 } else {
  60.                         $lastSentReportDate = $this->dateTimeFormatter->formatDate($lastSentReportTime);
  61.                 }
  63.                 $lastReport = $this->config->getAppValue('survey_client', 'last_report', '');
  64.                 if ($lastReport !== '') {
  65.                         $lastReport = json_encode(json_decode($lastReport, true), JSON_PRETTY_PRINT);
  66.                 }
  68.                 $parameters = [
  69.                         'is_enabled' => $this->jobList->has('OCA\Survey_Client\BackgroundJobs\MonthlyReport', null),
  70.                         'last_sent' => $lastSentReportDate,
  71.                         'last_report' => $lastReport,
  72.                         'categories' => $this->collector->getCategories()
  73.                 ];
  75.                 return new TemplateResponse('yourappid', 'admin', $parameters);
  76.         }
  78.         /**
  79.          * @return string the section ID, e.g. 'sharing'
  80.          */
  81.         public function getSection() {
  82.                 return 'survey_client';
  83.         }
  85.         /**
  86.          * @return int whether the form should be rather on the top or bottom of
  87.          * the admin section. The forms are arranged in ascending order of the
  88.          * priority values. It is required to return a value between 0 and 100.
  89.          */
  90.         public function getPriority() {
  91.                 return 50;
  92.         }
  94. }

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.

  1. <?php
  2. /** @var $l \OCP\IL10N */
  3. /** @var $_ array */
  5. script('myappid', 'admin');         // adds a JavaScript file
  6. style('survey_client', 'admin');    // adds a CSS file
  7. ?>
  9. <div id="survey_client" class="section">
  10.         <h2><?php p($l->t('Your app')); ?></h2>
  12.         <p>
  13.                 <?php p($l->t('Only administrators are allowed to click the red button')); ?>
  14.         </p>
  16.         <button><?php p($l->t('Click red button')); ?></button>
  18.         <p>
  19.                 <input id="your_app_magic" name="your_app_magic"
  20.                            type="checkbox" class="checkbox" value="1" <?php if ($_['is_enabled']): ?> checked="checked"<?php endif; ?> />
  21.                 <label for="your_app_magic"><?php p($l->t('Do some magic')); ?></label>
  22.         </p>
  24.         <h3><?php p($l->t('Things to define')); ?></h3>
  25.         <?php
  26.         foreach ($_['categories'] as $category => $data) {
  27.                 ?>
  28.                 <p>
  29.                         <input id="your_app_<?php p($category); ?>" name="your_app_<?php p($category); ?>"
  30.                                    type="checkbox" class="checkbox your_app_category" value="1" <?php if ($data['enabled']): ?> checked="checked"<?php endif; ?> />
  31.                         <label for="your_app_<?php p($category); ?>"><?php print_unescaped($data['displayName']); ?></label>
  32.                 </p>
  33.                 <?php
  34.         }
  35.         ?>
  37.         <?php if (!empty($_['last_report'])): ?>
  39.         <h3><?php p($l->t('Last report')); ?></h3>
  41.         <p><textarea title="<?php p($l->t('Last report')); ?>" class="last_report" readonly="readonly"><?php p($_['last_report']);?></textarea></p>
  43.         <em class="last_sent"><?php p($l->t('Sent on: %s', [$_['last_sent']])); ?></em>
  45.         <?php endif; ?>
  47. </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\IIconSection.

An example implementation of the IIconSection interface:

  1. <?php
  2. namespace OCA\YourAppNamespace\Settings;
  4. use OCP\IL10N;
  5. use OCP\IURLGenerator;
  6. use OCP\Settings\IIconSection;
  8. class AdminSection implements IIconSection {
  10.         /** @var IL10N */
  11.         private $l;
  13.         /** @var IURLGenerator */
  14.         private $urlGenerator;
  16.         public function __construct(IL10N $l, IURLGenerator $urlGenerator) {
  17.                 $this->l = $l;
  18.                 $this->urlGenerator = $urlGenerator;
  19.         }
  21.         /**
  22.          * returns the ID of the section. It is supposed to be a lower case string
  23.          *
  24.          * @returns string
  25.          */
  26.         public function getID() {
  27.                 return 'yourappid'; //or a generic id if feasible
  28.         }
  30.         /**
  31.          * returns the translated name as it should be displayed, e.g. 'LDAP / AD
  32.          * integration'. Use the L10N service to translate it.
  33.          *
  34.          * @return string
  35.          */
  36.         public function getName() {
  37.                 return $this->l->t('Translatable Section Name');
  38.         }
  40.         /**
  41.          * @return int whether the form should be rather on the top or bottom of
  42.          * the settings navigation. The sections are arranged in ascending order of
  43.          * the priority values. It is required to return a value between 0 and 99.
  44.          */
  45.         public function getPriority() {
  46.                 return 80;
  47.         }
  49.         /**
  50.          * @return The relative path to a an icon describing the section
  51.          */
  52.         public function getIcon() {
  53.                 return $this->urlGenerator->imagePath('yourapp', 'icon.svg');
  54.         }
  56. }

Also the section must be registered in the app’s info.xml.

Registering Settings and Sections

As mentioned already both Settings and Sections should be registered in the info.xml of your app This is rather straight forward as you can see in the code snipplet below

  1. ...
  2. <settings>
  3.     <admin>OCA\YourAppNamespace\Settings\Admin</admin>
  4.     <admin-section>OCA\YourAppNamespace\Settings\AdminSection</admin-section>
  5.     <personal>OCA\YourAppNamespace\Settings\Personal</personal>
  6.     <personal-section>OCA\YourAppNamespace\Settings\PersonalSection</personal-section>
  7. </settings>
  8. ...