diff --git a/15/umbraco-ui-builder/advanced/encrypted-properties.md b/15/umbraco-ui-builder/advanced/encrypted-properties.md index 7962111773b..da6d659bd25 100644 --- a/15/umbraco-ui-builder/advanced/encrypted-properties.md +++ b/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 +``` + +#### Example ````csharp -// Example collectionConfig.AddEncryptedProperty(p => p.Secret); ```` diff --git a/15/umbraco-ui-builder/advanced/events.md b/15/umbraco-ui-builder/advanced/events.md index a6e2fd9425e..922b234443a 100644 --- a/15/umbraco-ui-builder/advanced/events.md +++ b/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 { @@ -21,7 +23,7 @@ public class MyEntitySavingEventHandler : INotificationHandler { public void Handle(EntitySavingNotification notification) @@ -53,14 +55,15 @@ public class MyEntitySavingEventHandler : INotificationHandler { public void Handle(EntitySavedNotification notification) @@ -74,12 +77,13 @@ public class MyEntitySavedEventHandler : INotificationHandler { public void Handle(EntityDeletingNotification notification) @@ -91,14 +95,15 @@ public class MyEntityDeletingEventHandler : INotificationHandler { public void Handle(EntityDeletedNotification notification) @@ -112,12 +117,13 @@ public class MyEntityDeletedEventHandler : INotificationHandler` 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` object, and the where clause/order by clauses. These will be used to generate the SQL query. + +#### Example ```csharp -// Example public class MySqlQueryBuildingEventHandler : INotificationHandler { public void Handle(SqlQueryBuildingNotification notification) @@ -128,12 +134,13 @@ public class MySqlQueryBuildingEventHandler : INotificationHandler` 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` object and the where clause/order by clauses that was used to generate the SQL query. +#### Example ```csharp -// Example public class MySqlQueryBuiltEventHandler : INotificationHandler { public void Handle(SqlQueryBuiltNotification notification) @@ -144,12 +151,13 @@ public class MySqlQueryBuiltEventHandler : INotificationHandler { public void Handle(EntitySavingNotification notification) diff --git a/15/umbraco-ui-builder/advanced/repositories.md b/15/umbraco-ui-builder/advanced/repositories.md index f49db720184..2f87fe37b36 100644 --- a/15/umbraco-ui-builder/advanced/repositories.md +++ b/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` and implements all of its abstract methods. +Create a class that inherits from `Repository` and implements all abstract methods. ````csharp // Example @@ -58,39 +58,62 @@ public class PersonRepository : Repository { } ```` -**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<TRepositoryType>() : CollectionConfigBuilder<TEntityType>** +### 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() : CollectionConfigBuilder +``` + +#### Example ````csharp -// Example collectionConfig.SetRepositoryType(); ```` -### **SetRepositoryType(Type repositoryType) : CollectionConfigBuilder<TEntityType>** +### 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 +``` + +#### 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<TEntity, TId>() : Repository<TEntity, TId>** +### Using the `GetRepository()` 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() : Repository +``` + +#### Example + ````csharp -// Example public class MyController : Controller { private readonly Repository _repo; @@ -102,12 +125,19 @@ public class MyController : Controller } ```` -### **IRepositoryFactory.GetRepository<TEntity, TId>(string collectionAlias) : Repository<TEntity, TId>** +### Using the `GetRepository(string collectionAlias)` Method Creates a repository for the given entity type from the collection with the given alias. +#### Method Syntax + +```cs +IRepositoryFactory.GetRepository(string collectionAlias) : Repository +``` + +#### Example + ````csharp -// Example public class MyController : Controller { private readonly Repository _repo; diff --git a/15/umbraco-ui-builder/advanced/value-mappers.md b/15/umbraco-ui-builder/advanced/value-mappers.md index e49f44aadd7..b440e8e3e9d 100644 --- a/15/umbraco-ui-builder/advanced/value-mappers.md +++ b/15/umbraco-ui-builder/advanced/value-mappers.md @@ -1,19 +1,20 @@ --- -description: Configuring value mappers in Umbraco UI Builder, the backoffice UI builder for Umbraco. +description: Configuring value mappers in Umbraco UI Builder to modify how data is stored and retrieved. --- # Value Mappers -A value mapper is an Umbraco UI Builder helper class that sits between the editor UI and the database. It also lets you tweak the stored value of a field. By default Umbraco UI Builder will save a datatype value as it would be stored in Umbraco. Value mappers let you change this. +Value mappers in Umbraco UI Builder act as intermediaries between the editor UI and the database, allowing customization of stored field values. By default, Umbraco UI Builder saves data as it would be stored in Umbraco, but value mappers enable modifications. -When Umbraco UI Builder resolves a value mapper it will attempt to do so from the global DI container. This means you can inject any dependencies that you require for your mapper. If there is no type defined in the DI container, Umbraco UI Builder will fall-back to manually instantiating a new instance of value mapper. +When resolving a value mapper, Umbraco UI Builder first checks the global DI container. If no type is defined, it manually instantiates a new instance. -## Defining a value mapper +## Defining a Value Mapper -To define a mapper create a class that inherits from the base class `ValueMapper` and implements the methods `EditorToModel` and `ModelToEditor`. +To define a mapper, create a class that inherits from the base class `ValueMapper` and implements the `EditorToModel` and `ModelToEditor` methods. + +### Example ````csharp -// Example public class MyValueMapper : ValueMapper { public override object EditorToModel(object input) @@ -30,33 +31,54 @@ public class MyValueMapper : ValueMapper } ```` -## Setting a field value mapper +## Setting a Field Value Mapper Value mappers are defined as part of a collection editor field configuration. -### **SetValueMapper<TMapperType>() : EditorFieldConfigBuilder<TEntityType, TValueType>** +### Using the `SetValueMapper()` Method Set the value mapper for the current field. +#### Method Syntax + +```csharp +SetValueMapper() : EditorFieldConfigBuilder +``` + +#### Example + ````csharp -// Example fieldConfig.SetValueMapper(); ```` -### **SetValueMapper(Type mapperType) : EditorFieldConfigBuilder<TEntityType, TValueType>** +### Using the `SetValueMapper(Type mapperType)` Method -Set the value mapper for the current field. +Set the value mapper for the current field using a type reference. + +#### Method Syntax + +```csharp +SetValueMapper(Type mapperType) : EditorFieldConfigBuilder +``` + +#### Example ````csharp -// Example fieldConfig.SetValueMapper(typeof(MyValueMapper)); ```` -### **SetValueMapper(Mapper mapper) : EditorFieldConfigBuilder<TEntityType, TValueType>** +### Using the `SetValueMapper(Mapper mapper)` Method -Set the value mapper for the current field. +Set the value mapper for the current field using an instance. + +#### Method Syntax + +```csharp +SetValueMapper(Mapper mapper) : EditorFieldConfigBuilder +``` + +#### Example ````csharp -// Example fieldConfig.SetValueMapper(new MyValueMapper()); ```` diff --git a/15/umbraco-ui-builder/advanced/virtual-sub-trees.md b/15/umbraco-ui-builder/advanced/virtual-sub-trees.md index 3394a2f20e1..6be46b481a9 100644 --- a/15/umbraco-ui-builder/advanced/virtual-sub-trees.md +++ b/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(); ```` -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.