From 5819b2ba9e7f592daec3db3260804e7c900ef772 Mon Sep 17 00:00:00 2001
From: Jannik Stehle <jannik.stehle@kiteworks.com>
Date: Tue, 23 Jul 2024 13:16:06 +0200
Subject: [PATCH] docs: add docs for app menu item extension

---
 .../extension-types/app-menu-items.md         | 77 +++++++++++++++++++
 docs/extension-system/viewer-editor-apps.md   | 26 ++++---
 2 files changed, 93 insertions(+), 10 deletions(-)
 create mode 100644 docs/extension-system/extension-types/app-menu-items.md

diff --git a/docs/extension-system/extension-types/app-menu-items.md b/docs/extension-system/extension-types/app-menu-items.md
new file mode 100644
index 00000000000..fff46e91ba5
--- /dev/null
+++ b/docs/extension-system/extension-types/app-menu-items.md
@@ -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
+    }
+  }
+})
+```
diff --git a/docs/extension-system/viewer-editor-apps.md b/docs/extension-system/viewer-editor-apps.md
index a38b4cd5a2e..95505e674a7 100644
--- a/docs/extension-system/viewer-editor-apps.md
+++ b/docs/extension-system/viewer-editor-apps.md
@@ -29,9 +29,10 @@ To learn more about apps in general, please refer to the [Web app docs]({{< ref
 Inside the `src` folder you will need an `index.ts` file that sets up the app so it can be registered by the Web runtime. It follows the basic structure as described in [the apps section]({{< ref "_index.md#apps" >}}), so it may look like this:
 
 ```typescript
-import { AppWrapperRoute, defineWebApplication } from '@ownclouders/web-pkg'
+import { AppWrapperRoute, defineWebApplication, AppMenuItemExtension } from '@ownclouders/web-pkg'
 import translations from '../l10n/translations.json'
 import { useGettext } from 'vue3-gettext'
+import { computed } from 'vue'
 
 // This is the base component of your app.
 import App from './App.vue'
@@ -60,6 +61,17 @@ export default defineWebApplication({
       }
     ]
 
+    // if you want your app to be present in the app menu on the top left.
+    const menuItems = computed<AppMenuItemExtension[]>(() => [
+      {
+        label: () => $gettext('Advanced PDF Viewer'),
+        type: 'appMenuItem',
+        handler: () => {
+          // do stuff...
+        }
+      }
+    ])
+
     return {
       appInfo: {
         name: 'Advanced PDF Viewer',
@@ -80,17 +92,11 @@ export default defineWebApplication({
               }
             }
           }
-        ],
-
-        // Add this if you want your app to be present in the app menu on the top left.
-        applicationMenu: {
-          enabled: () => true,
-          openAsEditor: true,
-          priority: 10
-        }
+        ]
       },
       routes,
-      translations
+      translations,
+      extensions: menuItems
     }
   }
 })