-
Notifications
You must be signed in to change notification settings - Fork 157
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add docs for app menu item extension
- Loading branch information
1 parent
50aa993
commit 5819b2b
Showing
2 changed files
with
93 additions
and
10 deletions.
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,77 @@ | ||
--- | ||
title: 'Application menu item extensions' | ||
date: 2024-07-23T00:00:00+00:00 | ||
weight: 60 | ||
geekdocRepo: https://github.com/owncloud/web | ||
geekdocEditPath: edit/master/docs/extension-system/extension-types | ||
geekdocFilePath: app-menu-items.md | ||
geekdocCollapseSection: true | ||
--- | ||
|
||
{{< toc >}} | ||
|
||
## Extension Type AppMenuItem | ||
|
||
This extension type allows apps to register links to internal or external pages within the application switcher menu on the top left. | ||
|
||
### Configuration | ||
|
||
The Interface for an `AppMenuItemExtension` looks like so: | ||
|
||
```typescript | ||
interface AppMenuItemExtension { | ||
id: string | ||
type: 'appMenuItem' | ||
extensionPointIds?: string[] | ||
label: () => string | ||
color?: string | ||
handler?: () => void | ||
icon?: string | ||
path?: string | ||
priority?: number | ||
url?: string | ||
} | ||
``` | ||
|
||
For `id`, `type`, and `extensionPointIds`, please see [extension base section]({{< ref "../_index.md#extension-base-configuration" >}}) in the top level docs. | ||
|
||
A `handler` will result in a `<button>` element. This is necessary when an action should be performed when clicking the menu item (e.g. opening a file editor). | ||
|
||
A `path` will result in a `<a>` element that links to an internal page. That means the given path needs to exist within the application. | ||
|
||
A `url` will result in a `<a>` element that links to an external page. External pages always open in a new tab or window. | ||
|
||
Since these properties are optional, the priority order is `handler` > `path` > `url`. At least one of them has to be provided when registering an extension. | ||
|
||
## Example | ||
|
||
The following example shows how an app creates an extension that registers an app menu item, linking to an internal page. All helper types and composables are being provided via the [web-pkg](https://github.com/owncloud/web/tree/master/packages/web-pkg) package. | ||
|
||
```typescript | ||
export default defineWebApplication({ | ||
setup() { | ||
const { $gettext } = useGettext() | ||
const appId = 'my-cool-app' | ||
|
||
const menuItems = computed<AppMenuItemExtension[]>(() => [ | ||
{ | ||
id: 'com.github.owncloud.web.my-cool-app.menu-item', | ||
type: 'appMenuItem', | ||
label: () => $gettext('My cool app'), | ||
path: urlJoin(appId), | ||
icon: 'star', | ||
color: '#0D856F', | ||
priority: 60 | ||
} | ||
]) | ||
|
||
return { | ||
appInfo: { | ||
name: $gettext('My cool app'), | ||
id: appId | ||
}, | ||
extensions: menuItems | ||
} | ||
} | ||
}) | ||
``` |
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