View Source

Class BlockEditorVarianceHandler

Handles value variance for the Block Editor property editor, determining how property values differ based on culture and segment.

Inheritance

object

Namespace: Umbraco.Cms.Core.PropertyEditors.ValueConverters

Assembly: Umbraco.Infrastructure.dll

Syntax

public sealed class BlockEditorVarianceHandler

Constructors

View Source

BlockEditorVarianceHandler(ILanguageService, IContentTypeService)

Initializes a new instance of the BlockEditorVarianceHandler class.

Declaration

public BlockEditorVarianceHandler(ILanguageService languageService, IContentTypeService contentTypeService)

Parameters

Type	Name	Description
ILanguageService	languageService	Service used to manage and retrieve language information for localization.
IContentTypeService	contentTypeService	Service used to manage and retrieve content type definitions.

Methods

View Source

AlignExposeVariance(BlockValue)

Aligns block value expose for variance changes.

Declaration

[Obsolete("Please use the overload that takes the culture being aligned. Scheduled for removal in Umbraco 19.")]
public void AlignExposeVariance(BlockValue blockValue)

Parameters

Type	Name	Description
BlockValue	blockValue	The block value to align.

View Source

AlignExposeVariance(BlockValue, string?)

Aligns block value expose for variance changes.

Declaration

public void AlignExposeVariance(BlockValue blockValue, string? culture)

Parameters

Type	Name	Description
BlockValue	blockValue	The block value to align.
string	culture	The culture of the property value being aligned (null if invariant).

Remarks

Used for aligning variance changes when editing content.

This is expected to be invoked after all block values have been aligned for variance changes by AlignPropertyVarianceAsync(IList<BlockPropertyValue>, string?).

A block that holds no property values has no value variance to derive its expose entries from, so it is exposed for culture when its element type varies by culture, and invariantly when it does not.

View Source

AlignPropertyVarianceAsync(IList<BlockPropertyValue>, string?)

Aligns a collection of block property values for variance changes.

Declaration

public Task<IList<BlockPropertyValue>> AlignPropertyVarianceAsync(IList<BlockPropertyValue> blockPropertyValues, string? culture)

Parameters

Type	Name	Description
IList<BlockPropertyValue>	blockPropertyValues	The block property values to align.
string	culture	The culture of the property value being aligned (null if invariant).

Returns

Type	Description
Task<IList<BlockPropertyValue>>	A task that represents the asynchronous operation, containing the aligned block property values.

Remarks

Used for aligning variance changes when editing content.

A property type that has become culture variant adopts culture. A property type that has become culture invariant can only retain a single value per alias and segment; an explicitly invariant value takes precedence, then the value for culture, then the value for the default language.

View Source

AlignedExposeVarianceAsync(BlockValue, IPublishedElement, IPublishedElement)

Aligns a block value for variance changes.

Declaration

[Obsolete("Please use the overload that takes the culture of the owning property value. Scheduled for removal in Umbraco 19.")]
public Task<IEnumerable<BlockItemVariation>> AlignedExposeVarianceAsync(BlockValue blockValue, IPublishedElement owner, IPublishedElement element)

Parameters

Type	Name	Description
BlockValue	blockValue	The block property value to align for variance.
IPublishedElement	owner	The owner element, which is either the content for block properties at the content level or the parent element for nested block properties.
IPublishedElement	element	The block element containing the property.

Returns

Type	Description
Task<IEnumerable<BlockItemVariation>>	A task representing the asynchronous operation, with a result containing the aligned BlockItemVariation instances for the specified block element.

View Source

AlignedExposeVarianceAsync(BlockValue, IPublishedElement, IPublishedElement, string?)

Aligns a block value for variance changes.

Declaration

public Task<IEnumerable<BlockItemVariation>> AlignedExposeVarianceAsync(BlockValue blockValue, IPublishedElement owner, IPublishedElement element, string? culture)

Parameters

Type	Name	Description
BlockValue	blockValue	The block property value to align for variance.
IPublishedElement	owner	The owner element, which is either the content for block properties at the content level or the parent element for nested block properties.
IPublishedElement	element	The block element containing the property.
string	culture	The culture of the owning property value, or `null` when the owning property does not vary by culture.

Returns

Type	Description
Task<IEnumerable<BlockItemVariation>>	A task representing the asynchronous operation, with a result containing the aligned BlockItemVariation instances for the specified block element.

Remarks

Used for aligning block item variations according to variance (such as culture or segment) when rendering content.

In case of mismatch in culture variation for block value variation:

If the expected variation is by culture but all expose entries are invariant, assign the default culture.
If the expected variation is invariant but all expose entries have cultures, use the entry for culture as invariant, falling back to the one for the default culture.

View Source

AlignedPropertyVarianceAsync(IList<BlockPropertyValue>, IPublishedContentType, IPublishedElement, string?)

Aligns the property values of a block element for variance changes.

Declaration

public Task<IList<BlockPropertyValue>> AlignedPropertyVarianceAsync(IList<BlockPropertyValue> blockPropertyValues, IPublishedContentType elementType, IPublishedElement owner, string? culture)

Parameters

Type	Name	Description
IList<BlockPropertyValue>	blockPropertyValues	The block property values to align.
IPublishedContentType	elementType	The published element type the values belong to.
IPublishedElement	owner	The owner element, which is either the content for block properties at the content level or the parent element for nested block properties.
string	culture	The culture of the owning property value, or `null` when the owning property does not vary by culture.

Returns

Type	Description
Task<IList<BlockPropertyValue>>	A task representing the asynchronous operation, with a result containing the aligned block property values.

Remarks

Used for aligning variance changes when rendering content.

This applies the same rule as AlignPropertyVarianceAsync(IList<BlockPropertyValue>, string?) does when editing: a property type that has become culture variant adopts culture, and a property type that has become culture invariant retains a single value per alias and segment - an explicitly invariant value first, then the value for culture, then the value for the default language.

The supplied values are never modified; realigned values are returned as new instances.

View Source

AlignedPropertyVarianceAsync(BlockPropertyValue, IPublishedPropertyType, IPublishedElement)

Aligns a block property value for variance changes.

Declaration

[Obsolete("Please use the overload that aligns all property values of a block element. Scheduled for removal in Umbraco 19.")]
public Task<BlockPropertyValue?> AlignedPropertyVarianceAsync(BlockPropertyValue blockPropertyValue, IPublishedPropertyType propertyType, IPublishedElement owner)

Parameters

Type	Name	Description
BlockPropertyValue	blockPropertyValue	The block property value to align.
IPublishedPropertyType	propertyType	The underlying property type.
IPublishedElement	owner	The containing block element.

Returns

Type	Description
Task<BlockPropertyValue>	A task representing the asynchronous operation. The task result contains the aligned BlockPropertyValue, or `null` if alignment is not applicable.