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
Almost any UI in the Backoffice is an extension. All managed by the Extension
4
+
Registry on the Client at Runtime. Giving you enourmes flexibility.
5
+
---
2
6
3
-
{% hint style="warning" %}
4
-
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.
5
-
{% endhint %}
7
+
# Extension Registry
6
8
7
-
The Extensions Registry is your entry to extend or customize the Backoffice. Therefor it is crucial to understand the abilities of the Extension Registry.
9
+
The Extensions Registry is your entry to extend or customize the Backoffice. Therefore, it is crucial to understand the abilities of the Extension Registry.
The extension registry is a global registry that can be accessed and changed at anytime while Backoffice is running.
13
+
The extension registry is a global registry that can be accessed and changed at any time while Backoffice is running.
12
14
13
15
## [Extension Manifest](extension-manifest.md)
14
16
15
-
Each Extension Manifest has to declare its type, this is used to determine where it hooks into the system. It also looks at what data is required to declare within it.
17
+
Each Extension Manifest has to declare its type. This is used to determine where it hooks into the system. It also looks at what data is required to declare within it.
16
18
17
19
## [Replace, Exclude, or Unregister](replace-exclude-or-unregister.md)
18
20
19
-
Once you understand how to declare your own, you may want to replace or remove existing.
21
+
Once you understand how to declare your own, you may want to replace or remove existing ones.
Copy file name to clipboardExpand all lines: 16/umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest.md
+15-73Lines changed: 15 additions & 73 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,87 +6,45 @@ description: Learn about the different methods for declaring an Extension Manife
6
6
7
7
The Extension Manifest is the first step for any extension. It is the declaration of what you want to register.
8
8
9
-
In this section you will find all the Extension Types provided by the Backoffice. [See all Extension Types here.](../extension-types/)
9
+
In this section, you will find all the Extension Types provided by the Backoffice. [See all Extension Types here.](../extension-types/)
10
10
11
11
## Extension Manifest Format
12
12
13
13
An Extension Manifest can be written as a JavaScript or JSON Object.
14
14
15
-
There are a few general properties, the required set of properties consists of the `type`, `alias`, and `name`.
15
+
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. Other types require files, like a JavaScript file containing a Web Component.
16
16
17
17
```typescript
18
-
const manifest ={
18
+
{
19
19
type: '...',
20
20
alias: 'my.customization',
21
21
name: 'My customization'
22
22
...
23
23
};
24
24
```
25
25
26
-
The `type` defines what it is declaring. The `alias` is a unique identifier for this manifest. It must be globally unique, so make sure to prefix it with something that makes your extension unique. The `name` is a representational name of this manifest, this does not need to be unique but such can be beneficial when debugging extensions.
27
-
28
-
## Manifest Data
29
-
30
-
Each Extension Manifest has to declare its type. This is used to determine where it hooks into the system. It also determines what data is required of this manifest.
31
-
32
-
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. Other requires files, like a JavaScript file containing a Web Component.
26
+
The required fields of any Extension Manifest are:
33
27
34
-
The required fields of any extension manifest are:
28
+
*`type` — The type defines the purpose of the extension. It is used to determine where the extension will be used.
29
+
*`alias` — This is a unique identifier for this manifest. Prefix it with something that makes your extension unique. Example: `mfc.Dashboard.Overview` .
30
+
*`name` — This is a representational name of this manifest; It does not need to be unique, but this can be beneficial when debugging extensions. Example: `My Fictive Company Overview Dashboar` .
35
31
36
-
*`type` - The type defines the type and purpose of the extension. It is used to determine where the extension will be used and defines the data needed for this manifest.
37
-
*`alias`- The alias is used to identify the extension. This has to be unique for each extension.
38
-
*`name` - The name of the extension. This is used to identify the extension in the UI.
32
+
### Additional Manifest features
39
33
40
-
Additionally, many extensions support the use of the following fields:
34
+
Most extension types support the use of the following generic features for their Manifest:
41
35
42
-
*`weight` - Define a weight, to determine the importance or visual order of this extension. The higher the weight, the higher in the list it will appear.
36
+
*`weight` - Define a weight to determine the importance or visual order of this extension. A higher weight gives a more prominent position.
43
37
*`overwrites` - Define one or more Extension Aliases that this extension should replace. Notice it only omits the listed Extensions when this is rendered in the same spot. [Read more in Replace, Exclude or Unregister](replace-exclude-or-unregister.md).
44
38
*`conditions` - Define one or more conditions that must be permitted for the extension to become available. [Extension Conditions](../extension-conditions.md).
45
-
*`kind` - Define a kind-alias of which this manifest should be based upon. Kinds acts like a preset for your manifest. [Extension Kinds](../extension-kind.md).
39
+
*`kind` - Define a kind-alias of which this manifest should be based upon. Kind acts like a preset for your manifest. [Extension Kinds](../extension-kind.md).
46
40
47
41
Many of the Extension Types require additional information declared as part of a `meta` field.
48
42
49
-
## Registration
50
-
51
-
An Extension Manifest can be registered in multiple ways.
52
-
53
-
The primary registration should take part of the Umbraco Package Manifest.
54
-
55
-
You can choose to declare all Extensions in the Package Manifest, or use one of three Extension Types to registere more extensions.
56
-
57
-
This enables you to locate your Manifests in files together with the implementation code and the ability to declare Extension Manifests in TypeScript.
58
-
59
-
A typical structure would be to declare one or more `Bundle` extensions in the Package Manifest. Each of the Bundles points to a `manifests.js` file which declares the Extensions of interest.
60
-
61
-
### The `bundle` extension type
62
-
63
-
The Bundle extension type is used to declare multiple Extension Manifests from a single JavaScript file.
64
-
65
-
The Bundle is loaded at startup. All the Extension Manifests exported of the JavaScript file will be registered.
66
-
67
-
Read more about the `bundle` extension type in the [Bundle](../extension-types/bundle.md)article.
68
-
69
-
### The `backofficeEntryPoint` extension type
70
-
71
-
Run any JavaScript code when Backoffice startups, after the user is logged in. This can be used as an entry point for a package, registering more extensions or configuring your package.
72
-
73
-
There are many use cases. To name a few, it could be to load external libraries shared by all your extensions or load **global CSS files** for the whole application.
74
-
75
-
The entry point declares a single JavaScript file that will be loaded and run when the Backoffice starts.
76
-
77
-
Read more about the `backofficeEntryPoint` extension type in the [Backoffice Entry Point](../extension-types/backoffice-entry-point.md) article.
78
-
79
-
### The `appEntryPoint` extension type
80
-
81
-
Similar as `appEntryPoint` this runs as startup, the difference is that this runs before the user is logged in. Use this to initiate things before the user is logged in or to provide things for the Login screen.
82
-
83
-
Read more about the `appEntryPoint` extension type in the [App Entry Point](../extension-types/app-entry-point.md) article.
84
-
85
43
## Type intellisense
86
44
87
-
It is recommend to make use of the Type intellisense that we provide.
45
+
It is recommended to make use of the Type IntelliSense that we provide.
88
46
89
-
When writing your Manifest in TypeScript you should use the Type `UmbExtensionManifest`, see the [TypeScript setup](broken-reference) article to make sure you have Types correctly configured.
47
+
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`
62
+
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` .
105
63
106
64
```json
107
65
{
108
66
"$schema": "../../umbraco-package-schema.json",
109
-
"name": "Fast Track Customizations",
67
+
"name": "My Customizations",
110
68
"extensions": [
111
69
{
112
70
"type": "...",
@@ -119,19 +77,3 @@ When writing the Umbraco Package Manifest you can use the JSON Schema located in
119
77
}
120
78
```
121
79
122
-
### Registration via any JavaScript code
123
-
124
-
Alternatively, an Extension Manifest can be declared in JavaScript at any given point.
125
-
126
-
The following example shows how to register an extension manifest via JavaScript code:
Bringing new UI or additional features to the Backoffice is done by
4
+
registering an Extension via an Extension Manifest.
5
+
---
2
6
3
-
{% hint style="warning" %}
4
-
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.
5
-
{% endhint %}
7
+
# Register an Extension
6
8
7
-
The extension registry is the center piece of the Backoffice UI. It holds information about most of the Backoffice UI, as most are extensions. This includes the built-in UI. The registry can be manipulated at any time, meaning you can add or remove extensions at runtime.
9
+
Whether you're looking to make a single correction or a package, it is done via a file on the server that we call Umbraco Package JSON. This will be your starting point.
8
10
9
-
To provide new UI to the backoffice, you must register them via an Extension Manifest. This can be initiated via an Umbraco Package JSON file on the server. This will be your starting point.
11
+
## Umbraco-package.json
10
12
11
-
Declaring a new extension is done by declaring an [extension manifest](extension-manifest.md). This can be done in one of two ways:
13
+
In this file, you declare a name for the Package and declare one or more [`extension manifests`](extension-manifest.md).
12
14
13
-
1. Via a manifest JSON file on the server.
14
-
2. In a JavaScript/TypeScript file.
15
+
```json
16
+
{
17
+
"name": "My Customizations",
18
+
"extensions": [
19
+
{
20
+
"type": "...",
21
+
"alias": "my.customization",
22
+
"name": "My customization"
23
+
...
24
+
},
25
+
...
26
+
]
27
+
}
28
+
```
15
29
16
-
These two options can be combined as you like.
30
+
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`
17
31
18
-
A typical use case of such is achieved by registering a single extension manifest in your Umbraco Package JSON file. This manifest would then load a JS file, that registers the rest of your extensions. Learn more about these abilities in the [bundle](../extension-types/bundle.md) or [backoffice entry point](../extension-types/backoffice-entry-point.md) articles.
32
+
```json
33
+
{
34
+
"$schema": "../../umbraco-package-schema.json",
35
+
"name": "My Customizations",
36
+
"extensions": [
37
+
...
38
+
]
39
+
}
40
+
```
41
+
42
+
## Declare Extensions in JavaScript/TypeScript
43
+
44
+
Are you looking for as much help as you can get, or to make a bigger project? Then it's recommended to spend the time setting up a TypeScript Project for your Customizations. [Read more about Development Setups here](../../development-flow/).
45
+
46
+
TypeScript gives IntelliSense for everything, acting as documentation.
47
+
48
+
The following example demonstrates how you can configure your `umbraco-package.json` file to point to a single JavaScript/TypeScript file that declares all your Manifests.
49
+
50
+
There are two approaches for declaring Manifests in JavaScript/TypeScript. Read more about each option:
The Bundle is an Extension that declares one or more Extension Manifests.
55
+
56
+
### [The Entry Point approach](../extension-types/backoffice-entry-point.md)
57
+
58
+
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.
59
+
60
+
### Registration via any JavaScript code
61
+
62
+
Once you have running code, you can declare an Extension Manifest at any given point.
63
+
64
+
It's not a recommended approach, but for some cases, you may like to register and unregister Extensions on the fly. The following example shows how to register an extension manifest via JavaScript/TypeScript code:
description: The App Entry Point extension type is used to run some JavaScript code before the user is logged in.
2
+
description: >-
3
+
The App Entry Point extension type is used to run some JavaScript code before
4
+
the user is logged in.
3
5
---
4
6
5
7
# App Entry Point
6
8
7
9
This manifest declares a single JavaScript file that will be loaded and run when the Backoffice starts. Additionally, the code will also run on the login screen.
8
10
11
+
{% hint style="info" %}
12
+
See [Backoffice Entry Point](backoffice-entry-point.md) if you are looking for an Extension that runs when the user is logged in.
13
+
{% endhint %}
14
+
9
15
It performs the same function as the `backofficeEntryPoint` extension type, but the difference is that this runs before the user is logged in. Use this to initiate things before the user is logged in or to provide things for the Login screen.
10
16
11
17
Read more about `backofficeEntryPoint` to learn how to use it:
Copy file name to clipboardExpand all lines: 16/umbraco-cms/customizing/extending-overview/extension-types/backoffice-entry-point.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,12 +8,12 @@ description: >-
8
8
9
9
This manifest declares a single JavaScript file that will be loaded and run when the Backoffice starts. In other words, this can be used as an entry point for a package.
10
10
11
-
The `backofficeEntryPoint` extension is also the way to go if you want to load in external libraries such as jQuery, Angular, React, etc. You can use the `backofficeEntryPoint` to load in the external libraries to be shared by all your extensions. Additionally, **global CSS files** can also be used in the `backofficeEntryPoint` extension.
12
-
13
11
{% hint style="info" %}
14
-
See also the [App Entry Point](app-entry-point.md)article for a similar extension type that runs before the user is logged in.
12
+
See [App Entry Point](app-entry-point.md)if you are looking for an Extension that runs before the user is logged in.
15
13
{% endhint %}
16
14
15
+
The `backofficeEntryPoint` extension is also the way to go if you want to load in external libraries such as jQuery, Angular, React, etc. You can use the `backofficeEntryPoint` to load the external libraries to be shared by all your extensions. Additionally, **global CSS files** can also be used in the `backofficeEntryPoint` extension.
16
+
17
17
**Register a Backoffice Entry Point in the `umbraco-package.json` manifest**
It is recommended to make use of the Type intellisense that we provide.
127
127
128
-
When writing your Manifest in TypeScript you should use the Type `UmbExtensionManifest`, see the [TypeScript setup](broken-reference) article to make sure you have Types correctly configured.
128
+
When writing your Manifest in TypeScript, you should use the `UmbExtensionManifest` type. Read the [TypeScript setup](broken-reference/) article to make sure you have Types correctly configured.
129
129
130
130
{% code title="index.ts" %}
131
131
```typescript
@@ -156,7 +156,7 @@ See the Extension Types article for more information about all the different ext
156
156
[.](./)
157
157
{% endcontent-ref %}
158
158
159
-
Read about running code before log in using an `appEntryPoint`:
159
+
Read about running code before logging in using an `appEntryPoint`:
0 commit comments