Merge pull request #4 from owncloud/initial-docs

Add initial docs and diagram

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(),<br>listSettingsValues(),<br>saveSettingsValue(value)"| os[ocis-settings]
+    owc ---|"listSettingsValues()<br>getSettingsValue(id)"| sdk[oC SDK]
+    sdk --- sdks{ocis-settings<br>available?}
+    sdks ---|"yes"| os
+    sdks ---|"no"| defaults[Use set of<br>default values]
+    oa[oCIS extensions<br>e.g. ocis-accounts] ---|"saveSettingsBundle(bundle),<br>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 >}}

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"
+          }
+        ]
+      }
+    }
+  ]
+}
+```

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

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