Declarative Settings

Starting from Nextcloud 29, AppAPI provides the ability to display ex-application settings. When admin or user changes some ex-app settings they will be stored in the database and can be received using Preferences or AppConfig API.

Note

Settings rendered only for enabled ExApps.

Warning

section_id from scheme should be already registered by any PHP application.

AppAPI provides two sections for that: ai_integration_team and declarative_settings, you can use them.

Register Settings

OCS endpoint: POST /apps/app_api/api/v1/ui/settings

Params

Complete list of params (including optional):

{
        "formScheme": "settings scheme"
}

Unregister Menu Entry

OCS endpoint: DELETE /apps/app_api/api/v1/ui/settings

Params

{
        "formId": "formId from scheme"
}

Example of settings scheme in Python:

{
        "id": "settings_example",
        "priority": 10,
        "section_type": "admin",
        "section_id": "ai_integration_team",
        "title": "AppAPI declarative settings",
        "description": "These fields are rendered dynamically from declarative schema",
        "fields": [
                {
                        "id": "field1",
                        "title": "Multi-selection",
                        "description": "Select some option setting",
                        "type": 'multi-select',
                        "options": ["foo", "bar", "baz"],
                        "placeholder": "Select some multiple options",
                        "default": ["foo", "bar"],
                },
                {
                        "id": "some_real_setting",
                        'title': 'Choose init status check background job interval',
                        'description': 'How often AppAPI should check for initialization status',
                        'type': 'radio',
                        'placeholder': 'Choose init status check background job interval',
                        'default': '40m',
                        'options': [
                                {
                                        'name': 'Each 40 minutes',
                                        'value': '40m',
                                },
                                {
                                        'name': 'Each 60 minutes',
                                        'value': '60m',
                                },
                                {
                                        'name': 'Each 120 minutes',
                                        'value': '120m',
                                },
                                {
                                        'name': 'Each day',
                                        'value': f"{60 * 24}m",
                                },
                        ],
                },
                {
                        'id': 'test_ex_app_field_1',
                        'title': 'Default text field',
                        'description': 'Set some simple text setting',
                        'type': 'text',
                        'placeholder': 'Enter text setting',
                        'default': 'foo',
                },
                {
                        'id': 'test_ex_app_field_1_1',
                        'title': 'Email field',
                        'description': 'Set email config',
                        'type': 'email',
                        'placeholder': 'Enter email',
                        'default': '',
                },
                {
                        'id': 'test_ex_app_field_1_2',
                        'title': 'Tel field',
                        'description': 'Set tel config',
                        'type': 'tel',
                        'placeholder': 'Enter your tel',
                        'default': '',
                },
                {
                        'id': 'test_ex_app_field_1_3',
                        'title': 'Url (website) field',
                        'description': 'Set url config',
                        'type': url',
                        'placeholder': 'Enter url',
                        'default': '',
                },
                {
                        'id': 'test_ex_app_field_1_4',
                        'title': 'Number field',
                        'description': 'Set number config',
                        'type': 'number',
                        'placeholder': 'Enter number value',
                        'default': 0,
                },
                {
                        'id': 'test_ex_app_field_2',
                        'title': 'Password',
                        'description': 'Set some secure value setting',
                        'type': password',
                        'placeholder': 'Set secure value',
                        'default': '',
                },
                {
                        'id': 'test_ex_app_field_3',
                        'title': 'Selection',
                        'description': 'Select some option setting',
                        'type': 'select',
                        'options': ['foo', 'bar', 'baz'],
                        'placeholder': 'Select some option setting',
                        'default': 'foo',
                },
                {
                        'id': 'test_ex_app_field_4',
                        'title': 'Toggle something',
                        'description': 'Select checkbox option setting',
                        'type': 'checkbox',
                        'label': 'Verify something if enabled',
                        'default': False,
                },
                {
                        'id': 'test_ex_app_field_5',
                        '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': 'multi-checkbox',
                        'default': {'foo': True, 'bar': True},
                        'options': [
                                {
                                        'name':'Foo',
                                        'value': 'foo',
                                },
                                {
                                        'name': 'Bar',
                                        'value': 'bar',
                                },
                                {
                                        'name': 'Baz',
                                        'value': 'baz',
                                },
                                {
                                        'name': 'Qux',
                                        'value': 'qux',
                                },
                        ],
                },
                {
                        'id': 'test_ex_app_field_6',
                        'title': 'Radio toggles, describing one setting like single select',
                        'description': 'Select radio option setting',
                        'type': 'radio',
                        'label': 'Select single toggle',
                        'default': 'foo',
                        'options': [
                                {
                                        'name': 'First radio',
                                        'value': 'foo'
                                },
                                {
                                        'name': 'Second radio',
                                        'value': 'bar'
                                },
                                {
                                        'name': 'Second radio',
                                        'value': 'baz'
                                },
                        ],
                },
        ]
}