First draft done

Author: Luuk Peters

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

@@ -7,13 +7,17 @@ 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.
 
-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. You can see in the backoffice what extensions are registered by going to Settings > Extensions Insights.
+{% hint style="info" %}
+You can see in the backoffice what extensions are registered and to go to Settings > Extensions Insights.
+{% endhint %}
+
+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. 
 
 ## [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 handles what an extension manifest looks like and what is required or not.
+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.
 
 ## [Register an extension](extension-registry.md)
-The extension registry is a global registry that can be accessed and changed at any time while Backoffice is running.
+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,13 +3,12 @@ description: Learn about the different methods for declaring an Extension Manife
 ---
 
 # Extension Manifest
-This page explains how to author Extension Manifests for Umbraco backoffice extensions.
-It outlines the manifest structure, required fields, and optional features used across types.
+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.
 
 ## What is an Extension Manifest?
 An Extension Manifest declares a single backoffice extension and its configuration.
 Umbraco reads the manifest to register the extension in the Extension Registry.
-The chosen extension type determines required fields and available capabilities.
+Each extension is of a certain type and this determines the required fields of the manifest and its available capabilities.
 Some extensions need extra assets, like a JavaScript file with a Web Component.
 
 ## Extension Manifest Format
@@ -18,7 +17,7 @@ An Extension Manifest has a strict format where some properties are required and
 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.
 
 ### Required Manifest properties
-A minimal Extension Manifest looks like this (in JSON formatting):
+A minimal Extension Manifest looks like this:
 
 ```json
 {

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

@@ -5,30 +5,35 @@ description: >-
 ---
 
 # Register extensions
-
-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.
+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.
 
 ## Umbraco-package.json
+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.
 
-In this file, you declare a name for the Package and declare one or more [`extension manifests`](extension-manifest.md).
+{% 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",
-            "name": "My customization"
+            "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",
@@ -38,30 +43,55 @@ When writing the Umbraco Package Manifest, you can use the JSON Schema located i
     ]
 }
 ```
+{% endcode %}
 
-## Declare Extensions in JavaScript/TypeScript
-
-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/).
-
-TypeScript gives IntelliSense for everything, acting as documentation.
-
-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.
-
-There are two approaches for declaring Manifests in JavaScript/TypeScript. Read more about each option:
+There are two additional properties that are not required, but can be useful:
 
-### [The Bundle approach](../extension-types/bundle.md)
+* `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.
 
-The Bundle is an Extension that declares one or more Extension Manifests.
+This is an example of a full umbraco-package.json that registers two localization extensions:
 
-### [The Entry Point approach](../extension-types/backoffice-entry-point.md)
+```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"
+    }
+  ]
+}
+```
 
-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.
+## 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).
 
-### Registration via any JavaScript code
+### The entry point approach
+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).
 
-Once you have running code, you can declare an Extension Manifest at any given point.
+### 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 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. 
 
-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:
+The following example shows how to register an extension manifest via JavaScript/TypeScript code:
 
 ```typescript
 import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
@@ -73,3 +103,5 @@ const manifest = {
 
 umbExtensionsRegistry.register(extension);
 ```
+
+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).

16/umbraco-cms/customizing/extending-overview/extension-registry/replace-exclude-or-unregister.md

@@ -5,14 +5,15 @@ description: >-
 ---
 
 # Replace, Exclude or Unregister
+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.
 
 ## Replace
+You can have an extension that replaces another extension.
+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.
 
-If you want to bring your own extension and remove an existing,  define your Extension to replace one or more other Extensions.
 
-This can be done by defining `overwrites` of your manifest with one Extension-alias or an array of Extension-aliases. [Read more about the Manifest Declaration here.](extension-manifest.md)
 
-Overwrite a single extension:
+This example overrides the save and preview button with an external preview button (single overwrite):
 
 ```typescript
 const manifest = {
@@ -24,7 +25,7 @@ const manifest = {
 };
 ```
 
-Overwrite multiple extensions:
+This example overrides both the save and preview button as well as the save button with an external preview button (multiple overwrite):
 
 ```typescript
 const manifest = {
@@ -36,13 +37,14 @@ const manifest = {
 };
 ```
 
-Once your extension is displayed in the same spot as the one defined in `overwrites`, those will be hidden.
-
 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.
 
 ## Exclude
+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.
 
-To make an extension go away completely, you should exclude it. This approach secures that the extension will never be presented.
+{% hint style="warning" %}
+Currently, it's not possible to un-exclude extensions once excluded.
+{% endhint %}
 
 The following JavaScript code hides the `Save and Preview` button from the Document Workspace.
 
@@ -51,17 +53,19 @@ import { UmbExtensionRegistry } from '@umbraco-cms/backoffice/extension-api';
 
 UmbExtensionRegistry.exclude('Umb.WorkspaceAction.Document.SaveAndPreview');
 ```
+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).
 
 ## Unregister
+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.
 
-You can also choose to unregister an extension, this is only preferred if you registered the extension and are in control of the flow. If it's not your Extension please seek to use the `Overwrites` or `Exclude` feature.
+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.
 
 ```typescript
 import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
 
 umbExtensionsRegistry.unregister('My.WorkspaceAction.AutoFillWithUnicorns');
 ```
 
-This will not prevent the Extension from being registered again.
+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).
+
 
-A use case for this is if you temporarily registered an extension and you like to remove it again.