Work with custom child views

Abstract

How to extend the properties associated with a Commerce entity and use Composer to create a Composer template.

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. If required, you can make custom properties available to other Commerce entities by converting your custom views into Composer templates.

Note

You cannot make any changes to a Commerce entity that has already been published. If you want to customize a Commerce entity, you must create a new entity version and make the relevant changes in the new version.

Note

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.

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.

XC_BizTools_Custom_Child_View.png

To add a child view, for example, to add a custom property to a catalog entity:

  1. Open the Merchandising dashboard.

  2. In the Catalogs section, click a catalog.

  3. On the catalog Details page, in the Summary section, in the drop-down menu, click Add View.

  4. In the Add View window, enter an internal name and a display name for the child view.

  5. On the catalog Details page, open the drop-down menu in the new child view and click Add Property.

  6. In the Add Property window, 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

  7. 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.

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:

  1. In the Business Tools, on the Commerce item Details page, in the custom child view section, in the drop-down menu, click Make Template .

  2. In the Make Template window, specify an an internal name and a display name for the Composer template.

  3. In the left navigation pane, to open the Composer dashboard, click Composer.

  4. Verify that the new Composer template is listed in the Templates section.

You can create a Composer template directly from the Composer dashboard.

To create a new Composer template:

  1. In the left navigation pane, to open the Composer dashboard, click Composer.

  2. In the Templates section, in the drop-down menu, click Create Template.

  3. In the Create Template window, 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

  4. On the Composer dashboard, in the Templates section, click the new Composer template in the Templates section.

  5. On the Composer template Details page, add one or more custom properties.

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:

  1. On the Details page of the Commerce item, in the Summary section, in the drop-down menu, click Add View From Template.

  2. In the Add View From Template window, click the Composer template in the drop-down list.

You can apply a custom child view 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.

Note

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:

  1. On the Composer dashboard, in the Templates section, click the Composer template you want to apply. 

  2. On the Composer template Details page, click the link icon. 

  3. In the Link To Entities dialog box, select all of the entity types that you want to inherit the custom child view.

    Displays the Link To Entities dialog box which contains a list of catalog entities that can be selected.

    Note

    When 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.

You can apply a custom child view to a subset of specific sellable items by matching tags or item definitions applied to those sellable items.

Note

For custom properties to be visible from the Sitecore Content Editor, you must apply the Composer template items using Associate item definitions.

Custom properties in Composer templates that are applied to sellable items using tags are not displayed in the Sitecore Content Editor.

To apply a custom child view to a subset of sellable items: 

  1. On the Composer dashboard, in the Templates section, click the Composer template you want to apply.

  2. On the Details page, click the tag icon. 

  3. In the Manage Tags window, enter the tags you want to associate with the Composer template. You must associate the same tag with a sellable item for that sellable item to inherit the custom child view.

  4. Alternatively, on the Composer template Details page, click the + icon.

  5. To obtain a list of valid item definitions, in the Associate To Item Definitions window, in the drop-down list, click a catalog.

  6. 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.

    Note

    If 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 the changes in the Content Editor.

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.

Note

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:

  1. In the Business Tools, open the Merchandising dashboard.

  2. In the Catalogs section, click the catalog (and category, if applicable) that contains the sellable item.

  3. In the Sellable Items section, click the sellable item.

  4. 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.

    Note

    If 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.

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.

Note

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:

  1. In the Business Tools, open the Composer dashboard.

  2. In the Templates section, click the display name of the Composer template that defines the properties you want to remove.

    Note

    To remove the Composer template from all associated Commerce entities, in the drop-down menu, click Remove.

  3. To remove the association with one or more specific Commerce entity types, click the drop-down menu, and then click Link to Entities.

  4. 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.

  5. 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.

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.

Note

  • 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:

  1. On the Sitecore Launchpad, click Content Editor

  2. In the Content Editor, in the ribbon, click Commerce.

  3. 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>

Note

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.

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:

  1. On the Sitecore Launchpad, click Content Editor.

  2. In the Content Editor, on the ribbon, click the Commerce tab.

  3. Click Delete Data Templates.

    After you deleted data templates, you can update them again to reapply valid Commerce templates to Commerce content items.