Merge pull request #6995 from umbraco/advanced

Updated UI Builder Advanced section articles

Author: eshanrnh

15/umbraco-ui-builder/advanced/encrypted-properties.md

@@ -1,22 +1,29 @@
 ---
-description: Configuring encrypted properties in Umbraco UI Builder, the backoffice UI builder for Umbraco.
+description: Configuring and using encrypted properties in Umbraco UI Builder to securely store sensitive data.
 ---
 
 # Encrypted Properties
 
-If needed to collect sensitive information in a collection but don't want to persist in a plain text format to the data storage mechanism. Umbraco UI Builder can help with this by allowing you to define properties as encrypted. After which any time the value is persisted or retrieved from persistence, Umbraco UI Builder will automatically encrypt and decrypt the value.
+Umbraco UI Builder allows encrypting properties to store sensitive information securely. When a property is marked as encrypted, its value is automatically encrypted before storage and decrypted upon retrieval.
 
 {% hint style="info" %}
-Umbraco UI Builder uses the `IDataProtectionProvider` instance registered in the DI container to perform its encryption/decryption. If you need to change the encryption algorithm, you should replace the `IDataProtectionProvider` instance in the DI container.
+Umbraco UI Builder uses the `IDataProtectionProvider` instance registered in the DI container for encryption and decryption. To modify the encryption algorithm, replace the `IDataProtectionProvider` instance in the DI container.
 {% endhint %}
 
-## Defining encrypted properties
+## Defining Encrypted Properties
 
-### **AddEncryptedProperty(Lambda encryptedPropertyExpression) : CollectionConfigBuilder<TEntityType>**
+### Using the `AddEncryptedProperty()` Method
 
-Adds the given property to the encrypted properties collection. Property must be of type `String`. When set, the property will be encrypted/decrypted on write/read respectively.
+Encrypts the specified property. The property must be of type `String`. The value is encrypted before storage and decrypted when retrieved.
+
+#### Method Syntax
+
+```csharp
+AddEncryptedProperty(Lambda encryptedPropertyExpression) : CollectionConfigBuilder<TEntityType>
+```
+
+#### Example
 
 ````csharp
-// Example
 collectionConfig.AddEncryptedProperty(p => p.Secret);
 ````

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/repositories.md

@@ -1,14 +1,14 @@
 ---
-description: Configuring repositories in Umbraco UI Builder, the backoffice UI builder for Umbraco.
+description: Configure repositories in Umbraco UI Builder.
 ---
 
 # Repositories
 
-Repositories are used by Umbraco UI Builder to access the entity data stores. By default, collections will use a generic built-in NPoco repository. However, you can define your own repository implementation should you wish to store your entities via an alternative strategy.
+Repositories in Umbraco UI Builder manage entity data storage. By default, collections use a built-in NPoco repository. To use a different storage strategy, define a custom repository implementation.
 
-## Defining a repository
+## Defining a Repository
 
-To define a repository create a class that inherits from the base class `Repository<TEntity, TId>` and implements all of its abstract methods.
+Create a class that inherits from `Repository<TEntity, TId>` and implements all abstract methods.
 
 ````csharp
 // Example
@@ -58,39 +58,62 @@ public class PersonRepository : Repository<Person, int> {
 }
 ````
 
-**Note:** For all `Impl` methods there are public alternatives without the `Impl` suffix. However, there are separate implementation methods in order to ensure all repositories fire the relevant Umbraco UI Builder events. This is whether triggered via the Umbraco UI Builder's UI or not.
+{% hint style="info" %}
+`Impl` methods have public alternatives without the suffix. Separate implementation methods ensure repositories trigger Umbraco UI Builder events, whether actions originate from the UI or not.
+{% endhint %}
 
-## Changing the repository implementation of a collection
+## Changing the Repository Implementation of a Collection
 
-### **SetRepositoryType&lt;TRepositoryType&gt;() : CollectionConfigBuilder&lt;TEntityType&gt;**
+### Using the `SetRepositoryType()` Method
 
-Sets the repository type to the given type for the current collection.
+Assign a custom repository type to a collection.
+
+#### Method Syntax
+
+```cs
+SetRepositoryType<TRepositoryType>() : CollectionConfigBuilder<TEntityType>
+```
+
+#### Example
 
 ````csharp
-// Example
 collectionConfig.SetRepositoryType<PersonRepositoryType>();
 ````
 
-### **SetRepositoryType(Type repositoryType) : CollectionConfigBuilder&lt;TEntityType&gt;**
+### Using the `SetRepositoryType(Type repositoryType)` Method
 
-Sets the repository type to the given type for the current collection.
+Sets the repository type dynamically to the given type for the current collection.
+
+#### Method Syntax
+
+```cs
+SetRepositoryType(Type repositoryType) : CollectionConfigBuilder<TEntityType>
+```
+
+#### Example
 
 ````csharp
-// Example
 collectionConfig.SetRepositoryType(typeof(PersonRepositoryType));
 ````
 
-## Accessing a repository in code
+## Accessing a Repository in Code
 
 To help with accessing a repository (default or custom) Umbraco UI Builder has an `IRepositoryFactory` you can inject into your code base. This includes a couple of factory methods to create the repository instances for you.
 Repositories should only be created via the repository factory as there are some injected dependencies that can only be resolved by Umbraco UI Builder.
 
-### **IRepositoryFactory.GetRepository&lt;TEntity, TId&gt;() : Repository&lt;TEntity, TId&gt;**
+### Using the `GetRepository<TEntity, TId>()` Method
 
 Creates a repository for the given entity type. Umbraco UI Builder will search the configuration for the first section/collection with a configuration for the given entity type. Then it will use that as a repository configuration.
 
+#### Method Syntax
+
+```cs
+IRepositoryFactory.GetRepository<TEntity, TId>() : Repository<TEntity, TId>
+```
+
+#### Example
+
 ````csharp
-// Example
 public class MyController : Controller
 {
     private readonly Repository<Person, int> _repo;
@@ -102,12 +125,19 @@ public class MyController : Controller
 }
 ````
 
-### **IRepositoryFactory.GetRepository&lt;TEntity, TId&gt;(string collectionAlias) : Repository&lt;TEntity, TId&gt;**
+### Using the `GetRepository<TEntity, TId>(string collectionAlias)` Method
 
 Creates a repository for the given entity type from the collection with the given alias.
 
+#### Method Syntax
+
+```cs
+IRepositoryFactory.GetRepository<TEntity, TId>(string collectionAlias) : Repository<TEntity, TId>
+```
+
+#### Example
+
 ````csharp
-// Example
 public class MyController : Controller
 {
     private readonly Repository<Person, int> _repo;