Lessons from the Front: Mapping Bootstrap Grid Parameters

Intro 📖

While working on a recent project to migrate a Sitecore 9.1 solution to Sitecore XM Cloud, an interesting situation arose with Bootstrap grid parameters. More specifically, with grid rendering parameters configured on renderings migrated from the legacy 9.1 content tree into the XM Cloud content tree.

To start, some (brief?) background on SXA and the grid system. SXA includes several grid systems out-of-the-box (reference), including Bootstrap 4 (BS4) and Bootstrap 5 (BS5). These grid systems allow developers to build responsive layouts in a consistent, predictable way. When adding a new headless site in XM Cloud, BS5 is the default grid system (reference). The supporting Sitecore items for the different grid systems can be found in the content tree under /sitecore/system/Settings/Feature/Experience Accelerator (BS4 and BS5 are highlighted in the screenshot below, but there are others):

The grid system(s) a site uses can be configured on the site’s Settings item, e.g., /sitecore/content/Test Site Collection/Headless Site A/Settings:

When editing a rendering on a page in the Content Editor, Experience Editor, or XM Cloud Pages (which was recently updated 🎉), content authors can configure the grid and set things like column sizes, offsets, order, etc.:

These grid settings are stored as a single rendering parameter named GridParameters associated to the parent rendering in the page’s Renderings and/or Final Renderings field. For example, assuming a Container rendering has the Size settings depicted in the animation above (meaning: Mobile | Size | 12), the raw value of the rendering in presentation details would look something like this:

<r uid="{FE9A8A21-02C7-4EB0-B1B1-DF67ADD29ADD}"
  ...
  s:par="?Styles=%7b6221E315-B00F-4832-9054-B46F347EC247%7d&amp;GridParameters=%7b7465D855-992E-4DC2-9855-A03250DFA74B%7d&amp;DynamicPlaceholderId=1"
  s:ph="headless-main" />

The s:par attribute stores a URL-encoded query string containing the rendering parameters. The value of GridParameters is “%7b7465D855-992E-4DC2-9855-A03250DFA74B%7d”, or, when URL-decoded, “{7465D855-992E-4DC2-9855-A03250DFA74B}”. That looks a lot like a Sitecore item ID, right 😉?

📝 Note that, if there was more than one grid parameter, GridParameters would be a pipe-delimited (“|”) string of IDs.

The ID points to the grid size definition item located at (in this case, for BS5) /sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 5/Bootstrap 5 Grid Definition/Extra small/Size/12. Finally, as part of the definition of the size item, the applicable Bootstrap CSS class is specified in the Class field. It is this class (or classes, if more than one grid parameter is specified) that is applied to the markup when the component is rendered in the UI.

For a slightly more “real world” example, assume a Container rendering had (BS5) grid settings that looked like this:

Revolutionize Your Business With Generative AI

From product design and software development to virtual agents, content creation, and reporting, GenAI is transforming business. Our AI experts help you unlock GenAI’s full potential and drive growth.

Let’s Get Started

The value of the GridParameters rendering parameter would be:

<r uid="{FE9A8A21-02C7-4EB0-B1B1-DF67ADD29ADD}"
  ...
  s:par="GridParameters=%7B7465D855-992E-4DC2-9855-A03250DFA74B%7D%7C%7B597223E6-B7EE-4D86-BC89-F7DA3DE8A7E5%7D%7C%7B7D865A50-F089-421E-ACDC-620DB03BC49D%7D&amp;FieldNames&amp;BackgroundImage&amp;Styles=%7B6221E315-B00F-4832-9054-B46F347EC247%7D&amp;RenderingIdentifier&amp;CSSStyles&amp;DynamicPlaceholderId=1"
  s:ph="headless-main" />

Which, URL-decoded would be: “{7465D855-992E-4DC2-9855-A03250DFA74B}|{597223E6-B7EE-4D86-BC89-F7DA3DE8A7E5}|{7D865A50-F089-421E-ACDC-620DB03BC49D}”.

The JSON pulled from the layout service for the rendering would look like this:

...
"uid": "fe9a8a21-02c7-4eb0-b1b1-df67add29add",
"componentName": "Container",
"dataSource": "",
"params": {
  "GridParameters": "col-12 col-md-10 col-xl-5", // <=== HERE
  "Styles": "container",
  "DynamicPlaceholderId": "1",
  "FieldNames": "Default"
}
...

And, finally, the resulting markup would look like this:

<div class="col-12 col-md-10 col-xl-5">
...
</div>

For the remainder of this post, assume the following:

• The legacy 9.1 solution used BS4.
• The XM Cloud solution used BS5 (but supported BS4).
• The legacy 9.1 renderings were migrated to XM Cloud (and converted to JSON renderings).
• The migrated renderings were implemented and appear as expected in the head application UI, complete with the expected/correct CSS grid classes.

The Problem 🙅‍♂️

Okay, so, what’s the issue? We have BS4 and BS5 available in XM Cloud and the migrated renderings are emitting the correct grid styles in the markup (e.g., col-12). What’s the problem?

The problem came when content authors went to view and/or update the grid style parameters, either in the Content Editor, Experience Editor, or XM Cloud Pages. There wasn’t an error or anything, but nothing appeared in the Grid tab or the Advanced tab when editing the rendering parameters for the rendering, as if the parameters weren’t there…🤔.

When viewing raw values of the Renderings and Final Renderings fields on the page, the GridParameters parameter was clearly present–so why wasn’t anything appearing in the editing UI for content authors?

The Cause 🐛

As you may have already guessed (and, yes, it seems obvious now), the reason for this was that the item IDs referenced in the grid rendering parameter are different between BS4 and BS5, even for two grid size definition items with the same CSS class. For example, the col-12 item for BS4 (/sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 4/Bootstrap 4 Grid Definition/Extra small/Size/12) didn’t have the same ID as the matching col-12 item in BS5 (/sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 5/Bootstrap 5 Grid Definition/Extra small/Size/12).

Because the new XM Cloud solution had both the supporting BS4 and BS5 items available under /sitecore/system/Settings/Feature/Experience Accelerator, the BS4 grid CSS classes were still coming through in the UI. However, when editing, the rendering parameters modal was expecting the BS5 IDs (since the site was configured to use BS5) to bind the editing controls. Since no BS5 parameter IDs were found, the editing controls in the modal weren’t bound to the correct values and appeared broken for content authors.

The Solution ✅

As usual, Sitecore PowerShell Extensions (SPE) to the rescue. A PowerShell script was written to iterate over page renderings, map the Bootstrap 4 parameter IDs to their equivalent Bootstrap 5 parameter IDs based on a CSS class name match, if possible, and then save the updated rendering parameters back to the page.

⚠ In some cases, it wasn’t possible to map parameters between the two grid systems as there are breaking changes between BS4 and BS5. In BS4, for example, some Order definitions exist that do not exist in BS5 i.e., /sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 4/Bootstrap 4 Grid Definition/Extra small/Order/6.

Luckily, in the case of this particular project, the vast majority of the parameters did have a BS5 equivalent and were remapped accordingy, allowing the rendering parameters modal to properly reflect the current grid parameters for content authors. ✨

The Script ⚙

Update-GridParameters.ps1

A few highlights on the script and how it works:

1. 1. The script is intended to be executed via the PowerShell ISE interface in Sitecore.
   2. Update the -Path parameter according to where your content pages live in the tree; I’d recommend running the script on a subset of items initially.
   3. The script emits a report using the Show-ListView command that enumerates which renderings and parameters were updated (or that won’t be updated); the report can be exported if you need to, say, attach it to a work item in Azure DevOps or JIRA.
   4. If a grid rendering parameter ID cannot be mapped to a BS5 ID or if the candidate ID isn’t a BS4 ID (including if it’s already a BS5 ID), then it is skipped but still appears in the report.
   5. Keep the -WhatIf switch set until you’re ready to apply the updates.

Here’s the script:

Function Update-GridParameters {
    <#
    .SYNOPSIS
        Maps Bootstrap 4 grid rendering parameters to Bootstrap 5 grid rendering parameters.

    .DESCRIPTION
        This function maps Bootstrap 4 grid rendering parameter IDs to their Bootstrap 5 equivalent rendering parameter IDs, if possible.

    .NOTES
        Nick Sturdivant | Perficient | nick.sturdivant@perficient.com | https://www.linkedin.com/in/nicksturdivant/
    #>

    param
    (
        [Parameter()]
        [String] $Path,

        [Parameter()]
        [Switch] $WhatIf
    )

    BEGIN {
        Write-Host "Beginning $($MyInvocation.MyCommand)"
    }

    PROCESS {
        # get bootstrap 4 grid parameter definitions
        $bs4GridParameters = Get-ChildItem -Path "/sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 4/Bootstrap 4 Grid Definition" -Recurse `
        | Where-Object {
            $_.TemplateID -eq "{CB3B3906-BE80-4D9B-A2A4-038193DA5422}" # /sitecore/templates/Foundation/Experience Accelerator/Grid/Grid Definition Items/Class
        }

        # get bootstrap 5 grid parameter definitions
        $bs5GridParameters = Get-ChildItem -Path "/sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 5/Bootstrap 5 Grid Definition" -Recurse `
        | Where-Object {
            $_.TemplateID -eq "{CB3B3906-BE80-4D9B-A2A4-038193DA5422}" # /sitecore/templates/Foundation/Experience Accelerator/Grid/Grid Definition Items/Class
        }

        # build mapping
        $bs4To5Mappings = @()
        foreach ($bs4GridParameter in $bs4GridParameters) {
            # match bootstrap 5 parameter based on class name
            $bs5GridParameter = $bs5GridParameters | Where-Object { $_.Fields["Class"].Value -eq $bs4GridParameter.Fields["Class"].Value }

            if ($null -ne $bs5GridParameter) {
                $bs4To5Mappings += [PSCustomObject]@{
                    BS4Id    = $bs4GridParameter.ID
                    BS4Class = $bs4GridParameter.Fields["Class"].Value
                    BS5Id    = $bs5GridParameter.ID
                    BS5Class = $bs5GridParameter.Fields["Class"].Value
                }
            }   
        }

        $report = @()

        Write-Host "Processing $Path..." -ForegroundColor Cyan
    
        # get children based on path parameter, filtering to only those items with a rendering defined in their final layout
        $items = Get-ChildItem -Path $Path -Recurse | Where-Object { ($null -ne (Get-Rendering -Item $_ -FinalLayout)) }
    
        foreach ($item in $items) {
            $renderings = Get-Rendering -Item $item -FinalLayout

            if ($null -ne $renderings) {
                foreach ($rendering in $renderings) {
                    # get grid rendering parameter
                    $renderingParameter = Get-RenderingParameter -Rendering $rendering -Name "GridParameters"

                    if ($null -ne $renderingParameter) {
                        Write-Host "Processing grid rendering parameters on item $($item.ID), rendering $($rendering.UniqueId)..." -ForegroundColor Green
                        $gridParametersIdString = $renderingParameter["GridParameters"]

                        if (-not [string]::IsNullOrWhiteSpace($gridParametersIdString)) {
                            $gridParameterIds = $gridParametersIdString.Split("|")
                            $newGridParameterIds = @()

                            foreach ($gridParameterId in $gridParameterIds) {
                                # check if the parameter is bootstrap 4
                                $mappedParameter = $bs4To5Mappings | Where-Object { $_.BS4Id.ToString() -eq $gridParameterId } | Select-Object -First 1

                                if ($null -eq $mappedParameter) {   
                                    $message = "Grid parameter ID $gridParameterId is not a Bootstrap 4 parameter that can be mapped to a Bootstrap 5 parameter, retaining original ID."
    
                                    Write-Host $message -ForegroundColor Yellow
    
                                    $report += @{
                                        ItemId                 = $item.ID
                                        ItemPath               = $item.FullPath
                                        RenderingItemId        = $rendering.ItemID
                                        RenderingUniqueId      = $rendering.UniqueId
                                        CurrentGridParameterId = $gridParameterId
                                        MappedGridParameterId  = "N/A"
                                        GridClassName          = "N/A"
                                        Notes                  = $message
                                    }

                                    $newGridParameterIds += $gridParameterId

                                    # process next parameter
                                    continue
                                }
    
                                # map to bootstrap 5 parameter
                                $report += @{
    
                                    ItemId                 = $item.ID
    
                                    ItemPath               = $item.FullPath
    
                                    RenderingItemId        = $rendering.ItemID
    
                                    RenderingUniqueId      = $rendering.UniqueId
    
                                    CurrentGridParameterId = $gridParameterId
    
                                    MappedGridParameterId  = $mappedParameter.BS5Id.ToString()
    
                                    GridClassName          = $mappedParameter.BS5Class
    
                                    Notes                  = "Mapping Bootstrap 4 grid parameter ID $gridParameterId to Bootstrap 5 grid parameter ID $($mappedParameter.BS5Id.ToString())."
    
                                }
    
                                $newGridParameterIds += $mappedParameter.BS5Id.ToString()   
                            }
    
                            $newGridParametersIdString = $newGridParameterIds -join "|"
    
                            Write-Host "Current: $gridParametersIdString"
    
                            Write-Host "Mapped: $newGridParametersIdString"
    
                            if ($gridParametersIdString -eq $newGridParametersIdString) {   
                                Write-Host "Current and mapped grid parameters match, skipping update..." -ForegroundColor Yellow
                                
                                # process next rendering
                                continue
                            }
    
                            # set new rendering parameter   
                            $setMessage = "Setting new grid parameters on item $($item.ID) ($($item.FullPath)), rendering $($rendering.UniqueId)..."
    
                            Write-Host $setMessage -ForegroundColor Yellow
    
                            $newGridParameters = [Ordered]@{"GridParameters" = $newGridParametersIdString }
    
                            $report += @{
                                ItemId                 = $item.ID
                                ItemPath               = $item.FullPath
                                RenderingItemId        = $rendering.ItemID
                                RenderingUniqueId      = $rendering.UniqueId
                                CurrentGridParameterId = $gridParametersIdString
                                MappedGridParameterId  = $newGridParametersIdString
                                GridClassName          = ""
                                Notes                  = "$setMessage ($gridParametersIdString ==> $newGridParametersIdString)"
                            }

                            if (-not $WhatIf) {
                                # update new grid parameters and then update the rendering
                                $rendering | Set-RenderingParameter -Parameter $newGridParameters | Set-Rendering -Item $item -FinalLayout
                            }
                        }
                    }
                }
            }
        }
    
        # display report
        $report |
        Show-ListView -Property @{ Label = "Item ID"; Expression = { $_.ItemId } },
        @{Label = "Item Path"; Expression = { $_.ItemPath } },
        @{Label = "Rendering Item ID"; Expression = { $_.RenderingItemId } },
        @{Label = "Rendering Unique ID"; Expression = { $_.RenderingUniqueId } },
        @{Label = "Current Grid Parameter ID"; Expression = { $_.CurrentGridParameterId } },
        @{Label = "Mapped Grid Parameter ID"; Expression = { $_.MappedGridParameterId } },
        @{Label = "Grid Class Name"; Expression = { $_.GridClassName } },
        @{Label = "Notes"; Expression = { $_.Notes } }
    }

    END {
        Write-Host "Ending $($MyInvocation.MyCommand)"
    }
}

# 1. Change the Path parameter as necessary, depending on where the content pages are in the tree.
# 2. Use the -WhatIf switch to preview the changes; remove the switch to update the renderings and pages.
Update-GridParameters -Path "/sitecore/content/Test Site Collection/Headless Site A" -WhatIf

Bonus Script 🌟

My colleague (and Sitecore MVP) Eric Sanner happened to write a similar script recently. I can neither confirm nor deny that the two of us wrote two scripts to do the same thing at around the same time 😅. His script can be found below and illustrates another approach to solve the same problem. Thanks for sharing, Eric!

BS4toBS5.ps1

<#
    .SYNOPSIS
       Update Final Layouts
        
    .DESCRIPTION
        Find bootstrap4 grid settings in final layout and convert to bootstrap5
        
    .NOTES  
        Eric Sanner | Perficient | eric.sanner@perficient.com | https://www.linkedin.com/in/ericsanner/      
#>

#BEGIN Config
$database = "master"
$allowDelete = $false
#END Config

#BEGIN Helper Functions

function Write-LogExtended {
    param(
        [string]$Message,
        [System.ConsoleColor]$ForegroundColor = $host.UI.RawUI.ForegroundColor,
        [System.ConsoleColor]$BackgroundColor = $host.UI.RawUI.BackgroundColor
    )

    Write-Log -Object $message
    Write-Host -Object $message -ForegroundColor $ForegroundColor -BackgroundColor $backgroundColor
}

function Strip-Html {
    #https://www.regular-expressions.info/lookaround.html#lookahead Replaces multiple spaces with a single space
    param (
        [string]$text
    )
    
    $text = $text -replace '<[^>]+>',' '
    $text = $text -replace " (?= )", "$1"
    $text = $text.Trim()
    
    return $text
}

function Truncate-Output {
    param (
        $obj,
        $maxLeng
    )
    
    $ret = "";
    
    if($obj -ne $null)
    {
        $str = $obj.ToString().Trim()
        $leng = [System.Math]::Min($str.Length, $maxLeng)
        $truncated = ($str.Length -gt $maxLeng)
        
        $ret = $str.Substring(0, $leng)
        if($truncated -eq $true)
        {
            $ret = $ret + "..."
        }
    }

    return $ret
}

#END Helper Functions

#BEGIN Sitecore Functions

function Get-SitecoreItemById {
    param(
        [string]$id
    )

    return Get-Item -Path $database -ID $id -ErrorAction SilentlyContinue
}

function Update-SitecoreItem {
    param(
        [Sitecore.Data.Items.Item]$item,
        [System.Collections.Hashtable]$updates
    )
    
    if($item -eq $null)
    {
        Write-LogExtended "[E] Error updating item $($item) - Item is null" Red
        return
    }
    
    if($updates -eq $null)
    {
        Write-LogExtended "[E] Error updating item $($item) - Update hashtable is null" Red
        return
    }
        
    $changeDetected = $false
    $foregroundColor = "Green"
    
    Write-LogExtended "[I] Updating Item $($item.ID) - $($item.Name)"
    $item.Editing.BeginEdit()
    
    foreach($key in $updates.GetEnumerator())
    {
        if($item.($key.Name) -ne $null)
        {
            $output = "Field Name '$($key.Name)' Current Value: '$(Truncate-Output $item.($key.Name) 40)' New Value: '$(Truncate-Output $key.Value 40)'"            
            
            if($item.($key.Name) -ne $key.Value)
            {
                Write-LogExtended "[U] $($output)"
                $item.($key.Name) = $key.Value
                $changeDetected = $true
            }
            else
            {
                Write-LogExtended "[-] $($output)"
            }
        }
    }
    
    $itemModified = $item.Editing.EndEdit()
    
    if($changeDetected -ne $itemModified)
    {
        $foregroundColor = "Red"
    }
    
    Write-LogExtended "[I] Change Detected: $($changeDetected) Item modified $($itemModified)" $foregroundColor
}
#END Sitecore Functions

#BEGIN Conversion Functions

function ProcessItem {
    param(
        [Sitecore.Data.Items.Item]$item     
    )
    
    Write-LogExtended "[I] Processing item $($item.ID): $($item.ItemPath)"

    $gridPattern = "GridParameters=%7B(\w{8}-\w{4}-\w{4}-\w{4}-\w{12})%7D"
    $bs4Pattern = "Bootstrap 4"
    $finalRenderings = $item["__Final Renderings"]
    $finalRenderingsNew = $item["__Final Renderings"]
    $gridRenderings = @{}

    $gridMatches = Select-String -InputObject $finalRenderings -Pattern $gridPattern -AllMatches    
    foreach($gridMatch in $gridMatches.Matches)
    {       
        if(!$gridRenderings.ContainsKey("$($gridMatch.Groups[1].Value)"))
        {
            $gridRenderingItem = Get-SitecoreItemById $gridMatch.Groups[1].Value
            $gridRenderings["$($gridMatch.Groups[1].Value)"] = $gridRenderingItem.ItemPath          
        }
    }

    foreach($rendering in $gridRenderings.GetEnumerator())
    {
        $bs4Matches = Select-String -InputObject $rendering.Value -Pattern $bs4Pattern
        if($bs4Matches)
        {
            Write-LogExtended "[I] Found BS4 GridParams $($rendering.Value)" -ForegroundColor "Red"
            $bs4Items.Add($item.ID, $item.Path)

            if($bs4ToBs5Mapping.ContainsKey($rendering.Name))
            {
                Write-LogExtended "[I] Mapping $($rendering.Name) to $($bs4ToBs5Mapping[$rendering.Name])"  -ForegroundColor "Green"
                
                $finalRenderingsNew = $finalRenderingsNew -replace $rendering.Name, $bs4ToBs5Mapping[$rendering.Name]
            }
            else
            {
                Write-LogExtended "[E] No Mapping Found for $($rendering.Name)"  -ForegroundColor "Red"
            }
        }
    }   

    if($update -and $finalRenderings -ne $finalRenderingsNew)
    {
        $updates = @{}  
        $updates.Add("__Final Renderings", $finalRenderingsNew)

        Update-SitecoreItem $item $updates
    }
}

#END Conversion Functions

#BEGIN Main

    $update = $true
    $bs4Items = @{}

    $bs4ToBs5Mapping = @{}
    #/sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 4/Bootstrap 4 Grid Definition/Extra small/Size/12 -> /sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 5/Bootstrap 5 Grid Definition/Extra small/Size/12
    $bs4ToBs5Mapping.Add("908E2BC6-C110-4ED7-AF39-7EEACBB31A34", "7465D855-992E-4DC2-9855-A03250DFA74B") 
    #/sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 4/Bootstrap 4 Grid Definition/Extra small/Size/8 -> /sitecore/system/Settings/Feature/Experience Accelerator/Bootstrap 5/Bootstrap 5 Grid Definition/Extra small/Size/8
    $bs4ToBs5Mapping.Add("D65D90FB-45BF-4A04-A1EA-6F348E7CCBEA", "F2A11D85-8B09-40AC-B5D8-A9E1025F899D")    

    $parentPath = "master:/sitecore/content/<tenantName>/<siteName>/Home"
    $childItems = Get-ChildItem -Path $parentPath -Recurse

    $childItems | ForEach-Object {
        ProcessItem $_
    }

    Write-LogExtended "[I] Found $($bs4Items.Count) Items that reference BS4"
    
#END Main

Thanks for the read! 🙏