Blog posts by Ynze Nunnink

How to add a custom property in Optimizely Graph

Thu, 09 May 2024 00:29:14 GMT

In the Optimizely CMS content can be synchronized to the Optimizely Graph service for it then to be exposed by the GraphQL API. In some cases, you may want to add or adjust a property when the content is being synchronized.

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.

Next level content delivery with Optimizely Graph

Mon, 02 Oct 2023 13:00:00 GMT

Optimizely introduced a new product called Optimizely Graph earlier this year. We were one of the first partners to adopt this new service in a large-scale web development project. Let’s take a look at what Graph brings to the table and why I call it the next level for content delivery.

Translating content blocks recursively in Optimizely CMS

Fri, 14 Jul 2023 06:26:32 GMT

Translating a lot of pages in Optimizely can become a real chore for content editors because pages generally have a lot of child content in the form of blocks. To make things more complicated, blocks can recursively also have child blocks. An average page can easily have 10 or more blocks depending on the amount of content that is displayed.

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 include child content

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" : [  
                  "AlloyTemplates.Models.Pages.ExamplePage1",  
                  "AlloyTemplates.Models.Pages.ExamplePage2"  
                ]  
            }  
        }  
    }  
}

Startup.cs

using EPiServer.Labs.LanguageManager;

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

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!

Translating content blocks recursively in Optimizely CMS

Fri, 14 Jul 2023 06:26:32 GMT

The Language Manager

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'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.

Optimizely named a leader in the Gartner 2023 Magic Quadrant

Mon, 20 Mar 2023 01:00:00 GMT

The Optimizely DXP and CMP are once again being recognised as leaders in the Magic Quadrant by Gartner.

Optimizely as a headless CMS

Thu, 16 Mar 2023 13:00:00 GMT

The Optimizely CMS has always been known as a traditional CMS, but is this still the case? Newly added features are pushing it into headless territory, and they come with some competitive advantages.

How to use Optimizely to personalise your website

Mon, 27 Feb 2023 13:00:00 GMT

Optimizely has many personalisation capabilities, and it can be challenging to understand how they all work. Let's take a look at some of the personalisation solutions and how they operate.

What’s next after Google Optimize’s sunsetting?

Tue, 31 Jan 2023 02:00:00 GMT

Google has announced that it is sunsetting the Google Optimize and Optimize 360 services, forcing customers to explore new platforms and invest in transitioning before September 2023.

Optimizely multi-site best practices: a presentation by MVP Ynze Nunnink

Sun, 09 Oct 2022 13:00:00 GMT

A showcase of Optimizely multi-site best practices, featuring Daimler sub-brands Fuso and Freightliner.

Optimizely names Luminary Senior Developer, Ynze Nunnink, OMVP

Sun, 02 Oct 2022 13:00:00 GMT

Luminary Senior Developer and Optimizely Lead, Ynze Nunnink has secured the coveted position of Optimizely MVP. Earning a Platinum badge for his contribution to the Optimizely and greater CMS community, Ynze will continue to share knowledge and enhance the Optimizely product offering through his work.

A multi-brand strategy in Optimizely DXP

Thu, 29 Sep 2022 14:00:00 GMT

The Optimizely Digital Experience Platform (DXP) is ideally suited to digital projects featuring multiple websites or applications. Here, we showcase a multi-brand engagement we are undertaking for Daimler.

Optimizely community meetup - Sept 29 (virtual + Melbourne)

Tue, 27 Sep 2022 04:48:08 GMT

Super excited to be presenting this Thursday the 29th of September at the Optimizely community meetup. For the full details and RSVP's see the official Meetup page: https://www.meetup.com/optimizely-melbourne/events/288300244/

Meetup details

Luminary and Optimizely are warmly welcoming back the Optimizely community with a mega meetup, including three great in-person talks (remote enabled). Hear about the latest platform developments as well as seeing some truly incredible projects in action.

This is an event for the entire Optimizely developer and user community. There will be three 20-minute short talks, each with social breaks in between:

A showcase of Optimizely multi-site best-practices, featuring Fuso Trucks from Ynze Nunnink, Luminary Optimizely Lead & Optimizely MVP The evolution of personalisation Nicola Ayan, Director of Technology and Growth, Optimizely APJ Unveiling of exciting new developments from Optimizely (plus two books to give away!) For those attending the event in person, Luminary is catering with substantial food and premium drink options.

The three best questions from guests (as voted by our speakers) will each receive a $100 Prezzee Gift Card, redeemable at more than 250 major retailers Australia-wide.

We are so excited to share this event with you!

How to join online?

Keep an eye on the meetup page for the latest details on how to join. It will be a zoom meeting and you will be able to communicate and ask questions!

Optimizely community meetup - Sept 29 (virtual + Melbourne)

Tue, 27 Sep 2022 04:48:08 GMT

Super excited to be presenting this Thursday the 29th of September at the Optimizely community meetup. For the full details and RSVP's see the official Meetup page:https://www.meetup.com/optimizely-melbourne/events/288300244/

Meetup details

This is an event for the entire Optimizely developer and user community.There will be three 20-minute short talks, each with social breaks in between:

A showcase of Optimizely multi-site best-practices, featuring Fuso Trucks from Ynze Nunnink, Luminary Optimizely Lead & Optimizely MVPThe evolution of personalisation Nicola Ayan, Director of Technology and Growth, Optimizely APJUnveiling of exciting new developments from Optimizely (plus two books to give away!)For those attending the event in person, Luminary is catering with substantial food and premium drink options.

The three best questions from guests (as voted by our speakers) will each receive a $100 Prezzee Gift Card, redeemable at more than 250 major retailers Australia-wide.

We are so excited to share this event with you!

How to join online?

Keep an eye on the meetup page for the latest details on how to join. It will be a zoom meeting and you will be able to communicate and ask questions!

How to bypass the content creation view in Optimizely

Fri, 23 Sep 2022 04:43:51 GMT

Something that has come up a couple of times in the last few year is feedback from content editors about the editing view that comes up when creating new content. The view is based on properties (or content fields) that are required, so you cannot create the content before you've provided values for those properties. The view only comes up if there are any required properties.

It can be a real nuisance because it's at least one extra step to complete every time you need to create a piece of content. When working with lots of pages it can be a real time waster. In some cases the editor just wants to set up the IA without having to worry about all the required content on each page. In practice it's not that important to provide the required values when creating the content, but it is important that the required values are provided before the content can be published.

Creating a metadata extender class

The cool thing is that there is actually a way to skip the initial 'create content' editing view. The trick is to dynamically adjust the metadata of the properties to make them non-required when the content is being newly created. We need to make sure that the properties are still required after the content has been created, so that it cannot be published before the values are provided.

public class SkipContentCreateViewMetadataExtender : IMetadataExtender
{
    public void ModifyMetadata(ExtendedMetadata metadata, IEnumerable<Attribute> attributes)
    {
        // When content is being created the content link is 0
        if (metadata.Model is IContent data && data.ContentLink.ID == 0)
        {
            foreach (var modelMetadata in metadata.Properties)
            {
                var property = (ExtendedMetadata)modelMetadata;

                property.ShowForEdit = false;

                //If property if required you won't be able to create the content
                //Therefore set required to false
                if (property.IsRequired)
                    property.IsRequired = false;
            }
        }
    }
}

Registering the metadata extender

Then in order for the metadata extender to work it needs to be registered using an initialization module. You can specify the content type that the metadata extender should be used for, in case you only want this to be used for a particular content type, and it also works inherently with base classes. In this case I used the ContentData type, which means that the extender will be executed for practically any content. If for example you only want to use this for pages then you can change it to PageData.

[ModuleDependency(typeof(InitializationModule))]
public class MetadataHandlerInitialization : IInitializableModule
{
    public void Initialize(InitializationEngine context)
    {
        var registry = context.Locate.Advanced.GetInstance<MetadataHandlerRegistry>();
        registry.RegisterMetadataHandler(typeof(ContentData), new SkipContentCreateViewMetadataExtender());
    }

    public void Uninitialize(InitializationEngine context){ }
}

The outcome

Now when you create any new content it will only the title will be required, making it much quicker to create a large amount of pages and blocks. On top of that required properties are still required before the content can be published.

Closing thoughts

Quick shoutout to this blog post by David Knipe, which inspired me to create the solution described in this article. Go check it out!

How to bypass the content creation view in Optimizely

Fri, 23 Sep 2022 04:43:51 GMT

Creating a metadata extender class

public class SkipContentCreateViewMetadataExtender : IMetadataExtender{    public void ModifyMetadata(ExtendedMetadata metadata, IEnumerable<Attribute> attributes)    {        // When content is being created the content link is 0        if (metadata.Model is IContent data && data.ContentLink.ID == 0)        {            foreach (var modelMetadata in metadata.Properties)            {                var property = (ExtendedMetadata)modelMetadata;                property.ShowForEdit = false;                //If property if required you won't be able to create the content                //Therefore set required to false                if (property.IsRequired)                    property.IsRequired = false;            }        }    }}

Registering the metadata extender

[ModuleDependency(typeof(InitializationModule))]public class MetadataHandlerInitialization : IInitializableModule{    public void Initialize(InitializationEngine context)    {        var registry = context.Locate.Advanced.GetInstance<MetadataHandlerRegistry>();        registry.RegisterMetadataHandler(typeof(ContentData), new SkipContentCreateViewMetadataExtender());    }    public void Uninitialize(InitializationEngine context){ }}

The outcome

Closing thoughts

Quick shoutout to this blog post by David Knipe, which inspired me to create the solution described in this article. Go check it out!

Conditional content properties in Optimizely

Wed, 21 Sep 2022 01:43:47 GMT

In a recent Optimizely project we were building multiple sites that could share content types between them. One problem we encountered was that some of the blocks and pages required slightly different content, and therefore separate content fields (known as properties). The simplest solution is to have 2 properties and if one is empty then the other one is used. The page or block can then display the content accordingly depending on what the content editor has provided.

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.

Conditional content properties in Optimizely

Wed, 21 Sep 2022 01:43:47 GMT

Transform metadata with custom attributes

Hide a property based on the current site

[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();        }    }}

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

Closing thoughts

Content type mismatch exception in Optimizely

Fri, 19 Aug 2022 05:25:56 GMT

The TypeMismatchException exception came up recently after making some changes to namespaces and assemblies in an Optimizely project. This proved to be an interesting issue and I will explain my findings from investigating the problem in the hopes that it will help another developer in the future.

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.

Content type mismatch exception in Optimizely

Fri, 19 Aug 2022 05:25:56 GMT

The exception

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?

Content type synchronization

How to fix it

Conclusion

Contextualizing content type thumbnails in Optimizely CMS

Tue, 12 Jul 2022 04:23:53 GMT

In the CMS when creating a block or a page a list of all the available content types will be displayed. Each content type can have its own custom thumbnail image to help identify what the content is used for. One common practice is to take a screenshot of the component as it was designed and use that as the thumbnail. To configure the thumbnail image you can add the ImageUrl attribute to any content type. The attribute has a parameter that can be used to set the path to the image.

Now I had a scenario where a block is used in multiple different sites and each site has its own styling theme. If I were to use a screenshot of the block design then the styling will would be incorrect for all but one of the sites. This is because the thumbnail path can only be configured once per block type. To solve this I created a simple solution that enables a different thumbnail to be displayed for a block type based on the context. Note that for this example I'm only using block types, but it can be used for any content types.

The following snippet contains a custom attribute that inherits from the aforementioned ImageUrlAttribute and overrides the Path variable in order to get the thumbnail path based on the name of the current site.

public class ContextualImageUrlAttribute : ImageUrlAttribute
{
    public ContextualImageUrlAttribute(string name) : base(string.Empty)
    {
        FileName = name;
    }

    public string FileName { get; }

    public override string Path => $"~/{SiteDefinition.Current.Name}/Thumbnails/" + FileName + ".jpg";
}

For this to work the thumbnails have to be stored inside folders that are named after each site. For example the path to a thumbnail for one site could be /MySite/Thumbnails/custom-block.jpg.

The new attribute can then be added to any content type. Here you can see it being used on a block.

[ContextualImageUrl("hero-banner-block")]
public class HeroBannerBlock : BlockData
{
}

This is a simple example of how you can use a custom attribute implementation to contextualize the thumbnail path. In other scenario's you may want to change the path based on a configurable setting or some other contextual property. Hopefully this example can help developers make the editing experience more user friendly in a similar multi-site solution.