-
Notifications
You must be signed in to change notification settings - Fork 159
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add documentation for extension system #10067
Closed
pascalwengerter
wants to merge
20
commits into
owncloud:master
from
pascalwengerter:docs/extension-system
Closed
Changes from 9 commits
Commits
Show all changes
20 commits
Select commit
Hold shift + click to select a range
ef4e1a4
Change: Remove skeleton app
pascalwengerter a8cccd7
Remove skeleton custom app docs, start extension system docs
pascalwengerter 30ca76c
Remove skeleton app leftovers
pascalwengerter c80d5fa
Add drafts for extension docs
pascalwengerter f6b2fec
wip apps and extensions abstract
kulmann a4f7f80
Add most basic extension example to docs
pascalwengerter 049e65c
WIP: add extension abstract draft
kulmann 56197da
Further formulate extension docs basics
pascalwengerter efab13f
Add search extension type docs
pascalwengerter 7151a32
Add extension base docs and link to it from dedicated extension type …
pascalwengerter 0494921
Furhter complete left sidebar menu item extension type documentation
pascalwengerter 039c00e
docs: add right sidebar panel extension docs
kulmann af4c6db
fixup! docs: add right sidebar panel extension docs
kulmann 8e0c33e
Refactor actions/leftsidebarmenuitem/folderview docs subsections
pascalwengerter a1b223e
fixup! docs: add right sidebar panel extension docs
kulmann ac08b2a
Remove misplaced file editor example, switch to TS in extension doc c…
pascalwengerter 2deeebc
docs: add details about extension registry and extension base config
kulmann 791691f
docs: fix date in sidebar panel extension docs
kulmann f5d68d1
docs: streamline extension main page and add scopes details
kulmann 39b6659
docs: streamline and cross link extension docs index page
kulmann File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
Change: Remove skeleton app | ||
|
||
Due to improvements in the extension system in general, we have removed the skeleton app. | ||
Documentation regarding the extension API and guides/examples can be found in the dev docs. | ||
|
||
https://github.com/owncloud/web/issues/9892 | ||
https://github.com/owncloud/web/pull/10067 |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,140 @@ | ||
--- | ||
title: 'Extension system' | ||
date: 2024-01-23T00:00:00+00:00 | ||
weight: 60 | ||
geekdocRepo: https://github.com/owncloud/web | ||
geekdocEditPath: edit/master/docs/extension-system | ||
geekdocFilePath: _index.md | ||
geekdocCollapseSection: true | ||
--- | ||
|
||
{{< toc >}} | ||
|
||
The ownCloud Web can be extended through various entry points with custom **apps** and **extensions**. | ||
|
||
## Concepts and building blocks | ||
|
||
### Apps | ||
|
||
#### Abstract | ||
|
||
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. | ||
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. | ||
|
||
Both parts are optional. This means that an application can be a file editor without any custom extensions, or even contain | ||
no custom application code at all and only host extensions to be registered in the extension registry, or a combination of both. | ||
|
||
#### Technical Details | ||
|
||
To get started, define a `src/index.ts`. Below is the most basic example of its content: | ||
|
||
```ts | ||
// Install '@ownclouders/web-pkg' as a devDependency first (only relevant for types and autocompletion, dependency is already provided by the ownCloud Web at runtime). | ||
kulmann marked this conversation as resolved.
Show resolved
Hide resolved
|
||
import { | ||
AppWrapperRoute, | ||
ApplicationFileExtension, | ||
defineWebApplication | ||
} from '@ownclouders/web-pkg' | ||
|
||
|
||
export default defineWebApplication({ | ||
setup({ applicationConfig }) { | ||
// Here, you have access to the full injection context, meaning you can use all composable that we provide via web-pkg | ||
kulmann marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
// Needs to be unique within all installed extensions in any ownCloud web instance | ||
kulmann marked this conversation as resolved.
Show resolved
Hide resolved
|
||
// Should be short, unique and expressive as it gets prefixed on all routes within your application | ||
const appId = 'your-extension' | ||
|
||
// See extensions section below | ||
const extensions = [ | ||
... | ||
] | ||
|
||
// See details below | ||
const navItems = [ | ||
... | ||
] | ||
|
||
// See details below | ||
const routes = [ | ||
... | ||
] | ||
|
||
return { | ||
appInfo: { | ||
name: $gettext('Your extension'), | ||
kulmann marked this conversation as resolved.
Show resolved
Hide resolved
|
||
id: appId, | ||
icon: 'aliens', // See https://owncloud.design/#/Design%20Tokens/IconList for available options | ||
}, | ||
extensions, | ||
navItems, | ||
routes | ||
} | ||
} | ||
}) | ||
``` | ||
|
||
By defining an application via `defineWebApplication` you can provide the following: | ||
- `appInfo` - the application metadata, which is used to make the application available via the app switcher and the app registry | ||
- `navItems` - the statically defined navigation items for the left side bar. Only gets rendered when more than 1 navigation item exists at runtime. | ||
Additional dynamic navigation items can be registered via the extension registry. | ||
- `routes` - the routes to the different views of your application. May be referenced within the `navItems`. Authentication requirements can be defined per item. | ||
- `extensions` - the extensions to be registered in the extension registry. For more details see the `Extensions` section below. | ||
|
||
### Extensions | ||
|
||
#### Abstract | ||
|
||
In contrast to applications, extensions usually have a rather small scope and dedicated functionality. | ||
|
||
#### Extension Types | ||
|
||
Building an extension is limited to the extension types that are defined by the ownCloud Web extension system. See the full list of available extension types below. | ||
kulmann marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
1. `ActionExtension` - An extension that can register `Action` items which then get shown in various places (e.g. context menus, batch actions), depending on their | ||
respective scope. Most commonly used for file and folder actions (e.g. copy, rename, delete, etc). | ||
2. `SearchExtension` - An extension that can register additional search providers. Please see the dedicated [documentation on search extensions](). | ||
3. `SidebarNavExtension` - An extension that can register additional navigation items to the left side bar. These can be scoped to specific apps, and programmatically enabled/disabled. | ||
4. `SidebarPanelExtension` - An extension that can register panels to the right side bar. | ||
5. `FolderViewExtension` - An extension that can register additional ways of displaying the content of a folder (resources, so spaces, folders or files) to the user. | ||
|
||
#### Extension Points | ||
|
||
There are standardized components and places where extensions are being used automatically. These are the ones that are currently provided: | ||
|
||
1. Left Sidebar for Navigation | ||
2. Right Sidebar in any file(s) context | ||
3. Folder Views in the files app | ||
4. Right click context menu in the files app | ||
5. Batch actions in the files app | ||
6. Search results in the search app | ||
|
||
#### Scopes | ||
|
||
<!-- Where does an extension get used // where is it available --> | ||
|
||
|
||
## Further information (digging deeper) | ||
|
||
AKA "under the hood" | ||
|
||
### Global Extension Registry | ||
|
||
- What is Global Extension Registry? | ||
|
||
### - What can / can't I do with an extension? | ||
|
||
|
||
|
||
### js-package / commonjs-file | ||
|
||
- current limitations | ||
|
||
### extension-sdk | ||
|
||
- Rename to application-sdk? |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
--- | ||
title: 'Action extensions' | ||
date: 2023-11-26T00:00:00+00:00 | ||
weight: 60 | ||
geekdocRepo: https://github.com/owncloud/web | ||
geekdocEditPath: edit/master/docs/extension-system/extension-types | ||
geekdocFilePath: actions.md | ||
geekdocCollapseSection: true | ||
--- | ||
|
||
{{< toc >}} | ||
|
||
One possible extension type is actions. | ||
|
||
|
||
### 3. Actions | ||
- E.g. contextmenu | ||
- E.g. batch actions | ||
- E.g. new action | ||
|
||
<!-- TODO: Add link to next extension type doc page --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
--- | ||
title: 'File editor extensions' | ||
date: 2023-11-26T00:00:00+00:00 | ||
weight: 60 | ||
geekdocRepo: https://github.com/owncloud/web | ||
geekdocEditPath: edit/master/docs/extension-system/extension-types | ||
geekdocFilePath: file-editor.md | ||
geekdocCollapseSection: true | ||
--- | ||
|
||
{{< toc >}} | ||
|
||
One possible extension type is ___. | ||
|
||
# Dokumentation der Verwendung der AppWrapper-Component | ||
<!-- TODO: Add link to next extension type doc page --> |
17 changes: 17 additions & 0 deletions
17
docs/extension-system/extension-types/left-sidebar-menu-item.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
--- | ||
title: 'Left sidebar menu item extensions' | ||
date: 2023-11-26T00:00:00+00:00 | ||
weight: 60 | ||
geekdocRepo: https://github.com/owncloud/web | ||
geekdocEditPath: edit/master/docs/extension-system/extension-types | ||
geekdocFilePath: left-sidebar-menu-item.md | ||
geekdocCollapseSection: true | ||
--- | ||
|
||
{{< toc >}} | ||
|
||
One possible extension type is left sidebar menu items. | ||
|
||
### 2. Left sidebar menu item | ||
- How to add items | ||
<!-- TODO: Add link to next extension type doc page --> |
18 changes: 18 additions & 0 deletions
18
docs/extension-system/extension-types/right-sidebar-panels.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
--- | ||
title: 'Right sidebar panel extensions' | ||
date: 2023-11-26T00:00:00+00:00 | ||
weight: 60 | ||
geekdocRepo: https://github.com/owncloud/web | ||
geekdocEditPath: edit/master/docs/extension-system/extension-types | ||
geekdocFilePath: right-sidebar-panels.md | ||
geekdocCollapseSection: true | ||
--- | ||
|
||
{{< toc >}} | ||
|
||
One possible extension type is right sidebar panels. | ||
|
||
### 4. Global registration of right sidebar panels | ||
|
||
- Makes them reusable in all other apps | ||
<!-- TODO: Add link to next extension type doc page --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
--- | ||
title: 'Search extensions' | ||
date: 2024-01-23T00:00:00+00:00 | ||
weight: 60 | ||
geekdocRepo: https://github.com/owncloud/web | ||
geekdocEditPath: edit/master/docs/extension-system/extension-types | ||
geekdocFilePath: search.md | ||
geekdocCollapseSection: true | ||
--- | ||
|
||
{{< toc >}} | ||
|
||
# Search extensions | ||
|
||
One possible extension type is search. Registered search extensions are available when using the search field in the topbar. | ||
|
||
## Configuration | ||
|
||
An example of a search extension configuration can be found below: | ||
|
||
```js | ||
const exampleSearchExtension = { | ||
id: string, | ||
type: 'search', | ||
scopes?: ExtensionScope[], | ||
searchProvider: { | ||
id: string | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We should either go for example values or a type here, not a mix 😅 my bad! |
||
available: boolean | ||
displayName?: string | ||
previewSearch?: { | ||
// See SearchPreview section below | ||
}, | ||
listSearch?: { | ||
// See SearchList section below | ||
} | ||
} | ||
} | ||
``` | ||
|
||
For `id`, `type`, and `scopes`, please see extension [id section]() in top level docs. | ||
|
||
The `searchProvider` object configures the actual provider. It consist of the following: | ||
- `id` - Since your extension has an `id` and can only have one searchProvider, you can reuse the same value | ||
- `available` - Can be used to programmatically disable/enable any searchProvider, e.g. by dynamically checking backend capabilities | ||
- `displayName` - Optional, used to add a small hint to indicate the connection between search providers and their corresponding results | ||
- `previewSearch` - See below | ||
- `listSearch` - See below | ||
|
||
|
||
### ListSearch | ||
|
||
The listSearch object consists of: | ||
|
||
- `component` - Vue component that can render the values from the SearchResult below | ||
- `search(term: string)` - Function that exectues the search, based on a given term. The term is formatted in [KQL](https://owncloud.dev/services/search/#query-language). Please note that the returned values needs to be formatted to fit either `SearchResource` or `GenericSearchResultItem` type | ||
|
||
### PreviewSearch | ||
|
||
The previewSearch object extends the listSearch with one additional attribute: | ||
|
||
- `available` - Indicates whether a preview underneath the search bar is available for this search provider |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
distributed to ... an admin? kinda odd to my ears
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe
An Application in the context of ownCloud Web is an artifact which can be installed in an ownCloud Infinite Scale instance.
?