mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-02 17:59:36 +07:00
add Settings doc
This commit is contained in:
Arthur Schiwon
@@ -32,6 +32,7 @@
|
||||
two-factor-provider
|
||||
hooks
|
||||
backgroundjobs
|
||||
settings
|
||||
logging
|
||||
testing
|
||||
publishing
|
||||
|
||||
@@ -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
|
||||
----------
|
||||
|
||||
|
||||
277
developer_manual/app/settings.rst
Normal file
277
developer_manual/app/settings.rst
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user