The versioned layout API changes

Current version: 8.2

This topic describes the changes to the Sitecore API that the implementation of versioned layouts introduced in Sitecore 8.

The Sitecore.FieldIDs class

The public static readonly ID FinalLayoutField field was added to the class. This field stores an identifier of the __Final Renderings field.

The Sitecore.Data.Fields.LayoutField class

This section describes a number of changes to the LayoutField class.

The public LayoutField([NotNull] Item item) constructor

Prior to Sitecore 8, the constructor always loaded layout data from the shared __Renderings field.

In Sitecore 8 and later, the constructor checks whether the item has a value in the versioned __Final Renderings field. If it does, layout data is loaded from this field. If it does not, layout data is loaded from the shared __Renderings field.

In Sitecore 8 and later, you should use the constructor to get or to set the layout of an item:

var layout = new LayoutField(contextItem).Value;

new LayoutField(contextItem).Value = layoutXmlValue;

The public static string GetFieldValue([NotNull] Field field) method

Prior to Sitecore 8, the public static string GetFieldValue([NotNull] Field field) method only returned layout data from the shared __Renderings field. In Sitecore 8 and later, this method can return layout data either from the shared __Renderings field or from the versioned __Final Renderings field.

The method does not return the raw value of the field. It uses the layout patching workflow to calculate the resulting layout, and it returns this layout.

If you pass the versioned __Final Renderings field as an argument, the XML patch from this field is applied to the resulting layout.

If you pass the shared __Renderings field as an argument, the value of __Final Renderings field is ignored.

In Sitecore 8 and later, you should use the following method to get layout data when you want to ignore the value of the versioned __Final Renderings field:

var sharedLayout = LayoutField.GetFieldValue(item.Fields[FieldIDs.LayoutField]);

The public static void SetFieldValue([NotNull] Field field, [NotNull] string value) method

Before Sitecore 8, you could only use this method to save layout data to the shared __Renderings field.

In Sitecore 8 and later, you can use this method to save layout data either to the shared __Renderings field or to the versioned __Final Renderings field.

The method does not always save the complete layout value to the field. If possible, it saves only the XML patch to the selected field.

In Sitecore 8 and later, you should use the following method to save layout data to the shared __Renderings field:

LayoutField.SetFieldValue(item.Fields[FieldIDs.LayoutField], sharedLayout);

The Sitecore.Data.Items.ItemUtil class

  • The public static void SetLayoutDetails([NotNull] Item item, [NotNull] string sharedLayout, [NotNull] string finalLayout) method was added.

    In Sitecore 8 and later, you should use this method to save the shared layout and the final layout of an item:

    ItemUtil.SetLayoutDetails(item, sharedLayout, finalLayout);

  • The public static void ResetLayoutDetails([NotNull] Item item, bool resetShared, ResetFinalLayoutOptions resetFinal) method was added.

    In Sitecore 8 and later, you should use this method to reset shared and final layouts of an item:

    ItemUtil.ResetLayoutDetails(item, resetSharedLayout, resetFinalLayout);

The Sitecore.Data.Items.RenderingItem class

The public string GetMultiVariateTestForLanguage([NotNull] Language language) method was removed.

The Sitecore.Layouts.MultiVariateTestingExtensions class

The Sitecore.Layouts.MultiVariateTestingExtensions class was removed because the shared __Renderings field is no longer used for storing multivariate test data for all languages. Each version of the item can have different multivariate test data in the versioned __Final Renderings field.

The shared __Renderings field

Multivariate test data for all languages is no longer stored in the shared __Renderings field. Each version of an item can have different multivariate test data in the versioned __Final Renderings field.

The Sitecore.Shell.Applications.ContentEditor.LayoutField class

The following properties were added to the class:

  • public string FieldID

  • public string ItemLanguage

  • public string ItemVersion

Do you have some feedback for us?

If you have suggestions for improving this article,