You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 15/umbraco-cms/customizing/extending-overview/extension-kind.md
+15-14Lines changed: 15 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,29 +8,29 @@ description: Learn how to use the Kind extension in your manifest files when ext
8
8
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.
9
9
{% endhint %}
10
10
11
-
Extension Manifest Kind enables declarations to be based upon a preset Manifest.
11
+
The **Extension Manifest Kind** is used to declare a preset configuration that other extensions can inherit. It ensures maintainability and consistency when creating extensions for the Umbraco CMS backoffice. By using a Kind, developers can reuse predefined settings, which reduces redundancy across extensions.
12
12
13
-
This is used for maintainability or to inherit existing features.
13
+
When a Kind is applied, the extension's manifest inherits the fields defined in the Kind. This approach prevents the need to repeat configuration details across multiple extensions.
14
14
15
15
## Manifest Kind Declaration
16
16
17
-
A Kind is utilized by declaring it in the `kind` field of a Manifest:
17
+
A **Kind** is declared in the `kind` field of the manifest, which is part of the extension registration process. The declaration is linked to a specific extension type.
18
18
19
19
```typescript
20
20
const manifest = {
21
-
type: 'headerApp',
22
-
kind: 'button',
21
+
type: 'headerApp',// The type of the extension
22
+
kind: 'button',// The kind alias to inherit settings from
23
23
...
24
24
};
25
25
```
26
26
27
-
By declaring a kind, the Manifest will inherit fields of the defined Kind.
27
+
By setting the `kind` field, the extension automatically inherits all properties associated with that **Kind**. This is useful when you want to standardize a component (like a button) across multiple extensions.
28
28
29
-
A typical use case is a Kind that provides an element, but requires additional meta fields, to fulfill the needs of its element.
29
+
## Using the Kind for Inheritance
30
30
31
-
In the following example, a manifest using the type 'headerApp' utilizes the 'button' kind. This brings an element and requires some additional information as part of the meta object.
31
+
A Kind not only defines the basic configuration but may also require additional metadata to fully configure the element or component.
32
32
33
-
Adding the metadata provides the ability to use and configure existing functionality to a specific need.
33
+
### Example: Using the Button Kind in a Header App
34
34
35
35
```typescript
36
36
const manifest = {
@@ -46,10 +46,11 @@ const manifest = {
46
46
};
47
47
```
48
48
49
-
## Learn more
49
+
In this example:
50
+
51
+
- The `kind: 'button'` inherits all default settings from the **Button Kind**.
52
+
- The `meta` object is added to configure additional properties, such as the button's label, icon, and the URL to open when clicked.
50
53
51
-
Learn more about Kinds and how to create your own:
54
+
The Kind allows you to extend existing functionality and tailor it to specific needs while maintaining consistency.
52
55
53
-
{% content-ref url="extension-types/kind.md" %}
54
-
Kind Extension Type
55
-
{% endcontent-ref %}
56
+
For a deeper dive into Kind and how to create your own, see the [Kind](extension-types/kind.md) article.
description: A kind extension provides the preset for other extensions to use
2
+
description: A kind extension provides the preset for other extensions to use.
3
3
---
4
4
5
5
# Kind
@@ -8,56 +8,86 @@ description: A kind extension provides the preset for other extensions to use
8
8
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.
9
9
{% endhint %}
10
10
11
-
A kind is matched with a specific type. When another extension uses that type and kind it will inherit the preset manifest of the kind extension.
11
+
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.
12
12
13
-
The registration of Kinds is done in the same manner as the registration of other extensions. But the format of it is different. Let's take a look at an example of how to implement the `Kind registration` for a [**Header App**](../extension-types/header-apps.md)**Button Kind**.
13
+
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.
14
14
15
-
## Understanding the Kind Extension
15
+
## Benefits of Using a Kind
16
16
17
-
The root properties of this object define the `Kind registration`. Then the manifest property holds the preset for the extension using this kind to be based upon. This object can hold the property values that make sense for the Kind.
17
+
- Reduces redundancy – Common settings are defined once and reused across extensions.
18
+
- Ensures consistency – Extensions using the same Kind follow a standardized structure and behavior.
To register a Kind, use the same method as other extensions. The key properties that define a Kind registration are:
24
+
25
+
-`type`: Always set to `kind`.
26
+
-`alias`: A unique identifier for the Kind.
27
+
-`matchType`: Specifies the extension type that the Kind applies to.
28
+
-`matchKind`: Defines the Kind alias, which extensions must reference.
29
+
-`manifest`: Contains the preset values that extensions will inherit.
21
30
31
+
### Example: Registering a Button Kind for Header Apps
32
+
33
+
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.
34
+
35
+
```typescript
22
36
const manifest:ManifestKind= {
23
37
type: 'kind',
24
-
alias: 'Umb.Kind.MyButtonKind',
25
-
matchType: 'headerApp',
26
-
matchKind: 'button',
38
+
alias: 'Umb.Kind.MyButtonKind',// Unique alias for the Kind
39
+
matchType: 'headerApp',// Applies to Header App extensions
40
+
matchKind: 'button',// Defines the Kind alias
27
41
manifest: {
28
-
...
42
+
// Add default properties for the 'button' Kind
43
+
elementName: 'umb-header-app-button',
29
44
},
30
45
};
31
-
32
-
...
33
46
```
34
47
35
-
For the kind to be used, it needs to match up with the registration of the extension using it. This happens when the extension uses a type, which matches the value of `matchType` of the Kind. As well the extension has to utilize that kind, by setting the value of `kind` to the value of `matchKind` the Kind.
48
+
In this example:
36
49
37
-
```typescript
38
-
...
50
+
-`type` is set to 'kind' to register it as a Kind extension.
51
+
-`matchType` is 'headerApp', specifying that this Kind is for Header App extensions.
52
+
-`matchKind` is 'button', which is the alias of the Kind.
53
+
- The `manifest` contains default properties like elementName that extensions using this Kind will inherit.
54
+
55
+
## Using the Kind in Other Extensions
39
56
57
+
To use the Kind in other extensions, the extension must reference it by setting the `type` and `kind` properties. The extension will automatically inherit the Kind's properties.
58
+
59
+
### Example: Header App Extension Using the Button Kind
60
+
61
+
```typescript
40
62
const manifest = {
41
-
type: 'headerApp',
42
-
kind: 'button',
43
-
...
63
+
type: 'headerApp', // Extension type
64
+
kind: 'button', // References the 'button' Kind
65
+
name: 'My Header App Example',
66
+
alias: 'My.HeaderApp.Example',
67
+
meta: {
68
+
label: 'My Example',
69
+
icon: 'icon-home',
70
+
href: '/some/path/to/open/when/clicked',
71
+
},
44
72
};
45
73
46
-
...
74
+
extensionRegistry.register(manifest);
47
75
```
48
76
49
-
## Kind example
77
+
In this example, the Header App extension uses the `kind: 'button'`, meaning it inherits the `elementName` defined in the Button Kind. The extension can still add custom properties (like metadata in this case) to further customize the behavior or appearance.
78
+
79
+
## Kind Example
50
80
51
-
In the following example, a kind is registered. This kind provides a default element for extensions utilizing this kind.
81
+
Here’s an example of how to register and use the Button Kind in a Header App extension:
This enables other extensions to use this kind and inherit the manifest properties defined in the kind.
99
+
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'`.
70
100
71
-
In this example a **Header App** is registered without defining an element, this is possible because the registration inherits the elementName from the kind.
101
+
Now, another Header App extension can be created without defining `elementName`, as it will automatically inherit it from the Kind:
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.
122
+
123
+
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.
0 commit comments