From e2deda3eb1768bdd608bc8c990854e0d8a4776c6 Mon Sep 17 00:00:00 2001
From: Jannik Stehle <50302941+JammingBen@users.noreply.github.com>
Date: Thu, 14 Mar 2024 07:20:13 +0000
Subject: [PATCH] docs: add documentation for viewer and editor apps (#10592)

* docs: add documentation for viewer and editor apps

* docs: apply text suggestions from code review

* docs: add referer to the new docs section

* docs: refer to the web service docs for integration
---
 extension-system/_index.md             |   4 +
 extension-system/viewer-editor-apps.md | 118 +++++++++++++++++++++++++
 2 files changed, 122 insertions(+)
 create mode 100644 extension-system/viewer-editor-apps.md

diff --git a/extension-system/_index.md b/extension-system/_index.md
index 3262476b7ed..97eafb34249 100644
--- a/extension-system/_index.md
+++ b/extension-system/_index.md
@@ -84,6 +84,10 @@ 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.
 
+If you want to learn how to implement an app for viewing and editing specific file types, please consult the [relevant documentation]({{< ref "viewer-editor-apps.md" >}}) for detailed instructions and guidance.
+
+To learn how to integrate an app into ownCloud Web, please refer to the [Web service docs]({{< ref "web.md#web-apps" >}}).
+
 ### Extensions
 
 In contrast to applications, extensions usually have a rather small scope and dedicated functionality.
diff --git a/extension-system/viewer-editor-apps.md b/extension-system/viewer-editor-apps.md
new file mode 100644
index 00000000000..24f0a2906c0
--- /dev/null
+++ b/extension-system/viewer-editor-apps.md
@@ -0,0 +1,118 @@
+---
+title: 'Viewer and editor apps'
+date: 2024-03-12T00:00:00+00:00
+weight: 60
+geekdocRepo: https://github.com/owncloud/web
+geekdocEditPath: edit/master/docs/extension-system
+geekdocFilePath: viewer-editor-apps.md
+geekdocCollapseSection: true
+---
+
+{{< toc >}}
+
+## Viewer and editor apps
+
+ownCloud Web allows developers to implement apps for viewing and editing specific file types. For instance, the built-in preview app serves as the default application for opening media files like images, videos, or audio.
+
+This section will guide you through the process of implementing such an app within ownCloud Web.
+
+### Basic app structure
+
+An app is essentially a distinct package that must be specified as an external application in the Web configuration.
+
+The structure of an app is quite simple and straightforward. Consider, for example, the [draw.io app](https://github.com/owncloud/web/tree/master/packages/web-app-draw-io). It consists of a `package.json` file, a `src` directory containing all the source code, and a `l10n` directory for translations. Optionally, you may also include a `tests` directory if your application requires testing.
+
+To learn more about apps in general, please refer to the [Web app docs]({{< ref "_index.md#apps" >}}).
+
+### App setup
+
+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 translations from '../l10n/translations.json'
+import { useGettext } from 'vue3-gettext'
+
+// This is the base component of your app.
+import App from './App.vue'
+
+export default defineWebApplication({
+  setup() {
+    // The ID of your app.
+    const appId = 'advanced-pdf-viewer'
+
+    const { $gettext } = useGettext()
+
+    // This creates a route under which your app can be opened.
+    // Later, this route will be bound to one or more file extensions.
+    const routes = [
+      {
+        name: 'advanced-pdf-viewer',
+        path: '/:driveAliasAndItem(.*)?',
+        component: AppWrapperRoute(App, {
+          applicationId: appId
+        }),
+        meta: {
+          authContext: 'hybrid',
+          title: $gettext('Advanced PDF Viewer'),
+          patchCleanPath: true
+        }
+      }
+    ]
+
+    return {
+      appInfo: {
+        name: 'Advanced PDF Viewer',
+        id: appId,
+        defaultExtension: 'pdf',
+        isFileEditor: true,
+        extensions: [
+          // This makes sure all files with the "pdf" extension will be routed to your app when being opened.
+          // See the `ApplicationFileExtension` interface down below for a list of all possible properties.
+          {
+            extension: 'pdf',
+            routeName: 'advanced-pdf-viewer',
+
+            // Add this if you want your app to be present in the "New" file menu.
+            newFileMenu: {
+              menuTitle() {
+                return $gettext('PDF document')
+              }
+            }
+          }
+        ],
+
+        // 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
+    }
+  }
+})
+```
+
+Here is the interface defining the `extensions` property of the `appInfo` object.
+
+```typescript
+interface ApplicationFileExtension {
+  app?: string
+  extension?: string
+  createFileHandler?: (arg: {
+    fileName: string
+    space: SpaceResource
+    currentFolder: Resource
+  }) => Promise<Resource>
+  hasPriority?: boolean
+  label?: string
+  name?: string
+  icon?: string
+  mimeType?: string
+  newFileMenu?: { menuTitle: () => string }
+  routeName?: string
+}
+```