Add 15 stuff and also #6533

sofietoft · sofietoft · commit 61b081bd2671 · 2024-11-06T09:55:52.000+01:00
diff --git a/15/umbraco-cms/SUMMARY.md b/15/umbraco-cms/SUMMARY.md
@@ -30,6 +30,8 @@
   * [Property Editors](fundamentals/backoffice/property-editors/README.md)
     * [Built-in Property Editors](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/README.md)
       * [Image Cropper](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/image-cropper.md)
+      * [Block Editors](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md)
+        * [Block Grid](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/block-grid-editor.md)
 
 ## Implementation
 
@@ -83,6 +85,7 @@
   * [Web routing](reference/configuration/webroutingsettings.md)
 * [Querying & Models](reference/querying/README.md)
   * [ITagQuery](reference/querying/itagquery.md)
+  * [UmbracoContext helper](reference/querying/umbraco-context.md)
 * [Routing & Controllers](reference/routing/README.md)
   * [Routing in Umbraco](reference/routing/request-pipeline/README.md)
     * [IContentFinder](reference/routing/request-pipeline/icontentfinder.md)
diff --git a/15/umbraco-cms/release-candidate-guide.md b/15/umbraco-cms/release-candidate-guide.md
@@ -79,6 +79,8 @@ Here is a list of all the articles that are new to this version or have been upd
   * [Working with Caching: Tags example](reference/cache/examples/tags.md)
   * [Unit Testing](implementation/unit-testing.md)
   * [Querying: ITagQuery](reference/querying/itagquery.md)
+  * [UmbracoContext helper](reference/querying/umbraco-context.md)
+  * [Block Grid](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/block-grid-editor.md)
 
 * Replacing the deprecated GetAll() method
   * [Working with Caching: Tags example](reference/cache/examples/tags.md)
diff --git a/15/umbraco-deploy/deployment-workflow/import-export-v7.md b/15/umbraco-deploy/deployment-workflow/import-export-v7.md
@@ -1,17 +1,16 @@
 ---
-meta.Title: Migrating from Umbraco 7
 description: How to export content and schema from Umbraco 7 and import into a newer version
 ---
 
-### Migrating from Umbraco 7
+# Migrating from Umbraco 7
 
-The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from there in the same way.
+The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from the backoffice or use the service.
 
-We can use this feature to help migrate from Umbraco 7 to a supported major version. However, it requires additional logic to be added to the Deploy Contrib project.
+However, you can still use this feature to help migrate from Umbraco 7 to a supported major version. This requires adding additional logic to your Umbraco 7 project to create an export ZIP archive similar to newer versions.
 
-#### Exporting Umbraco 7 content and schema
+## Exporting Umbraco 7 content and schema
 
-We can generate an export archive in the same format as used by the import/export feature. This is done by adding the [`Umbraco.Deploy.Contrib.Export` assembly](https://github.com/umbraco/Umbraco.Deploy.Contrib/releases/tag/release-2.0.0-export) to your Umbraco 7 project. This archive can then be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents.
+You can generate an export archive in the same format as the import/export feature. This is done by adding the [`Umbraco.Deploy.Contrib.Export` assembly](https://github.com/umbraco/Umbraco.Deploy.Contrib/releases/tag/release-2.0.0-export) to your Umbraco 7 project (that already has Deploy and Deploy Contrib installed, see below). This archive can be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents.
 
 This is possible via code, by temporarily applying a composer to an Umbraco 7 project to generate the export archive on start-up:
 
@@ -88,7 +87,7 @@ public class DeployExportApplicationHandler : ApplicationEventHandler
 
 </details>
 
-#### Importing Umbraco 7 content and schema
+## Importing Umbraco 7 content and schema
 
 To import this archive into a newer Umbraco project, you need to install either of these packages:
 
@@ -150,6 +149,9 @@ internal class LegacyImportComposer : IComposer
         builder.DeployArtifactMigrators()
             .AddLegacyMigrators()
             .Append<ElementTypeArtifactMigrator>();
+        
+        builder.DeployPropertyTypeMigrators()
+            .AddLegacyMigrators(); // Available from Deploy Contrib 13.3.0 and 14.2.0+
     }
 
     private class ElementTypeArtifactMigrator : ElementTypeArtifactMigratorBase
@@ -167,23 +169,23 @@ internal class LegacyImportComposer : IComposer
 It is recommended to start by importing only the schema and schema files (by deselecting 'Content' and 'Content files' in the dialog). Then, you can proceed with importing all content and schema together. The order in which the artifacts are imported depends on their dependencies. By importing the schema first, we ensure that the schema is updated before any content is processed.
 {% endhint %}
 
-#### Obtaining Umbraco Deploy for Umbraco 7
+## Obtaining Umbraco Deploy for Umbraco 7
 
 Umbraco Deploy for Umbraco 7 is no longer supported and was only available on Umbraco Cloud. It was not released for use on-premise.
 
 As such if you are looking to migrate from an Umbraco Cloud project running on Umbraco 7, you already have Umbraco Deploy installed.
 
-If you have an Umbraco 7 on-premise website, you can use this guide to migrate from on-premise to Umbraco Cloud. Or to upgrade to a newer Deploy on-premise version. You will need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature.
+If you have an Umbraco 7 on-premises website, you can use this guide to migrate from on-premises to Umbraco Cloud. Or to upgrade to a newer Deploy On-premises version. You need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature.
 
 The export feature can be used without a license.
 
 {% hint style="info" %}
 
-A license is required for the Umbraco project you are importing into. This can be a license that comes as part of an Umbraco Cloud subscription, or an on-premise one.
+A license is required for the Umbraco project you are importing into. This can be a license that comes as part of an Umbraco Cloud subscription, or a Deploy On-premises one.
 
 {% endhint %}
 
-Use this guide to migrate from on-premise to Umbraco Cloud or to upgrade to a newer Deploy version on-premise.
+Use this guide to migrate from on-premises to Umbraco Cloud or to upgrade to a newer Deploy On-premises version.
 
 1. Download the required `dll` files for Umbraco Deploy for Umbraco 7 from the following links:
 
diff --git a/15/umbraco-deploy/deployment-workflow/import-with-migrations.md b/15/umbraco-deploy/deployment-workflow/import-with-migrations.md
@@ -1,5 +1,4 @@
 ---
-meta.Title: Import with migrations in Umbraco Deploy
 description: How to import content and schema while migrating them into newer alternatives
 ---
 
@@ -15,7 +14,7 @@ For example, we can migrate from a Nested Content property in Umbraco 8 to a Blo
 
 We provide the necessary migration hooks for this to happen, divided into two types - **artifact migrators** and **property migrators**.
 
-### Artifact migrators
+## Artifact migrators
 
 Artifact migrators work by transforming the serialized artifact of any imported artifact, via two interfaces:
 
@@ -37,7 +36,7 @@ We've also made available base implementations that you can use to build your ow
 - `ArtifactJsonMigratorBase<TArtifact>` - migrates the JSON of the specified artifact type
 - `ReplaceGridDataTypeArtifactMigratorBase` - migrates a Data Type based on the legacy Grid layout into the Block Grid
 
-### Property migrators
+## Property migrators
 
 Property migrators work to transform the content property data itself. They are used in the Deploy content connectors (documents, media and members) when the property editor is changed during an import:
 
@@ -60,7 +59,7 @@ And a base type to help you build your own migrations:
 Property editor changes are determined by comparing the `PropertyEditorAliases` dictionary stored in the content artifact to the current Content Type/Data Type configuration. The dictionary contains editor aliases for each content property.
 {% endhint %}
 
-### Registering migrators
+## Registering migrators
 
 Migrators will run if you have registered them, so you can enable only the ones needed for your solution.
 
@@ -84,21 +83,50 @@ internal class ArtifactMigratorsComposer : IComposer
             .Append<MediaPickerPropertyTypeMigrator>();
     }
 }
- ```
+```
 
-### Details of Specific Migrations
+## Import and migration flow
+
+When an import is started, the following happens:
+
+1. Artifact signatures are read from the import provider (using `IArtifactImportProvider.GetArtifactSignatures()`).
+2. The artifact signatures are sorted based on dependencies with `Ordering` enabled (ensuring dependent items are processed in the correct order, like parent items before children and data types before document types).
+3. For each artifact signature:
+   1. Check whether the entity type is allowed to be imported.
+   2. Publish an `ArtifactImportingNotification` (cancelling will skip importing the artifact).
+4. Publish a `ValidateArtifactImportNotification`:
+   - Deploy adds a default handler (`ValidateArtifactImportDependenciesNotificationHandler`) to validate whether all dependencies are either in the import or already present in the current environment. It emits warnings for missing content artifacts, missing or different artifact checksums and errors for missing schema artifacts.
+   - The import fails on validation errors or 'soft' fails on warnings if the `WarningsAsErrors` import option is set.
+5. Create a Deploy scope and context (containing the 'owner' user for auditing purposes and cultures to import, in case the user doesn't have edit permissions for all languages).
+6. For each artifact signature:
+   1. Create a (readonly) `Stream` for the artifact (using `IArtifactImportProvider.CreateArtifactReadStream(Udi)`).
+   2. Deserialize the artifact into a generic JSON object (`JsonNode`).
+   3. Parse the `__version` and `__type` properties and resolve the artifact type (using `IArtifactTypeResolver`).
+   4. Migrate the JSON object (using `IArtifactJsonMigrator`).
+   5. Deserialize the JSON object into the artifact type.
+   6. Migrate the artifact (using `IArtifactMigrator`).
+   7. Initialize artifact processing (using `IServiceConnector.ProcessInit(...)`) and track deploy state with next passes.
+7. For each next process pass (starting at the lowest initial next pass):
+   1. Process artifact (using `IServiceConnector.Process(...)`).
+   2. During processing: service connectors for content, media and members migrate property type values if a property editor alias has changed (using `IPropertyTypeMigrator`).
+   3. When no next pass is required (the deploy state returns -1 as next pass):
+      1. Publish an `ArtifactImportedNotification`.
+      2. Report the import process (using `IProgress.Report(...)`).
+8. The Deploy scope is completed, causing all scoped notifications to be published to handlers implementing `IDistributedCacheNotificationHandler`) and completing the import.
+
+## Details of Specific Migrations
 
 Umbraco Deploy ships with migrators to handle the conversion of core property editors as they have changed, been removed or replaced between versions.
 
-Open source migrators may be built by HQ or the community for property editors found in community packages. They will be made available for [use](https://www.nuget.org/packages/Umbraco.Deploy.Contrib) and [review](https://github.com/umbraco/Umbraco.Deploy.Contrib/tree/v13/dev/src/Umbraco.Deploy.Contrib/Migrators) via the `Umbraco.Deploy.Contrib` package.
+Open source migrators may be built by HQ or the community for property editors found in community packages. They will be made available for [use](https://www.nuget.org/packages/Umbraco.Deploy.Contrib) and [review](https://github.com/umbraco/Umbraco.Deploy.Contrib/tree/v15/dev/src/Umbraco.Deploy.Contrib/Migrators) via the `Umbraco.Deploy.Contrib` package.
 
-#### Grid to Block Grid
+### Grid to Block Grid
 
-The grid editor introduced in Umbraco 7 has been removed from Umbraco 14. It's functionality is replaced with the Block Grid.
+The Grid editor introduced in Umbraco 7 has been removed from Umbraco 14. Its functionality is replaced with the Block Grid.
 
 With Deploy migrators we have support for migrating Data Type configuration and property data between these property editors.
 
-You can configure the default migration with the following composer:
+Deploy adds the `ReplaceGridDataTypeArtifactMigrator` and `GridPropertyTypeMigrator` migrators by default, so using a custom migrator requires replacing the default ones:
 
 ```csharp
 using Umbraco.Cms.Core.Composing;
@@ -109,20 +137,24 @@ internal sealed class DeployMigratorsComposer : IComposer
     public void Compose(IUmbracoBuilder builder)
     {
         builder.DeployArtifactMigrators()
-            .Append<ReplaceGridDataTypeArtifactMigrator>();
+            .Replace<ReplaceGridDataTypeArtifactMigrator, CustomReplaceGridDataTypeArtifactMigrator>();
 
         builder.DeployPropertyTypeMigrators()
-            .Append<GridPropertyTypeMigrator>();
+            .Replace<GridPropertyTypeMigrator, CustomGridPropertyTypeMigrator>();
     }
 }
 ```
 
+{% hint style="info" %}
+The project you are importing into needs to know about any custom legacy Grid editor configurations to migrate to the Block Grid editor correctly. Make sure to either copy the `grid.editors.config.js` and `package.manifest` (containing grid editors) files or override the `GetGridEditors()` method of the artifact migrator to provide this.
+{% endhint %}
+
 These implementations make use of the following conventions to migrate the data:
 
 - `ReplaceGridDataTypeArtifactMigrator`:
   - Grid layouts are migrated to an existing or new element type with an alias based on the layout name, prefixed with `gridLayout_` (this can be customized by overriding `MigrateGridTemplate()`);
   - Row configurations are migrated to an existing or new element type with an alias based on the row name, prefixed with `gridRow_` (this can be customized by overriding `MigrateGridLayout()`);
-  - Similarly, grid editors are migrated to an existing or new element type with an alias based on the editor alias, prefixed with `gridEditor_` (this can be customized by overriding `MigrateGridEditor()`). The available editors are retrieved from the `grid.editors.config.js` files (can be overridden in `GetGridEditors()`). Each migrated grid editor will have the following property types added to the element type:
+  - Similarly, grid editors are migrated to an existing or new element type with an alias based on the editor alias, prefixed with `gridEditor_` (this can be customized by overriding `MigrateGridEditor()`). The default editors used in version 13 are returned by `GetGridEditors()` and you can override this method to include your custom editors. Each migrated grid editor will have the following property types added to the element type:
     - The `media` grid editor is migrated to multiple properties: the `value` property contains the selected media item (using Media Picker v3), `altText` the alternate text (using a Textbox) and `caption` the caption (also using a Textbox);
     - The remaining grid editors create a single `value` property that uses the following editors:
       - `rte` - the default 'Rich Text Editor', falling back to the first `Umbraco.TinyMCE` editor.
@@ -170,7 +202,7 @@ The base classes provide the following functionality. Methods you should look to
   - Similarly, if a layout block can be found for the grid layout name, all items are wrapped into that block.
   - The JSON serialized `BlockValue` is returned.
 
-#### Migrating From Doc Type Grid Editor
+### Migrating From Doc Type Grid Editor
 
 [Doc Type Grid Editor](https://our.umbraco.com/packages/backoffice-extensions/doc-type-grid-editor/) was a community package commonly used with the legacy grid editor. If you are using this with Umbraco 7 and up, you can export and migrate into the Block Grid on Umbraco 13 or above.
 
@@ -200,7 +232,11 @@ The migrators add the following behavior:
 - `ReplaceDocTypeGridEditorDataTypeArtifactMigrator` extends `ReplaceGridDataTypeArtifactMigrator` and ensures any DocTypeGridEditor is migrated to blocks using the allowed element types. If the element types aren't found the default implementation will migrate to new element types.
 - `DocTypeGridEditorPropertyTypeMigrator` extends `GridPropertyTypeMigrator` and ensures the Doc Type Grid Editor values are mapped one-to-one to the block item data.
 
-#### Migrating from Matryoshka
+{% hint style="info" %}
+The artifact migrator adds the default DocTypeGridEditor configuration (with alias `docType`). This can be disabled by setting the `AddDefaultDocTypeGridEditor` property to `false` in a custom/inherited class. Similar to the base migrator, any custom DocTypeGridEditor configurations must be available to migrate to the Block Grid editor correctly.
+{% endhint %}
+
+### Migrating from Matryoshka
 
 [Matryoshka](https://our.umbraco.com/packages/backoffice-extensions/matryoshka-tabs-for-umbraco-8/) was an Umbraco package that added tab support for document types in Umbraco. The feature was subsequently added to the product itself.
 
@@ -224,7 +260,7 @@ internal sealed class DeployMigratorsComposer : IComposer
 }
 ```
 
-### Source Code Example -  Nested Content to Block List
+## Source Code Example -  Nested Content to Block List
 
 As described above, the nested content to block list migration will occur register the corresponding migrator with your application.
 
