[Breaking change]: Block Level Variations

[kjac]

Description

The block data format will change to support Block Level Variations.

Version

Umbraco 15

Previous behavior

Block editors does not support variation at block level.

New behavior

Blocks will support variation at block level.

Type of breaking change

• [X] Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• [X] Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

We want to give more opportunities for multilingual sites and personalised content in blocks. By introducing Block Level Variations we'll support invariant block editors with variant blocks. Effectively this means that the structure of the block editor can be the same across all variants, while the property values of the individual blocks can vary between variants. Block Level Variations is opt-in at element type level, meaning the block editors will work as per usual by default.

Recommended action

If you're creating block editor content through code, please read the documentation before upgrading to V15. As the format changes, your code will have to be updated to match. Currently, if you have enabled variance on any element types, this is somewhat ignored by Umbraco. Moving forward, element type variance will carry meaning. We recommend you test any usage of variance enabled element types thoroughly - ideally disable the element type variance.

Affected APIs

We are still assessing the scope of this change. At this time we can say for sure that the BlockItemData will change, as it carries the block data format. This in turn will incur changes in most parts of the block editor value handling, but likely these changes will be internal and non-breaking. We also foresee changes in the way property data indexing for search is handled - the IPropertyIndexValueFactory. These changes will be breaking if you have implemented custom property data indexing. This is however a rare case, so hopefully this breakage will have a low actual impact.

[cornehoskam]

Very excited to see this change happening Kenn! The team over at uMarketingSuite has been asked numerous times if/when personalization on a Block Level is going to be made possible, and with this change we can finally get to work on adding support for it! 👏

[sniffdk]

This is a great change, we've been eagerly awaiting Block Level Variations for a loooong time, thank you 😊🔥

[tristanjthompson]

This is a neat change - will be very useful! I'm interested to understand how this works in when a block list/grid document level property is marked as Vary by Language/Segment at the same time as the block elements within it having block level properties which Vary by Language/Segment.

Example

An example I example think of is if you have a block that's used on 2 different document types - let's say it's a "banner" block. This block has a "Text" property set to vary by language.

• The "homepage" is set to "Vary by Language"
  • There is a block list property on it which is set to "Vary by Language"
  • The block list can have the "banner" block added to it.
• The "content" page is set to "Vary by Language"
  • There is a block list property on it which is not set to "Vary by Language"
  • The block list can have the "banner" block added to it.

In this case - I would assume that if there is a document level block list/grid property with "Vary by Language" set, then it would take priority and the block level "Vary by Language" configuration would be ignored.

e.g.

• Homepage
  • Entire block list varies by language - i.e. new blocks need to be added for each language.
  • If a "banner" block is added, it is used only for the language(s) it is added to and the "Text" field does not vary by language
• Content page
  • Individual blocks within the block list can vary by language - i.e. any block added is used for all languages, with block-level variations.
  • If a "banner" block is added, it is used for all languages and the "Text" field varies by language.

Does that make sense? I can't think of a reason that the document level variation wouldn't take priority over block-level configuration - do we think it will prioritise like this?

[kjac]

@tristanjthompson I might not have understood entirely correctly 🙈 but let me try to answer anyway.

First and foremost, element type variance in previous versions is largely ignored as-is - but it is entirely possible to enable variance at element type level (why? that's a whole other story).

In V15, this will be taken into account, meaning any existing element types with variance should explicitly have their variance disabled - as described above:

Currently, if you have enabled variance on any element types, this is somewhat ignored by Umbraco. Moving forward, element type variance will carry meaning. We recommend you test any usage of variance enabled element types thoroughly - ideally disable the element type variance.

Now, to answer your question: Since the element type variance now matters, your example may count as a misconfiguration. The configuration will have an impact at data level for the individual blocks, which might end up causing a lot of disturbance for the "homepage" in your example.

This feature is meant for the "content" use case in your example; a variant page, with an invariant block editor that contains variant elements.

This is not yet set in stone, but for the time being I'm guessing that the divergence in your example would have to be solved by compositions; you could have a "bannerBase" composition with the common properties for a "heroPageBanner" element type (invariant) and a "contentPageBanner" element type (variant).

In short - we're trying to make this feature "not magic" 😛 so it converges stringently to the configuration, in order to be predictable in the future.

[tristanjthompson]

Thanks @kjac - that does make sense - you're focussing on a specific scenario (invariant block editors with variant blocks) and want things to be predictable for everyone.

For my "homepage" example, you've mentioned this might count as "misconfiguration" - I was wondering if you are going to try to validate against configuring it in this way? I've been thinking about where the validation might kick in and I'm not sure there's an easy way to do this validation to stop someone adding a block with variation to a block editor that is also set to be a variant? And if they do manage to do this, it sounds like you're saying it would cause "disturbance" in the block data? I'm assuming that could break things or cause it to act unpredictably?

I've never been able to easily misconfigure Umbraco in such a way that it would cause disturbance to content data, so I'm wondering if it's worth pre-emptively handling things in a graceful way to avoid this? If not handled, it feels very easy to misconfigure things which might cause a lot of issues for developers/sites.

Do you think it might be more predictable to only recognise block level variation in the specific scenario you're aiming at where the block editor is invariant. For all other configurations (especially where you can't validate against it) you could ignore block level variance to stop any kind of unpredictable disturbance to the data?

[kjac]

@tristanjthompson we'll definitively have to look into these kinds of scenarios; obviously we can't live with common misconfigurations causing issues at data level. I'm quite happy with your feedback here, because this is certainly one of the things we need to address when implementing the feature 😄 so thanks!

[JeffreyPerplex]

Hi @kjac,

it's great to see that this is picked up. Hereby some stuff that we've created before and that perhaps helps you in your thought process. Feel free of course to reach out to me if you need more info / live demo's or anything else.

We've created Perplex Contentblocks in the past (https://github.com/PerplexDigital/Perplex.ContentBlocks) which essential is our variant of a block list editor, but a bit more visual than the Umbraco implementation. Underneath it's using the exact same data structure as Umbraco is using, so swapping from Perplex Contentblocks to Umbraco Blocklist editor is easily possible, because it's (almost) only a different visual representation.

Within uMarketingSuite we've built an extra layer on top of Perplex Contentblocks (https://www.nuget.org/packages/uMarketingSuite.ContentBlocks/). This adds the possibility for personalized blocks (on a block level). Although the package is not maintained any longer by uMarketingSuite (but perhaps by Perplex towards the future), it may give some inspiration for you.

The default Perplex.Contentblocks looks like this:

• Blocks and the possibility to add new blocks

With uMarketingSuite.Contentblocks installed it gives you the extra option to personalize on a block level:

And if you click it, you can create personalized variants of the block:

In this specific case; rendering a different form for visitors from denmark, during the timeperiod of Codegarden 2024:

I think this is exactly what you try to achieve with this topic I guess...

Hopefully it helps! Keep rocking,

Jeffrey

[kjac]

A little update to the previously discussed "misconfiguration" subject. After analysing this more thoroughly, we're going to attempt a more lenient strategy, to make element variance more flexible.

In short: If a blocks property varies at document type level, the "corresponding" variance will be ignored by the individual blocks.

For example: If the blocks property varies by culture, any configured culture variance will be ignored by the individual blocks - but it will still be possible to use block level segment variation.

This should also cover @tristanjthompson's excellent example above.

The change is also necessary to facilitate the use of variant element types in document type compositions.

It does make things a little more "magic", since the block level variance will now in part depend on the context in which the block is used. But the flexibility to mix and match variance between document and element level is quite valuable, and this "magic" is the price we'll have to pay to achieve it.