Customize Commerce tenant and site scaffolding

Abstract

How to create and deploy Commerce scaffolding plans with custom items.

You can add to or modify the templates and scripts provided for tenant and site scaffolding. This enables you to, for example, add a new page or run a new script automatically when you create a tenant or site simply by selecting the new module. The same updates can be made to an existing site by adding the new module to the tenant or site.

You manage scaffolding plans using the commands in the PowerShell Script Results dialog box.

To manage the scaffolding plan:

  1. In the Content Editor, go to the scaffolding plan you want to update. For example, to modify the Storefront Components Scaffolding Plan, go to /sitecore/System/Settings/Feature/Commerce Experience Accelerator/Storefront Components/Storefront Components Scaffolding Plan.

  2. Right-click the scaffolding plan and click Scripts, Edit Scaffolding Plan.

    The items managed by the plan are displayed in the PowerShell Script Results dialog box.

    Powershell Script Results dialog box showing available commands.
  3. In the Scaffolding Plan Editor (PowerShell Script Results dialog box), use any of the following commands:

    • View - to display the fields and associated values. The following example displays the Catalog Configuration source item for the Habitat Catalog Scaffolding Plan. The Reference Value column shows the original field value under the branch template node. The Dynamic Value column shows the tokenized form of the reference value. Tokenization is used to resolve relative links and values.

      Powershell Script Results
    • Add - to add a new snapshot item. You must define the source item (the item under the Branch template) and the Reference item (the corresponding item under the site). For example, use Add to add a new page to the scaffolding. When you click Add, you are prompted to specify the source and reference items as well as indicate whether you want to include standard fields and which fields to include and exclude from the snapshot.

    • Remove - to delete the snapshot item.

    • Update Item - to update the fields and associated values in an existing snapshot item. For example, use Update item when you have changed the Login page (reference item) and want to replace it in the plan (source item) with the new version.

    • Update Plan - to update the items contained in an existing plan. When you click Update Plan, you are prompted to select the tenant or site that you want to update the plan from.

    • Deploy Plan - to execute the items in the plan, which means adding items to a new site or replacing them if they already exist. When you click Deploy Plan, you are prompted to select the tenant or site that you want to deploy the plan to.

This procedure provides an example of how to add a new page to the site scaffolding plan and uses the Storefront site template and Habitat catalog.

To add a new page to the site scaffolding plan:

  1. In the Content Editor, go to sitecore/Content/<tenant>/Storefront/Home/Landing Pages, right-click Landing Page and click Insert, From template, go to /sitecore/templates/Project/<tenant> and select the page template you want to use, and then click Insert.

  2. To copy the new page to the branch template, in the tree view, right-click the new page, click Copying, Copy To, go to /sitecore/Templates/Branches/Project/Commerce Experience Accelerator/<site>/Pages/<site> Pages/Home/Landing Pages and click Copy.

  3. Change the template of this newly copied item to /sitecore/Templates/Branches/Foundation/Commerce Experience Accelerator/Commerce Foundation/Tenant Templates/Page.

  4. To add the new page to the site scaffolding, in the Content Editor, go to /sitecore/System/Settings/Project/Commerce Experience Accelerator, right-click Storefront Template Scaffolding Plan and click Scripts, Edit Scaffolding Plan.

    The location of the new page (in the Foundation, Feature, or Project folder) is dictated by Helix principles.

  5. In the Powershell Script Results dialog box, on the ribbon menu, click Add.

  6. In the Create New Item Snapshot dialog box, click in the Source Item field and go to Branches/Project/Commerce Experience Accelerator/Storefront/Pages/Storefront Pages/Home/Landing Pages/<New page>.

  7. Click in the Reference Item field and go to sitecore/Content/Sitecore/Storefront/Home/Landing Pages/<New page> and click Create.

    The next time you create a new site, the new page is automatically added to the site.

    New page displayed in the Content Editor for the new site.

Follow the high-level steps below to create a scaffolding plan that contains customized items and deploy it to a new or existing site.

To create a custom scaffolding plan:

  1. In the Content Editor, go to sitecore/System/Settings/<Feature or Foundation>/Project/<module>.

  2. Create a scaffolding plan definition item based on the /sitecore/Templates/Foundation/Commerce Experience Accelerator/Scaffolding/Scaffolding Plan template.

    Ensure the plan has an relevant name that indicates the general feature or purpose. In the following example, the Demo Scaffolding Plan is in the Commerce Experience Accelerator folder.

    Scaffolding Plan definition item
  3. Create the plan deployment script and put it in the /sitecore/System/Modules/PowerShell/Script Library/Commerce Experience Accelerator/Functions/Commerce Site Features/Scripts folder.

  4. Paste the following code in the plan deployment script.

    Note

    Replace the [ID of Scaffolding plan definition] in the code with the ID of the plan definition item you created.

    Import-Function Deploy-ScaffoldingPlan
    
    function Invoke-ModuleScriptBody {
        [CmdletBinding()]
        param(
            [Parameter(Mandatory = $true, Position = 0 )]
            [Item]$Tenant,
            
            [Parameter(Mandatory = $true, Position = 1 )]
            [Item[]]$TenantTemplates
            )
     
            begin {
                Write-Verbose "Cmdlet Invoke-ModuleScriptBody - Begin"
            }
     
            process {
                Write-Verbose "Cmdlet Invoke-ModuleScriptBody - Process"
                $Plan = Get-Item master: -ID [ID of Scaffolding plan definition]
                $result  = Deploy-ScaffoldingPlan $Plan $Tenant
            }
            
            end {
                Write-Verbose "Cmdlet Invoke-ModuleScriptBody - End"
            }
    }
    

    The ID of the scaffolding plan definition is processed in the deployment script as shown in the following image.

    Example of a scaffolding plan deployment script
  5. To create a new scaffolding action of type ExecuteScript under the scaffolding plan that you want this action to be part of, right-click the module and click Insert, Execute Site Script.

    In the following image, the new scaffolding plan is called Demo Scaffolding Module and the new action is Deploy scaffolding plan.

    Demo scaffolding module and plan
  6. In the tree view, click the scaffolding action (for example, Deploy scaffolding plan) and, on the Content tab, in the Script section, go to the location of the Deploy scaffolding plan script and then double-click to move it to the Selected list.

    Deployment script selected
  7. Save your changes.