diff --git a/docs/dev/web/extension-system/extension-types/floating-action-button-extensions.md b/docs/dev/web/extension-system/extension-types/floating-action-button-extensions.md new file mode 100644 index 00000000..a8736440 --- /dev/null +++ b/docs/dev/web/extension-system/extension-types/floating-action-button-extensions.md @@ -0,0 +1,69 @@ +--- +title: 'Floating Action Button extensions' +sidebar_position: 8 +id: floating-action-button-extensions +--- + +## Extension Type FloatingActionButton + +This extension type allows apps to register a global action that is either displayed within the left sidebar (for desktop resolutions) or as a floating action button (for mobile resolutions). The extension point for this extension type is `global.floating-action-button`. + +:::warning +You need to take care of the visibility of your floating action button extension via the `isActive` property, otherwise you might end up overwriting other extensions' action buttons. In most cases, it makes sense to only display the button when your app is currently active. +::: + +### Configuration + +To define a floating action button extension, you implement the `FloatingActionButtonExtension` interface. Here's what it looks like: + +```typescript +interface FloatingActionButtonExtension { + id: string; + type: 'floatingActionButton'; + extensionPointIds?: string[]; + label: () => string; + isActive: () => boolean; + isDisabled?: () => boolean; + color?: string; + icon?: string; + handler?: () => Promise | void; + dropComponent?: Component; +} +``` + +For `id`, `type`, and `extensionPointIds`, please see [extension base section](../#extension-base-configuration) in the top level docs. + +The `handler` property specifies a function to be executed when the floating action button is clicked. If you want to use a dropdown component instead of a click handler, you can specify a `dropComponent` that will be rendered on click. + +`isDisabled` controls the disabled state of the button whereas `isActive` determines if the button is showing at all. + +`icon` is an icon name string that can be picked from [Remix Icon](https://remixicon.com/). + +### Example + +The following example shows how the files app is registering a floating action button extension for creating new files or folders. Note that the example assumes you're in a Vue injection context (e.g. within the `setup` method of your app's `defineWebApplication` call). + +```typescript +import { useGettext } from 'vue3-gettext'; +import CreateOrUploadMenu from './components/CreateOrUploadMenu.vue'; +import { useIsFilesAppActive, useResourcesStore } from '@opencloud-eu/web-pkg'; + +const { $gettext } = useGettext(); +const isFilesAppActive = useIsFilesAppActive(); +const resourcesStore = useResourcesStore(); + +const extension = { + id: 'com.github.opencloud-eu.web.files.floating-action-button', + extensionPointIds: ['global.floating-action-button'], + type: 'floatingActionButton', + icon: 'add', + label: () => $gettext('New'), + isActive: () => { + return unref(isFilesAppActive); + }, + isDisabled: () => { + return !resourcesStore.currentFolder?.canUpload(); + }, + dropComponent: CreateOrUploadMenu +}; +``` diff --git a/docs/dev/web/extension-system/index.md b/docs/dev/web/extension-system/index.md index 9770aad2..17b2bbb1 100644 --- a/docs/dev/web/extension-system/index.md +++ b/docs/dev/web/extension-system/index.md @@ -114,6 +114,8 @@ For building an extension you can choose from the types predefined by the OpenCl For details, please refer to the [folder view docs](./extension-types/folder-view-extensions). 6. `CustomComponentExtension` (type `customComponent`) - An extension that can register a custom component for a render target. For details, please refer to the [custom component docs](./extension-types/custom-component-extensions) +7. `FloatingActionButtonExtension` (type `floatingActionButton`) - An extension that can register a global action that is either displayed within the left sidebar (for desktop resolutions) or as a floating action button (for mobile resolutions). For details, please refer to the + [floating action button docs](./extension-types/floating-action-button-extensions). You're free to introduce your own extension types within your application code and use the extension registry to query the available ones. However, if you have the impression that an important extension type is missing and would be beneficial for the platform, please reach out to us by opening a [GitHub issue](https://github.com/opencloud-eu/web/issues/new/choose). @@ -140,9 +142,16 @@ your extension will be used automatically. 1. Left Sidebar for Navigation. ExtensionPointId `app.${appName}.navItems` (dynamically created for each app). Mounts extensions of type `sidebarNav`. 2. Global top bar 1. Center area. ExtensionPointId `app.runtime.header.center`. Mounts extensions of type `customComponent`. - 2. Progress bar for the global loading state. ExtensionPointId `app.runtime.global-progress-bar`. Mounts a single extensions of type `customComponent`. If multiple exist, the user can choose via the account page. + 2. Left area. ExtensionPointId `app.runtime.header.left`. Mounts extensions of type `customComponent`. + 3. Right area. ExtensionPointId `app.runtime.header.right`. Mounts extensions of type `customComponent`. + 4. Progress bar for the global loading state. ExtensionPointId `app.runtime.global-progress-bar`. Mounts a single extension of type `customComponent`. If multiple exist, the user can choose via the account page. 3. Files app - 1. Right sidebar. ExtensionPointId `app.files.sidebar`. Mounts extensions of type `sidebarPanel`. Used in any file(s) context (files app, file viewer apps, file editor apps). + 1. Right sidebar. + 1. Panels. ExtensionPointId `app.files.sidebar`. Mounts extensions of type `sidebarPanel`. Used in any file(s) context (files app, file viewer apps, file editor apps). + 2. File details table. ExtensionPointId `app.files.sidebar.file-details.table`. Mounts extensions of type `customComponent`. Properties `space` and `resource` can be retrieved via injection context. + 3. Space details table. ExtensionPointId `app.files.sidebar.space-details.table`. Mounts extensions of type `customComponent`. Properties `space` and `resource` can be retrieved via injection context. + 4. Shares panel people list top section. ExtensionPointId `app.files.sidebar.shares-panel.shared-with.top`. Mounts extensions of type `customComponent`. Properties `space` and `resource` can be retrieved via injection context. + 5. Shares panel people list bottom section. ExtensionPointId `app.files.sidebar.shares-panel.shared-with.bottom`. Mounts extensions of type `customComponent`. Properties `space` and `resource` can be retrieved via injection context. 2. Folder views for regular folders. ExtensionPointId `app.files.folder-views.folder`. Mounts extensions of type `folderView`. 3. Folder views for the project spaces overview. ExtensionPointId `app.files.folder-views.project-spaces`. Mounts extensions of type `folderView`. 4. Folder views for the favorites page. ExtensionPointId `app.files.folder-views.favorites`. Mounts extensions of type `folderView`. @@ -154,6 +163,7 @@ your extension will be used automatically. 10. Quick actions for the trash overview. ExtensionPointId `app.files.trash-quick-actions`. Mounts extensions of type `action`. 4. Global search providers. ExtensionPointId `app.search.providers`. Utilizes extensions of type `search` as search engines for the search input in the global top bar. 5. User preference panels. ExtensionPointId `app.runtime.preferences.panels`. Mounts extensions of type `customComponent`. +6. Global Floating Action button. ExtensionPointId `global.floating-action-button`. Mounts extensions of type `floatingActionButton`. #### User Preferences for Extensions