Extension registry

16/umbraco-cms/.gitbook.yaml

@@ -145,3 +145,4 @@ redirects:
     extending/customize-backoffice: customizing/README.md
     extending/content-apps: customizing/extending-overview/extension-types/workspaces/workspace-views.md
     extending/backoffice-setup/extension-types: customizing/extending-overview/extension-types/README.md
+    customizing/extending-overview/extension-registry/extension-registry: customizing/extending-overview/extension-registry/register-extensions.md

16/umbraco-cms/customizing/extending-overview/extension-registry/README.md

@@ -5,17 +5,19 @@ description: >-
 ---
 
 # Extension Registry
+The Umbraco backoffice is build with extendability in mind. The backoffice without extensions is more or less a blank canvas that is build out using extensions. These extensions dictate how the backoffice functions and looks. All visual elements in an Umbraco installation, like the sections, menu's, trees and buttons, are extensions. But extensions also dictate behaviour and the editing experience. So everything in the backoffice is governed (and extendable) by extensions.
 
-The Extensions Registry is your entry to extend or customize the Backoffice. Therefore, it is crucial to understand the abilities of the Extension Registry.
+{% hint style="info" %}
+You can see in the backoffice what extensions are registered and to go to Settings > Extensions Insights.
+{% endhint %}
 
-## [Extension Registration](extension-registry.md) <a href="#registration" id="registration"></a>
+All extensions are registered in the extension registry. The registry can be manipulated at any time, meaning you can add or remove extensions at runtime. You as a developer have the same possibilities as an Umbraco HQ developer, which means what HQ can do, you can do. This also means that you can change almost everything that is by default present in Umbraco. 
 
-The extension registry is a global registry that can be accessed and changed at any time while Backoffice is running.
+## [Introduction to a Extension Manifest](extension-manifest.md)
+An Extension Manifest is a declaration on what you want to register in the Umbraco backoffice. This articles handles what an extension manifest looks like and what is required or not.
 
-## [Extension Manifest](extension-manifest.md)
-
-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.
-
-## [Replace, Exclude, or Unregister](replace-exclude-or-unregister.md)
+## [Register an extension](extension-registry.md)
+This article handles how to register an extension using an umbraco-package.json file.
 
+## [Change an existing extension](replace-exclude-or-unregister.md)
 Once you understand how to declare your own, you may want to replace or remove existing ones.

16/umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest.md

@@ -3,77 +3,43 @@ description: Learn about the different methods for declaring an Extension Manife
 ---
 
 # Extension Manifest
+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.
 
-The Extension Manifest is the first step for any extension. It is the declaration of what you want to register.
-
-In this section, you will find all the Extension Types provided by the Backoffice. [See all Extension Types here.](../extension-types/)
+## What is an Extension Manifest?
+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.
+Umbraco reads the manifest to register the extension in the Extension Registry.
+Each extension is of a certain type and this determines the required fields of the manifest and its available capabilities.
+An Extension Manifest declares a single backoffice extension along with its configuration.
 
 ## Extension Manifest Format
+Some extensions need extra assets, such as a JavaScript file with a Web Component.
 
-An Extension Manifest can be written as a JavaScript or JSON Object.
-
-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.
+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.
+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).
+### Required Manifest properties
+A minimal Extension Manifest looks like this:
 
-```typescript
+```json
 {
-    type: '...',
-    alias: 'my.customization',
-    name: 'My customization'
-    ...
-};
+    "type": "...",
+    "alias": "my.customization",
+    "name": "My customization"
+}
 ```
 
-The required fields of any Extension Manifest are:
-
-* `type` — The type defines the purpose of the extension. It is used to determine where the extension will be used.
-* `alias` — This is a unique identifier for this manifest. Prefix it with something that makes your extension unique. Example: `mfc.Dashboard.Overview` .
-* `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 Dashboard` .
+These fields are all required and have the following meaning:
 
-### Additional Manifest features
+* `type` — The type defines the purpose of the extension. Umbraco has many [extension types](../extension-types) available.
+* `alias` — This is a unique identifier for this manifest. Prefix it with something that makes your extension unique. For example: _FictiveCompany.MyProject.Dashboard.Overview_.
+* `name` — This is a representational name of this manifest; It does not need to be unique, but this can be beneficial when debugging extensions. This name also shows up in the Extensions Insights in the backoffice of Umbraco. For example: _My Fictive Company Overview Dashboard_.
 
+### Additional Manifest properties
 Most extension types support the use of the following generic features for their Manifest:
 
-* `weight` - Define a weight to determine the importance or visual order of this extension. A higher weight gives a more prominent position.
-* `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).
-* `conditions` - Define one or more conditions that must be permitted for the extension to become available. [Extension Conditions](../extension-conditions.md).
-* `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).
-
-Many of the Extension Types require additional information declared as part of a `meta` field.
-
-## Type intellisense
-
-It is recommended to make use of the Type IntelliSense that we provide.
-
-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.
-
-{% code title="manifests.ts" %}
-```typescript
-export const manifests: Array<UmbExtensionManifest> = [
-    {
-        type: '...',
-        alias: 'my.customization',
-        name: 'My customization'
-        ...
-    }
-]
-```
-{% endcode %}
-
-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` .
-
-```json
-{
-    "$schema": "../../umbraco-package-schema.json",
-    "name": "My Customizations",
-    "extensions": [
-        {
-            "type": "...",
-            "alias": "my.customization",
-            "name": "My customization"
-            ...
-        },
-        ...
-    ]
-}
-```
+* `weight` - Define a weight to determine the importance or visual order of this extension. A higher weight gives a more prominent position. For instance, for a dashboard it determines it's order between other dashboards.
+* `overwrites` - If replacing an existing extension, this define one or more Extension Aliases that this extension should replace. Read more in [Replace, Exclude or Unregister extensions](replace-exclude-or-unregister.md).
+* `conditions` - Define one or more conditions that must pass for the extension to become available. For instance, don't show a section if you don't have the proper rights. Read more in [Extension Conditions](../extension-conditions.md). 
+* `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).
+* `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.
 
+For more information, see an overview of all possible [Extension Types](../extension-types/) and their requirements.

16/umbraco-cms/customizing/extending-overview/extension-registry/register-extensions.md

@@ -0,0 +1,114 @@
+---
+description: >-
+  Bringing new UI or additional features to the Backoffice is done by
+  registering an Extension via an Extension Manifest.
+---
+
+
+# Register Extensions
+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.
+
+## Umbraco-package.json
+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.
+
+{% hint style="info" %}
+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.
+{% endhint %}
+
+{% code title="umbraco-package.json" %}
+```json
+{
+    "name": "My Customizations",
+    "extensions": [
+        {
+            "type": "...",
+            "alias": "my.customization.extension1",
+            "name": "My customization extension 1"
+            ...
+        },
+        ...
+    ]
+}
+```
+{% endcode %}
+
+
+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`.
+
+{% code title="umbraco-package.json" %}
+```json
+{
+    "$schema": "../../umbraco-package-schema.json",
+    "name": "My Customizations",
+    "extensions": [
+        ...
+    ]
+}
+```
+{% endcode %}
+
+
+There are two additional, optional properties that can be useful:
+
+* `id` - a unique identifier of the package. If you are creating a NuGet package, use that as the id.
+* `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.
+
+
+This is an example of a full umbraco-package.json that registers two localization extensions:
+
+```json
+{
+  "$schema": "../../umbraco-package-schema.json",
+  "id": "MyCustomizations",
+  "name": "My Customizations",
+  "version": "16.0.0",
+  "extensions": [
+    {
+      "type": "localization",
+      "alias": "MyCustomizations.Localize.EnUS",
+      "name": "English",
+      "meta": {
+        "culture": "en"
+      },
+      "js": "/App_Plugins/MyCustomizations/localization/en.js"
+    },
+    {
+      "type": "localization",
+      "alias": "MyCustomizations.Localize.NlNl",
+      "name": "Danish",
+      "meta": {
+        "culture": "dk"
+      },
+      "js": "/App_Plugins/MyCustomizations/localization/dk.js"
+    }
+  ]
+}
+```
+
+
+## Advanced Registration
+### The Bundle Approach
+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).
+
+### The Entry Point Approach
+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).
+
+### Registration with JavaScript on the Fly
+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.
+
+The following example shows how to register an Extension Manifest via JavaScript/TypeScript code:
+
+```typescript
+
+import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
+
+const manifest = {
+  type: '...',
+  // ...
+};
+
+umbExtensionsRegistry.register(manifest);
+```
+
+
+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).