Customize a Commerce view to show or hide information in the Business Tools

Version: 10.2

The Commerce Views plugin allows you to customize certain aspects of the Business Tools user interface without having to make changes to the Business Tools application itself. For example, you can create a custom plugin that adds a new view property to an existing view. Or you might need to remove elements from the Business Tools UI, such as a child view or a property. You can accomplish these types of customization by extending the appropriate Commerce Engine plugin.

Note

You can also use the Business Tools user interface to add or remove custom child views and properties, but you cannot use it to remove default child views and properties.

To customize a Commerce view, for example, to add or remove a custom child view or property, your must create a custom pipeline block, and configure it to run after the default block it modifies. In the example that follows, we extend the default Customer Entitlements view (entitlementView) to display a gift card's code as a new property. The new pipeline block is named GetCustomerGiftCardCodeViewBlock.

To customize a Commerce view to show or hide information:

  1. Create your custom plugin and block. The extension must contain a reference to the Sitecore.Commerce.Plugin.GiftCards plugin, because the intent of the customization is to retrieve gift card data.

  2. The new GetCustomerGiftCardCodeViewBlock block must take an EntityView as a parameter and return an EntityView.

    RequestResponse
    public class GetCustomerGiftCardCodeViewBlock : PipelineBlock<EntityView, EntityView, CommercePipelineExecutionContext>

  3. Add the run method to the custom block. The custom block must first specify the conditions that identify the Commerce entity view to modify.

    The following illustrates a custom block:

    RequestResponse
        {
        private readonly FindEntityCommand _findEntityCommand;

        public GetCustomerGiftCardCodeViewBlock(FindEntityCommand command)
        {
            _findEntityCommand = command;
        }
        public override async Task<EntityView> RunAsync(EntityView arg, CommercePipelineExecutionContext context)
        {
            Condition.Requires(arg).IsNotNull($"{this.Name}: The argument cannot be null.");
            var request = context.CommerceContext.GetObject<EntityViewArgument>();

            // Do nothing if:
            // -the EntityViewArgument object cannot be found in the context
            // -or the name of the requested view is not Commented 
            // -or the requested entity is not a Customer
            if (string.IsNullOrEmpty(request?.ViewName) ||
                (!request.ViewName.Equals(context.GetPolicy<KnownEntitlementsViewsPolicy>().CustomerEntitlements, StringComparison.OrdinalIgnoreCase)
                    && !request.ViewName.Equals(context.GetPolicy<KnownCustomerViewsPolicy>().Master, StringComparison.OrdinalIgnoreCase))
                || !(request.Entity is Customer))
            {
                return arg;
            }

            var customer = (Customer)request.Entity;

            // Check if the Customer has entitlements
            if (!customer.HasComponent<EntitlementsComponent>())
            {
                return arg;
            }

            // Find all the entitlements view that were already added by another block
            var entitlementsView = request.ViewName.Equals(context.GetPolicy<KnownCustomerViewsPolicy>().Master, StringComparison.OrdinalIgnoreCase) ? arg.ChildViews.OfType<EntityView>().FirstOrDefault(ev => ev.Name.Equals(context.GetPolicy<KnownEntitlementsViewsPolicy>().CustomerEntitlements, StringComparison.OrdinalIgnoreCase)) : arg;
            var entitlementViews = entitlementsView?.ChildViews.Where(cv => cv.Name.Equals(context.GetPolicy<KnownEntitlementsViewsPolicy>().CustomerEntitlementDetails, StringComparison.OrdinalIgnoreCase)).OfType<EntityView>().ToList();
            if (entitlementViews == null)
            {
                return arg;
            }

            foreach (var entitlementView in entitlementViews)
            {
                var entitlement = await _findEntityCommand.Process(context.CommerceContext, typeof(Entitlement), entitlementView.ItemId).ConfigureAwait(false);
                if (entitlement == null)
                {
                    continue;
                }

                var card = entitlement as GiftCard;
                if (card == null)
                {
                    continue;
                }

                entitlementView.Properties.Add(new ViewProperty { Name = "Code", IsReadOnly = true, RawValue = card.GiftCardCode });
            }

            return arg;
        }
    }
}

  4. Register your custom pipeline and blocks with the Commerce Engine. In your custom plugin project, open the ConfigureSitecore.cs file, and add the custom GetCustomerGiftCardCodeViewBlock block to the IGetEntityViewPipeline, after the Sitecore.Commerce.Plugin.GiftCards plugin block GetCustomerGiftCardEntitlementDetailsViewBlock.

  5. Deploy your Sitecore XC solution.

Remove a custom child view

To remove a custom Commerce entity:

  • Use the RemoveChildView method, as shown in the following example:

    RequestResponse
     public static void RemoveChildView(EntityView entityView, string viewNameToRemove)
        {
            // Remove a child view
            var viewToRemove = entityView.ChildViews.FirstOrDefault(p => p.Name.Equals(viewNameToRemove, StringComparison.OrdinalIgnoreCase)) as EntityView;
            entityView.ChildViews.Remove(viewToRemove);
        }

Remove a custom view property

To remove a custom Commerce view property:

  • Use the RemoveViewPropertyFromView method as shown in the following example:

    RequestResponse
     public static void RemoveViewPropertyFromView(EntityView entityView, string viewPropertyName)
        {
            // Remove a property
            var propertyToRemove = entityView.Properties.FirstOrDefault(p => p.Name.Equals(viewPropertyName, StringComparison.OrdinalIgnoreCase));
            entityView.Properties.Remove(propertyToRemove);
        }

Do you have some feedback for us?

If you have suggestions for improving this article,