Walkthrough: Enabling direct navigation for customized Commerce entities

Current version: 9.2

The Sitecore XC Business Tools let you extend and customize the information stored for any sellable item using the Composer feature. For every customized entity, templates are generated in Sitecore to match the data in the Commerce Engine.

By default, there are four commerce templates (Commerce Category, Commerce Product, Commerce Product Variant, Commerce Bundle) that you can configure on the catalog for the data provider to use when exposing catalog items. To enable direct navigation for a customized Commerce entity, you first extend an existing entity definition and then associate it to a custom page design.

When you create a Commerce entity using Composer, two corresponding templates are created in Sitecore. In this walkthrough, these are:

  • Headphones

  • HeadphonesVariant

By completing this walkthrough, you will associate all headphones in the Audio department including the Studio X Over-the-Ear Wireless Headphones with a customized template that includes three new properties. After you enable direct navigation, you can open any of the headphones in the Experience Editor directly from the Content Editor.

This walkthrough steps you through how to:

Note

This walkthrough uses the Storefront site template and the Habitat catalog to illustrate how to enable direct navigation for custom Commerce entities. It assumes that you have the Habitat catalog installed and that you are completing the procedures in order. The content of this walkthrough, however, also applies when using Sitecore Commerce without SXA Storefront.

Extend the template definition for the Headphones category

In the context of this walkthrough, to apply direct navigation to sellable items using a customized Composer template, you first extend the template definition by adding new fields.

To extend the template definition for the Headphones category:

  1. On the Sitecore Launchpad, click Business Tools, Merchandising and in the Catalogs section, click Habitat_Master.

  2. In the Categories section, click Departments, and then click Audio.

  3. In the list of sellable items, click Studio X Over-the-Ear Wireless Headphones.

  4. In the Entity Versions section, to create a new version, click Add Entity Version (+) and confirm that you want to add an entity version.

  5. Click the new entity version to select it and, in the Summary section, from the drop-down list, click Add View.

  6. In the Add View dialog box, in both the Name field and the Display Name field, enter Headphones and confirm your changes.

  7. In the Headphones section, from the drop-down list, click Add Property and, in the Add Property dialog box, in both the Name field and the Display Name field, enter Type and assign a property type of String. Confirm your changes.

  8. Repeat step 8 adding the following two properties:

    Name

    Display Name

    Property

    NoiseCancelling

    Noise Cancelling

    Boolean

    IncludesMicrophone

    Includes Microphone

    Boolean

  9. In the Headphones section, from the drop-down list, click Add Selection Option Constraint, define the constraints shown in the following figure, and accept your changes.

  10. In the Headphones section, from the drop-down list, click Edit View and specify the default properties you want to display for the Headphones section. Confirm your changes.

  11. In the Headphones section, from the drop-down list, click Make Template and, in the Make template dialog box, in the Name and Display Name fields, enter Headphones Template and confirm your changes.

Assign the custom template

To make the new fields visible for all headphones, you must assign the custom template you just created to an item definition.

To assign the custom template:

  1. On the Business Tools dashboard, click Composer.

    In the Templates section, you can see the custom template Headphones Template that you just created.

  2. In the Templates section, from the drop-down list, click Associate to Item Definitions.

  3. In the Associate to Item Definition dialog box, from the Catalog list, click Habitat_Master, and confirm your changes.

  4. Select the Headphones check box and confirm your changes.

Approve and publish the Headphones template

To see the new properties on the storefront, you must approve and publish the updated version of the entity item.

To approve and publish the entity item:

  1. On the Business Tools, click Merchandising.

  2. In the Catalogs section, click Habitat_Master.

  3. In the Categories section, click Departments, and then click Audio.

  4. In the list of sellable items, to open the product page, click Studio X Over-the-Ear Wireless Headphones.

  5. In the Summary section, in the drop-down list, click Promote to next workflow state and, in the Command drop-down list, click Submit, and confirm your changes.

  6. To complete the workflow, in the Summary section, in the drop-down list, click Promote to next workflow state and, in the Command drop-down list, click Approve, and confirm your changes.

  7. To update the template in Sitecore and see your changes in the Content Editor, on the Sitecore Launchpad, click Content Editor.

  8. On the ribbon, on the Commerce tab, click Update Data Templates.

    This step generates templates using the new definition defined in the previous procedure so that the new property is available. If you used Composer to remove fields or templates, you must delete the data templates and then update them to see your changes.

  9. On the Commerce tab, click Refresh Commerce Cache.

    To see the changes you have made, go to sitecore/Content/Sitecore/Storefront/Home/Catalogs/Habitat_Master/Departments/Audio and click Noise-Canceling Over-the_Ear Headphones.

Extend the catalog template with a new field for the entity type

To extend the catalog template with a new field for the entity type:

  1. In the content tree, go to sitecore/Templates/Commerce/Catalog and click Commerce Catalog.

  2. On the Builder tab, in the Template Overrides section, click Add a new field.

  3. Define a field name (HeadphonesTemplate) for the custom template, specify the same properties as the other templates in this section, and click Save.

    This adds a new field in the Template Overrides section (sitecore/Content/ Sitecore/Storefront/Home/Catalogs/Habitat_Master).

Note

The Dynamic Bundle override template is not used.

Create a custom page for the entity type

To create a custom page for the entity type:

  1. To create a new page item template at the tenant level, in the content tree, go to sitecore/Templates/Project/Sitecore, right-click the Commerce Product template and click Duplicate.

  2. In the Message dialog box, enter Headphones Product, and click OK.

  3. With the Headphones Product selected, on the Content tab, in the Data section, add the Headphones template (Templates\Commerce\Catalog Generated) from the Base template list to the Selected list.

  4. In the Selected list, double-click the Commerce Product template to move it out of the Selected list and then use the up/down arrows to change the order of the selected templates. The Selected templates list now looks as follows:

  5. On the ribbon, click Save and then click OK to confirm your changes.

  6. Go to sitecore/Content/Sitecore/Storefront/Home/Catalogs, click Habitat_Master and, in the Template Overrides section, in the HeadphonesTemplate field, click Headphones Product (Templates\Project\Sitecore) and, on the ribbon, click Save.

  7. On the ribbon, on the Commerce tab, click Refresh Commerce Cache.

Associate the custom item template to the custom page design

Now you must associate the custom template Headphones to the custom page design.

To associate the custom item template to the custom page design:

  1. In the content tree, go to sitecore/Content/Sitecore/Storefront/Presentation/Page Designs.

  2. Right-click Commerce Product Page, click Duplicate and, in the Message dialog box, in the Enter a new name for the page field, enter Headphones Page Design, and click OK.

  3. In the content tree, click Page Designs (sitecore/Content/Sitecore/Storefront/Presentation) and, on the Content tab, in the Designing section, map the Headphones Product template to Headphones Page Design.

  4. On the ribbon, click Save.

    When you select the Studio X Over-the-Ear Wireless Headphones, you can see in the Quick Info section that this sellable item is now linked to the new template.

    You can now navigate to sitecore/Content/Sitecore/Storefront/Home/Catalogs/Habitat_Master/Departments/Audio, right-click Studio X Over-the-Ear Wireless Headphones and open the page in the Experience Editor.

    Important

    You cannot edit layout and components in the Experience Editor when you open a catalog item directly or when you navigate to the catalog item, although you can edit some of the text. To edit components, in the Content Editor, go to sitecore/Content/Sitecore/Storefront/Presentation/Partial Designs/Default Main Product Page Content.

Do you have some feedback for us?

If you have suggestions for improving this article,