I recently spent some time troubleshooting SitecoreAI Page Branches, and what initially looked like one problem actually turned out to be two different things.
The requirement was fairly straightforward:
We wanted content authors to be able to create pages using Page Branches directly from Page Builder, without having to manually configure insert options on every page template.
At the same time, we wanted the Page Branch to provide the required datasource structure for the components used by the page design.
That led to two questions:
- Why are my Page Branches not appearing as insert options?
- Why aren't the datasource items being automatically created when a page is created from a Page Branch?
The interesting part was that the answers were different.
The Original Requirement
We had Page Branches configured under:
/sitecore/content/mysite/Shared/Presentation/Page BranchesThe idea was to configure a rule on the Page Branches folder so that a particular Page Branch would be available as an insert option when the current item was in the appropriate site context.
For example, the expectation was essentially:
If the current item is in the required site context, allow the Blog Page Branch as an insert option.
Instead, the Page Branch was not consistently appearing as an available insert option.
As a workaround, I had added the Page Branch ID directly to the Insert Options field on the standard values of the page template.
That worked, but it wasn't the behaviour I wanted.
The First Investigation: Page Branch Rules
Sitecore support investigated the Page Branch configuration and found something interesting.
Some of the subitems under the Page Branches folder contained rules that had actions but no conditions.
After removing those rules, the behaviour still wasn't completely resolved, so the investigation continued.
Eventually, the Sitecore logs revealed the important clue:
ERROR Exception while getting item Masters
Exception: System.NullReferenceException
Message: Object reference not set to an instance of an object.
Source: Sitecore.XA.Foundation.PageBranches
at Sitecore.XA.Foundation.PageBranches.PageBranchesContext.ParseRules(Item pageBranchesFolder)
at Sitecore.XA.Foundation.PageBranches.PageBranchesContext.GetInsertOptionsForSite(Item item, Item site)
at Sitecore.XA.Foundation.PageBranches.PageBranchesContext.GetInsertOptions(Item item)
at Sitecore.XA.Foundation.PageBranches.Processors.UiGetMasters.GetItemMasters.Process(GetMastersArgs args)This was much more useful than simply knowing that the Page Branch wasn't appearing.
The Hidden <ruleset /> Value
The problem turned out to be the Rules field itself.
Although the rule had apparently been cleared, the field still contained a value similar to:
<ruleset />This is easy to miss when working with the normal field editor because visually it can look as though there is no rule configured.
Sitecore support recommended switching the field to Raw Values and removing the remaining value.
Once that was done, the Page Branch insert options started behaving correctly.
This was a good reminder that when troubleshooting Sitecore rules, especially when the UI says there is no rule, it can be worth checking the underlying raw field value.
Then Came the Datasource Question
Once the Page Branch insert-option problem was resolved, I moved on to the second requirement.
The Page Design contained a Partial Design with a Hero Banner rendering.
The rendering had:
IsAutoDatasourceRendering = trueSo the expectation was that when a content author created a new page from the Page Branch, Sitecore would automatically create the datasource items required by the Hero Banner.
My setup was roughly:
- Set
IsAutoDatasourceRenderingtotrueon the rendering. - Create a Partial Design containing the Hero Banner.
- Create a Page Design containing that Partial Design.
- Map the Page Design to the page template.
- Create a Page Branch based on that page template.
- Create a
Datafolder under the Page Branch's$nameitem. - Create a new page from that Page Branch in Page Builder.
What I expected was for Sitecore to create the page and automatically generate the associated datasource items.
But that didn't happen.
Why IsAutoDatasourceRendering Doesn't Help Here
This was the key clarification from Sitecore support.
IsAutoDatasourceRendering automatically generates a datasource when a rendering is added to a page.
But that isn't what is happening when a Page Branch is used.
A Page Branch is effectively providing a predefined structure that is copied into the new page.
So the important distinction is:
| Scenario | What happens |
|---|---|
| Rendering is added to a page | IsAutoDatasourceRendering can generate the datasource |
| Page is created from a Page Branch | The Page Branch structure is copied |
That distinction explained why enabling IsAutoDatasourceRendering did not produce the result I was expecting.
Think of a Page Branch Like a Branch Template
The explanation from Sitecore support was that a Page Branch can be thought of similarly to a branch template.
When a new page is created from the Page Branch, Sitecore copies the structure that exists inside the Page Branch.
In my case, the structure looked roughly like:
Test Page Branch
└── $name
└── DataThere were no datasource items inside the Data folder.
Therefore, when the page was created, Sitecore had nothing to copy other than the page and the Data folder.
The resulting structure was effectively:
New Page
└── DataIt wasn't a failure to generate the datasources. The datasources simply weren't part of the Page Branch structure being copied.
So How Should the Datasources Be Included?
If the Page Branch is expected to contain default datasource items, those datasource items need to be included in the Page Branch structure.
For example:
Test Page Branch
└── $name
└── Data
└── Hero Banner
└── ...
When the Page Branch is used, this structure can then be copied into the new page.
Another approach suggested by Sitecore support is to create a template page containing the desired structure, design it in Page Builder, populate it with the required datasources and then copy that structure into the Page Branch.
What Happens When the Page Design Changes?
This is where the distinction becomes particularly important.
Imagine the Page Design initially contains:
Content Page
└── Hero Bannerand the Page Branch contains the corresponding datasource:
$name
└── Data
└── Hero Banner DatasourceLater, another Partial Design is added to the Page Design:
Content Page
├── Hero Banner
└── Feature CardsThe Page Branch does not magically gain the new Feature Cards datasource just because the Page Design changed.
If the Page Branch is expected to provide that datasource when a new page is created, the Page Branch itself needs to contain the corresponding datasource structure.
This is an important maintenance consideration when using Page Branches.
The Two Problems Were Actually Independent
Looking back, the support case became much easier to understand once these two issues were separated.
| Problem | Root Cause / Behaviour | Resolution |
|---|---|---|
| Page Branch not appearing as insert option | Page Branch rules contained an uncleared <ruleset /> value |
Clear the raw Rules field value |
| Datasource not created when using Page Branch | Page Branch copies its existing structure; IsAutoDatasourceRendering applies when a rendering is added |
Include required datasource items in the Page Branch structure |
What I Learned
There were a couple of useful lessons from this investigation.
First, don't assume that a configuration property applies to every way a rendering can appear on a page.
IsAutoDatasourceRendering is useful when a rendering is added to a page, but a Page Branch follows a different model because it copies a predefined content structure.
Second, check raw field values when Sitecore configuration appears correct but behaves incorrectly.
In this case, the UI suggested that the rule had been cleared, but the underlying field still contained <ruleset />. That small leftover value was enough to cause a NullReferenceException while Sitecore was parsing the Page Branch rules.
And finally, Page Branches should be treated as predefined content structures.
If a Page Branch is expected to provide datasource items, those items need to be part of the structure being copied.
Conclusion
Page Branches are a useful way of giving content authors a predefined starting point for creating pages, but it is important to understand what Sitecore is actually doing behind the scenes.
The Page Branch controls the structure that gets copied into the new page. It isn't the same mechanism as adding a rendering to an existing page.
Once that distinction is clear, the behaviour around IsAutoDatasourceRendering, Page Designs, Partial Designs and datasource items becomes much easier to understand.
And if Page Branch insert options suddenly stop appearing, don't forget to check the underlying Rules field. A seemingly empty field containing <ruleset /> can be enough to break Page Branch rule processing.
Comments
Post a Comment