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: 16/umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest.md
+5-45Lines changed: 5 additions & 45 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,16 +6,16 @@ description: Learn about the different methods for declaring an Extension Manife
6
6
This page explains what an Extension Manifests for Umbraco backoffice extensions is. It outlines the manifest structure, required fields, and optional features used across types.
7
7
8
8
## What is an Extension Manifest?
9
-
An Extension Manifest declares a single backoffice extension and its configuration.
9
+
This page explains what an Extension Manifest for Umbraco backoffice extensions is. It outlines the manifest structure, required fields, and optional features used across types.
10
10
Umbraco reads the manifest to register the extension in the Extension Registry.
11
11
Each extension is of a certain type and this determines the required fields of the manifest and its available capabilities.
12
-
Some extensions need extra assets, like a JavaScript file with a Web Component.
12
+
An Extension Manifest declares a single backoffice extension along with its configuration.
13
13
14
14
## Extension Manifest Format
15
-
An Extension Manifest has a strict format where some properties are required and some depend on the Extension Type. An Extension Manifest can be written as a JavaScript or JSON Object. We'll dive deeper into that when [registering an extension](extension-registry).
15
+
Some extensions need extra assets, such as a JavaScript file with a Web Component.
16
16
17
17
The abilities of the extensions rely on the specific extension type. The Type sets the scene for what the extension can do and what it needs to be utilized. Some extension types can be made purely via the manifest, like a section or menu item. Other types require files, like a JavaScript file containing a Web Component, like a custom property editor.
18
-
18
+
An Extension Manifest has a strict format where some properties are required and some depend on the Extension Type. An Extension Manifest can be written as a JavaScript or JSON object. You can learn more about this when [registering an extension](extension-registry).
19
19
### Required Manifest properties
20
20
A minimal Extension Manifest looks like this:
21
21
@@ -42,44 +42,4 @@ Most extension types support the use of the following generic features for their
42
42
*`kind` - Some extension types can reference a predefined Kind. By specifying a Kind, the manifest inherits the Kind's properties. This allows for reuse of predefined settings. See [Extension Kind](../extension-kind.md).
43
43
*`meta` - Many Extension Types require additional information declared as part of a `meta` field. It depends on the extension what is required. For instance label and icon of a menu item.
44
44
45
-
For more information, see an overview of all possible [Extension Types](../extension-types/) and their requirements.
46
-
47
-
48
-
---- Below should be moved or removed, because it requires too much context for this file -----
49
-
50
-
## Type intellisense
51
-
It is recommended to make use of the Type IntelliSense that we provide.
52
-
53
-
When writing your Manifest in TypeScript, you should use the Type `UmbExtensionManifest`. See the article on [Development Setup](../../development-flow/) to ensure you have Types correctly configured.
When writing the Umbraco Package Manifest, you can use the JSON Schema located in the root of your Umbraco project called `umbraco-package-schema.json` .
69
-
70
-
```json
71
-
{
72
-
"$schema": "../../umbraco-package-schema.json",
73
-
"name": "My Customizations",
74
-
"extensions": [
75
-
{
76
-
"type": "...",
77
-
"alias": "my.customization",
78
-
"name": "My customization"
79
-
...
80
-
},
81
-
...
82
-
]
83
-
}
84
-
```
85
-
45
+
For more information, see an overview of all possible [Extension Types](../extension-types/) and their requirements.
Copy file name to clipboardExpand all lines: 16/umbraco-cms/customizing/extending-overview/extension-registry/register-extensions.md
+25-17Lines changed: 25 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,11 +4,13 @@ description: >-
4
4
registering an Extension via an Extension Manifest.
5
5
---
6
6
7
-
# Register extensions
8
-
Whether you're looking to make extensions in the context of an Umbraco project or a package, you always need a specific JSON file for this, the umbraco-package.json file. This is the starting point of any extension.
7
+
8
+
# Register Extensions
9
+
Whether you are looking to make extensions in the context of an Umbraco project or a package, you always need a specific JSON file for this: the umbraco-package.json file. This is the starting point for any extension.
10
+
9
11
10
12
## Umbraco-package.json
11
-
To get extensions registered in Umbraco, you need to have an `umbraco-package.json` file. This file needs to be located in `wwwroot/App_Plugins/#YOUR_EXTENSION_NAME#`. Umbraco scans for these files on boot and reads the [`extension manifests`](extension-manifest.md) that are present in the file to register the extensions.
13
+
To get extensions registered in Umbraco, you need to have an `umbraco-package.json` file. This file must be located in or in a subfolder of either the `App_Plugins` folder or the `wwwroot` folder. It's recommended to place the file in `App_Plugins/#YOUR_EXTENSION_NAME#/umbraco-package.json`, or in `wwwroot/App_Plugins/#YOUR_EXTENSION_NAME#/umbraco-package.json` for packages and Razor Class Libraries. Umbraco scans for these files on boot and reads the [`Extension Manifests`](extension-manifest.md) that are present in the file to register the extensions.
12
14
13
15
{% hint style="info" %}
14
16
Even though the file is called umbraco-package.json and even though it will be displayed in the 'installed packages' overview in the backoffice, it does not mean that extensions can only work in the context of a package.
@@ -31,7 +33,8 @@ Even though the file is called umbraco-package.json and even though it will be d
31
33
```
32
34
{% endcode %}
33
35
34
-
When writing the Umbraco Package Manifest, you can use the JSON Schema located in the root of your Umbraco project. The file is called `umbraco-package-schema.json`
36
+
37
+
When writing the Umbraco Package Manifest, you can use the JSON Schema located in the root of your Umbraco project. The file is called `umbraco-package-schema.json`.
35
38
36
39
{% code title="umbraco-package.json" %}
37
40
```json
@@ -45,11 +48,13 @@ When writing the Umbraco Package Manifest, you can use the JSON Schema located i
45
48
```
46
49
{% endcode %}
47
50
48
-
There are two additional properties that are not required, but can be useful:
51
+
52
+
There are two additional, optional properties that can be useful:
49
53
50
54
*`id` - a unique identifier of the package. If you are creating a NuGet package, use that as the id.
51
55
*`version` - the version of the package that is displayed in the backoffice in the overview of installed packages. This is also used for package migrations.
52
56
57
+
53
58
This is an example of a full umbraco-package.json that registers two localization extensions:
54
59
55
60
```json
@@ -81,27 +86,30 @@ This is an example of a full umbraco-package.json that registers two localizatio
81
86
}
82
87
```
83
88
84
-
## Advanced registration
85
-
### The bundle approach
86
-
Instead of registering each manifest in the `umbraco-package.json` you can have multiple manifests and build them into a bundle. You then register this bundle in a single `bundle` extension. In larger projects with a lot of extensions, this allows you to keep your umbraco-package.json file leaner. Read more in the [bundle approach](../extension-types/bundle.md).
87
89
88
-
### The entry point approach
89
-
The Entry Point is an Extension that executes a method on startup. This can be used for different tasks, such as performing initial configuration and registering other Extension Manifests. Read more in [the entry point approach](../extension-types/backoffice-entry-point.md).
90
+
## Advanced Registration
91
+
### The Bundle Approach
92
+
Instead of registering each manifest in the `umbraco-package.json`, you can have multiple manifests and build them into a bundle. You then register this bundle in a single `bundle` extension. In larger projects with a lot of extensions, this allows you to keep your umbraco-package.json file leaner. Read more in the [bundle approach](../extension-types/bundle.md).
93
+
94
+
### The Entry Point Approach
95
+
The Entry Point is an extension that executes a method on startup. You can use this for different tasks, such as performing initial configuration and registering other Extension Manifests. Read more in [the entry point approach](../extension-types/backoffice-entry-point.md).
90
96
91
-
### Registration with JavaScript on the fly
92
-
In some cases, extensions are not static and cannot be registered in the umbraco-package.json or in a bundle. For instance, your manifest gets defined based on information from the server. Or you can even generate the manifests server side based on data in the database. In that case, you need to register extensions on the fly.
97
+
### Registration with JavaScript on the Fly
98
+
In some cases, extensions are not static and cannot be registered in the umbraco-package.json or in a bundle. For instance, your manifest might be defined based on information from the server, or you might generate the manifests server side based on data in the database. In that case, you need to register extensions on the fly.
93
99
94
-
The following example shows how to register an extension manifest via JavaScript/TypeScript code:
100
+
The following example shows how to register an Extension Manifest via JavaScript/TypeScript code:
When and where to execute this code is up to you and depending on your situation. But in a lot of cases, it makes sense to execute this on boot, using the [the entry point approach](../extension-types/backoffice-entry-point.md).
114
+
115
+
When and where you execute this code depends on your situation. In many cases, it makes sense to execute this on boot, using the [entry point approach](../extension-types/backoffice-entry-point.md).
Copy file name to clipboardExpand all lines: 16/umbraco-cms/customizing/extending-overview/extension-registry/replace-exclude-or-unregister.md
+20-9Lines changed: 20 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,12 +4,15 @@ description: >-
4
4
interest, 3 different options are available.
5
5
---
6
6
7
+
7
8
# Replace, Exclude or Unregister
8
-
Besides adding extensions to Umbraco, sometimes you want to change what's already there. You can replace extensions with your own and exclude or unregister extensions.
9
+
Besides adding extensions to Umbraco, sometimes you want to change what is already there. You can replace extensions with your own and exclude or unregister extensions.
10
+
9
11
10
12
## Replace
11
13
You can have an extension that replaces another extension.
12
-
This can be done by defining `overwrites` of your [manifest](extension-manifest.md) with one Extension-alias or an array of Extension-aliases that need to be replaced.
14
+
You can do this by defining the `overwrites` property in your [Extension Manifest](extension-manifest.md) with one Extension Alias or an array of Extension Aliases that need to be replaced.
15
+
13
16
14
17
15
18
@@ -25,6 +28,7 @@ const manifest = {
25
28
};
26
29
```
27
30
31
+
28
32
This example overrides both the save and preview button as well as the save button with an external preview button (multiple overwrite):
29
33
30
34
```typescript
@@ -37,35 +41,42 @@ const manifest = {
37
41
};
38
42
```
39
43
40
-
If your extension has conditions, then the overwrites will only be hidden when your extension is displayed. This means that the overwrites only have an effect if all the conditions are permitted and the extensions are displayed at the same spot.
44
+
45
+
If your extension has conditions, the overwritten extensions will only be hidden when your extension is displayed. This means that the overwrites only have an effect if all the conditions are permitted and the extensions are displayed at the same spot.
46
+
41
47
42
48
## Exclude
43
-
When you exclude an extension, the extension will never be displayed. This allows for permanently hiding for example a menu or a button. This does not unregister the extensions, but rather flags it as excluded. This also means that no-one else can register an extension with the same alias as the excluded extension.
49
+
When you exclude an extension, the extension will never be displayed. This allows you to permanently hide, for example, a menu or a button. This does not unregister the extensions, but rather flags them as excluded. This also means that no one else can register an extension with the same alias as the excluded extension.
50
+
44
51
45
52
{% hint style="warning" %}
46
-
Currently, it's not possible to un-exclude extensions once excluded.
53
+
Currently, it is not possible to un-exclude extensions once excluded.
47
54
{% endhint %}
48
55
56
+
49
57
The following JavaScript code hides the `Save and Preview` button from the Document Workspace.
When and where to execute this code is up to you and depending on your situation. But in a lot of cases, it makes sense to execute this on boot, using the [the entry point approach](../extension-types/backoffice-entry-point.md).
64
+
65
+
When and where you execute this code depends on your situation. In many cases, it makes sense to execute this on boot, using the [entry point approach](../extension-types/backoffice-entry-point.md).
66
+
57
67
58
68
## Unregister
59
-
You can also choose to unregister an extension. It's recommended to only use this of on extension you registered yourself and have control over. Otherwise you might try to remove an extension before it's registered. A use case for this is if you temporarily registered an extension and you like to remove it again.
69
+
You can also choose to unregister an extension. You should only use this on extensions you registered yourself and have control over. Otherwise, you might try to remove an extension before it is registered. A use case for this is if you temporarily registered an extension and you want to remove it again.
60
70
61
-
In other cases you can use the `overwrites` or `exclude` option. The difference with the `exclude` approach, is that unregistering removes the extension from the extension registry. This allows for re-registering extensions with the same alias.
71
+
In other cases, you can use the `overwrites` or `exclude` option. The difference with the `exclude` approach is that unregistering removes the extension from the Extension Registry. This allows you to re-register extensions with the same alias.
When and where to execute this code is up to you and depending on your situation. But in a lot of cases, it makes sense to execute this on boot, using the [the entry point approach](../extension-types/backoffice-entry-point.md).
79
+
80
+
When and where you execute this code depends on your situation. In many cases, it makes sense to execute this on boot, using the [entry point approach](../extension-types/backoffice-entry-point.md).
0 commit comments