In this little article I would like to focus on the topic of how to extend basic commerce entities like catalogs, categories or products with new custom properties using the newly introduced Composer. As we already know in the previous version of Sitecore XC it was not so easy to extend existing product definitions. The existing workaround was described in this kb article, but was in deed quiet uncomfortable.
With the release of Sitecore Commerce 9.0.2 Sitecore now introduced a new Business Tool called Composer, which is, together with some new mechansims of creation of views on commerce entities, responsible for extending the entities with custom components.
Lets assume we have the following scenario: We want to extend all commerce products with some new properties. To achieve this we only have to do the following steps.
At first just use the Merchandise Manager and navigate to some SellableItem. Within that item, just right click on the actions tab of the Summary View. There just click Add View.
Note: If you cannot add a View right now, you most likely did not add a new version to your SellableItem.
To do that simply click Add Entity Version.
After the page reloaded you will see now in the Entity Versions View a new version. We now have Version 1 which was default and already published and which was not editable anymore. And we now have version 2, which can be used to edit stuff on our SellableItem. If you now want to change the second version, simply click on the “2” and the page redirects to the version 2 of the SellableItem.
You can see that this version is still not published, so it is editable. Within the URL you can see and also change the version by changing the number in the marked area. And within Version 2 now, we can finally use the Add View action to create a new View. More to workflows and publishment will follow in a deep dive in one of my later blog posts.
You can now specify a Name and a Display Name for the new View. Now just click “ok” (the arrow button)
Now the page should reload and your newly created View should be visible directly at the top of the page under Summary View. Within that view you have various actions available for interacting with that view, like seen in the screenshot above. We just want to create new properties within that view, so we click Add Property.
Within that dialog we again can set a Name and a Display Name. In addition we can choose the Property Type of our new Property. Currently we can choose between the following types
In addition of creating the custom properties there are already, as far as I can see, two Constraints you can assign to your custom properties
- Selection Option Constraint
- Min-Max Constraint
After adding a new Property to your view you get, depending on the type of the property one of the mentioned constraint. If you e.g. add a string property you get the Selection Option Constraint, like seen in the example below.
If you have e.g. no property of type string this action will not be displayed. And if you have a property of type string within that view, but it has already an assign Constraint, this action is greyed out. But if you still have a field without a constraint, you can easily assign on by clicking on the action.
Within the dialog you can choose the property, for which the constraint should be created and in this case define the Option Values for the field.
After saving the constraint it is directly available while editing the views. If you now try to edit the view and especially the property with the constaint, you will recognize, that it changed now to a dropdown with your predefined option values.
Same way it also works with the second available constraint; The Min-Max Constaint
If you added properties of type Integer or Decimal, you will get the action Add Min-Max Constaint.
As the name already implies, you can set a Minimum and a Maximum value for your property.
When you save your new constraint and now try to edit a view and e.g. enter a value which violates the contraint, you will receive the error message like seen above.
That was a little excourse of creating and applying constraints. Now back to creating a template. Till now we have created a new View and within that view some new Properties. But now this View can only be used by the SellableItem, where we created that View. If we e.g. open another SellableItem, we will see, that the newly created View is not visible here. It is only visible right now on the item, where we created that View.
We now want to make this View usable by every Item of the template SellableItem.
To achieve this, we simple right click on the actions of our view and click Make Template.
After clicking Make Template this View is now displayed also in the Composer under Templates. There we are also able to change or manipulate the view, like we did on the specific SellableItem. But in addition we can also associate this Template to other Entities.
We just have to click one of the actions on the Details tab
- Manage Tags
- Link to Entities
- Associate Item Definitions to a Composer Template
With these actions we can handle various scenarios of extending templates to specific entities. Sitecore itself describes very good, when to use which action
You can apply a custom child view (and its properties) to other Commerce items, at different levels of granularity:
- To apply the template to a single Commerce item (for example, a sellable item), add a tag to the Composer template, and add the same tag to the corresponding Commerce item. Any item that shares a tag with the Composer template inherits the properties in that template.
- To apply the template to all Commerce items of a certain type (for example, all categories), use the Link to Entities function on the Composer dashboard (and select the appropriate entity type).
- To apply the template to a subset of Commerce items (for example, a group of sellable items), associate the template to one or more Item Definitions (which have been defined in a catalog), and ensure that the apopropriate sellable items are associated with the same Item Definition (in their Details page).
In this case we use the action Link to Entities to apply our View/ Template to a whole group of items.
In our scenario we want, that every SellableItem gets the newly created view with all properties, so we simply choose Sitecore.Commerce.Plugin.Catalog.SellableItem. Of course it is also possible to choose other entities of the commerce system seen above and it does not even matter for which entity we initially created the view. So e.g. we created the view for a SellableItem within a SellableItem, but it could also be used of Customers, Orders, Catalogs or any other commerce entity.
After doing that, we can see the Linked Entities in the Details View within the Composer.
If we now have a look again at some random SellableItem, we see, that now our View is also available for every SellableItem in the system.
If we want to edit content of the new View, we of course first have to create a new version of the time, like described in the beginning. But then we just right click on the actions of the view and click Edit View. Within that dialog, we can very simple adapt all our properties within that View. This structure is very similar to the construct of sections and fields in standard Sitecore templates.
In the end we now have created a new View with some custom Properties and Constraints on our properties. We created a reusable Template out of that view, which was then usable by the Composer. After linking the new template in our case to all commerce entities of type SellableItem, the new View and properties were also available for every other product.
As a conclusion, I think this way of extending the commerce entities on the one hand differs very much from the “traditional” way we normally do with standard sitecore templates, but its quiet intuitive to use and a very powerful tool to manage all the Views and Templates of commerce entities. This mechanism / tool closes a big gap we had within the last releases of Sitecore XC while customizing entities.