Updated articles

Author: eshanrnh

15/umbraco-ui-builder/advanced/events.md

@@ -1,14 +1,16 @@
 ---
-description: Configuring event handlers in Umbraco UI Builder, the backoffice UI builder for Umbraco.
+description: Configuring event handlers in Umbraco UI Builder.
 ---
 
 # Events
 
-Umbraco UI Builder fires a number of notification events during regular operation to allow for extending of the default behaviour.
+Umbraco UI Builder triggers different notification events during operation, allowing customization of default behavior.
 
-## Registering event handlers
+## Registering Event Handlers
 
-Umbraco UI Builder uses the same [Notification Mechanism built into Umbraco v9+](../../umbraco-cms/fundamentals/code/subscribing-to-notifications.md) and so uses the same registration process. First you will need to define a notification event handler for the event you wish to handle like below:
+Umbraco UI Builder follows the [Umbraco Notification mechanism](../../umbraco-cms/fundamentals/code/subscribing-to-notifications.md) for event registration.
+
+Define a notification event handler for the target event:
 
 ```csharp
 public class MyEntitySavingEventHandler :  INotificationHandler<EntitySavingNotification> {
@@ -21,7 +23,7 @@ public class MyEntitySavingEventHandler :  INotificationHandler<EntitySavingNoti
 }
 ```
 
-Then register your event handler in the `Program.cs` file like below:
+Register the event handler in `Program.cs`:
 
 ```csharp
 builder.CreateUmbracoBuilder()
@@ -33,15 +35,15 @@ builder.CreateUmbracoBuilder()
     .Build();
 ```
 
-## Repository events
+## Repository Events
+
+### Using the `EntitySavingNotification()`
 
-### **EntitySavingNotification**
+Triggers when `Save` is called before persisting the entity. The notification contains an `Entity` property with `Before` and `After` values, providing access to the previous and updated entities. Modify the `After` entity to persist changes. If the `Cancel` property of the notification is set to `true` then the save operation will be canceled and no changes will be saved.
 
-Raised when the repository `Save` method is called and before the entity has been persisted. The notification contains an `Entity` property with `Before` and `After` inner properties. These properties provide access to a copy of the currently persisted entity (or null if a new entity) and the updated entity that´s saved.
-Changes can be made to the `After` entity and they will be persisted as part of the save operation. If the `Cancel` property of the notification is set to `true` then the save operation will be canceled and no changes will be saved.
+#### Example
 
 ```csharp
-// Example
 public class MyEntitySavingEventHandler :  INotificationHandler<EntitySavingNotification> {
 
     public void Handle(EntitySavingNotification notification)
@@ -53,14 +55,15 @@ public class MyEntitySavingEventHandler :  INotificationHandler<EntitySavingNoti
     }
 
 }
-````
+```
 
-### **EntitySavedNotification**
+### Using the `EntitySavedNotification()`
 
-Raised when the repository `Save` method is called and after the entity has been persisted. The notification contains an `Entity` property with `Before` and `After` inner properties. These properties provide access to a copy of the previously persisted entity (or null if a new entity) and the updated entity that´s saved.
+Triggers when the repository `Save` method is called and after the entity has been persisted. The notification contains an `Entity` property with `Before` and `After` inner properties. These properties provide access to a copy of the previously persisted entity (or null if a new entity) and the updated entity that´s saved.
 
-````csharp
-// Example
+#### Example
+
+```csharp
 public class MyEntitySavedEventHandler :  INotificationHandler<EntitySavedNotification> {
 
     public void Handle(EntitySavedNotification notification)
@@ -74,12 +77,13 @@ public class MyEntitySavedEventHandler :  INotificationHandler<EntitySavedNotifi
 }
 ```
 
-### **EntityDeletingNotification**
+### Using the `EntityDeletingNotification()`
+
+Triggers when the repository `Delete` method is called and **before** the entity is deleted. The notification contains an `Entity` property providing access to a copy of the entity about to be deleted. If the `Cancel` property of notification is set to `true` then the delete operation will be cancelled and entity won't be deleted.
 
-Raised when the repository `Delete` method is called and **before** the entity is deleted. The notification contains an `Entity` property providing access to a copy of the entity about to be deleted. If the `Cancel` property of notification is set to `true` then the delete operation will be cancelled and entity won't be deleted.
+#### Example
 
-````csharp
-// Example
+```csharp
 public class MyEntityDeletingEventHandler :  INotificationHandler<EntityDeletingNotification> {
 
     public void Handle(EntityDeletingNotification notification)
@@ -91,14 +95,15 @@ public class MyEntityDeletingEventHandler :  INotificationHandler<EntityDeleting
     }
 
 }
-````
+```
+
+### Using the `EntityDeletedNotification()`
 
-### **EntityDeletedNotification**
+Triggers when the repository `Delete` method is called and **after** the entity has been deleted. The notification contains an `Entity` property providing access to a copy of the entity that´s deleted.
 
-Raised when the repository `Delete` method is called and **after** the entity has been deleted. The notification contains an `Entity` property providing access to a copy of the entity that´s deleted.
+#### Example
 
 ```csharp
-// Example
 public class MyEntityDeletedEventHandler :  INotificationHandler<EntityDeletedNotification> {
 
     public void Handle(EntityDeletedNotification notification)
@@ -112,12 +117,13 @@ public class MyEntityDeletedEventHandler :  INotificationHandler<EntityDeletedNo
 }
 ```
 
-### **SqlQueryBuildingNotification**
+### Using the `SqlQueryBuildingNotification()`
 
-Raised when the repository is **preparing** a SQL query. The notification contains the collection alias + type, the NPoco `Sql<ISqlContext>` object, and the where clause/order by clauses. These will be used to generate the SQL query.
+Triggers when the repository is **preparing** a SQL query. The notification contains the collection alias + type, the NPoco `Sql<ISqlContext>` object, and the where clause/order by clauses. These will be used to generate the SQL query.
+
+#### Example
 
 ```csharp
-// Example
 public class MySqlQueryBuildingEventHandler :  INotificationHandler<SqlQueryBuildingNotification> {
 
     public void Handle(SqlQueryBuildingNotification notification)
@@ -128,12 +134,13 @@ public class MySqlQueryBuildingEventHandler :  INotificationHandler<SqlQueryBuil
 }
 ```
 
-### **SqlQueryBuiltNotification**
+### Using the `SqlQueryBuiltNotification()`
+
+Triggers when the repository has **repaired** a SQL query. The notification contains the collection alias + type, the NPoco `Sql<ISqlContext>` object and the where clause/order by clauses that was used to generate the SQL query.
 
-Raised when the repository has **repaired** a SQL query. The notification contains the collection alias + type, the NPoco `Sql<ISqlContext>` object and the where clause/order by clauses that was used to generate the SQL query.
+#### Example
 
 ```csharp
-// Example
 public class MySqlQueryBuiltEventHandler :  INotificationHandler<SqlQueryBuiltNotification> {
 
     public void Handle(SqlQueryBuiltNotification notification)
@@ -144,12 +151,13 @@ public class MySqlQueryBuiltEventHandler :  INotificationHandler<SqlQueryBuiltNo
 }
 ```
 
-## Repository events validation
+## Repository Events Validation
+
+From version `15.1.0`, complex server-side validation can be added to a collection using the `CancelOperation` method of the notification.
 
-Starting with version `15.1.0`, complex server-side validation can be added to a collection by calling the `CancelOperation` method of the notification.
+### Example
 
 ```csharp
-// Example
 public class MyEntitySavingEventHandler :  INotificationHandler<EntitySavingNotification> {
 
     public void Handle(EntitySavingNotification notification)

15/umbraco-ui-builder/advanced/virtual-sub-trees.md

@@ -1,5 +1,5 @@
 ---
-description: Configuring virtual sub trees in Umbraco UI Builder, the backoffice UI builder for Umbraco.
+description: Configuring virtual sub trees in Umbraco UI Builder.
 ---
 
 # Virtual SubTrees
@@ -8,52 +8,73 @@ description: Configuring virtual sub trees in Umbraco UI Builder, the backoffice
 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.
 {% endhint %}
 
-Virtual subtrees are a powerful feature that allows you to inject an Umbraco UI Builder tree structure into another Umbraco tree at a desired location. Thus acting as child nodes to the node chosen as the injection point. With virtual subtrees it allows you to extend built in or even 3rd party package trees with additional features. An example could be developing a "loyalty point" program for your e-commerce site and injecting the related database tables into a Vendr store tree. This allows the management of the program in its most logical location.
+Virtual subtrees inject an Umbraco UI Builder tree structure into another Umbraco tree at a specified location, acting as child nodes of the injection point. They extend built-in or third-party package trees with additional features. For example a "loyalty points" program for an e-commerce site can inject related database tables into a Commerce store tree, making management more intuitive.
 
-![Example virtual sub tree injected into a Vendr store tree](../images/virtual-sub-tree.png)
+![Virtual sub tree injected into a Commerce store tree](../images/virtual-sub-tree.png)
 
-## Defining virtual SubTrees
+## Defining Virtual SubTrees
 
-You define a virtual subtree by calling one of the `AddVirtualSubTree` methods of a [`WithTreeConfigBuilder`](../areas/trees.md#extending-an-existing-tree) instance.
+Use the `AddVirtualSubTree` methods of a [WithTreeConfigBuilder](../areas/trees.md#extending-an-existing-tree) instance to define a virtual subtree.
 
-### **AddVirtualSubTree(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder**
+### Using the `AddVirtualSubTree()` Method
 
-Adds a virtual subtree to the current tree with its visibility controlled via the visibility expression.
+Adds a virtual subtree to the current tree with visibility controlled by the specified expression.
+
+#### Method Syntax
+
+```csharp
+AddVirtualSubTree(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder
+```
+
+#### Example
 
 ````csharp
-// Example
 withTreeConfig.AddVirtualSubTree(ctx => ctx.Source.Id == 1056, contextAppConfig => {
     ...
 });
 ````
 
-### **AddVirtualSubTreeBefore(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda matchExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder**
+### Using the `AddVirtualSubTreeBefore()` Method
+
+Adds a virtual subtree to the current tree **before** the tree node matches the match expression, with its visibility controlled by the specified expression.
+
+#### Method Syntax
 
-Adds a virtual subtree to the current tree, **before** the tree node matches the match expression, with its visibility controlled via the visibility expression.
+```csharp
+AddVirtualSubTreeBefore(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda matchExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder
+```
+
+#### Example
 
 ````csharp
-// Example
 withTreeConfig.AddVirtualSubTreeBefore(ctx => ctx.Source.Id == 1056, treeNode => treeNode.Name == "Settings", contextAppConfig => {
     ...
 });
 ````
 
-### **AddVirtualSubTreeAfter(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda matchExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder**
+### Using the `AddVirtualSubTreeAfter()` Method
+
+Adds a virtual subtree to the current tree **after** the tree node matches the match expression, with its visibility controlled by the specified expression.
+
+#### Method Syntax
+
+```csharp
+AddVirtualSubTreeAfter(string sectionAlias, string treeAlias, Lambda visibilityExpression, Lambda matchExpression, Lambda virtualSubTreeConfig = null) : VirtualSubTreeConfigBuilder
+```
 
-Adds a virtual subtree to the current tree, **after** the tree node matches the match expression, with its visibility controlled via the visibility expression.
+#### Example
 
 ````csharp
-// Example
 withTreeConfig.AddVirtualSubTreeAfter(ctx => ctx.Source.Id == 1056, treeNode => treeNode.Name == "Settings", contextAppConfig => {
     ...
 });
 ````
 
-## Controlling where to inject the Virtual SubTrees
+## Control the Virtual SubTrees Inject Location
 
-Controlling where a virtual subtree is injected is done via the visibility expression passed to one of the `AddVirtualSubTree` methods on the root `UIBuilderConfigBuilder` instance. Without a visibility expression, Umbraco UI Builder would inject the virtual subtree under every node in the given tree. This expression can be used to identify the exact location where our tree should go.
+Control the injection location by passing a visibility expression to the `AddVirtualSubTree` methods on the root `UIBuilderConfigBuilder` instance. Without a visibility expression, the subtree appears under every node in the target tree. This expression can be used to identify the exact location where the tree should go.
 
-To help with this, the visibility expression is passed a single `VirtualSubTreeFilterContext` argument with relevant contextual information. This information is about the current node being rendered, alongside a list of the current user's user groups for permission-based visibility control. It also includes access to an `IServiceProvider` in case you need to resolve a service to determine the correct node to inject below.
+The visibility expression receives a `VirtualSubTreeFilterContext` argument with relevant contextual information. The information includes the current node being rendered, alongside a list of the current user's user groups for permission-based visibility control. It also includes access to an `IServiceProvider` for dependency resolution.
 
 ````csharp
 public class VirtualSubTreeFilterContext
@@ -72,7 +93,7 @@ public class NodeContext
 }
 ````
 
-Below you can find an example of a more complex filter expression where injection is based on the Document Type of a content node:
+### Example: Filter Injection by Document Type
 
 ````csharp
 withTreeConfig.AddVirtualSubTree(ctx =>
@@ -89,9 +110,9 @@ withTreeConfig.AddVirtualSubTree(ctx =>
 );
 ````
 
-## Controlling the position of the injected Virtual SubTrees
+## Control the Position of the injected Virtual SubTrees
 
-The position of a virtual subtree within the child nodes of the injection node is controlled by using one of the  `AddVirtualSubTreeBefore` or `AddVirtualSubTreeAfter` methods. These methods need to be on the root level `UIBuilderConfigBuilder` instance and pass a match expression used to identify the tree node to insert before/after. This expression is passed a single `TreeNode` argument to determine the position. It also requires a `boolean` return value to indicate the relevant location has been found.
+The position of a virtual subtree within the child nodes of the injection node is controlled by using one of the  `AddVirtualSubTreeBefore` or `AddVirtualSubTreeAfter` methods. These methods need to be on the root level `UIBuilderConfigBuilder` instance. The match expression identifies the node for insertion. This expression passes a single `TreeNode` argument to determine the position. It also requires a `boolean` return value to indicate the relevant location has been found.
 
 ````csharp
 public class TreeNode
@@ -114,13 +135,13 @@ Below you can find an example of positioning a subtree after a node with the ali
 treeNode => treeNode.alias == "settings"
 ````
 
-## Configuring a Virtual SubTrees
+## Configuring a Virtual SubTree
 
-Virtual subtrees share the same API as the `Tree` config builder API including support for folders and collections. There is an exception when adding collections to a subtree where you will have an additional foreign key expression parameter to define. The foreign key expression links the entities of the collection to the parent node of the subtree. For more information check the [Core Trees Documentation](../areas/trees.md).
+Virtual subtrees use the `Tree` config builder API including support for folders and collections. There is an exception when adding collections to a subtree where you will have an additional foreign key expression parameter to define. The foreign key expression links the entities of the collection to the parent node of the subtree. For more information, see the [Trees](../areas/trees.md) article.
 
-## Injecting Virtual SubTrees into 3rd party trees
+## Inject Virtual Subtrees into Third-Party Trees
 
-Out of the box, Umbraco UI Builder supports injecting subtrees into the core content, media, members, and member group trees. It also includes 3rd party support for [Umbraco Commerce](../../umbraco-commerce/README.md) settings and commerce trees. In order to support additional trees to inject into, you must implement an `ITreeHelper` which is used to extract the required information. The tree helper consists of a tree alias for which the tree helper is. It includes methods to correctly identify the full parent path, a unique ID for a given node ID, and to resolve the actual entity ID. The entity ID should be used for the foreign key collection values.
+Out of the box, Umbraco UI Builder supports injecting subtrees into the core content, media, members, and member group trees. It also includes third-party support for [Umbraco Commerce](../../umbraco-commerce/README.md) settings and commerce trees. To inject into additional trees, implement an `ITreeHelper` to extract necessary data. The tree helper consists of a tree alias for which the tree helper is. It includes methods to correctly identify the full parent path, a unique ID for a given node ID, and to resolve the actual entity ID. The entity ID should be used for the foreign key collection values.
 
 ````csharp
 public interface ITreeHelper
@@ -132,10 +153,10 @@ public interface ITreeHelper
 }
 ````
 
-Once you have defined a tree helper, you can register the DI container in your startup class.
+Once you have defined a tree helper, register the DI container in your startup class.
 
 ````csharp
 builder.Services.AddSingleton<ITreeHelper, MyCustomTreeHelper>();
 ````
 
-Once registered any virtual subtrees registered against the given helpers tree alias will then use your tree helper to locate the required information.
+Once registered, any virtual subtree assigned to the helper’s tree alias will use it to locate required data.