diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/workspaces/workspace-action-menu-items.md b/17/umbraco-cms/customizing/extending-overview/extension-types/workspaces/workspace-action-menu-items.md index 6c83776811f..46fabd60b57 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/workspaces/workspace-action-menu-items.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/workspaces/workspace-action-menu-items.md @@ -34,6 +34,58 @@ Workspace Action Menu Items extend existing workspace actions by adding dropdown - **`meta.label`** - Text displayed in dropdown - **`meta.icon`** - Icon displayed alongside label +## Kinds + +The `kind` property determines the behavior and purpose of the workspace action menu item. Each kind provides specialized functionality for different use cases. + +### default + +The `default` kind provides standard menu item functionality for executing custom actions. + +**Properties:** +- **`api`** - Class that extends `UmbWorkspaceActionMenuItemBase` and implements either `execute()` or `getHref()` method +- **`meta.label`** - Text displayed in the menu item +- **`meta.icon`** - Optional icon displayed alongside the label + +The API class provides either a `getHref()` method or an `execute()` method. If the `getHref()` method is provided, the action will open the returned URL. Otherwise, the `execute()` method will be run when the menu item is clicked. + +**Use case:** General purpose menu items that execute custom logic or navigate to a URL when clicked. + +### previewOption + +The `previewOption` kind creates menu items for document preview scenarios, integrating with server-side URL providers to generate preview URLs for different environments. + +**Properties:** +- **`meta.label`** - Text displayed in the menu item +- **`meta.icon`** - Icon displayed alongside the label +- **`meta.urlProviderAlias`** - Alias of the server-side `IUrlProvider` that generates the preview URL + +**Use case:** Custom preview options that open documents in different preview environments (staging, production, or custom domains). + +{% code caption="Custom Preview Option Manifest" %} +```typescript +{ + type: 'workspaceActionMenuItem', + kind: 'previewOption', + alias: 'My.Custom.PreviewOption', + name: 'My Custom Preview Option', + forWorkspaceActions: 'Umb.WorkspaceAction.Document.SaveAndPreview', + weight: 101, + meta: { + icon: 'icon-umbraco', + label: 'Preview on Staging', + urlProviderAlias: 'MyStagingUrlProvider', + }, +} +``` +{% endcode %} + +{% hint style="info" %} +The `previewOption` kind requires a server-side `IUrlProvider` to be registered with the matching `urlProviderAlias`. The provider generates the preview URL when the menu item is clicked. + +Learn more about implementing server-side URL providers in the [Additional preview environments support](../../../../reference/content-delivery-api/additional-preview-environments-support.md) article. +{% endhint %} + ## Implementation Create a workspace action menu item by extending `UmbWorkspaceActionMenuItemBase` and implementing the `execute` method. This provides the functionality that runs when a user interacts with the menu item: @@ -50,7 +102,7 @@ export class ExampleResetCounterMenuItemAction extends UmbWorkspaceActionMenuIte if (!context) { throw new Error('Could not get the counter context'); } - + context.reset(); } } @@ -84,9 +136,9 @@ Menu items display a dropdown menu for their associated actions: } { - type: 'workspaceActionMenuItem', + type: 'workspaceActionMenuItem', alias: 'example.menuItem.saveAsDraft', forWorkspaceActions: 'example.workspaceAction.save', meta: { label: 'Save as Draft' }, } -``` \ No newline at end of file +``` diff --git a/17/umbraco-cms/reference/content-delivery-api/additional-preview-environments-support.md b/17/umbraco-cms/reference/content-delivery-api/additional-preview-environments-support.md index cd22ac1bbe4..1e5d0acf4c8 100644 --- a/17/umbraco-cms/reference/content-delivery-api/additional-preview-environments-support.md +++ b/17/umbraco-cms/reference/content-delivery-api/additional-preview-environments-support.md @@ -82,7 +82,9 @@ On the client side, you'll need an extension of: - Kind: `previewOption`. {% hint style="info" %} -You can read more about extensions in the [Extending the Umbraco Backoffice](https://docs.umbraco.com/welcome/getting-started/developing-websites-with-umbraco/extending-the-umbraco-backoffice) article. +Learn more about the `previewOption` kind and workspace action menu items in the [Workspace Action Menu Items](../../customizing/extending-overview/extension-types/workspaces/workspace-action-menu-items.md) article. + +You can also read more about extensions in the [Extending the Umbraco Backoffice](https://docs.umbraco.com/welcome/getting-started/developing-websites-with-umbraco/extending-the-umbraco-backoffice) article. {% endhint %} Here's a sample extension: @@ -121,4 +123,13 @@ The default "Save and preview" button is also an extension of this type. In other words, multiple preview options can co-exist. If you have multiple external environments, you can create preview options for all of them. The extension `weight` determines the order of appearance. A `weight` above 100 will swap the default preview option with the custom one. + +{% hint style="tip" %} +**Alternative approach without server-side URL provider** + +If you want to create a preview option that opens a specific URL without server-side logic, you can use the `default` kind instead of `previewOption`. With the `default` kind, you provide an `api` class that implements a `getHref()` method to return the URL to open. + +This is useful for static preview URLs or when you can construct the preview URL entirely on the client side. + +Learn more in the [Workspace Action Menu Items](../../customizing/extending-overview/extension-types/workspaces/workspace-action-menu-items.md#default) article. {% endhint %}