From 89272f7a1e08c6d9392719d7f61f20969b25d9db Mon Sep 17 00:00:00 2001 From: Benedikt Kulmann Date: Mon, 4 May 2020 16:31:11 +0200 Subject: [PATCH 1/2] Add initial docs and diagram --- docs/_index.md | 37 +++++++++++++++++++- docs/bundles.md | 75 +++++++++++++++++++++++++++++++++++++++++ docs/getting-started.md | 2 +- docs/glossary.md | 35 +++++++++++++++++++ 4 files changed, 147 insertions(+), 2 deletions(-) create mode 100644 docs/bundles.md create mode 100644 docs/glossary.md diff --git a/docs/_index.md b/docs/_index.md index 27646f4580..75f85f01d7 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -7,4 +7,39 @@ geekdocEditPath: edit/master/docs geekdocFilePath: _index.md --- -This service provides ... +## Abstract + +When using oCIS, the requirement to store settings arises. This extension provides functionality +for other extensions to register new settings within oCIS. It is responsible for saving the respective +settings values as well. + +For ease of use, this extension provides an ocis-web extension which allows users to change their settings values. +Please refer to the [extensions docs](https://owncloud.github.io/ocis/extensions/#external-phoenix-apps) +for running ocis-web extensions. + +{{< mermaid class="text-center">}} +graph TD + subgraph ow[ocis-web] + ows[ocis-web-settings] + owc[ocis-web-core] + end + ows ---|"listSettingsBundles(),
listSettingsValues(),
saveSettingsValue(value)"| os[ocis-settings] + owc ---|"listSettingsValues()
getSettingsValue(id)"| sdk[oC SDK] + sdk --- sdks{ocis-settings
available?} + sdks ---|"yes"| os + sdks ---|"no"| defaults[Use set of
default values] + oa[oCIS extensions
e.g. ocis-accounts] ---|"saveSettingsBundle(bundle),
getSettingsValue(id)"| os +{{< /mermaid >}} + +The diagram shows how the settings service integrates into oCIS: +- oCIS extensions can register settings bundles with ocis-settings. +- The frontend can be plugged into ocis-web, showing generated forms for changing settings values as a user. +- Extensions can query ocis-settings for settings values of a user. +- The ownCloud SDK, used as a data abstraction layer for ocis-web, will query ocis-settings for settings values of a user, +if it's available. The SDK uses sensible defaults when ocis-settings is not part of the setup. + +For compatibility with ownCloud 10, a migration of settings into the storage of ocis-settings will be available. + +## Table of Contents + +{{< toc-tree >}} diff --git a/docs/bundles.md b/docs/bundles.md new file mode 100644 index 0000000000..4b5b7e6f9c --- /dev/null +++ b/docs/bundles.md @@ -0,0 +1,75 @@ +--- +title: "Settings Bundles" +date: 2020-05-04T00:00:00+00:00 +weight: 17 +geekdocRepo: https://github.com/owncloud/ocis-settings +geekdocEditPath: edit/master/docs +geekdocFilePath: bundles.md +--- + +A **Settings Bundle** is a collection of settings, uniquely identified by the key of the +extension registering the bundle and the key of the bundle itself. It's purpose is to let +oCIS extensions define settings and make them available to users. They are dynamically +rendered into forms, available in the frontend. + +As of now we support five different types of settings: +- boolean +- integer +- string +- single choice list of integers or strings +- multiple choice list of integers or strings + +Each **Setting** is uniquely identified by a key within the bundle. Some attributes +depend on the chosen type of setting. Through the information provided with the +attributes of the setting, the settings frontend dynamically renders form elements, +allowing users to change their settings individually. + +## Example + +```json +{ + "identifier": { + "extension": "ocis-accounts", + "bundleKey": "profile" + }, + "displayName": "Profile", + "settings": [ + { + "settingKey": "lastname", + "displayName": "Lastname", + "description": "Input for lastname", + "stringValue": { + "placeholder": "Set lastname" + } + }, + { + "settingKey": "age", + "displayName": "Age", + "description": "Input for age", + "intValue": { + "min": "16", + "max": "200", + "step": "2", + "placeholder": "Set age" + } + }, + { + "settingKey": "timezone", + "displayName": "Timezone", + "description": "User timezone", + "singleChoiceValue": { + "options": [ + { + "stringValue": "Europe/Berlin", + "displayValue": "Europe/Berlin" + }, + { + "stringValue": "Asia/Kathmandu", + "displayValue": "Asia/Kathmandu" + } + ] + } + } + ] +} +``` diff --git a/docs/getting-started.md b/docs/getting-started.md index b1c3f0b58b..b1a0f7c1de 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,7 +1,7 @@ --- title: "Getting Started" date: 2018-05-02T00:00:00+00:00 -weight: 20 +weight: 25 geekdocRepo: https://github.com/owncloud/ocis-settings geekdocEditPath: edit/master/docs geekdocFilePath: getting-started.md diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000000..e6d8831b64 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,35 @@ +--- +title: "Glossary" +date: 2020-05-04T12:35:00+01:00 +weight: 15 +geekdocRepo: https://github.com/owncloud/ocis-settings +geekdocEditPath: edit/master/docs +geekdocFilePath: glossary.md +--- + +In the context of this extension and oCIS in general, we are using the following terminology. + +### Configuration + +- System configuration +- e.g. service host names and ports +- Changes need to be propagated to other services +- Typically modified on the CLI + +### Settings + +- Application level settings +- e.g. default language +- Can be modified at runtime without restarting the service +- Typically modified in the UI + +### Preferences + +- User settings +- Subset of "Settings" +- e.g. preferred language of a user + +### Settings Bundle + +- Collection of related settings +- Registered by an ocis extension From 93f49e50a7111163d74fd5004fb49bc005f15553 Mon Sep 17 00:00:00 2001 From: Benedikt Kulmann Date: Tue, 5 May 2020 08:55:03 +0200 Subject: [PATCH 2/2] Fix index page and change order of menu items --- docs/_index.md | 17 ++++++++--------- docs/bundles.md | 2 +- docs/glossary.md | 2 +- docs/license.md | 2 +- 4 files changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/_index.md b/docs/_index.md index 75f85f01d7..ed4cf5021a 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -10,11 +10,11 @@ geekdocFilePath: _index.md ## Abstract When using oCIS, the requirement to store settings arises. This extension provides functionality -for other extensions to register new settings within oCIS. It is responsible for saving the respective +for other extensions to register new settings within oCIS. It is responsible for storing the respective settings values as well. For ease of use, this extension provides an ocis-web extension which allows users to change their settings values. -Please refer to the [extensions docs](https://owncloud.github.io/ocis/extensions/#external-phoenix-apps) +Please refer to the [ocis-web extension docs](https://owncloud.github.io/ocis/extensions/#external-phoenix-apps) for running ocis-web extensions. {{< mermaid class="text-center">}} @@ -32,14 +32,13 @@ graph TD {{< /mermaid >}} The diagram shows how the settings service integrates into oCIS: -- oCIS extensions can register settings bundles with ocis-settings. -- The frontend can be plugged into ocis-web, showing generated forms for changing settings values as a user. +**Settings management:** +- oCIS extensions can register settings bundles with the ocis-settings service. +- The settings frontend can be plugged into ocis-web, showing generated forms for changing settings values as a user. + +**Settings usage:** - Extensions can query ocis-settings for settings values of a user. - The ownCloud SDK, used as a data abstraction layer for ocis-web, will query ocis-settings for settings values of a user, if it's available. The SDK uses sensible defaults when ocis-settings is not part of the setup. -For compatibility with ownCloud 10, a migration of settings into the storage of ocis-settings will be available. - -## Table of Contents - -{{< toc-tree >}} +For compatibility with ownCloud 10, a migration of ownCloud 10 settings into the storage of ocis-settings will be available. diff --git a/docs/bundles.md b/docs/bundles.md index 4b5b7e6f9c..957c214780 100644 --- a/docs/bundles.md +++ b/docs/bundles.md @@ -1,7 +1,7 @@ --- title: "Settings Bundles" date: 2020-05-04T00:00:00+00:00 -weight: 17 +weight: 50 geekdocRepo: https://github.com/owncloud/ocis-settings geekdocEditPath: edit/master/docs geekdocFilePath: bundles.md diff --git a/docs/glossary.md b/docs/glossary.md index e6d8831b64..4a90da330e 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,7 +1,7 @@ --- title: "Glossary" date: 2020-05-04T12:35:00+01:00 -weight: 15 +weight: 80 geekdocRepo: https://github.com/owncloud/ocis-settings geekdocEditPath: edit/master/docs geekdocFilePath: glossary.md diff --git a/docs/license.md b/docs/license.md index 7c61030799..319d426c28 100644 --- a/docs/license.md +++ b/docs/license.md @@ -1,7 +1,7 @@ --- title: "License" date: 2018-05-02T00:00:00+00:00 -weight: 40 +weight: 90 geekdocRepo: https://github.com/owncloud/ocis-settings geekdocEditPath: edit/master/docs geekdocFilePath: license.md