Add documentation for extension system #10067
Conversation
pascalwengerter
force-pushed
the
docs/extension-system
branch
from
2e4ad98 to
274ff3e
Compare
pascalwengerter
force-pushed
the
docs/extension-system
branch
from
b5dcb84 to
c80d5fa
Compare
|
| type: 'search', | ||
| scopes?: ExtensionScope[], | ||
| searchProvider: { | ||
| id: string |
There was a problem hiding this comment.
We should either go for example values or a type here, not a mix 😅 my bad!
|
Superseded by #10400 (too dumb to work with branch protection in the fork and force-with-lease pushes) |
|
|
||
| ### Distinction between Apps and Extensions | ||
|
|
||
| An Application in the context of ownCloud Web is an artifact which can be distributed to and installed by an ownCloud admin. |
There was a problem hiding this comment.
distributed to ... an admin? kinda odd to my ears
There was a problem hiding this comment.
Maybe An Application in the context of ownCloud Web is an artifact which can be installed in an ownCloud Infinite Scale instance.?
| An Application in the context of ownCloud Web is an artifact which can be distributed to and installed by an ownCloud admin. | ||
| It serves two main purposes: | ||
| 1. It makes the full app viewport (everything below the top bar) available to the application developer for any custom | ||
| application code. This includes the ability to define views with routes, navigation items for the left side bar, and more. |
There was a problem hiding this comment.
Don't really agree with this, this is no property of an "app" - it's just that an app can register routes which are rendered in the full viewport.
There was a problem hiding this comment.
hm... I'd like to hint to what is possible, not only the most basic functionality.
| 1. It makes the full app viewport (everything below the top bar) available to the application developer for any custom | ||
| application code. This includes the ability to define views with routes, navigation items for the left side bar, and more. | ||
| 2. Through the `extensions` key in the application interface the developer can register extensions of any extension type. | ||
| Those extensions will become available in standardized extension points and for being queried from the extension registry |
There was a problem hiding this comment.
... and will be queried?
I assume you mean they will become available for being queried - but that doesn't work well with the two parts of the sentence imho
There was a problem hiding this comment.
Changed the paragraph to Through the extensions key in the application interface you can register extensions of any extension type. Those extensions are then available in standardized extension points. Additionally, they can be queried from the extension registry for your own purposes.. How about that?
| application code. This includes the ability to define views with routes, navigation items for the left side bar, and more. | ||
| 2. Through the `extensions` key in the application interface the developer can register extensions of any extension type. | ||
| Those extensions will become available in standardized extension points and for being queried from the extension registry | ||
| for custom use. |
There was a problem hiding this comment.
your own purposes - whatever you want to do, go wild.
|
|
||
| ### Extensions | ||
|
|
||
| In contrast to applications, extensions usually have a rather small scope and dedicated functionality. |
There was a problem hiding this comment.
Do you have a different idea? 😇
| Any extension is required to define at least an `id` and a `type`. | ||
|
|
||
| The `id` is supposed to be unique throughout the ownCloud Web ecosystem. In order to keep `id`s readable for humans we didn't want to enforce uniqueness through e.g. uuids. | ||
| Instead, we chose to use dot-formatted namespaces like e.g. `com.github.owncloud.web.files.search`. We'd like to encourage you to follow the same format for your own extensions. |
There was a problem hiding this comment.
Maybe worth dropping a line why we require it (basically to be able to disable specific extensions via global config)
There was a problem hiding this comment.
Since the whole config is a mess and subject to change, I'd like to not go into detail
First iteration, let's get it in quickly and then iterate as the extension system evolves