Walkthrough: Creating a custom module and rendering for SXA Storefront

Abstract

How to create a custom module and add a cloned Commerce rendering to it.

To simplify storefront development when creating a custom solution, you can customize standard renderings while preserving basic Sitecore functionality. We recommend that you clone the original rendering and make your changes on the cloned instance.

This walkthrough describes how to:

  • Create a custom module

  • Clone a Commerce rendering

  • Add the custom module to a storefront site

  • Create a data folder and configure the data source item template

Before you clone renderings, you need to create a custom module in which you can store the customized cloned renderings. This follows the Helix principles that items in a module be grouped together.

To create a custom module:

  1. In the Content Editor, go to /sitecore/System/Settings, right-click Feature and click Insert, Folder to create a folder to hold the custom modules.

  2. In the Message dialog box, enter a name for the folder, for example My custom modules, and click OK.

  3. In the content tree, go to /sitecore/System/Settings/Feature, right-click and create a custom module.

  4. In the Create new module dialog box, enter a name for the module, for example My custom module and, in the Add to module group field, select the folder you created in step 1 (for example Custom modules).

  5. To accept the default values for the remaining parameters, click Proceed and then click Close.

    Now when you create a new tenant or site, My custom module is available in the Create a tenant and Create a new SXA site dialog box.

Generally, it is easier to take an existing rendering, clone it and customize it rather than create a new rendering from scratch. To help you decide, refer to the Flowchart to determine whether to create a custom rendering.

Note

Commerce Controllers do not verify the path to rendering view property of the corresponding controller rendering items. For this reason, you need to specify the data source.

To clone a Commerce rendering:

  1. In the Content Editor, go to the rendering you want to clone, for example, /sitecore/Layout/Renderings/Feature/Commerce Experience Accelerator/, and clone a rendering, for example the Shopping Cart Lines.

  2. In the Create derivative rendering dialog box, enter a name for the new rendering, for example Shopping Cart Lines Clone and, in the Add to module field, select the module you created in step 2.

  3. To accept the default values for the remaining parameters, click Proceed and Close.

Now that you have a custom module that contains the cloned rendering, you must make it available to the storefront site.

To add the custom module to a storefront site:

  1. In the Content Editor, go to /sitecore/Content/<tenant>/<site> and add the custom module to the site.

  2. To see the cloned rendering in the Experience Editor, go to /sitecore/Content/<tenant>/<site>, right-click Home and click Experience Editor.

    In the Toolbox, you can see a new group that contains the cloned rendering.

    Custom module and rendering in the Toolbox.

Note

New renderings that you clone are not automatically added to the storefront site. You must manually add them by repeating step 1.

A cloned rendering that works with a dedicated data source automatically gets its own new datasource item and folder template created as part of the cloning process. Depending on the option you select on the Datasource tab in the Create derivative rendering dialog box, the cloned rendering either inherits from the original datasource or works with a copy of the original datasource. Regardless, the cloned rendering is not automatically configured and available as insert option under the site data folder. For this reason, you need to create a new custom folder based on the folder template to hold the datasource items for the custom rendering with the new datasource templates configured as insert options.

To create a data folder and configure the the data source:

  1. In the Content Editor, go to /sitecore/Content/<tenant>/<site>/Data, right-click Commerce and click Insert, Folder. In the Message dialog box, enter a name, for example My custom module, and click OK.

  2. On the ribbon menu, on the Configure tab, in the Insert Options section, click Assign.

  3. In the Insert Options dialog box, go to /Templates/Feature/<My custom modules>/<My custom module> and double-click the cloned rendering folder (for example, Shopping Cart Lines Clone Folder) to move it to the Selected list, and click OK.

  4. On the ribbon menu, on the View tab, click the Standard fields check box.

  5. On the ribbon menu, on the Home tab, in the Insert section, click the name of the folder template for the custom rendering (for example My Custom Shopping Cart Lines Folder). In the Message dialog box, enter a name for the new item, for example, My Custom Shopping Cart Lines, and click OK.

  6. In the Content Editor, go to the cloned rendering (/sitecore/Layout/Renderings/Feature/My custom modules/My custom module/<cloned rendering).

  7. On the Content tab, in the Data section, update the Data source field to find the new custom module folder under Data, for example, query:./ancestor::*[@@templatename='Site']/Data/Commerce/My custom module and save your changes.

  8. Open or refresh the Experience Editor, and drag the custom rendering onto the page.

  9. Click the rendering and, on the rendering toolbar, click Add or change the associated content and click Add associated content.

  10. In the Select the Associated Content dialog box, next to Data, click Create and, in the Message dialog box, enter a name, for example My Custom Shopping Cart Lines, click OK, and save your changes.