Customising Line Items in Sitecore Experience Commerce - Part 1 (Engine)
Sometimes the products that we are selling need to have custom information on each line item, and it’s a fairly straightforward process in Sitecore Experience Commerce to achieve this.
The steps for the engine are:
Create a custom line item component that will store the extra data
Create new controller with new endpoint(s) to save cart line data
Create a ServiceApiBlock that will wire up the odata endpoint to your controller
Create a ConfigureSitecore class to tell the engine what needs to be configured.
Test it
The component
First, we’ll create a new component with a single field where the custom line item data will be stored. This will be persisted as a child component of the line item.
Components/LineItemPersonalisationComponent.cs
The controller
Next, we’ll create the controller that will implement the line item saving logic, including our new field(s). The name CommandsController is a convention and will be automatically registered by the engine. Make sure that the method name in the controller exactly matches the name in the route attribute and the name declared in the ServiceApiBlock.
Controllers/CommandsController.cs
This code is almost exactly what can be decompiled from Sitecore.Commerce.Plugin.Carts.dll with the addition of the personalMessage field and component, and I tidied up the validation of the required fields into a separate reusable method.
The AddPersonalisedCartLine method will handle adding a new item to the cart and will insert our new personalisation component on to each line item. Note that by default, the engine has a policy to roll up line items (ie, just add an extra quantity, rather than a new line item each time the user adds another one to the cart). For this reason, the default behaviour you will see is that the first item will add the new component, but subsequent items with the same sellable item/variant ID added to the cart will only increase the quantity, not change the message.
The UpdatePersonalisedCartLine method will handle updates such as changing the quantity by entering a new value. Similarly, if a field is provided for the user to change the message, it will be applied here. The inputs on the cart page might look something like this:
As with the add method, if the line item roll up policy is in effect, you may get undesirable results because your message will only be applied once to all line items with the same sellable item/variant ID.
The ServiceApiBlock
That’s most of the work done now. Once we have the controller, we wire it up to the odata end point and tell it what parameters to expect. Once again most of this is extracted from the carts dll and cleaned up with the message field added.
ConfigureServiceApiBlock.cs
This will make our new endpoint available in the API, and include our message field. Note that the message field is required, even if it’s empty.
ConfigureSitecore
Lastly, we need a ConfigureSitecore so that we can add our ConfigureServiceApiBlock to the correct pipeline.
ConfigureSitecore.cs
Test it
Finally we can build and test the solution.
In postman, we can use the pre-built add to cart from the SDK postman scripts, replacing the default path with our new end point.
And using the get cart script, we should see the new component on the line item that was added.
Don’t forget to rebuild the Service Proxy to add the new goodness so that it can be used in the Storefront.