Work with custom child views
Sitecore XC lets you create custom child views so that you can add sections to pages in the Business Tools user interface when you need to extend the properties associated with a Commerce entity, for example catalog or sellable item entities.
You can make your custom properties available in Sitecore Content Editor and for storefront rendering by converting your custom child views into Composer templates.
In the Sitecore XC Business Tools, you cannot modify to a Commerce entity that has already been published. If you want customize a Commerce entity view, you must create a new entity version, and make the relevant changes in the new version.
You can add your custom Catalog properties to the search index (including the sitecore_web_index
and the sitecore_master_index
), so that they become searchable in Sitecore search.
Add a child view to a Commerce entity
You can add a child view to any Commerce entity to create a custom property.
The following shows an example of a child view named Custom child view used to extend the properties of the sample Habitat_Master catalog. In this example, the child view defines and displays the custom property Custom View Property.
When you create a custom child view, it is only visible in the Business Tools. It is not surfaced in Sitecore Content Editor unless you add it or you convert it to a Composer template.
To add a child view, for example, to add a custom property to a catalog entity:
-
Open the Merchandising dashboard.
-
In the Catalogs section, click a catalog.
-
On the catalog Details page, in the Summary section, in the drop-down menu, click Add View.
-
In the Add View dialog box, enter an internal name and a display name for the child view.
-
On the catalog Details page, open the drop-down menu in the new child view and click Add Property.
-
In the Add Property dialog box, enter an internal name and a display name for new property. Then in the drop-down menu, click one of the following data types:
-
String
-
DateTimeOffSet
-
Decimal
-
Integer
-
Boolean
-
Rich text
-
-
Depending on the data type of the new property, you can optionally configure a constraint on the permitted values for the property.
-
To configure a maximum-minimum constraint on properties of type integer or decimal, in the drop-down menu, click Add Min-Max Constraint.
-
To specify a set of permitted values for properties of type string, in the drop-down menu, click Add Selection Option Constraint.
-
Convert an existing child view to a Composer template
After you have added a child view to a Commerce entity to define custom entity properties, you can convert the custom child view to a Composer template, to make the properties it defines available to other Commerce entities.
To convert an existing custom child view to a Composer template:
-
In the Business Tools, on the Commerce item Details page, in the custom child view section, in the drop-down menu, click Make Template .
-
In the Make Template dialog box, specify an an internal name and a display name for the Composer template.
-
In the left navigation pane, to open the Composer dashboard, click Composer.
-
Verify that the new Composer template is listed in the Templates section.
Create a Composer template
You can create a Composer template directly from the Composer dashboard.
To create a new Composer template:
-
In the left navigation pane, to open the Composer dashboard, click Composer.
-
In the Templates section, in the drop-down menu, click Create Template.
-
In the Create Template diablo box, specify the following fields:
-
Name - an internal name for the Composer template
-
Display Name - an external name for the Composer template on the Composer dashboard
-
View Name - an internal name for the custom child view
-
Display View Name - an external name for the child view on the Commerce item Details page
-
-
On the Composer dashboard, in the Templates section, click the new Composer template in the Templates section.
-
On the Composer template Details page, add one or more custom properties.
Add a child view from a Composer template
You can add a child view to a Commerce entity from an existing Composer template. When you add a child view from the Commerce entity menu, you can make changes to the child view without affecting the original Composer template.
To add a custom child view from a Composer template:
-
On the Details page of the Commerce item, in the Summary section, in the drop-down menu, click Add View From Template.
-
In the Add View From Template dialog box, click the Composer template in the drop-down list.
Apply a Composer template to multiple Commerce entity types
You can apply a Composer template to multiple Commerce entity types, at different levels of granularity. For example, you can apply a custom child view to all Commerce entities of a certain type.
When you add a child view from a Composer template on the Composer dashboard, you cannot add or remove properties from the child view in the Commerce entity. You must make changes to the template itself, and those changes apply to all Commerce entities that inherit the child view.
To apply a custom child view to all commerce entities of a specific type:
-
On the Composer dashboard, in the Templates section, click the Composer template you want to apply.
-
On the Composer template Details page, click the link icon.
-
In the Link To Entities dialog box, select all of the entity types that you want to inherit the custom child view.
NoteWhen a Composer template is linked to any one of the following entity types, the Sitecore Content Editor displays the custom properties defined in the Composer Template's view for all content items of that entity type:
-
Sitecore.Commerce.Plugin.Catalog.SellableItem
-
Sitecore.Commerce.Plugin.Catalog.category
-
Sitecore.Commerce.Plugin.Catalog.catalog
You can only link a Composer template to one catalog entity type (that is, to either catalog, or category, or sellable item). You cannot link a Composer template to a combination of these entities. You must create different Composer templates for different Catalog entity types.
-
Apply a Composer template to a subset of specific sellable items
You can apply a custom Composer template to a subset of sellable items with matching tags or item definitions.
For custom properties to be visible from the Sitecore Content Editor, or to render a custom property on the storefront, you must apply the Composer template to the subset of sellable items using item definitions.
Custom properties in Composer templates that are applied to sellable items using tags are not displayed in Sitecore Content Editor, and therefore cannot be rendered on the storefront.
To apply a custom child view to a subset of sellable items:
-
On the Composer dashboard, in the Templates section, click the Composer template you want to apply.
-
To apply the template on sellable items with matching tags, on the Details page, click the tag icon.
NoteTo use item definitions instead of tags to apply the template to matching sellable items, go to step 4.
-
In the Manage Tags dialog box, enter the tags you want to associate with the Composer template.
NoteThe tag strings must match exactly. All sellable items with a matching tag inherit the custom child view and its properties.
-
Alternatively, to use item definitions: on the Composer template Details page, click the + icon.
-
To display a list of valid item definitions, in the Associate To Item Definitions dialog box, in the drop-down list, click a catalog. The item definitions defined for that catalog are displayed.
-
Check all of the item definitions you want to associate with the Composer template. Any sellable item in the catalog that has the same item definition inherits the custom child view.
NoteIf your Composer template defines custom properties for a Catalog entity type (that is, catalog, category, or sellable item), you must update Commerce data templates to display custom child view in the Content Editor.
Remove a child view from a Commerce entity
If you added a child view directly from the entity details page (or by selecting a Composer template from the Commerce entity as your starting point), you can remove the child view from the Commerce entity itself.
If you defined the custom properties in the Composer template first, and then applied the Composer template to a Commerce entity from the Composer dashboard, then you must remove the association to the Commerce entity from within the Composer template.
To remove a child view from a Commerce entity, for example, from a sellable item:
-
In the Business Tools, open the Merchandising dashboard.
-
In the Catalogs section, click the catalog (and category, if applicable) that contains the sellable item.
-
In the Sellable Items section, click the sellable item.
-
On sellable item details page, in the section that contains the child view you want to remove, in the drop-down menu, click Remove View.
NoteIf the custom properties you removed were assigned to the Commerce entity using a Composer template, you must refresh the commerce cache after you removed the view.
Remove a child view from a Composer template
If you added a child view in a Composer template using the Composer dashboard, you can remove the association between the template and specific Commerce entities. Alternatively, you can remove the Composer template altogether if you no longer need to use the custom properties it defines across all Commerce entity types.
If you assigned the child view using item definitions, or tags, you can also remove individual item definitions or tags.
To remove a child view from a Composer template:
-
In the Business Tools, open the Composer dashboard.
-
In the Templates section, click the display name of the Composer template that defines the properties you want to remove.
NoteTo remove the Composer template from all associated Commerce entities, in the drop-down menu, click Remove.
-
To remove the association with one or more specific Commerce entity types, click the drop-down menu, and then click Link to Entities.
-
In the Link to Entities dialog box, clear the selected Commerce entities that you want to disassociate from the Composer template, and then click the check mark to save your changes.
-
After you removed the associated entities, delete the Commerce data templates from Sitecore, and then update the Commerce data templates to reapply default Commerce data templates.
Update Commerce data templates
When you create a Composer template to define custom properties for a Commerce entity of type catalog, or category, or sellable item, you must update data templates in the Content Editor so that the new properties become visible for that content item type in Sitecore.
-
Every time you make a change to a Composer Template, you must update data templates in the Content Editor in order to propagate your changes in Sitecore.
-
If you modify Composer Template's properties directly in an entity you need to Refresh Commerce Cache in the Content Editor in order to view those changes in Content Editor.
To display custom properties (from a child view) defined by a Composer template in the Content Editor:
-
On the Sitecore Launchpad, click Content Editor
-
In the Content Editor, in the ribbon, click Commerce.
-
Click Update Data Templates.
When the update is finished, the content items affected by the template display the custom properties.
Considerations for updating Commerce data templates
During the Commerce data template update, the template generation process randomly chooses an existing Commerce entity of the appropriate type (for example, catalog, category, or sellable Item) as a base upon which to construct the template. If that specific entity used as a base contains child views, then unexpected child views might become part of the generated template. When this occurs, you can see the unexpected child views in the Sitecore Content Editor, in the generated template folder for the entity type.
To avoid the inclusion of unwanted views in generated templates for catalog entities (catalog, category or sellable item), you can change the default template generator configuration (in the /App_Config/Include/Y.Commerce.Engine/Sitecore.Commerce.Engine.TemplateGenerator.config
file), to specify the entity ID to use as a base when generating data template for that entity type.
The following shows a sample of the default template generator configuration:
<!-- Defines the catalog item to use for template generation -->
<catalogId></catalogId>
<!-- Defines the category item to use for template generation -->
<categoryId></categoryId>
<!-- Defines the sellable item to use for template generation -->
<sellableItemId></sellableItemId>
<!-- Defines the bundle to use for template generation -->
<bundleId></bundleId>
The empty value means that the template generation process picks an entity at random. To override the default behavior, you specify an entity ID that uses the desired base template for that entity.
Delete Commerce data templates
You use Sitecore Content Editor to delete Commerce data templates. You delete Commerce data templates when you need to remove properties from Commerce items.
To delete Commerce data templates:
-
On the Sitecore Launchpad, click Content Editor.
-
In the Content Editor, on the ribbon, click the Commerce tab.
-
Click Delete Data Templates.
After you deleted data templates, you can update them again to reapply valid Commerce templates to Commerce content items.
Edit the value of a custom property
You can set or change the value of custom properties in a child view.
To edit the value of a custom property:
-
In the Business Tools, browse to the appropriate entity view and, in the drop-down menu of the child view that contains the custom property to edit, click Edit view.
-
In the Edit View dialog box, set the property to the required value:
-
To set a DateTime property type, use the date picker.
-
To set a
DecimalProperty
type, enter a value in decimal format. -
To set an Integer property type, enter an integer value.
-
To set a Boolean property type value to true, select Boolean. To set it to false, leave the check box empty.
-
To set a RichText value, use the rich text editor.
ImportantIn the rich text editor, make sure you disable the Source option (HTML view) before saving. If you save your rich text settings with the Source view enabled (where the Source button is grayed out), your configuration changes are not saved.
NoteSome formatting options are only visible in the rich text editor window, and do not render when you return to the Business Tools view, such as font colors or paragraph formatting for example. All formatting information is kept and passed to the Content Editor, whether or not it is visible in the Business Tools views.
-
-
Click the check mark to save your changes.