An example of this is when media files have a file size property that represents the file size as the number of bytes. The UI that displays this information will need to format the bytes (e.g. 10000000) into a readable string such as 10MB. The server can take on this responsibility by adding another property to the Graph schema that will display the formatted string, which ensures consistency across the applications that require the formatted file size.

The code below will add a custom API model property to the Graph schema called FileSizeFormatted, which uses the GetValue method to get the FileSize property and format it to a readable string using the custom extension method ToFormattedString().

[ServiceConfiguration(typeof(IContentApiModelProperty), Lifecycle = ServiceInstanceScope.Singleton)]
public class FileSizeContentApiModelProperty : IContentApiModelProperty
{
    //To override an existing property you can use the same name.
    public string Name => "FileSizeFormatted";

    public object GetValue(ContentApiModel contentApiModel)
    {
        //Validate that the model contains a FileSize property
        //Another option is to validate the content type
        if (!contentApiModel.Properties.TryGetValue("FileSize", out var property))
            return string.Empty;

        if (int.TryParse(property.ToString(), out var fileSize))
            return fileSize.ToFormattedString(); //Custom extension method

        return string.Empty;
    }
}

Then after running the content synchronization scheduled job, the GraphQL schema and content has been updated with the new property.

Query

{
  PdfFile(limit: 100) {
    items {
       FileSize
       FileSizeFormatted
    }
  }
}

Result

{
  "data": {
    "PdfFile": {
      "items": [
        {
          "FileSize": 2107621,
          "FileSizeFormatted": "2mb"
        },
        {
          "FileSize": 1070229,
          "FileSizeFormatted": "1045kb"
        }
      ]
    }
  }
}

This is a basic example of creating a custom API model property, and there is room for improvement, because any custom property is added to all schema types. It's still early days for Optimizely Graph, so we can expect that property customization will be improved in the future.

By default, blocks have to be translated individually. This means that translating a page will require the editor to do a lot of clicking to translate the content. Luckily there is a sneaky configuration that makes it a lot quicker.

The Language Manager

The language manager can be installed as a NuGet package that does not come with the base installation of Optimizely CMS. It's very useful for managing the language variations for your content. There are options available for auto-translating and duplicating content into other languages, which by default does not affect child content.

Optimizely Languages app – Support Help Center

Translating content

To give an example of how the translation works by default, I will use the Language Manager to duplicate content from one language to another on a page that has blocks inside it.

I'm also using the projects feature to get a clear view of what content is being changed. I recommend using projects when translating content because it can also be used to export and import translation (XLIFF) files.

I've created a page called 'About us' and added some blocks.

The 'Accordion - about us' block also has some child blocks.

Then I use the 'Duplicate content' feature to translate the 'About us' page to Japanese.

When I look into my project, I can see that only the About page itself has been created in the Japanese language, while the blocks inside it are still only available in the Australian language.

Next, I'll show you how to configure the Language Manager to automatically include child blocks recursively in the translations.

Configuring the content types that should include blocks

There is a somewhat hidden configuration that will make the Language Manager include blocks recursively using some of its translation features. To do this, we just need to configure the content types that should be checked for child blocks when being translated. That can be done in either the AppSettings.json or Startup.cs files, as can be seen in the examples below.

AppSettings.json

{  
    "Episerver": {  
        "CmsUI": {  
            "LanguageManager": {  
                "TranslateOrCopyContentAreaChildrenBlockForTypes" : [  
                  "MyProject.Models.Pages.StandardPage",  
                  "MyProject.Models.Pages.HomePage"  
                ]  
            }  
        }  
    }  
}

Startup.cs

using EPiServer.Labs.LanguageManager;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.Configure<LanguageManagerOptions>(o =>
        {
            o.TranslateOrCopyContentAreaChildrenBlockForTypes.Add("MyProject.Models.Pages.StandardPage");
            o.TranslateOrCopyContentAreaChildrenBlockForTypes.Add("MyProject.Models.Pages.HomePage");
        });
    }
}

Most of the time you will only need to do this for page types. Note that you need to include the entire namespace path, plus the name of the class.

The result

The result is that when I duplicate the content using the Language Manager, as I've shown earlier in this article, the content of the blocks is automatically created in the target language.

Something to note is that if your block is published in the language that you're copying from, then the block will also be published automatically in the new language. It will not automatically publish your pages, which means you can still review the content fully before publishing it on the site.

When I was asked if there was an easier way to bulk translate content, I thought that there wasn't going to be an easy approach. Luckily I found the Language Manager configuration that I had never heard about, even though it is in the documentation here. It's easy to miss, so I figured I should share it here!

The problem with that approach is that it becomes increasingly complex for the content editor and can result in content inconsistencies on the website. To solve this problem we developed a solution that could show or hide properties depending on the site that the shared content type is used. The use case in this article is for the properties to be conditional based on the site, however the same techniques can be applied to other similar use cases.

Transform metadata with custom attributes

Metadata is very important and useful in the Optimizely CMS because it controls how content is rendered in the editing view. The metadata of a property contains a bunch of setting values for things such as if the property is required, disabled or even hidden entirely. There are multiple ways to influence the metadata of a property — one option is to create a custom attribute that implements the IDisplayMetadataProvider interface.

Hide a property based on the current site

What we're trying to achieve here is to show the property only when it is rendered for a specific site. The code sample below contains a custom attribute that accepts a parameter containing names of the sites that the property should be available for. The CreateDisplayMetadata method from the IDisplayMetadataProvider interface is then used to dynamically update the metadata to only display the property if the current site matches those sites.

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Class)]
public class AvailableOnSitesAttribute : Attribute, IDisplayMetadataProvider
{
    public IEnumerable<string> SiteNames{ get; }

    public AvailableOnSitesAttribute(params string[] siteNames)
    {
        SiteNames = siteNames;
    }

    private bool IsCurrentSite()
    {
        return SiteNames.Any() && SiteNames.Contains(SiteDefinition.Current.Name, StringComparer.InvariantCultureIgnoreCase);
    }

    public void CreateDisplayMetadata(DisplayMetadataProviderContext context)
    {
        if(context.DisplayMetadata.AdditionalValues[ExtendedMetadata.ExtendedMetadataDisplayKey] is ExtendedMetadata extendedMetadata)
        {
            extendedMetadata.ShowForEdit = IsCurrentSite();
        }
    }
}

There are many use cases where this type of attribute can be useful. It doesn't necessarily have to be based on the current site, it can be completely conditional based on any requirements. One thing to note is that it requires a page reload for the metadata to update, meaning that it's not an ideal method when the condition is related to another property on the same content type.

The custom attribute can be applied to any content type property. Below is a simple example of how a different introduction property can be displayed for the sites called Site1, Site2 and Site3. The names of the sites are configured in the 'manage sites' section of the admin UI.

[AvailableOnSites("Site1")]
public virtual string Intro { get; set; }

[AvailableOnSites("Site2", "Site3")]
public virtual XhtmlString DetailedIntro { get; set; }

Closing thoughts

The use case and examples in this article were somewhat simplified to make it less complex and confusing. To make things more robust you can adjust the metadata based on the site ID, or a site setting of sorts, instead of the name of the site.

As a final note I suggest customising the functionality to meet your requirements and firstly considering all your options — before you end up overcomplicating the properties on your content types. Handling properties this way can be very powerful and this article is meant to help developers meet specific requirements.

The exception

As we can see in the exception below, there is a problem with a piece of content that does not inherit from the correct content type. The content is an image and it inherits from ImageData instead of the expectedImageFile type.

An unhandled exception occurred while processing the request.
TypeMismatchException: Content with id '1234' is of type 'EPiServer.Core.ImageData_DynamicProxy' which does not inherit required type 'MyProject.Models.Media.ImageFile'
EPiServer.Core.Internal.DefaultContentLoader.ThrowTypeMismatchException(ContentReference link, Type actual, Type required)

What's the problem?

The exception is caused by an invalid object cast. In my case I was casting image content to ImageFile, but the content had somehow changed to be of type ImageData. What is actually happening is that the custom content type is no longer recognized and the primary type is used as a fallback. The type does still exist in the solution, but it has been moved to a new assembly and namespace. The problem is that the content types in the new assembly are not picked up by the CMS.

Content type synchronization

On startup the assemblies of the application are automatically scanned for content types and then those types are synchronized to the database. Any of the referenced assemblies can also contain content types and will be synchronized in the same way. It's interesting to note that this only works for assemblies with a dependency to the EPiServer.Framework package. Besides that it also does not seem to work for assemblies that are added to the project as a direct DLL reference.

How to fix it

The new assembly that contains the content type was added to the project as a direct DLL reference. This assembly was not being picked up by the AssemblyScanner during startup and therefore the content type was not synchronized correctly — like I described in the section above. In order to solve this issue I had to reference the assembly in a different way and opted for a private nuget package. Another way is to add a reference to the project instead of to the DLL directly.

Conclusion

The issue turned out to be caused by something quite different than I originally expected. It was interesting to learn about how the content type synchronization works in Optimizely. I doubt many people will encounter the same issue, because it's really an unlucky edge case with assembly referencing specific to my architecture. Although if anyone finds themselves in a similar situation then hopefully this post will help them.

Hiding specific properties

The default properties are generally useful for every content type, however in some situations they are not used or require adjustments. For example the Category selector field and 'Display in navigation' checkbox that are rendered by default on every page. Now you might be thinking, I can easily override these properties in my page type and add the Ignore attribute to hide them, but unfortunately that does not work because of the way these properties are created in the PageData class.

It's still possible to hide those default properties by creating an EditorDescriptor class. The code in the following snippet will hide the 'Display in navigation' property. If we set the target type as 'bool' it will only be called for properties of type bool. Then the if statement will make sure we hide the correct property only on pages of type TagPage.

[EditorDescriptorRegistration(TargetType = typeof(bool))]
[EditorDescriptorRegistration(TargetType = typeof(bool?))]
public class HideVisibleInMenuEditorDescriptor : EditorDescriptor
{
    public override void ModifyMetadata(ExtendedMetadata metadata, IEnumerable<Attribute> attributes)
    {
        base.ModifyMetadata(metadata, attributes);

        //Get owner content
        dynamic data = metadata;
        var ownerContent = data.OwnerContent;

        //Only hide the property for content types inheriting from SettingsBase
        if (metadata.PropertyName == "PageVisibleInMenu" && ownerContent is TagPage)
        {
            metadata.ShowForEdit = false;
        }
    }
}

The result is that the checkbox is hidden on all of our tag pages.

Hiding the category field

In the next example the Category field gets hidden for content types inheriting from SettingsBase. It's very similar to the snippet above, the main difference is that the target type is set to CategoryList.

[EditorDescriptorRegistration(TargetType = typeof(CategoryList), EditorDescriptorBehavior = EditorDescriptorBehavior.Default)]
public class CategoryEditorDescriptor : EditorDescriptor
{
    public override void ModifyMetadata(
        ExtendedMetadata metadata,
        IEnumerable<Attribute> attributes)
    {
        base.ModifyMetadata(metadata, attributes);

        //Get owner content
        dynamic mayQuack = metadata;
        var ownerContent = mayQuack.OwnerContent;

        //Only hide category for content types inheriting from SettingsBase
        if (metadata.PropertyName == "icategorizable_category" && ownerContent is TagPage)
        {
            //Hide property
            metadata.ShowForDisplay = false;
            metadata.ShowForEdit = false;
        }
    }
}

Move category to the page header

With an editor descriptor it's also possible to move the category field. By default it is placed within the content tab, but as shown in the Optimizely Foundation project you can also move it into the page header. Using the same descriptor that we created earlier we can move the category by setting the group name.

metadata.GroupName = SystemTabNames.PageHeader;
metadata.Order = 10000;

Adding a custom property to the page header

This technique can also be used for custom properties. All you have to do is set the group name using the SystemTabNames.PageHeader constant.

[SelectOne(SelectionFactoryType = typeof(ThemeSelectionFactory))]
[Display(Name = "Theme", Order = 2, GroupName = SystemTabNames.PageHeader)]
public virtual string SiteTheme { get; set; }

The result is that we now have a 'Theme' dropdown in the header section.

These snippets are all just examples and can be used in many different ways depending on your content approach. The default properties are there for a reason so I recommend reconsidering all the options before hiding any of them. Over the years I've had to deal with requirements to make specific adjustments to the page header so that's why I'm sharing this knowledge.

Note that I only post the code that has been updated, for the full example please refer to the blog post: https://world.optimizely.com/blogs/Anders-Hattestad/Dates/2015/2/extending-the-hyperlink-with-custom-field/

First here is the updated code for the custom HyperLink model.

internal class HyperLinkModel
{
    public string Name { get; set; }

    public string DisplayName { get; set; }

    public string Title { get; set; }

    public IEnumerable<ContentReference> Roots { get; set; }

    public string WidgetType { get; set; }

    public IDictionary<string, object> WidgetSettings { get; set; }

    public IEnumerable<Type> LinkableTypes { get; set; }

    public bool Invisible { get; set; }

    public string SearchArea { get; set; }
}

Next is the custom editor descriptor that will initialize the existing fields followed by a new custom text field with the name Other. You can find the code for the custom field in the blog post linked above.

[EditorDescriptorRegistration(TargetType = typeof (string), UIHint = "HyperLink",
EditorDescriptorBehavior = EditorDescriptorBehavior.OverrideDefault)]
public class LinkEditorDescriptor : EditorDescriptor
{
    private readonly LocalizationService _localizationService;

    public LinkEditorDescriptor() : this(LocalizationService.Current)
    {
    }

    public LinkEditorDescriptor(LocalizationService localizationService)
    {
        _localizationService = localizationService;
    }

    public override void ModifyMetadata(ExtendedMetadata metadata, IEnumerable<Attribute> attributes)
    {
        base.ModifyMetadata(metadata, attributes);
        IEnumerable<IContentRepositoryDescriptor> allInstances =
            ServiceLocator.Current.GetAllInstances<IContentRepositoryDescriptor>();
        List<HyperLinkModel> list = (
            from r in allInstances
            orderby r.SortOrder
            where r.LinkableTypes != null && r.LinkableTypes.Any<Type>()
            select new HyperLinkModel
            {
                Name = (r.CustomSelectTitle ?? r.Name),
                Roots = r.Roots,
                WidgetType = "epi-cms/widget/ContentSelector",
                LinkableTypes = r.LinkableTypes,
                SearchArea = r.SearchArea
            }).ToList<HyperLinkModel>();
        list.InsertRange(list.Count, new HyperLinkModel[]
        {
            new HyperLinkModel
            {
                Name = "Email",
                Title = _localizationService.GetString("/episerver/cms/widget/editlink/emailtooltip"),
                DisplayName = _localizationService.GetString("/episerver/cms/widget/editlink/email"),
                WidgetType = "epi-cms/form/EmailValidationTextBox",
                WidgetSettings = new Dictionary<string, object>
                {
                    {
                        "addMailTo",
                        true
                    }
                }
            },
            new HyperLinkModel
            {
                Name = "FreeTextLink",
                Title = "Other links",
                DisplayName = "Other",
                WidgetType = "alloy/TextBoxMustHaveValue"
            },
            new HyperLinkModel
            {
                Name = "ExternalLink",
                Title = _localizationService.GetString("/episerver/cms/widget/editlink/externallinktooltip"),
                DisplayName = _localizationService.GetString("/episerver/cms/widget/editlink/externallink"),
                WidgetType = "epi-cms/form/UrlValidationTextBox"
            },
            new HyperLinkModel
            {
                Name = "Anchor",
                Title = _localizationService.GetString("/episerver/cms/widget/editlink/anchortooltip"),
                DisplayName = _localizationService.GetString("/episerver/cms/widget/editlink/anchor"),
                WidgetType = "epi-cms/form/AnchorSelectionEditor",
                Invisible = true
            }
        });
        metadata.EditorConfiguration["providers"] = list;
        metadata.DisplayName = string.Empty;
        metadata.ClientEditingClass = "epi-cms/widget/HyperLinkSelector";
    }
}