Merge pull request #11258 from owncloud/feat/app-menu-item-extension-…

…point

feat: add extension point for application menu items

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 an `<a>` element that links to an internal page via the vue router. That means the given path needs to exist within the application.
+
+A `url` will result in an `<a>` element that links to an external page. External pages always open in a new tab or window.
+
+At least one of these properties has to be provided when registering an extension. If you define more than one, the priority order is `handler` > `path` > `url`. 
+
+## 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
+    }
+  }
+})
+```

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
     }
   }
 })