Blog posts by Tomek Juranek

Branch Templates in Optimizely CMS

Tue, 22 Jul 2025 18:29:24 GMT

Optimizely CMS natively doesn't support branch templates, a concept known from different content management systems. Branch templates are useful if we want to help content authors to automate repetetive tasks with multiple content items, for example creation of a new product pages with subpages, all with predefined layout containing various blocks. This issue can be solved by copying and pasting exisitng page and adjusting the content on the copy, but it's more like a workaround which solves the problem only partially. For the blocks initial values in Optimizely CMS we can use SetDefaultValues method but managing it from code for larger structures can be painful, also it doesn't solve the problem of automated subpages creation. We can solve both issues by adding branch template functionality to the CMS.

We can achieve it by adding simple code, first let's add a new item template, we will only use it as a folder, so we don't need any fields:

[ContentType(DisplayName = "White Label Template Folder",
        GUID = "2acce58b-41cc-4edc-a361-a1baa86b51bc",
        Description = "A folder which allows to structure new branch templates.",
        GroupName = TabNames.BranchTemplate, Order = 40)]
public class TemplateFolderPage : PageData
{
}

We can also configure the folder icon:

[UIDescriptorRegistration]
public class TemplateFolderPageUIDescriptor : UIDescriptor<TemplateFolderPage>
{
    public TemplateFolderPageUIDescriptor()
            : base(ContentTypeCssClassNames.Folder)
    {
    }
}

To implement the core functionality we can use the code below. In a nutshell, inside the CreatedContent event, we first do some pre-checks:
- Is it a "new item" event? (we don't want to execute the code for example on copy/paste opetation).
- Do we have a folder with our branch templates under the root?
- Do we have a page item with the currently created type inside the root branch templates folder?
If all checks passed, we create a deep copy of the item from the branch folder and use it to replace the original page. We make sure that page name and URLSegment are unique:

[InitializableModule]
[ModuleDependency(typeof(InitializationModule))]
public class BranchTemplateInitialization : IInitializableModule
{
    private IContentRepository _contentRepository;
    private IContentLoader _contentLoader;
    private UrlSegmentOptions _urlSegmentOptions;
    private IUniqueIdentityCreator _uniqueIdentityCreator;

    public void Initialize(InitializationEngine context)
    {
        var contentEvents = ServiceLocator.Current.GetInstance<IContentEvents>();
        _contentRepository ??= ServiceLocator.Current.GetInstance<IContentRepository>();
        _contentLoader ??= ServiceLocator.Current.GetInstance<IContentLoader>();
        _urlSegmentOptions ??= ServiceLocator.Current.GetInstance<UrlSegmentOptions>();
        _uniqueIdentityCreator ??= ServiceLocator.Current.GetInstance<IUniqueIdentityCreator>();

        contentEvents.CreatedContent += ContentEvents_CreatedContent;
    }

    public void Uninitialize(InitializationEngine context)
    {
        var contentEvents = ServiceLocator.Current.GetInstance<IContentEvents>();
        contentEvents.CreatedContent -= ContentEvents_CreatedContent;
    }

    private void ContentEvents_CreatedContent(object sender, ContentEventArgs e)
    {
        var saveArgs = e as SaveContentEventArgs;
        if (e.Content == null || (saveArgs != null && saveArgs.MaskedAction == SaveAction.CheckOut))
        {
            // skip other actions like copying
            return;
        }

        var templateFolder = _contentLoader.GetChildren<TemplateFolderPage>(ContentReference.RootPage).FirstOrDefault();
        if (templateFolder == null) 
        { 
            return; 
        }

        // this is simplified code which only take 1st branch template item with the given type. 
        var myTemplateItem = _contentLoader.GetChildren<IContent>(templateFolder.ContentLink)?.FirstOrDefault(x => x.ContentTypeID == e.Content.ContentTypeID);
        if (myTemplateItem == null) 
        {
            return; 
        }

        var name = e.Content.Name;
        var oldItemLink = e.ContentLink;
        var parentLink = e.Content.ParentLink;
        var newItemLink = _contentRepository.Copy(myTemplateItem.ContentLink, parentLink, AccessLevel.NoAccess, AccessLevel.NoAccess, false);
        var newItem = _contentRepository.Get<PageData>(newItemLink);
        _contentRepository.Delete(oldItemLink, true);

        // rename page name and url segment to the one entered by author
        var newPage = newItem.CreateWritableClone();
        // we need to rename to new name and before forcing uniqueness
        newPage.Name = name;
        newPage.URLSegment = name;
        newPage.Name = _uniqueIdentityCreator.CreateName(newPage, name);
        newPage.URLSegment = _uniqueIdentityCreator.CreateURLSegment(newPage, _urlSegmentOptions);
        _contentRepository.Save(newPage, SaveAction.Default, AccessLevel.NoAccess);

        // update content link to point to new item
        e.ContentLink = newItemLink;
        e.Content = newItem;
    }
}

To make it work, we need to create the folder of type TemplateFolderPage under the root (I called it "Products Wizard"), then inside that folder we create a new page of selected type and predefined layout (I called it "Simple Product Template" and used "Product Page" type, but this is just an example). I also added a sub page called "Gallery" with it's own layout. This structure will serve as a template for all new product pages:

With the code in place, we can now create w new "Product Page" item using the standard "New Page" dialog. It should create a new product page under the given name and url segment, but with the predefined layout and the gallery subpage inside.

Display page/block thumbnail based on selected site in multi-site solution

Fri, 16 May 2025 11:50:18 GMT

In previous blog we described how to control the visibility of the blocks or properties based on the current site in multisite solution. We can use the same technique to display different thumbnails for pages and blocks inside the CMS based on selected site, to help the content authors to identify the components or page types.

Assuming we have SiteHelper helper class from the previous blog, we can create a folder structure under wwwroot, where each site has its own subfolder with thumbnail images and the subfolder names match ourMySite enum values:

Now we can implement an Attribute for our Blocks and Pages inheriting from ImageUrlAttribute. In constructor we will list the sites for which the thumbnail is available:

    [AttributeUsage(AttributeTargets.Class)]
    public class ImageUrlSitesAttribute : ImageUrlAttribute
    {
        private readonly ISiteHelper _siteHelper;

        //root folder with our thumbnails
        private readonly string _basePath = "/icons/blocks/";

        public Dictionary<MySite, string> Paths { get; set; }

        public override string Path
        {
            get
            {
                var currentSite = _siteHelper.GetCurrentSite(null);
                if (Paths.ContainsKey(currentSite))
                {
                    var currentPath = Paths[currentSite];
                    if (!string.IsNullOrWhiteSpace(currentPath))
                    {
                        return currentPath;
                    }
                }

                //default if not defined for site, we can place generic images in the _basePath folder
                return _basePath + base.Path;
            }
        }

        public ImageUrlSitesAttribute(string path, params MySite[] sites) : base(path)
        {
            _siteHelper = ServiceLocator.Current.GetService<ISiteHelper>();
            Paths = new Dictionary<MySite, string>();
            foreach (var site in sites)
            {
                var sitePath = System.IO.Path.Combine(_basePath, site.ToString().ToLower(), path);
                Paths.Add(site, sitePath);
            }
        }
    }

We can use now the attribute in Page class:

    [ContentType(
        DisplayName = "Generic Page",
        Description = "Standard page of an article.",
        GUID = "0AF06AF4-3185-4D8C-A65E-D942AC9A27D3")]
    [ImageUrlBrands("GenericPage.jpg", sites: new[] { MySite.Site1, MySite.Site2, MySite.Site3 })]
    public class GenericPage : PageData
    {
    }

or Block class:

    [ContentType(DisplayName = "Hero Full Screen",
        GUID = "A0C85434-35DE-42BF-88B7-1136B936AEAD",
        Description = "Display an immersive hero when the brand and/or hotel website pages load.",
        GroupName = GroupNames.Hero)]
    [ImageUrlBrands("HeroFullScreen.jpg", sites: new [] { MySite.Site1, MySite.Site2, MySite.Site3, MySite.Site4})]
    public class HeroFullScreenBlock : BlockData
    {
    }

Final results, when authors add new block under Site1:

and under Site2:

Show/hide blocks and properties based on selected site in multi-site solution

Sun, 06 Apr 2025 10:45:04 GMT

Optimizely PaaS CMS has a great support for multi-site solutions which can additionally be extended with the custom code. For example, we can enhance it to show or hide entire blocks or blocks elements based on the selected site in a multi-site setup. This enables tailored content experiences across different domains while maintaining a single content structure.

First let's create enum with list of our sites, it should match site definition names in CMS Settings -> Manage Websites panel:

public enum MySite 
{
    Site1,
    Site2,
    Site3
}

We will also need a helper class to resolve a site based on current host name and port (helpful for local development):

public interface ISiteHelper
{
    public MySite GetCurrentSite(ExtendedMetadata metadata);
}

public class SiteHelper : ISiteHelper
{
    private readonly ISiteDefinitionResolver _siteDefinitionResolver;
    private readonly IHttpContextAccessor _httpContextAccessor;

    public SiteHelper(ISiteDefinitionResolver siteDefinitionResolver, IHttpContextAccessor httpContextAccessor)
    {
        _siteDefinitionResolver = siteDefinitionResolver;
        _httpContextAccessor = httpContextAccessor;
    }

    public MySite GetCurrentSite(ExtendedMetadata metadata)
    {
        dynamic contentMetadata = metadata;
        var ownerContent = contentMetadata?.OwnerContent as IContent;

        SiteDefinition siteDefinition = null;
        if (ownerContent != null && ownerContent?.ContentLink?.ID != 0)
        {
            siteDefinition = _siteDefinitionResolver.GetByContent(ownerContent?.ContentLink, true);
        }

        if (siteDefinition == null){
            var request = _httpContextAccessor.HttpContext?.Request;
            var host = request?.Host.Host;
            if (request.Host.Port != null)
            {
                host += ":" + request.Host.Port;
            }
            siteDefinition = _siteDefinitionResolver.GetByHostname(host, true);
        }

        if (siteDefinition != null)
        {
            foreach (var name in Enum.GetNames(typeof(MySite)))
           {
               if (siteDefinition.Name.Equals(name, StringComparison.InvariantCultureIgnoreCase))
               {
                   return (MySite)Enum.Parse(typeof(MySite), name);
               }
           }
        }
        throw new Exception($"Site not configured");
    }
}

Next we can implement an attribute which utilizes the helper class described above. Besides hiding the element, we want to ensure that if property is required but should be hidden validation logic won't be execured for that site:

public class ShowOnSitesAttribute : Attribute, IDisplayMetadataProvider
{
    private readonly MySite[] _sites;
    private readonly ISiteHelper _siteHelper;
    public bool Hide => !_sites.Contains(_siteHelper.GetCurrentSite());
    
    public ShowOnSitesAttribute(params MySite[] sites)
    {
        _sites = sites;
        _siteHelper = ServiceLocator.Current.GetService();
    }

    public void CreateDisplayMetadata(DisplayMetadataProviderContext context)
    {
         var extendedMetadata = context.DisplayMetadata.AdditionalValues[ExtendedMetadata.ExtendedMetadataDisplayKey] as ExtendedMetadata;
         if (_sites.Contains(_siteHelper.GetCurrentSite(extendedMetadata)))
        {
            return;
        }

        if (extendedMetadata == null)
        {
            return;
        }

        extendedMetadata.ShowForEdit = false;
        foreach (var property in extendedMetadata.Properties)
        {
            property.IsRequired = false;
            property.ValidationMetadata.IsRequired = false;
        }
    }
}

Finally we can use the attribute in a block for entire class or for the properties:

[ContentType(DisplayName = "My Block", GUID = "A4ED27A1-2B34-4323-885E-4B478A137578")]
[ShowOnSites(MySite.Site1, MySite.Site2)]
public class MyBlock : BlockData
{
    [CultureSpecific]
    [Required]
    [Display(Name = "Heading", GroupName = TabNames.Content, Order = 10)]
    [ShowOnSites(MySite.Site1)]
    public virtual string Heading { get; set; }

    [CultureSpecific]
    [Display(Name = "Description", GroupName = TabNames.Content, Order = 20)]
    public virtual XhtmlString Description { get; set; }
}

Revalidate Page in Next.js after Publishing Content in Headless Optimizely PaaS CMS.

Tue, 25 Mar 2025 10:24:36 GMT

Headless CMS implementations are becoming increasingly popular. In this approach, the CMS and the front-end application are decoupled and can use different technology stacks. However, when building such a website, it is essential to ensure a seamless connection between the CMS and the front-end to maintain a smooth editing experience.

One of the most popular framework to implement head application for the headless CMS is Next.js, which offers different rendering techniques: client or server side rendering, static site generation and incremental static regeneration. We will not cover all of them here, if you need more information check out this article. In this blog we will focus on Incremental Static Regeneration (ISR), which is the way to go for majority of cases when working with CMS. ISR combines the ability of pre-rendering content to HTML files from Static Site Generation and flexibility of regenerating single pages without the need of rebuilding entire front-end application each time new content is published.

There are two ways of implementing the app in Next.js: Page Router and a newer App Router, in both, ISR works similar with some differences in Next APIs. In the base implementation content cache is invalidated in given period of time for example every 60 seconds. For the CMS editors this approach may be annoying cause they may not see their changes immediately after the publish. To address this issue we can implement on-demand revalidation and execute it every time content is published in Optmizely CMS. Keep in mind that revalidation in Next.js invalidates the cache, the actual regeneration happens when page is accessed for the first time.

First we need to implement a Content Published event. For Optimizely PaaS CMS we can use following code which hooks into the event, then finds the pages which content did changed and calls Next.js API passing security secret and the paths to changed pages:



[InitializableModule]
[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public class EventsInitialization : IInitializableModule
{
    private IContentEvents _contentEvents;
    private IContentRepository _contentRepository;
    private IContentLoader _contentLoader;
    private ISiteDefinitionResolver _sideDefinitionResolver;
    private IConfiguration _configuration;
    private IHttpClientFactory _httpClientFactory;

    public void Initialize(InitializationEngine context)
    {
        _contentEvents ??= ServiceLocator.Current.GetInstance();
        _contentRepository ??= ServiceLocator.Current.GetInstance();
        _contentLoader ??= ServiceLocator.Current.GetInstance();
        _sideDefinitionResolver ??= ServiceLocator.Current.GetInstance();
        _configuration ??= ServiceLocator.Current.GetInstance();
        _httpClientFactory ??= ServiceLocator.Current.GetService();
        _contentEvents.PublishedContent += ContentEvents_PublishedContent;
    }

    public void Uninitialize(InitializationEngine context)
    {
        _contentEvents ??= ServiceLocator.Current.GetInstance();
        _contentEvents.PublishedContent -= ContentEvents_PublishedContent;
    }

    private void ContentEvents_PublishedContent(object sender, ContentEventArgs e)
    {
        if (sender == null || e == null) return;

        var pages = PagesToRevalidate(e.Content);
        foreach (var page in pages)
        {
            RevalidatePages(page);
        }
    }

    protected List<BasePageData> PagesToRevalidate(IContent content)
    {
        // TODO this is simplified method to find pages referenced by the modified content. There may be more cases like deleting page, change page url and updating references, updating settings items, etc.
        if (content is BasePageData page)
        {
            return new List<BasePageData> { page };
        }

        return GetRefPages(content);
    }

    protected List<BasePageData> GetRefPages(IContent content)
    {
        var pages = new List<BasePageData>();
        if (content is BaseBlockData)
        {
            var references = _contentRepository.GetReferencesToContent(content.ContentLink, true).ToList();
            foreach (var reference in references)
            {
                var refContent = _contentLoader.Get(reference.OwnerID);
                if (refContent != null && refContent is BasePageData pageRef)
                {
                    if (!pages.Any(p => p.ContentLink.ID == refContent.ContentLink.ID))
                    {
                        pages.Add(pageRef);
                    }
                }
                else if (refContent is BaseBlockData)
                {
                    var refPages = GetRefPages(refContent);
                    foreach (var page in refPages)
                    {
                        if (!pages.Any(p => p.ContentLink.ID == page.ContentLink.ID))
                        {
                            pages.Add(page);
                        }
                    }
                }
            }
        }
        return pages;
    }

    protected void RevalidatePages(BasePageData page)
    {
        var langUrls = new List<string>();
        //TODO We take all languages, assuming pages have language fallback and changed content may be culture invariant. 
        foreach(var language in page.ExistingLanguages)
        {
            var url = UrlResolver.Current.GetUrl(page.ContentLink, language.Name);
            if (url != null)
            {
                langUrls.Add(url);
            }
        }

        var site = _sideDefinitionResolver.GetByContent(page.ContentLink, true);
        if (site == null || langUrls.Count == 0)
        {
            return;
        }

        var secretKey = _configuration["NextRevalidate:Secret"];
        var frontUrl = $"https://my-front-end-app.com/api/revalidate?secret={secretKey}";
        GetWebResponseAsync(frontUrl, langUrls);
    }

    protected async void GetWebResponseAsync(string apiUrl, List<string> urls)
    {
        HttpClient httpClient = _httpClientFactory.CreateClient();
        HttpRequestMessage httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, apiUrl);
        httpRequestMessage.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
        httpRequestMessage.Content = new StringContent(JsonConvert.SerializeObject(urls), Encoding.UTF8, "application/json");

        using (var reader = new StreamReader(await (await httpClient.SendAsync(httpRequestMessage).ConfigureAwait(continueOnCapturedContext: false)).Content.ReadAsStreamAsync(), Encoding.UTF8))
        {
            var resultText = await reader.ReadToEndAsync();
            Log.Information("Revalidate API result:", resultText);
        }
    }
}

Now we can implement "revalidate" API route in our Next.js application. This example uses Page Router, for the App Router adjust API function and use revalidatePath('/path') instead of res.revalidate('/path') The implementation reads from query parameters the secret (and compare it with value from env variable) and the path to revalidate ISR.


import type { NextApiRequest, NextApiResponse } from 'next';
 
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) { 
  try {
    if (req.query.secret !== process.env.NEXTAUTH_SECRET) {
        return res.status(401).json({ message: 'Invalid token' });
    }

    if (!req.body){
      return;
    }

    var results: string[] = await Promise.all(req.body.map(async (url: string): Promise => {
      await res.revalidate(url);
      return url;
    }));

    return res.json({ revalidated: results });
  } catch (err) {
    console.error(err);
    return res.status(500).send('Error revalidating');
  }
}

Run your Next application with next build and next start commands and start your CMS and publish some content, the change should be visible immediately after refreshing the page.

Optimizely CMS Developer Tools for macOS

Sat, 15 Mar 2025 14:18:27 GMT

Running Optimizely CMS on macOS presents unique challenges, as the platform was traditionally primarily designed for Windows environments. However, with the right setup-leveraging tools like Docker, .NET Framework, VS Code, Azure Storage Explorer and Azure Data Studio developers can create a smooth and efficient workflow for building and testing Optimizely projects on macOS. This article explores the necessary configurations, step-by-step installation processes to ensure a seamless development experience.

Installation

First of all you need to install Powershell on your Mac, there are couple of different methods to install it as described here. After the installation run pwsh in macOS terminal. Majority of CLI commands in this article should be run from Powershell.

To host PaaS CMS database on macOS you need Docker Desktop. After the installation, create docker-compose-yml file with:

version: "3.9"

services:

mssql:

image: mcr.microsoft.com/azure-sql-edge/developer

container_name: "mssql"

environment:

ACCEPT_EULA: "Y"

SA_PASSWORD: "MySecretPassword"

ports:

- "1433:1433"

volumes:

- ./data:/var/opt/mssql/data

- ./log:/var/opt/mssql/log

- ./secrets:/var/opt/mssql/secrets

Start the container with SQL database by running docker compose up command from the folder with .yml file.

To run Optimizely CMS locally you also need to install .Net framework for macOS. You may also need Node.js if you have headless front-end.

If you haven't install Optimizely PaaS CMS yet, you need to run few commands from Powershell CLI:

dotnet dev-certs https --trust

dotnet nuget add source http://nuget.episerver.com/feed/packages.svc -n Optimizely

dotnet new -i EPiServer.Templates

dotnet tool install EPiServer.Net.Cli --global --add-source https://nuget.optimizely.com/feed/packages.svc/

You can create a new project using Optimizely CLI commands. To create new database run from your project folder:

dotnet-episerver create-cms-database {You project}.csproj -S localhost -dn {You db name} -U sa -P {You SA password from docker-compose.yml}

dotnet-episerver add-admin-user {Your project}.csproj -u [username] -e [email] -p [password] -c EPiServerDB

Working with Code

To run and debug your Optimizely CMS project use Visual Studio Code with C# Dev Kit (for PaaS CMS). Other helpful extensions are ESLint to analyze javascript code and Prettier to help keeping the code formatting clean, but you may find more extensions for your use case. TIP: can create /{Your project root}/.vscode/extensions.json file with recommented VS Code extensions for your team.

Database Management

To manage local database server and migrate the database backup exported from DXP PaaS portal use Azure Data Studio for macOS with SQL Server dacpac extension.

First connect to your local SQL instance on Docker (use localhost server):

Then right click on Databases and select "Data-tier Application Wizard". Select "Create a database from a .backpac file". Choose a backpac file exported from PaaS Portal and import it under new name.

After the import is done, select new database and navigate to 'Security'->'Users', right click on the 'Users' folder and click on 'New User'. In 'User name' use the same name as you had before in your local instance, in 'Login name' use the same login as you had before, in 'Default schema' select dbo, in 'Owned schemas' use db_owner, in 'Membership' select db_owner.

Update connection string in your {You web project folder}\appsettings.Development.json so it points to new database name. After login to Optimizely on your local, go to settings sections: "Manage Websites" and "Open ID Connect" and update hostnames to point to your localhost.

Assets Management

To import assets from Optimizely DXP you need Powershell CLI and Azure Storage Explorer.

Using Powershell command line install EpiCloud Powershell CLI: Install-Module -Name EpiCloud
Then connect to the cloud on DXP environment by running Powershell: Connect-EpiCloud -ClientKey {your client key} -ClientSecret {your client secret} -ProjectId {your project id} you can find all necessary connection details in PaaS Portal under API tab.

Finally generate your sasLink to media storage by calling Powershell: Get-EpiStorageContainerSasLink -Environment "{name of the envionment for example: Integration}" -StorageContainer "mysitemedia" -RetentionHours 1 | Format-Table sasLink -AutoSize -Wrap.

In Azure Storage Explorer click "Open Connection Dialog", select 'Blob Container or directory' and use 'Shared access signature URL (SAS)' option. In 'Blob container or directory SAS URL' paste sasLink from previous command.

Open Blob Container and expand 'Download' button and use 'Download All' to download entire storage to local folder. Move the downloaded folder content to {You web project folder}\App_Data\blobs\.