From de16d9b77537c4bfa1200c8262cf87427ac7860f Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Sun, 5 Oct 2025 01:44:32 -0500 Subject: [PATCH 1/3] Revamp "Kind" documentation: clarified descriptions, updated examples for consistency, removed outdated warnings, and refined TypeScript integration details. --- .../extension-types/kind.md | 43 +++++++++++-------- 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md b/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md index 37bb77f1da4..fbe54c0270e 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md @@ -1,14 +1,10 @@ --- -description: A kind extension provides the preset for other extensions to use. +description: Create reusable, standardized configurations for extensions, helping to streamline development, ensure consistency, and reduce duplication. --- # Kind -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -A Kind is a preset configuration that can be inherited by extensions to ensure consistency and reduce redundancy. It defines a set of default properties or behaviors that extensions can adopt, making it easier to maintain and configure extensions that share similar functionality. +A Kind is a preset configuration that extensions can inherit to ensure consistency and reduce redundancy. It defines a set of default properties or behaviors that extensions can adopt, making it easier to maintain and configure extensions that share similar functionality. A Kind is always linked to a specific extension type. Extensions using the same type and referencing a Kind automatically inherit its settings, ensuring uniformity across different extensions. @@ -33,7 +29,7 @@ To register a Kind, use the same method as other extensions. The key properties The following example shows how to register a Button Kind for [**Header Apps**](../extension-types/header-apps.md). This kind provides a preset configuration for a button element that can be reused by other Header App extensions. ```typescript -const manifest: ManifestKind = { +const manifest: ManifestKind = { type: 'kind', alias: 'Umb.Kind.MyButtonKind', // Unique alias for the Kind matchType: 'headerApp', // Applies to Header App extensions @@ -49,7 +45,7 @@ In this example: - `type` is set to 'kind' to register it as a Kind extension. - `matchType` is 'headerApp', specifying that this Kind is for Header App extensions. -- `matchKind` is 'button', which is the alias of the Kind. +- `matchKind` is 'button,' which is the alias of the Kind. - The `manifest` contains default properties like elementName that extensions using this Kind will inherit. ## Using the Kind in Other Extensions @@ -80,14 +76,21 @@ In this example, the Header App extension uses the `kind: 'button'`, meaning it Here’s an example of how to register and use the Button Kind in a Header App extension: +{% code title="kinds/manifests.ts" %} + +{% hint style="warning" %} +This example uses the dynamic extension registration approach. `umbExtensionsRegistry.register()` might be called from within an entrypoint lifecycle method like `onInit()`. For more information, see the [Backoffice Entry Point](./backoffice-entry-point.md) article. +{% endhint %} + ```typescript import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry'; +import type { ManifestKind } from "@umbraco-cms/backoffice/extension-api"; -const manifest: UmbExtensionManifest = { +const manifest: ManifestKind = { type: 'kind', alias: 'Umb.Kind.MyButtonKind', // Alias for the Kind matchType: 'headerApp', // Extension type the Kind applies to - matchKind: 'button', // Defines the Kind alias + matchKind: 'customHeaderAppButton', // Defines the Kind alias manifest: { elementName: 'umb-header-app-button', }, @@ -95,17 +98,24 @@ const manifest: UmbExtensionManifest = { umbExtensionsRegistry.register(manifest); ``` +{% endcode %} -This code registers the Button Kind, so other Header App extensions using `type: 'headerApp'` and `kind: 'button'` will inherit the preset `elementName: 'umb-header-app-button'`. +This code registers the Button Kind, so other Header App extensions using `type: 'headerApp'` and `kind: 'customHeaderAppButton'` will inherit the preset `elementName: 'umb-header-app-button'`. -Now, another Header App extension can be created without defining `elementName`, as it will automatically inherit it from the Kind: +Now another Header App extension can be created without defining `elementName`, as it will automatically inherit it from the Kind: + +{% code title="kinds/manifests.ts" %} + +{% hint style="warning" %} +This example uses the dynamic extension registration approach. `umbExtensionsRegistry.register()` might be called from within an entrypoint lifecycle method like `onInit()`. For more information, see the [Backoffice Entry Point](./backoffice-entry-point.md) article. +{% endhint %} ```typescript -import { extensionRegistry } from '@umbraco-cms/extension-registry'; +import { umbExtensionsRegistry } from "@umbraco-cms/backoffice/extension-registry"; const manifest = { type: 'headerApp', // Extension type - kind: 'button', // References the 'button' Kind + kind: 'customHeaderAppButton', // References the matchKind property ('customHeaderAppButton') name: 'My Header App Example', alias: 'My.HeaderApp.Example', meta: { @@ -115,9 +125,8 @@ const manifest = { }, }; -extensionRegistry.register(manifest); +umbExtensionsRegistry.register(manifest); ``` +{% endcode %} By referencing the Kind, the extension inherits shared properties like `elementName`, ensuring consistency and reducing redundancy across extensions. This method also makes it easier to update configurations across multiple extensions. - -By using Kinds, you can create reusable, standardized configurations for extensions, helping to streamline development, ensure consistency, and reduce duplication. Understanding how to register and reference Kinds effectively will enhance the maintainability of your Umbraco extensions. From 00b9df3596d5c40f073627d815b388f8ff36ff9f Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Tue, 7 Oct 2025 12:11:09 -0500 Subject: [PATCH 2/3] formatting lint --- .../customizing/extending-overview/extension-types/kind.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md b/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md index fbe54c0270e..ef986bda541 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md @@ -45,7 +45,7 @@ In this example: - `type` is set to 'kind' to register it as a Kind extension. - `matchType` is 'headerApp', specifying that this Kind is for Header App extensions. -- `matchKind` is 'button,' which is the alias of the Kind. +- `matchKind` is 'button', which is the alias of the Kind. - The `manifest` contains default properties like elementName that extensions using this Kind will inherit. ## Using the Kind in Other Extensions From 4b1e29a7def873abed4c84b0fe673ac5105999d5 Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Wed, 22 Oct 2025 03:57:07 -0500 Subject: [PATCH 3/3] Addressing Andy's feedback --- .../extending-overview/extension-types/kind.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md b/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md index ef986bda541..010d92656ad 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/kind.md @@ -29,7 +29,9 @@ To register a Kind, use the same method as other extensions. The key properties The following example shows how to register a Button Kind for [**Header Apps**](../extension-types/header-apps.md). This kind provides a preset configuration for a button element that can be reused by other Header App extensions. ```typescript -const manifest: ManifestKind = { +import type { UmbExtensionManifestKind } from "@umbraco-cms/backoffice/extension-registry"; + +export const customHeaderAppButton: UmbExtensionManifestKind = { type: 'kind', alias: 'Umb.Kind.MyButtonKind', // Unique alias for the Kind matchType: 'headerApp', // Applies to Header App extensions @@ -41,7 +43,7 @@ const manifest: ManifestKind = { }; ``` -In this example: +Properties: - `type` is set to 'kind' to register it as a Kind extension. - `matchType` is 'headerApp', specifying that this Kind is for Header App extensions. @@ -78,15 +80,15 @@ Here’s an example of how to register and use the Button Kind in a Header App e {% code title="kinds/manifests.ts" %} -{% hint style="warning" %} +{% hint style="info" %} This example uses the dynamic extension registration approach. `umbExtensionsRegistry.register()` might be called from within an entrypoint lifecycle method like `onInit()`. For more information, see the [Backoffice Entry Point](./backoffice-entry-point.md) article. {% endhint %} ```typescript import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry'; -import type { ManifestKind } from "@umbraco-cms/backoffice/extension-api"; +import type { UmbExtensionManifestKind } from "@umbraco-cms/backoffice/extension-registry"; -const manifest: ManifestKind = { +export const customHeaderAppButton: UmbExtensionManifestKind = { type: 'kind', alias: 'Umb.Kind.MyButtonKind', // Alias for the Kind matchType: 'headerApp', // Extension type the Kind applies to @@ -105,11 +107,6 @@ This code registers the Button Kind, so other Header App extensions using `type: Now another Header App extension can be created without defining `elementName`, as it will automatically inherit it from the Kind: {% code title="kinds/manifests.ts" %} - -{% hint style="warning" %} -This example uses the dynamic extension registration approach. `umbExtensionsRegistry.register()` might be called from within an entrypoint lifecycle method like `onInit()`. For more information, see the [Backoffice Entry Point](./backoffice-entry-point.md) article. -{% endhint %} - ```typescript import { umbExtensionsRegistry } from "@umbraco-cms/backoffice/extension-registry";