Merge pull request #7538 from umbraco/v17/cms/additional-preview-kinds

CMS V17: Document different "kinds" of workspaceActionMenuItem (relevant for additional preview environments)

Author: eshanrnh

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' },
 }
-```
+```

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