mirror of
https://github.com/nextcloud/documentation.git
synced 2025-12-12 07:29:47 +07:00
487 lines
14 KiB
ReStructuredText
487 lines
14 KiB
ReStructuredText
.. _declarative_settings_section:
|
|
|
|
====================
|
|
Declarative settings
|
|
====================
|
|
|
|
.. sectionauthor:: Andrey Borysenko <andrey18106x@gmail.com>
|
|
|
|
.. versionadded:: 29.0.0
|
|
|
|
With Nextcloud 29 there is a new way to define app settings in a declarative way.
|
|
This means that you can just register your settings schema
|
|
without writing a custom settings handling front-end and back-end code
|
|
(except when more complex settings logic or design is required).
|
|
|
|
Registering settings schema
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
There are two ways to register a declarative settings schema:
|
|
|
|
1. Class-based using ``OCP\Settings\IDeclarativeSettingsForm`` interface
|
|
2. By using an event listener for the ``OCP\Settings\Events\DeclarativeSettingsRegisterFormEvent``
|
|
|
|
Additionally, you can register multiple declarative parameter schemes per application.
|
|
|
|
.. note::
|
|
|
|
Form fields ids (configkeys) must be unique within an app.
|
|
|
|
Class-based schema registration
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
To register a declarative settings schema using a class, you need to create a class that implements the ``OCP\Settings\IDeclarativeSettingsForm`` interface:
|
|
|
|
.. code-block:: php
|
|
:emphasize-lines: 8,11
|
|
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace OCA\MyApp\DeclarativeSettings;
|
|
|
|
use OCP\Settings\DeclarativeSettingsTypes;
|
|
use OCP\Settings\IDeclarativeSettingsForm;
|
|
|
|
class MyDeclarativeSettingsForm implements IDeclarativeSettingsForm {
|
|
public function getSchema(): array {
|
|
return [
|
|
'id' => 'my_declarative_settings_form', // unique form id
|
|
'priority' => 10, // declarative section priority (ordering)
|
|
'section_type' => DeclarativeSettingsTypes::SECTION_TYPE_ADMIN, // admin, personal
|
|
'section_id' => 'my_section_id', // existing section id or your custom section id
|
|
'storage_type' => DeclarativeSettingsTypes::STORAGE_TYPE_INTERNAL, // external, internal (handled by core to store in appconfig and preferences)
|
|
'title' => 'MyApp settings title', // NcSettingsSection name
|
|
'description' => 'My app settings section description', // NcSettingsSection description
|
|
'doc_url' => '', // NcSettingsSection doc_url for documentation or help page, empty string if not needed
|
|
'fields' => [
|
|
[
|
|
'id' => 'my_field_key', // configkey
|
|
'title' => 'Field title', // name or label
|
|
'description' => 'Additional setting hint or description', // hint
|
|
'type' => DeclarativeSettingsTypes::MULTI_SELECT,
|
|
'options' => ['foo', 'bar', 'baz'],
|
|
'placeholder' => 'Select some multiple options', // input placeholder
|
|
'default' => ['foo', 'bar'],
|
|
],
|
|
]
|
|
];
|
|
}
|
|
}
|
|
|
|
The ``OCP\Settings\IDeclarativeSettingsForm`` interface has only one method ``getSchema`` that should return an array with the settings schema.
|
|
|
|
|
|
After that, you can register schema class using ``IRegistrationContext->registerDeclarativeSettings`` method:
|
|
|
|
.. code-block:: php
|
|
:emphasize-lines: 9,17
|
|
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace OCA\MyApp\AppInfo;
|
|
|
|
use OCP\AppFramework\App;
|
|
use OCP\AppFramework\Bootstrap\IRegistrationContext;
|
|
use OCA\MyApp\DeclarativeSettings\MyDeclarativeSettingsForm;
|
|
|
|
class Application extends App {
|
|
public function __construct(array $urlParams = []) {
|
|
parent::__construct('my_app', $urlParams);
|
|
}
|
|
|
|
public function register(IRegistrationContext $context): void {
|
|
$context->registerDeclarativeSettings(MyDeclarativeSettingsForm::class);
|
|
}
|
|
}
|
|
|
|
|
|
Event-based schema registration
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
To register a declarative settings schema using an event system you need to implement event listener for ``OCP\Settings\Events\DeclarativeSettingsRegisterFormEvent``:
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace OCA\MyApp\Listener;
|
|
|
|
use OCP\EventDispatcher\Event;
|
|
use OCP\EventDispatcher\IEventListener;
|
|
use OCP\Settings\DeclarativeSettingsTypes;
|
|
use OCP\Settings\Events\DeclarativeSettingsRegisterFormEvent;
|
|
|
|
class RegisterDeclarativeSettingsListener implements IEventListener {
|
|
|
|
public function __construct() {
|
|
}
|
|
|
|
public function handle(Event $event): void {
|
|
if (!($event instanceof DeclarativeSettingsRegisterFormEvent)) {
|
|
return;
|
|
}
|
|
|
|
$event->registerSchema('my_app', [
|
|
// your declarative settings schema here
|
|
]);
|
|
}
|
|
}
|
|
|
|
|
|
And register the event listener as usually in your ``AppInfo/Application.php`` registration context:
|
|
|
|
.. code-block:: php
|
|
:emphasize-lines: 9,10,18
|
|
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace OCA\MyApp\AppInfo;
|
|
|
|
use OCP\AppFramework\App;
|
|
use OCP\AppFramework\Bootstrap\IRegistrationContext;
|
|
use OCP\Settings\Events\DeclarativeSettingsRegisterFormEvent;
|
|
use OCA\MyApp\Listener\RegisterDeclarativeSettingsListener;
|
|
|
|
class Application extends App {
|
|
public function __construct(array $urlParams = []) {
|
|
parent::__construct('my_app', $urlParams);
|
|
}
|
|
|
|
public function register(IRegistrationContext $context): void {
|
|
$context->registerEventListener(DeclarativeSettingsRegisterFormEvent::class, RegisterDeclarativeSettingsListener::class);
|
|
}
|
|
}
|
|
|
|
|
|
Handling settings storage
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
There are two types of schema ``storage_type`` supported:
|
|
|
|
1. internal ``OCP\Settings\DeclarativeSettingsTypes::STORAGE_TYPE_INTERNAL`` - settings values changes handled by core
|
|
1. external ``OCP\Settings\DeclarativeSettingsTypes::STORAGE_TYPE_EXTERNAL`` - settings values changes handled by your app handlers (event listeners).
|
|
|
|
Internal storage type
|
|
---------------------
|
|
|
|
Internal (``storage_type='internal'``) storage type is handled by core, you don't have to implement additional handlers for that.
|
|
|
|
Section type admin
|
|
******************
|
|
|
|
For declarative settings schema with ``section_type`` set to ``DeclarativeSettingsTypes::SECTION_TYPE_ADMIN`` - settings values
|
|
are stored in ``appconfig`` table.
|
|
|
|
Accessible via ``OCP\IConfig->getAppValue`` interface.
|
|
|
|
Section type personal
|
|
*********************
|
|
|
|
For declarative settings schema with ``section_type`` set to ``DeclarativeSettingsTypes::SECTION_TYPE_PERSONAL`` - settings values
|
|
are user specific and stored in ``preferences`` table.
|
|
|
|
Accessible via ``OCP\IConfig->getUserValue`` interface.
|
|
|
|
External storage type
|
|
---------------------
|
|
|
|
Handling of an external (``storage_type='external'``) storage type is always done via listening to the following events:
|
|
|
|
1. ``OCP\Settings\Events\DeclarativeSettingsGetValueEvent`` - to return the declarative setting value from your storage
|
|
2. ``OCP\Settings\Events\DeclarativeSettingsSetValueEvent`` - to save the declarative setting value where you want to
|
|
|
|
Example of DeclarativeSettingsGetValueEvent event listener:
|
|
|
|
.. code-block:: php
|
|
:emphasize-lines: 27,28
|
|
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace OCA\MyApp\Listener;
|
|
|
|
use OCP\EventDispatcher\Event;
|
|
use OCP\EventDispatcher\IEventListener;
|
|
use OCP\IConfig;
|
|
use OCP\Settings\Events\DeclarativeSettingsGetValueEvent;
|
|
|
|
class GetDeclarativeSettingsValueListener implements IEventListener {
|
|
|
|
public function __construct(private IConfig $config) {
|
|
}
|
|
|
|
public function handle(Event $event): void {
|
|
if (!$event instanceof DeclarativeSettingsGetValueEvent) {
|
|
return;
|
|
}
|
|
|
|
// Always check if the event is related to your app declarative settings
|
|
if ($event->getApp() !== 'my_app') {
|
|
return;
|
|
}
|
|
|
|
$value = $this->config->getUserValue($event->getUser()->getUID(), $event->getApp(), $event->getFieldId());
|
|
$event->setValue($value);
|
|
}
|
|
}
|
|
|
|
Example of DeclarativeSettingsSetValueEvent event listener:
|
|
|
|
.. code-block:: php
|
|
:emphasize-lines: 27
|
|
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace OCA\MyApp\Listener;
|
|
|
|
use OCP\EventDispatcher\Event;
|
|
use OCP\EventDispatcher\IEventListener;
|
|
use OCP\IConfig;
|
|
use OCP\Settings\Events\DeclarativeSettingsSetValueEvent;
|
|
|
|
class SetDeclarativeSettingsValueListener implements IEventListener {
|
|
|
|
public function __construct(private IConfig $config) {
|
|
}
|
|
|
|
public function handle(Event $event): void {
|
|
if (!$event instanceof DeclarativeSettingsSetValueEvent) {
|
|
return;
|
|
}
|
|
|
|
// Always check if the event is related to your app declarative settings
|
|
if ($event->getApp() !== 'my_app') {
|
|
return;
|
|
}
|
|
|
|
$this->config->setUserValue($event->getUser()->getUID(), $event->getApp(), $event->getFieldId(), $event->getValue());
|
|
}
|
|
}
|
|
|
|
Register get/set listeners
|
|
--------------------------
|
|
|
|
.. code-block:: php
|
|
:emphasize-lines: 9,10,11,12,20,21
|
|
|
|
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace OCA\MyApp\AppInfo;
|
|
|
|
use OCP\AppFramework\App;
|
|
use OCP\AppFramework\Bootstrap\IRegistrationContext;
|
|
use OCP\Settings\Events\DeclarativeSettingsGetValueEvent;
|
|
use OCP\Settings\Events\DeclarativeSettingsSetValueEvent;
|
|
use OCA\MyApp\Listener\GetDeclarativeSettingsValueListener;
|
|
use OCA\MyApp\Listener\SetDeclarativeSettingsValueListener;
|
|
|
|
class Application extends App {
|
|
public function __construct(array $urlParams = []) {
|
|
parent::__construct('my_app', $urlParams);
|
|
}
|
|
|
|
public function register(IRegistrationContext $context): void {
|
|
$context->registerEventListener(DeclarativeSettingsGetValueEvent::class, GetDeclarativeSettingsValueListener::class);
|
|
$context->registerEventListener(DeclarativeSettingsSetValueEvent::class, SetDeclarativeSettingsValueListener::class);
|
|
}
|
|
}
|
|
|
|
|
|
|
|
Schema field types
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
Supported field types are declared in ``OCP\Settings\DeclarativeSettingsTypes`` class:
|
|
|
|
- ``DeclarativeSettingsTypes::TEXT`` - input type text
|
|
- ``DeclarativeSettingsTypes::PASSWORD``- input type password
|
|
- ``DeclarativeSettingsTypes::EMAIL`` - input type email
|
|
- ``DeclarativeSettingsTypes::TEL`` - input type tel
|
|
- ``DeclarativeSettingsTypes::URL`` - input type url
|
|
- ``DeclarativeSettingsTypes::NUMBER`` - input type number
|
|
- ``DeclarativeSettingsTypes::CHECKBOX`` - input type checkbox
|
|
- ``DeclarativeSettingsTypes::MULTI_CHECKBOX`` - multiple checkboxes representing one setting with multiple options
|
|
- ``DeclarativeSettingsTypes::RADIO`` - input type radio for setting with single option
|
|
- ``DeclarativeSettingsTypes::SELECT`` - input type select for setting with single option
|
|
- ``DeclarativeSettingsTypes::MULTI_SELECT`` - input type select for setting with multiple options
|
|
|
|
The examples of each field type are listed below.
|
|
|
|
.. note::
|
|
|
|
Field order is the same as in the schema array.
|
|
|
|
|
|
Basic input types
|
|
-----------------
|
|
|
|
For text, password, email, tel, url, number schema is similar:
|
|
|
|
.. figure:: ../images/declarative_settings_input_fields.png
|
|
:alt: Declarative settings input fields (text, password, email, tel, url, number)
|
|
|
|
.. code-block:: php
|
|
|
|
[
|
|
'id' => 'my_field_unique_id', // configkey
|
|
'title' => 'Default text field', // label
|
|
'description' => 'Set some simple text setting', // hint
|
|
'type' => DeclarativeSettingsTypes::TEXT, // text, password, email, tel, url, number
|
|
'placeholder' => 'Enter text setting', // placeholder
|
|
'default' => 'foo',
|
|
],
|
|
|
|
Checkbox and Multi-checkbox
|
|
---------------------------
|
|
|
|
.. figure:: ../images/declarative_settings_checkboxes.png
|
|
:alt: checkbox and multi-checkbox field types
|
|
|
|
.. code-block:: php
|
|
|
|
[
|
|
'id' => 'my_checkbox_field',
|
|
'title' => 'Toggle something',
|
|
'description' => 'Select checkbox option setting',
|
|
'type' => DeclarativeSettingsTypes::CHECKBOX, // checkbox, multiple-checkbox
|
|
'label' => 'Verify something if enabled',
|
|
'default' => false,
|
|
],
|
|
[
|
|
'id' => 'my_multicheckbox_field',
|
|
'title' => 'Multiple checkbox toggles, describing one setting, checked options are saved as an JSON object {foo: true, bar: false}',
|
|
'description' => 'Select checkbox option setting',
|
|
'type' => DeclarativeSettingsTypes::MULTI_CHECKBOX, // checkbox, multi-checkbox
|
|
'default' => ['foo' => true, 'bar' => true, 'baz' => true],
|
|
'options' => [
|
|
[
|
|
'name' => 'Foo',
|
|
'value' => 'foo', // multiple-checkbox configkey
|
|
],
|
|
[
|
|
'name' => 'Bar',
|
|
'value' => 'bar',
|
|
],
|
|
[
|
|
'name' => 'Baz',
|
|
'value' => 'baz',
|
|
],
|
|
[
|
|
'name' => 'Qux',
|
|
'value' => 'qux',
|
|
],
|
|
],
|
|
],
|
|
|
|
Radio
|
|
-----
|
|
|
|
.. figure:: ../images/declarative_settings_radio.png
|
|
:alt: radio field type
|
|
|
|
.. code-block:: php
|
|
|
|
[
|
|
'id' => 'my_radio_field',
|
|
'title' => 'Radio toggles, describing one setting like single select',
|
|
'description' => 'Select radio option setting',
|
|
'type' => DeclarativeSettingsTypes::RADIO, // radio (NcCheckboxRadioSwitch type radio)
|
|
'label' => 'Select single toggle',
|
|
'default' => 'foo',
|
|
'options' => [
|
|
[
|
|
'name' => 'First radio', // NcCheckboxRadioSwitch display name
|
|
'value' => 'foo' // NcCheckboxRadioSwitch value
|
|
],
|
|
[
|
|
'name' => 'Second radio',
|
|
'value' => 'bar'
|
|
],
|
|
[
|
|
'name' => 'Third radio',
|
|
'value' => 'baz'
|
|
],
|
|
],
|
|
],
|
|
|
|
Select and Multi-select
|
|
-----------------------
|
|
|
|
.. figure:: ../images/declarative_settings_select.png
|
|
:alt: select field type
|
|
|
|
.. code-block:: php
|
|
|
|
[
|
|
'id' => 'my_select_field',
|
|
'title' => 'Selection',
|
|
'description' => 'Select some option setting',
|
|
'type' => DeclarativeSettingsTypes::SELECT, // select, radio, multi-select
|
|
'options' => ['foo', 'bar', 'baz'],
|
|
'placeholder' => 'Select some option setting',
|
|
'default' => 'foo',
|
|
],
|
|
|
|
.. figure:: ../images/declarative_settings_multi_select.png
|
|
:alt: multi-select field type
|
|
|
|
.. code-block:: php
|
|
|
|
[
|
|
'id' => 'my_multi_select_field', // configkey
|
|
'title' => 'Multi-selection', // name or label
|
|
'description' => 'Select some option setting', // hint
|
|
'type' => DeclarativeSettingsTypes::MULTI_SELECT, // select, radio, multi-select
|
|
'options' => ['foo', 'bar', 'baz'], // simple options for select, radio, multi-select
|
|
'placeholder' => 'Select some multiple options', // input placeholder
|
|
'default' => ['foo', 'bar'],
|
|
],
|
|
|
|
|
|
Sensitive field type
|
|
--------------------
|
|
|
|
Since Nextcloud 32 there is a new field attribute ``sensitive: true/false`` available for ``DeclarativeSettingsTypes::TEXT``, ``DeclarativeSettingsTypes::PASSWORD`` types.
|
|
The values of such fields are stored in an encrypted form in the database and are not exposed to the UI.
|
|
|
|
|
|
.. code-block:: php
|
|
|
|
[
|
|
'id' => 'test_sensitive_field',
|
|
'title' => 'Sensitive text field',
|
|
'description' => 'Set some secure value setting that is stored encrypted',
|
|
'type' => DeclarativeSettingsTypes::TEXT,
|
|
'label' => 'Sensitive field',
|
|
'placeholder' => 'Set secure value',
|
|
'default' => '',
|
|
'sensitive' => true, // only for TEXT, PASSWORD types
|
|
],
|
|
[
|
|
'id' => 'test_sensitive_field_2',
|
|
'title' => 'Sensitive password field',
|
|
'description' => 'Set some password setting that is stored encrypted',
|
|
'type' => DeclarativeSettingsTypes::PASSWORD,
|
|
'label' => 'Sensitive field',
|
|
'placeholder' => 'Set secure value',
|
|
'default' => '',
|
|
'sensitive' => true, // only for TEXT, PASSWORD types
|
|
],
|
|
|
|
.. figure:: ../images/declarative_settings_sensitive.png
|
|
:alt: sensitive fields
|
|
|