Skip to content
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
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 Nov 26, 2023
a8cccd7
Remove skeleton custom app docs, start extension system docs
pascalwengerter Nov 26, 2023
30ca76c
Remove skeleton app leftovers
pascalwengerter Jan 8, 2024
c80d5fa
Add drafts for extension docs
pascalwengerter Jan 23, 2024
f6b2fec
wip apps and extensions abstract
kulmann Jan 23, 2024
a4f7f80
Add most basic extension example to docs
pascalwengerter Jan 23, 2024
049e65c
WIP: add extension abstract draft
kulmann Jan 23, 2024
56197da
Further formulate extension docs basics
pascalwengerter Jan 23, 2024
efab13f
Add search extension type docs
pascalwengerter Jan 23, 2024
7151a32
Add extension base docs and link to it from dedicated extension type …
pascalwengerter Jan 23, 2024
0494921
Furhter complete left sidebar menu item extension type documentation
pascalwengerter Jan 23, 2024
039c00e
docs: add right sidebar panel extension docs
kulmann Jan 23, 2024
af4c6db
fixup! docs: add right sidebar panel extension docs
kulmann Jan 23, 2024
8e0c33e
Refactor actions/leftsidebarmenuitem/folderview docs subsections
pascalwengerter Jan 23, 2024
a1b223e
fixup! docs: add right sidebar panel extension docs
kulmann Jan 23, 2024
ac08b2a
Remove misplaced file editor example, switch to TS in extension doc c…
pascalwengerter Jan 23, 2024
2deeebc
docs: add details about extension registry and extension base config
kulmann Jan 23, 2024
791691f
docs: fix date in sidebar panel extension docs
kulmann Jan 23, 2024
f5d68d1
docs: streamline extension main page and add scopes details
kulmann Jan 24, 2024
39b6659
docs: streamline and cross link extension docs index page
kulmann Jan 24, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -67,7 +67,6 @@ The repository's `packages` also contains the following apps, which can be en-/d
- **pdf-viewer:** An extension for opening PDF files without leaving the UI
- **preview:** An extension for opening audio, video and image files
- **search:** An extension for registering search providers, which then get rendered into the layout in the **runtime** using a portal
- **skeleton:** Bare extension serving as a playground for prototyping new custom extensions
- **text-editor:** An extension for creating, opening and editing plain text files, like e.g. `.md` or `.txt`
- **user-management:** An extension for basic user and group management by the admin. Only works with the Infinite Scale platform, as it uses the graph API.

7 changes: 7 additions & 0 deletions changelog/unreleased/change-remove-skeleton-app
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
86 changes: 0 additions & 86 deletions docs/custom-apps/_index.md

This file was deleted.

140 changes: 140 additions & 0 deletions docs/extension-system/_index.md
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.
Copy link
Member

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

Copy link
Member

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.?

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?
21 changes: 21 additions & 0 deletions docs/extension-system/extension-types/actions.md
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 -->
16 changes: 16 additions & 0 deletions docs/extension-system/extension-types/file-editor.md
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 docs/extension-system/extension-types/left-sidebar-menu-item.md
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 docs/extension-system/extension-types/right-sidebar-panels.md
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 -->
61 changes: 61 additions & 0 deletions docs/extension-system/extension-types/search.md
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
Copy link
Contributor Author

Choose a reason for hiding this comment

The 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
15 changes: 0 additions & 15 deletions packages/web-app-skeleton/README.md

This file was deleted.

Loading