mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-01-24 13:58:12 -05:00
Merge pull request #4 from owncloud/initial-docs
Add initial docs and diagram
This commit is contained in:
Jörn Friedrich Dreyer
@@ -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 >}}
|
||||
|
||||
75
docs/bundles.md
Normal file
75
docs/bundles.md
Normal file
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -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
|
||||
|
||||
35
docs/glossary.md
Normal file
35
docs/glossary.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user